Micro Focus Visual COBOL for Visual Studio 2010

Welcome to Visual COBOL

  • Welcome
  • Tour of the Visual Studio IDE for Visual COBOL
  • Getting Started
  • Product Information
  • Licensing

What's New

  • Building Projects to Multiple Output Files
  • Compiler Directives
  • Debugging Enhancements
  • Library Routines
  • Managed COBOL Language Features
  • Run-Time Tunables
  • Samples
  • SQL Support
  • Vision Data File Searching
  • XML Support

Featured Sections

  • Compatibility with ACUCOBOL-GT
  • Compatibility with RM/COBOL
  • Developing COBOL Applications
  • Tips and Tricks with the IDE
  • Managed COBOL Reference
  • Comparison of COBOL with Other Managed Languages
  • Differences between Visual COBOL and Earlier Products

Tutorials and Demonstrations

  • Tutorials on COBOL in the Visual Studio IDE
  • Demonstrations of .NET COBOL
  • Demonstrations of Native COBOL

Code Samples

  • Samples Browser

Online Resources

  • Micro Focus Infocenter
  • Micro Focus SupportLine
  • Micro Focus Product Updates
  • Micro Focus Knowledge Base
  • Micro Focus Community Forums
  • Micro Focus Training Store

Provide Feedback

  • Contacting Micro Focus
  • Email us feedback regarding this Help


Welcome

Visual COBOL enables you to develop COBOL applications within Microsoft Visual Studio. You use the integrated development environment (IDE) in Visual Studio to edit, compile and debug COBOL applications. The IDE provides all the functionality to manage projects and build applications.

You can develop COBOL applications that run as .NET managed code in the .NET environment. You can also develop and compile applications to native COBOL code, as .exe or .dll. You then deploy and further debug the application under COBOL Server.

.NET managed code and unmanaged native code can interoperate within the same application, enabling you to exploit existing COBOL in the .NET environment.

COBOL Server is a companion to Visual COBOL. COBOL Server provides the run-time environment for running COBOL applications. .NET applications also require the Microsoft .NET Framework to be installed and this is available from the Microsoft Web site.

  • Tour of the Visual Studio IDE for Visual COBOL
    Guides you though the main features offered by Visual COBOL for Visual Studio.
  • New Features
  • Tutorials on COBOL in the Visual Studio IDE
  • Product Information
  • Getting Started
  • Managing Licenses
  • Samples Browser
  • Demonstrations of .NET COBOL
  • Demonstrations of Native COBOL
  • Help on Help
Parent topic: Micro Focus Visual COBOL for Visual Studio 2010
Related information
Visual Studio and COBOL
Tips and Tricks with the IDE
Tutorials on COBOL in the Visual Studio IDE
Demonstrations of .NET COBOL
Samples Browser
Comparison of COBOL with Other Managed Languages


New Features

  • New Features in Visual COBOL 2.0
  • Features Added in Visual COBOL 2010 R4 Update 2
  • Features Added in Visual COBOL 2010 R4
  • Features Added in Visual COBOL 2010 R3
  • Features Added in Visual COBOL 2010 R2
  • Features Added in Visual COBOL 2010 R1
Parent topic: Welcome


New Features in Visual COBOL 2.0

  • Building Projects to Multiple Output Files
  • Compiler Directives
  • Debugging Enhancements
  • Library Routines
  • Managed COBOL Language Features
  • SQL Support
  • Run-Time Tunables
  • Samples
  • Vision Data File Searching
  • XML Support
Parent topic: New Features


Building Projects to Multiple Output Files

You can now build your native Link Library projects to multiple output files. To configure this, you need to go in the project properties and set Output To to Multiple Libraries.

Parent topic: New Features in Visual COBOL 2.0
Related concepts
Application Properties for Native Projects


Compiler Directives

The following new directives are now available:

  • COPYSEARCH - enables you to specify how copybooks are located. You can choose between usual Micro Focus COBOL behavior or usual RM/COBOL behavior.
  • ILSMARTNEST - enables you to nest ILSMARTLINKAGE classes inside the program class in which they are defined. This makes it possible to have multiple programs in a single compilation unit that include linkage records with the same name.

The following directives have been changed:

  • DIALECT(RM) - now accepts a new parameter, RM, which enables the RM-compatible functionality that the RM directive used to enable.
  • ILUSING - when set on a single file using the SET statement, $set ilusing, the directive only affects that file.
Parent topic: New Features in Visual COBOL 2.0
Related concepts
COPYSEARCH
ILSMARTNEST
ILUSING
RM DIALECT setting


Debugging Enhancements

This release provides the following enhancements to debugging:

Core dump files
On Windows, the core dump files created by this product are Microsoft minidump files. If you have a mixed language application you can use the minidump file to debug the other languages involved.
Debugging native COBOL Link Library projects
You can now debug native COBOL link library projects that get built to a single .dll file.
Program Breakpoints
Note: Program breakpoints are supported in native COBOL only, and are not supported with nested programs.
Use the Program Breakpoints (Native COBOL) window to add program breakpoints to your applications. When a program breakpoint is set the application breaks whenever the program or one of its entry points is called.

In the Program Breakpoints (Native COBOL) window, click New and type the name of the source file, without the extension. For multi-program source files, to set a break for a sub-program, use its program-id.

To display the Program Breakpoints (Native COBOL) window, click Debug > Windows > Program Breakpoints (Native COBOL).

Step out of OSVS perform statements
You can now step out of a perform statement when PERFORM-TYPE(OSVS) or DIALECT(OSVS) is set.
Support for debug attaching to programs launched by services
Visual COBOL now supports debugging of native CGI applications by waiting for attachment on a directory.
Wait for debuggable attachment option for native COBOL
Wait for debuggable attachment on the Debug page in the properties of native properties has been enhanced. You can now specify one the following options for it - Wait for any program, Wait for directory, and Wait for ID.
Parent topic: New Features in Visual COBOL 2.0
Related concepts
Debugging Native COBOL Link Libraries
To set a program breakpoint in native COBOL code


Library Routines

The following routine has been enhanced:

  • The CBL_SEMAPHORE_ACQUIRE routine now accepts a timeout parameter.
Parent topic: New Features in Visual COBOL 2.0
Related concepts
CBL_SEMAPHORE_ACQUIRE


Managed COBOL Language Features

The following new syntax elements are now available in managed COBOL:
Local Variables
In managed COBOL, Data items can now be declared in the procedure division, using the DECLARE statement. In addition, they can be declared inline as the iterator in a PERFORM statement, or as an exception message in a TRY … CATCH … FINALLY statement block.
Collections
There are two new collection types in managed COBOL: LIST and DICTIONARY. For a LIST, you can add elements to a list, retrieve the nth element of the list, replace the nth element, iterate through the list and clear the list. For a DICTIONARY, you can add key value pairs, retrieve a value corresponding to a key, to replace the value corresponding to a key, iterate through the dictionary and clear the dictionary.
Properties
In managed COBOL, a property can now be defined using PROPERTY-ID and GETTER and SETTER phrases to access to the property. The previous technique of specifying the keyword PROPERTY on a data declaration is still available.
Indexers
In managed COBOL, an indexer can now be defined using INDEXER-ID and GETTER and SETTER phrases to access the indexer value. Indexers are similar to properties, except that their accessors take parameters. Indexers allow instances of a class or valuetype to be indexed just like arrays.
Zero-based Indexing
The managed COBOL syntax for arrays now uses zero-base indexing to access arrays when square brackets are specified. For backward compatibility, one-base indexing is used when round parentheses are specified.
Parent topic: New Features in Visual COBOL 2.0
Related concepts
Comparison of COBOL with Other Managed Languages
Managed COBOL Reference
ILSMARTNEST


SQL Support

This release provides the following enhancements:

  • Improved IDE integration with SQL directives - 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.
  • OpenESQL has been enhanced and it now:
    • defaults to optimal performance
    • supports 64bit ODBC across all platforms
  • The OpenESQL ADO.NET managed run-time has been redesigned so it now works faster. It also supports multiple result sets with stored procedures.
Parent topic: New Features in Visual COBOL 2.0
Related concepts
SQL Properties


Run-Time Tunables

This release provides the following new tunables:

  • printer_raw_redirection - use this to redirect WRITE statements through the Windows print spooler as RAW data types.
  • subsystem_cancel_mode - use this to override the default cancel mode when you use the CBL_SUBSYSTEM library routine to cancel a subsystem.
Parent topic: New Features in Visual COBOL 2.0
Related concepts
printer_raw_redirection
subsystem_cancel_mode


Samples

The following new samples are now available:

  • CGI demonstrations:
    • Complex CGI application - demonstrates how to use native COBOL to create CGI programs which accept data from a form on a Web page and then redisplay that data in another Web page
    • Simple CGI application - demonstrates how to use native COBOL to create CGI programs which accept data from a form on a Web page and then redisplay that data in another Web page
  • The following samples have been added to the COBOL for .NET section:
    • Collections - demonstrates the new LIST and DICTIONARY collection types
    • Local Variables - shows how to declare data items in the procedure division in the DECLARE, PERFORM and TRY statements
  • The code in the Properties sample in the COBOL for .NET section of Samples Browser has been enhanced to use the new PROPERTY-ID syntax. The sample also includes a sample program for Indexers which illustrates the new INDEXER-ID syntax.
Parent topic: New Features in Visual COBOL 2.0


Vision Data File Searching

This release provides the following new ACUCOBOL-GT compatible environment variables to help search for Vision data files at run time:

  • APPLY_FILE_PATH
  • FILE_CASE
  • FILE_PREFIX
  • FILE_SUFFIX
Parent topic: New Features in Visual COBOL 2.0
Related concepts
APPLY_FILE_PATH


XML Support

The IBM-style XML GENERATE syntax is now supported in .NET managed COBOL.

Parent topic: New Features in Visual COBOL 2.0


Features Added in Visual COBOL 2010 R4 Update 2

  • Documentation for the Dialog System AddPack
  • OO COBOL Class Library Reference
  • Net Express Project Import Wizard
Parent topic: New Features


Documentation for the Dialog System AddPack

Documentation for the Dialog System AddPack is now available and is integrated with the Visual COBOL documentation.

This documentation describes the AddPack, which enables you to modernize Dialog System applications within Visual COBOL. You migrate an application to Visual COBOL and from there you can run the application without change, or modernize it over time.

The documentation describes some modernization techniques such as:

  • A Windows Forms form replacing a Dialog System dialog, where the form can contain .NET controls. See the Customer + .NET WinForm sample CustomerWinForm.sln.
  • A Windows Forms control wrapped as an ActiveX control and used on a Dialog System dialog. See the Customer + .NET GridView User Control sample custgrid.sln.
  • A WPF user control hosted by a Windows Forms user control, which is then exposed as ActiveX ready for use by Dialog System. See the Customer + .NET WPF GridView User Control sample CustGridWPF.sln
  • A .NET managed code application interacting with Dialog System as native COBOL .dll or as . See the Managed Customer sample ManagedCustomer.sln.
Note: The Dialog System AddPack is not part of Visual COBOL or COBOL Server. It is separately installable and available from Micro Focus SupportLine
Parent topic: Features Added in Visual COBOL 2010 R4 Update 2
Related information
Modernizing Dialog System Applications


OO COBOL Class Library Reference

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%\Micro Focus\Visual COBOL\Help.

To open the help, double-click nxrclr.chm in Windows Explorer.

Parent topic: Features Added in Visual COBOL 2010 R4 Update 2
Parent topic: Compatibility


Net Express Project Import Wizard

Visual COBOL for Visual Studio includes a Net Express Project Import Wizard that converts NetExpress projects into Visual Studio solutions. The wizard analyzes the Net Express project file and its configuration settings, creates one or more Visual Studio native projects based on this information, imports the existing source code into them and sets the appropriate directives. When the process is complete, it can optionally display a detailed conversion report.

Parent topic: Features Added in Visual COBOL 2010 R4 Update 2
Related information
Net Express Project Import Wizard


Features Added in Visual COBOL 2010 R4

  • ACUCOBOL-GT Compatibility
  • ADO.NET Runtime Improvements
  • Creating Projects from Selected Files
  • Debugging Enhancements
  • Documentation
  • Embedded HTML
  • Improvements to the Implements Smart Tag
  • Language Improvements
  • Large Projects Support
  • New Compiler Directives
  • New Samples and Tutorial
  • Project Details Window
  • Project Properties Updates
  • RM/COBOL Compatibility
  • Smart Linkage
  • WCF Services and Service References
  • XML Extensions
Parent topic: New Features


ACUCOBOL-GT Compatibility

The Compiler and run-time continue to provide support for ACUCOBOL-GT. The directive ACU is the main switch for turning on ACUCOBOL-GT compatibility. The ACU directive enables various ACUCOBOL-GT syntax extensions and other language elements. Additional ACUCOBOL-GT compatibility features include the following:

  • When using a CALL statement, the USING and GIVING/RETURNING phrases can now appear in either order.
  • The following ACUCOBOL-GT standard library routines can now be used with Visual COBOL in native code:
    • C$CALLEDBY
    • C$CALLERR
    • C$CHDIR
    • C$MAKEDIR
    • C$MEMCPY
    • C$MYFILE
    • C$PARAMSIZE
    • C$RERR
    • M$ALLOC
    • M$FREE
    • M$COPY
    • M$FILL
    • M$GET
    • M$PUT
    • WIN$VERSION
  • The following ACUCOBOL-GT 'ccbl' compiler options can now be used with Visual COBOL:
    • -E, -V
    • -Cv
    • -Da, -Db, -Dd31, -DL1/2/4/8, -Dq, -FpRounding
    • -La, -Li, -Lc, -Lf, -Ll, -Lo, -Ls, -Lw

      Note: The output that these list options provide differs in Visual COBOL.

    • -Qm
    • -Rc, -Rn, -Rw
    • -Sa, -St, -Sd, -Sp, -S1...-S9
    • -noTRUNC, -truncANSI, -Dz
    • -Td, -Te
    • -Vc
    • -Za, -Zc, -Zl, -Zn, -Zs, -Zi, -Zr1, -Zy, -arithmeticVSC2

Full ACUCOBOL-GT compatibility is documented under the Programming section in the product help.

Parent topic: Features Added in Visual COBOL 2010 R4
Related concepts
ACUCOBOL-GT Compatibility


ADO.NET Runtime Improvements

The OpenESQL ADO.NET runtime has been re-engineered, offering several advantages over previous versions, providing:
  • Better performance - the new runtime is much faster and can as much as double your performance, depending on the specifics of your application.
  • Support for multiple run unit processing.
  • Support for both client applications and SQL CLR stored procedures.
  • For stored procedure applications:
    • Support for input/output parameters defined as COBOL data types, in addition to the previously supported .NET data types
    • Support that enables stored procedures to return more than one result set.
    • Static SQL Support for the DIALECT=MAINFRAME Compiler directive.
  • For client-based applications:
    • Support for dynamic SQL that uses an SQLDA structure to pass parameter and result host variables, specifically including the following embedded SQL statements:
      • PREPARE - For example, the following statement passes a prepared statement into the SQLDA from a host variable:
          EXEC SQL
       PREPARE stmt1 INTO :sqlda FROM :stmt-buf
  END-EXEC
      • EXECUTE - For example, the following statement executes a prepared statement using a previously constructed SQLDA structure:
          EXEC SQL
       EXECUTE stmt1 USING DESCRIPTOR :sqlda-structure
  END-EXEC
      • OPEN - For example, the following statement opens a cursor using a previously constructed SQLDA structure:
          EXEC SQL
       OPEN c1 USING DESCRIPTOR :sqlda-structure
  END-EXEC

      For complete information on using these statements, see the PREPARE, EXECUTE, and OPEN topics.

    • Additional support for result set processing that allows you to receive more than one result set back from a stored procedure.
    • Support for applications built to target .NET Framework versions 2.0, 3.0 and 3.5, in addition to .NET Framework version 4.0.
Important: To take advantage of these improvements you must recompile your applications with the DBMAN=ADO Compiler directive. However, if you want to continue using the functionality available in previous releases, we now provide the DBMAN=OADO directive to use in place of the DBMAN=ADO directive. DBMAN=OADO provides the same functionality as was available with previous versions of the DBMAN=ADO Compiler directive, and has 100% backward compatibility with applications designed and developed with Visual COBOL R3.
Parent topic: Features Added in Visual COBOL 2010 R4
Related concepts
ADO.NET Support
Related reference
EXECUTE
OPEN
PREPARE


Creating Projects from Selected Files

A new option, Create Project From Selection, is now available for your projects in Solution Explorer. You can select a number of COBOL files and copybooks in your project and opt to create a new project from them in the same solution.

Parent topic: Features Added in Visual COBOL 2010 R4
Related concepts
Solutions and Projects in Visual Studio
Related information
Create Project from Selection


Debugging Enhancements

The ability to load core dump files in Visual Studio has been added. This feature works with native COBOL only.

Parent topic: Features Added in Visual COBOL 2010 R4
Related concepts
To produce and debug a core dump for a COBOL program


Documentation

If you are using Visual Studio 2010 Service Pack 1, the help is displayed in a stand-alone help viewer with an index and a fully expandable table of contents.

Parent topic: Features Added in Visual COBOL 2010 R4
Related concepts
Help on Help


Embedded HTML

We now support the use of Embedded HTML (EHTML) in COBOL CGI programs, which enables you to output HTML directly from your applications.

Parent topic: Features Added in Visual COBOL 2010 R4
Related concepts
Embedded HTML


Improvements to the Implements Smart Tag

The implements smart tag now supports value-types in addition to classes.

Parent topic: Features Added in Visual COBOL 2010 R4
Related information
Using Smart Tags


Language Improvements

The following improvements have been made to managed COBOL:

Extension methods and extending operators
Managed COBOL now supports extension methods. This feature enables you to add methods to existing types without the need to edit or recompile the code. You can also extend operators.
The SYNC modifier for methods
The SYNC modifier locks the values of the arguments sent to the method, so that they do not change while the method is processing.
Nested classes
In managed COBOL, a nested class can now be defined so that it can access the instance fields, properties and methods in its containing class. To allow this, you add the optional SHARING PARENT phrase to the nested class definition.
Parent topic: Features Added in Visual COBOL 2010 R4
Related information
Extension Methods
The Method-ID Paragraph
The Operator-ID Paragraph
The SYNC Statement
Nested and Inner Classes


Large Projects Support

Visual COBOL has been optimized to work with bigger, more complex applications. This includes faster processing of multiple files and various IDE features that facilitate the process of developing large-scale project.

You can quickly move existing COBOL code into Visual Studio with the help of various wizards and windows such as the Create Project from Existing Code wizard and the Create Project from Selection wizard. The IDE is preconfigured so that during the file import it automatically scans the files and sets Compiler directives on them as appropriate.

Parent topic: Features Added in Visual COBOL 2010 R4
Related concepts
Solutions and Projects in Visual Studio
Related information
File View


New Compiler Directives

The following new Compiler directives are provided:

  • ILCUTPREFIX - removes a specified prefix from the names of the COBOL data items in your source code.
  • ILSMARTLINKAGE - exposes the Linkage Section and entry points to managed code by creating types.
  • RUNTIME-ENCODING - determines the runtime encoding.
  • SOURCE-ENCODING - passes the encoding of the source program to the Compiler.
Parent topic: Features Added in Visual COBOL 2010 R4
Related concepts
RUNTIME-ENCODING
SOURCE-ENCODING
ILSMARTLINKAGE
ilcutprefix


New Samples and Tutorial

New samples and a new tutorial showing how to create WCF services in COBOL are available.

Parent topic: Features Added in Visual COBOL 2010 R4
Related concepts
Samples Browser
Demonstrations of .NET COBOL
Demonstrations of Native COBOL
Related information
Tutorial WCF Service References
WCF and COBOL


Project Details Window

A new window, Project Details, is available for your COBOL projects and solutions showing a complete list of the files in a project or a solution and various file details. You can open the window from the context menu for a project or a solution in Solution Explorer.

Parent topic: Features Added in Visual COBOL 2010 R4
Related information
File View


Project Properties Updates

The project properties pages have been restructured to make setting options more intuitive.

Parent topic: Features Added in Visual COBOL 2010 R4
Related concepts
Project Properties


RM/COBOL Compatibility

The Compiler and run-time continue to provide support for RM/COBOL. Additional RM/COBOL compatibility features include the following:

  • The following RM/COBOL standard library routines can now be used with Visual COBOL in native code:
    • C$Century
    • C$ConvertAnsiToOem
    • C$ConvertOemToAnsi
    • C$DARG
    • C$Delay
    • C$GetEnv
    • C$GetNativeCharset
    • C$LogicalAnd
    • C$LogicalComplement
    • C$LogicalOr
    • C$LogicalShiftLeft
    • C$LogicalShiftRight
    • C$LogicalXor
    • C$NARG
    • C$SetEnv
    • C$RERR
    • DELETE
    • RENAME
  • The RM/COBOL file handler can now be used with Visual COBOL, enabled by using the CALLFH(ACUFH) Compiler directive, and then configuring an add-on to the Vision file handler.

Full RM/COBOL compatibility is documented under the Programming section in the product help.

Parent topic: Features Added in Visual COBOL 2010 R4
Related concepts
Compatibility with DG and RM COBOL


Smart Linkage

Exposing COBOL group items as managed types
You can expose COBOL Linkage sections to other managed languages by using the ILSMARTLINKAGE directive. Smart Linkage saves the need to edit your original COBOL code or write wrapper classes.
Parent topic: Features Added in Visual COBOL 2010 R4
Related information
Exposing COBOL Linkage Data as Managed Types


WCF Services and Service References

Support is now available for adding WCF services as service references to your COBOL projects.

Note: WCF is not supported in the Visual Studio Shell but adding service references for client applications is supported.

Parent topic: Features Added in Visual COBOL 2010 R4
Related information
Tutorial WCF Service References
WCF and COBOL


XML Extensions

Note: This functionality is supported in native COBOL only.

You can now use XML Extensions, the system that enables your COBOL applications to interact with XML documents, with Visual COBOL.

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 RM/COBOL product documentation set, in the SupportLine section of the Micro Focus Web site.

Parent topic: Features Added in Visual COBOL 2010 R4
Related concepts
Software Requirements
Related information
XML Extensions


Features Added in Visual COBOL 2010 R3

  • .NET COBOL Syntax Improvements
  • Creating Projects from Existing Code
  • Add Existing COBOL Items Wizard
  • Override Class Members Dialog
  • Smart Tag for Implementing Interfaces
  • Snippet for Implements
  • Navigate To
  • Find All References
  • Web Application Projects
  • Debugging
  • Samples Browser
  • SQL CLR Integration Support
  • ACUCOBOL-GT Compatibility and RM/COBOL
  • XML Support
Parent topic: New Features


.NET COBOL Syntax Improvements

Quoteless syntax
Quotes are not needed when defining types, classes or methods, or when invoking classes and methods.
Construct improvements
The structure of class-id, method-id, enum-id, delegate-id, interface-id, valuetype-id has been improved.
Environment division, Configuration section, Repository
The Environment division, Configuration section and the Repository are no longer needed.
Static, Factory and Object blocks
The Static, Factory and Object blocks are no longer needed.
Attributes, Custom-Attribute and Class-Attributes
CUSTOM-ATTRIBUTE is now replaced by the ATTRIBUTES phrase. You no longer need to define class-attributes. Instead, specify the class custom attributes in the class definition.
Tip:
  • Visual COBOL supports the older syntax, so projects that are using it will still compile. However, it is recommended to create applications using the new syntax and adhere to the .NET COBOL Best Practices.
  • It is recommended to use the COBOL project and file templates, snippets and Intellisense as they use the new syntax. To see the new syntax in action, check the Visual COBOL samples.

The following is a more detailed overview of the changes in the syntax with examples:

Quoteless Syntax

Quotes are no longer needed when you define types, classes or methods, or when you invoke classes and methods. For example:

New Syntax Old Syntax
01 o1 type MyClass

01 o1 type "MyClass"

type MyClass::New

type "MyClass"::"New"

set o to new MyClass

set o to new "MyClass"

set class::Property to value

set "class"::"Property" to value

set return-value to class::Method(param1)

set return-value to "class"::"Method"(param1)

invoke class::Method(param1)

invoke "class"::"Method"(param1)

       method-id MyMethod public.

       local-storage section.

       procedure division.

           goback.
       end method.

       method-id. "MyMethod" public.
                local-storage section.

                procedure division.
                    goback.
                end method "MyMethod".

Construct of class-id, method-id, enum-id, delegate-id, interface-id, valuetype-id

The construct of class-id, method-id, enum-id, delegate-id, interface-id, valuetype-id has been improved as follows:

  • You do not have to type a period after the declaration (for example, method-id MethodName).
  • Quotes are no longer required around names.
  • You do not need to use the name in the end marker.
New Syntax Old Syntax
       class-id Namespace.MyClass.

       object-storage section.

       method-id InstanceMethod.
       local-storage section.
       procedure division.
           goback.
       end method.

       method-id StaticMethod public static.
       local-storage section.
       procedure division.
           goback.
       end method.

       end class.

       class-id. MyClass as "Namespace.MyClass".
       environment division.
       configuration section.
       repository.

       static.
       working-storage section.

       end static.

       object.
       working-storage section.

       method-id. "InstanceMethod".
       local-storage section.
       procedure division.

           goback.
       end method "InstanceMethod".

       end object.
       end class MyClass.

Environment Division, Configuration Section, Repository

You no longer need to use an Environment division, a Configuration section or a Repository paragraph. For example:

New Syntax Old Syntax
       program-id. Program1 as "MyProject.Program1".

       data division.
       working-storage section.
       procedure division.

           goback.
       end program Program1.

       program-id. Program1 as "MyProject.Program1".

       environment division.
       configuration section.
       repository.

       data division.
       working-storage section.
       procedure division.

           goback.
       end program Program1.

Static, Factory and Object Blocks

The Static and Object blocks are no longer used. With the new syntax you need only one working-storage section for items that were defined in a static or object block under the old syntax.

To define a static method, use the STATIC word.

The following example shows how to define static methods with the new syntax and how to avoid using an object block:

New Syntax Old Syntax
       class-id Namespace.MyClass.

       working-storage section.
       01 my-object-data pic x.
       01 my-static-data pic x static.

       method-id InstanceMethod.
       local-storage section.
       procedure division.
           goback.
       end method.

       method-id StaticMethod public static.
       local-storage section.
       procedure division.
           goback.
       end method.

       end class.

       class-id. MyClass as "Namespace.MyClass".
       environment division.
       configuration section.
       repository.

       static.
       working-storage section.
         01 my-static-data pic x.
       end static.

       object.
       working-storage section.
         01 my-object-data pic x.

       method-id. "InstanceMethod".
       local-storage section.
       procedure division.

           goback.
       end method "InstanceMethod".

       end object.
       end class MyClass.

Attributes, Custom-Attribute and Class-Attributes

These are the changes for CUSTOM-ATTRIBUTE and class-attributes:

  • The CUSTOM-ATTRIBUTE phrase is replaced by the ATTRIBUTE phrase.
  • You no longer have to define class-attributes. Instead, specify the class custom-attributes in the class definition using the ATTRIBUTE phrase.
  • Quotes are no longer needed around the name of the attribute and you can omit the word "Attribute" from the name.

For example:

New Syntax Old Syntax
       class-id MyNamespace.MyClass.
           attribute Serializable.

       working-storage section.
       ...

       end class.

       class-id. MyClass as "MyNamespace.MyClass".

       class-attributes.
       custom-attribute is type "SerializableAttribute".

       object.

       working-storage section.
          ...

       end object.

       end class MyClass.
Parent topic: Features Added in Visual COBOL 2010 R3
Related concepts
Comparison of COBOL with Other Managed Languages
Managed COBOL Programming
COBOL Language Reference


Creating Projects from Existing Code

Now you can create Visual Studio COBOL projects from existing applications using the Create New Project from Existing Code Files wizard. The wizard will create a new COBOL project and automatically add files to it from the specified directories. It will perform an automatic file scanning to identify which files are programs and copybooks, so that they can be correctly added to the project.

Parent topic: Features Added in Visual COBOL 2010 R3


Add Existing COBOL Items Wizard

You can add existing COBOL files to your Visual Studio project using the new Add Existing COBOL Items wizard available from the context menu of the project in Solution Explorer. The COBOL files will be scanned to determine which ones are programs or copybooks, and then they will be added to the project.

Parent topic: Features Added in Visual COBOL 2010 R3


Override Class Members Dialog

Note: This feature works with .NET managed code only.

The new Override Class Members dialog available in the editor enables you to override the members of inherited classes. The dialog helps you see the base classes from which a class inherits, select the members to override and add the construct of the overriding methods to the class.

Parent topic: Features Added in Visual COBOL 2010 R3


Smart Tag for Implementing Interfaces

Note: This feature works with .NET managed code only.

You can now easily implement interfaces with the help of a Smart Tag. The tag appears underneath at the beginning of the declaration of any interface that is not fully implemented. To implement the interface, you simply need to click the tag.

Parent topic: Features Added in Visual COBOL 2010 R3


Snippet for Implements

Note: This feature works with .NET managed code only.

The snippet for implements has been improved. It now automatically implements the members from an interface and has improved support for more complex method signatures.

Parent topic: Features Added in Visual COBOL 2010 R3


Navigate To

Use the Navigate To option in the Edit menu to search for files, variables and section names in all projects and files in your solution.

Parent topic: Features Added in Visual COBOL 2010 R3


Find All References

The Find All References option available from the editor enables you to search for references of COBOL data items, section or paragraph names in your solution.

Parent topic: Features Added in Visual COBOL 2010 R3


Web Application Projects

Note: This feature works with .NET managed code only.

This release offers Web Application Project templates for creating COBOL Web applications and Web sites and applications. The benefits of using a Web Application project include:

  • A Web Application project includes a project file which enables you to specify what files are part of the project and should be compiled.
  • It adds namespaces for all items of the project.
  • The source code is compiled into a single assembly on your local machine and is then deployed to the IIS server. You don’t have to deploy the code behind.
  • A Web Application project includes a “Publish” option for deploying the compiled assembly to an IIS server directly from the IDE using the automated tools of Visual Studio.
  • Supports the Visual Studio Code Analysis feature.
Parent topic: Features Added in Visual COBOL 2010 R3


Debugging

The following debugging enhancements have been made:

  • COBOL watchpoints and break on data change - you can set COBOL watchpoints on individual data items in native COBOL. COBOL watchpoints enable you to watch the area of memory associated with the particular data item and help track memory corruption. When the memory changes, debugging stops on the line that immediately follows the line on which the data has changed. This feature works with native code only.

  • Watchpoints (Native COBOL) window - enables you to manage the COBOL watchpoints you add to your applications and view the contents of the memory associated with each watchpoint. This feature works with native code only.

  • Simplified remote debugging - a simplified process for setting up remote debugging is provided.
  • Attach to 64-bit process and debug - provides the ability to attach to and debug 64-bit COBOL processes.
  • Debug tooltip for OCCURS items - you can now specify whether the debug tooltips for OCCURS items should display all items in an array or the value of an expression.

Parent topic: Features Added in Visual COBOL 2010 R3


Samples Browser

You can preview the samples and access them more easily with the help of the Samples Browser which is now available from the Start menu. Samples Browser lists the samples by category

Parent topic: Features Added in Visual COBOL 2010 R3


SQL CLR Integration Support

The new SQL CLR Integration support enables you to create stored procedures, user-defined functions and types, aggregates, and triggers in managed code, taking advantage of the Microsoft SQL Server 2008 R2 SQL CLR feature.

Parent topic: Features Added in Visual COBOL 2010 R3


ACUCOBOL-GT Compatibility and RM/COBOL

The Compiler and run-time now include initial support for ACUCOBOL-GT. This support is enabled by several new Compiler directives. The directive ACU is the main switch for turning on ACUCOBOL-GT compatibility. The ACU directive enables various ACUCOBOL-GT syntax extensions and other language elements. Additional ACUCOBOL-GT compatibility features include the following:

  • Vision indexed file system and utilities (vutil, vio, and logutil) support. Vision support is enabled by the new CALLFH(ACUFH) option.
  • ACUCOBOL-GT compiler options. By using the new ACUOPT directive you can specify the same options available in ACUCOBOL-GT.
  • ACUCOBOL-GT and RM/COBOL data type support. This enables you to mix ACUCOBOL-GT and Micro Focus Visual COBOL applications via data files or calls.
  • Initial ACUCOBOL-GT syntax support. The Compiler now supports some of the ACUCOBOL-GT extensions.
  • Interoperability between ACUCOBOL-GT and Visual COBOL components. You can begin to build applications that combine ACUCOBOL-GT with Visual COBOL features.

ACUCOBOL-GT compatibility is documented under the Programming section in the product help.

Parent topic: Features Added in Visual COBOL 2010 R3


XML Support

Enhancements have been made to XML Parse/Generate to provide compatibility with IBM® Enterprise COBOL for z/OS® v4.2.

New in XMLGENERATE:

  • ATTRIBUTES phrase
  • NAMESPACE and NAMESPACE-PREFIX phrases
  • XML-DECLARATION phrase

New in XMLPARSE:

There are now two modes of XMLPARSE support using the XMLPARSE() compiler directive:

  • XMLPARSE(COMPAT) – provides compatibility with IBM Enterprise COBOL for z/OS v4.1 and earlier.
  • XMLPARSE(XMLSS) – provides compatibility with IBM Enterprise COBOL for z/OS v4.2.

XMLPARSE(XMLSS) provides:

  • ENCODING phrase
  • RETURNING NATIONAL phrase
  • VALIDATING phrase
  • New special registers - XML-NAMESPACE, XML-NNAMESPACE, XML-NAMEPSACE-PREFIX and XML-NNAMESPACE-PREFIX.
  • New behaviors – for example, different return codes, different output registers depending on the EVENT.

Note: The ability to parse XML documents one segment at a time with the help of the END-OF-INPUT XML event is not supported yet.

Parent topic: Features Added in Visual COBOL 2010 R3


Features Added in Visual COBOL 2010 R2

  • File Handler
  • Go To Procedure Division
  • OpenESQL Assistant
  • Samples
  • Snippets
  • SQL Support
  • XML Parse/Generate
Parent topic: New Features


File Handler

The Micro Focus File Handler is now provided as both verifiable and non-verifiable versions. Compiling your application with the ILVERIFY directive will automatically reference the verifiable File Handler assembly.

Parent topic: Features Added in Visual COBOL 2010 R2


Go To Procedure Division

The Go To Procedure Division button is now available on the Go To Location toolbar. Clicking the button positions the cursor on a Procedure Division depending on the current context of the code.

Parent topic: Features Added in Visual COBOL 2010 R2


OpenESQL Assistant

Support for the OpenESQL Assistant has been added. The OpenESQL Assistant is an interactive tool that enables you to easily design and build SQL queries and embed those queries into your COBOL code. Features include:

  • Prototype SQL SELECT statements and test them against a database
  • Design SQL INSERT, UPDATE, and DELETE statements
  • Insert SQL queries into the COBOL code
  • Create and insert auxiliary code into your COBOL code
Parent topic: Features Added in Visual COBOL 2010 R2


Samples

The following games have been added to the samples:

  • COBOL Blitz - A shooter game in which the players use a laser cannon to defend themselves against the invasion of aliens troops. The goal is to destroy the troops and prevent them from reaching the bottom of the screen.

    Special Features:

    • 2D graphics
    • Audio effects
  • Snake - An arcade game in which the player navigates a long chain of symbols across the screen and scores by collecting numbers. Numbers add to the overall length and the speed of the snake. The player needs to avoid hitting the borders of the screen or touching the snake's body as this terminates the game.
  • Tic-Tac-Toe - The player competes with the PC to place three identical marks in a horizontal, vertical, or diagonal row on the 3x3 board.
Parent topic: Features Added in Visual COBOL 2010 R2


Snippets

This release provides new snippets for Attribute, DateTime, Implements and for static methods.

Parent topic: Features Added in Visual COBOL 2010 R2


SQL Support

The SQL technology that was present in Net Express is now seamlessly integrated within the Visual Studio 2010 development environment. When you develop COBOL SQL applications in Visual Studio, you can use the same development environment to extend and modernize your COBOL assets.

Features include:

  • OpenESQL technology that supports embedded SQL in your COBOL applications
  • OpenESQL Assistant wizard that automatically generates embedded SQL in a COBOL program template given basic database information
  • DB/2 ECM technology that uses embedded SQL to work with DB2 LUW
  • COBSQL processor that provides native DBMS SQL support for Oracle's Pro*COBOL and other vendors
Parent topic: Features Added in Visual COBOL 2010 R2


XML Parse/Generate

Visual COBOL now supports the IBM-style XML syntax and enables your applications to process XML data. Support for the XML PARSE and XML GENERATE statements is provided in the Visual COBOL compiler.

Parent topic: Features Added in Visual COBOL 2010 R2


Features Added in Visual COBOL 2010 R1

  • Visual Studio as the Core Integrated Development Environment
  • COBOL 2010
  • COBOL Language Extensions
Parent topic: New Features


Visual Studio as the Core Integrated Development Environment

The Visual Studio editor has been extended in a number of ways to enhance its support for COBOL, including Standard Visual Studio 2010 features for program navigation are exploited for COBOL applications.

  • Fully integrated COBOL development environment delivers high programmer productivity by exploiting Visual Studio tools and providing instant feedback.
  • Enhanced COBOL syntax for .NET programmers makes it easier for COBOL programmers to use .NET services or for programmers with .NET experience in other programming languages to be productive with COBOL.
  • Visual COBOL supports the development and deployment of both "managed" .NET (with multi-targeting for .NET Framework V4 and earlier versions) and "unmanaged", native code applications.
  • Visual COBOL is a part of the Visual Studio 2010 product portfolio from Micro Focus which also includes testing and developer productivity tools.
  • COBOL Margins - visual indication of COBOL margins which are sensitive to the COBOL margin directive currently selected for the program – if the setting is changed via an embedded "$SET SOURCEFORMAT" directive, then the display is immediately updated.
  • COBOL sensitivity is extended to support COBOL methods and data items in IntelliSense and preconfigured "code snippets" reduce the effort required to complete code and avoid errors being introduced.
  • Background parsing continuously ensures that the code being worked on will compile cleanly.
Parent topic: Features Added in Visual COBOL 2010 R1


COBOL 2010

Visual COBOL supports the development of both "managed" code which is fully interoperable with other .NET languages and "native code". It is built on a new Micro Focus COBOL platform "COBOL 2010".

A standalone COBOL Server is available for deploying applications developed within Visual COBOL.

Visual COBOL provides a test license version of the COBOL Server to allow system testing before deployment into production.

Parent topic: Features Added in Visual COBOL 2010 R1


COBOL Language Extensions

Historically, COBOL has been case-insensitive which makes interoperation with .NET methods more difficult than it should be. For example, method or member names had to be enclosed within quotation marks and declare synonyms to refer to external types. With Visual COBOL these restrictions have been removed and the code is more “.NET-like” while still retaining COBOL’s traditional ease of understanding. Unnecessary COBOL elements such as “repository” have been made optional which greatly reduces the size and complexity of a COBOL .NET program. The language changes improve readability and simplify the learning process for existing C# or VB programmers who can easily work on the COBOL code. With this flexibility, teams can be more agile and thus reduce development and maintenance costs.

Parent topic: Features Added in Visual COBOL 2010 R1


Tutorials on COBOL in the Visual Studio IDE

There are a number of tutorials that guide you through creating COBOL applications of various sorts using the Visual Studio IDE. The source files for the tutorials are installed in subfolders of the %PUBLIC%\Documents\Micro Focus\Visual COBOL\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\<product name>\Samples.

The following tutorials are available:

Tutorials on Native COBOL

Tutorial | Shows you how to
Tutorial: Developing and Debugging a Native COBOL Application | Create a native COBOL application and debug using various debugging features.
Tutorial: Debugging COBOL Applications Remotely | Edit and compile a native COBOL application locally. Copy the application files to a remote Windows machine, prepare for debugging and debug the application remotely.

Tutorials on Managed COBOL

Tutorial | Shows you how to
Tutorial: Developing .NET Managed COBOL | Create a simple Windows application in .NET managed COBOL. You create a Windows form that says "Hello World".
Tutorial: Creating Windows Forms in COBOL | Create a Windows form that interacts with an existing COBOL program.
Tutorial: Creating Web Forms in COBOL | Create a Web page that interacts with an existing COBOL program.
Tutorial: Developing Web Application Projects | Create a Web Application Project that interacts with an existing COBOL program
Parent topic: Welcome
Related information
Demonstrations of .NET COBOL
Demonstrations of Native COBOL
Samples Browser


Product Information

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

  • System Requirements
  • Installation Notes
  • Updates and Product Support
  • Micro Focus End User License Agreement
  • Backward Compatibility with Earlier Micro Focus Products
  • Backward Compatibility with Previous Versions of Visual Studio
  • Third Party Software
  • Known Errors and Restrictions
  • Contacting Micro Focus
Parent topic: Welcome


System Requirements

  • Hardware Requirements
  • Software Requirements
  • Operating Systems Supported
Parent topic: Product Information


Hardware Requirements

Visual COBOL has the same requirements as Microsoft Visual Studio, as well as the following. See the Visual Studio documentation for details of the Microsoft requirements.

Disk space

58 Mb for the Sentinel RMS license server

200 Mb for Micro Focus COBOL integration into Visual Studio

This disk size includes the space needed to cache information locally so that you can modify the installation without the original source media.

Parent topic: System Requirements


Software Requirements

The following functionality, tools and features have additional requirements:

Visual Studio IDE
  • Microsoft Visual Studio 2010 or Microsoft Visual Studio Shell 2010. Note that Microsoft Visual Studio Express Edition is not supported.
  • Microsoft Windows SDK is required if you are using Visual Studio Shell. See the Microsoft Download site and search for Windows SDK.
  • Microsoft .NET Framework 4.0. This is included with the above versions of Visual Studio.
Consolidated Trace Facility
The Microsoft .NET Framework 2.0 or later is required for the CTF Viewer. It is available from the Microsoft .NET downloads area.
Java Compilation
The Java Development Kit (JDK) is required for compiling Java. The JDK is downloadable from the Oracle Web site. After installing the JDK, you must put the tools.jar file for the JDK on your classpath, using a command similar to:
 set classpath=jdk-install-directory\lib\tools.jar
Windows Forms
  • Microsoft Internet Information Service (IIS) is also required for generating Windows Forms test clients.
XML Extensions
XML Extensions has the same requirements as RM/COBOL version 12 for 32-bit Windows. (See the RM/COBOL User's Guide, Second Edition or later.) Additionally, XML Extensions may be used in conjunction with Terminal Server.
Parent topic: System Requirements
Related information
Microsoft Download site


Operating Systems Supported

The following platforms are supported:

32-bit Windows Platforms
  • Windows Server 2003
  • Windows Server 2003 R2
  • Windows Server 2008
  • Windows Server 2008 SP2
  • Windows Server 2008 R2
  • Windows Vista
  • Windows XP Professional SP3 or later
  • Windows 7
64-bit Windows Platforms
  • Windows Server 2003
  • Windows Server 2008
  • Windows Server 2008 SP2
  • Windows Server 2008 R2
  • Windows Vista
  • Windows XP Professional SP2 or later
  • Windows 7
Citrix and Terminal Server
  • Windows Server 2000
  • Windows Server 2003
  • Windows Server 2003 R2
  • Windows Server 2003 - 64-bit
  • Windows Server 2008
  • Windows Server 2008 SP2
  • Windows Server 2008 R2
  • Windows 7
Parent topic: System Requirements


Installation Notes

  • Installation Restrictions and Requirements
  • Installing Visual COBOL for Visual Studio
  • Installing Silently
  • Installing with the Micro Focus Web Installer
  • Microsoft Terminal Server
  • Installing from a Server
  • Repairing
  • Uninstalling
Parent topic: Product Information


Installation Restrictions and Requirements

Note: The following information applies to Windows only.

Before starting the installation you should consider the following:

  • Visual COBOL and COBOL Server cannot co-exist on the same machine. This applies to Windows only.
  • If, when you install COBOL Server, the machine does not have Microsoft Visual C++ 2010 Redistributable Runtime already installed, it will be installed as required by COBOL Server. The installation of Microsoft Visual C++ 2008 Redistributable Runtime will add a number of .dll files, without digital signatures, into the winsxs directory.
  • If you are installing this as an upgrade, make sure that none of the product files are in use when you start the installation.
  • To install on Windows, 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: Installation Notes


Installing Visual COBOL for Visual Studio

Note:
  • This version of the product is a full install.
  • It is recommended to install this product using the Web Installer. The Web Installer helps you install any missing prerequisite software and the product on your machine.

Downloading the Product

  1. Click on the product download link in your delivery notice.

    This opens the Micro Focus Electronic Product Delivery page for your order.

  2. Before downloading your product, check the Legal Information tab and read the End User License Agreement.
  3. Check the Documentation tab and read the documentation supplied for your product.
  4. Check the respective links to download the setup file or the Web installer for your product to your machine.

Installing

To use the Web Installer:

  1. Double-click the VisualCOBOLVisualStudio20_webinstaller.exe file.
  2. Click Start in the Web Installer dialog and follow the instructions to install the prerequisite software and the product.

Alternatively, you can use the setup file on your machine and install the product as follows:

  1. Run the VisualCOBOLVisualStudio20.exe file and follow the wizard instructions to complete the installation.
Note:
  • If you are installing onto a machine that has an existing Micro Focus product that uses an older Sentinel RMS License Manager, you might be prompted to remove it and install the Micro Focus License Manager. By doing this you will maintain the existing Sentinel RMS license files while adding the Micro Focus License Manager. If you are unsure about existing licenses on your computer or removing the Sentinel RMS License Manager, consult your System Administrator. If you want to proceed, remove Sentinel RMS License Manager by using Windows Add or Remove Programs and rerun the installation file.
  • Trial licenses cannot be used with remote desktop services. If you want to use your product in this way, please contact Micro Focus SupportLine to obtain a relevant license.
  • We recommend that you install any updates for Visual Studio and the .NET Framework that are available at the Microsoft Download site.
  • If you install JDK you might be prompted to install the latest update. The latest update is not required for use with Visual COBOL but you can install it if you wish.

Installing as an Upgrade

This release does not work concurrently with earlier releases and installing it uninstalls previous versions of the product.

  • Visual COBOL and COBOL Server (or COBOL Server for Unit Testing) cannot co-exist on the same machine.
  • If you are installing this as an update to an earlier version of the product, make sure that the product is not running on your machine when you start the installation.
  • To install the product, 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.

After Installing

You are now ready to run Visual COBOL. From the Windows taskbar click Start > All Programs > Micro Focus Visual COBOL > Visual COBOL for Visual Studio 2010.

Please refer to the Start Here and Product Information sections in your product Help. Here, you will find information on getting started including tutorials and demonstration programs.

If you have problems trying to view the Micro Focus help, ensure that the Visual Studio Help Library is pointing to local help. From the Visual Studio menu click Help > Manage Help Systems > Choose online or local help and check the I want to use local help button.

Note: The first release of Visual Studio 2010 has a browser-based help system, Microsoft Help Viewer 1.0, which does not include an index for the locally-installed help. Navigation of the content is only available using the table of contents and Search and the help contents for the Help system does not expand and collapse in the same way as previous Help systems.

Visual Studio 2010 SP1 provides an upgrade of the help system, Microsoft Help Viewer 1.1, which provides a stand-alone help viewer with an index and a fully expandable table of contents.

If you do not wish to install Visual Studio 2010 SP1, you can install some third party tools that enable the index or the fully expanding table of contents. Read http://kb.microfocus.com/display/4/kb/article.aspx?aid=31484 for more.

Parent topic: Installation Notes


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.

On Windows:

To install silently use the following command:

start /wait install-file.exe /q [parameters]

where install-file for the following products is as follows:

Visual COBOL
VisualCOBOLVisualStudio20.exe

VisualCOBOLVisualStudio20.exe and COBOLServer20.exe include a number of individual .msi files, where each .msi file installs one software component. For instance, VisualCOBOLVisualStudio20.exe includes one .msi file to install Visual COBOL and another to install License Manager; running VisualCOBOLVisualStudio20.exe installs both Visual COBOL and License Manager.

You can specify different parameters for the different .msi files within the same .exe file by using the /componentargs parameter. Valid values for the /componentargs parameter are as follows:

  • License Manager
  • Visual COBOL

The examples show how to use the /componentargs parameter.

After the installation is complete you can install the license silently. You need to have your Authorization Code. To install the license execute:

start /wait <install-dir>\bin\cesadmintool –term activate AuthorizationCode

Directory Considerations (Windows)

  • You must have read and write access for every directory accessed during the install.
  • You can override the default installation folder using the INSTALLDIR parameter:
  • If a path in a definition contains spaces, then the path must be preceded by a backslash and double quotation mark (\"). For example:
    INSTALLDIR=path
INSTALLDIR=\"c:\MyProduct\"
INSTALLDIR=\"c:\Program Files\Micro Focus\My Product\"
  • Installing creates a log file in %temp%\LogFilename by default. To change the location or name, use the /l parameter on your Setup command line and specify the path and file name, for example:
    /l*v drive:\path\LogFilename

    The default names for the log files are as follows:

    VisualCOBOL_install_log.txt | for the Visual COBOL wrapper
    VisualCOBOLx??_install_log.txt | for Visual COBOL, where ?? is "86" for 32-bit systems and "64" for 64-bit systems.
    lmsetup_install_log.txt | for License Manager
    EnterpriseServerDotNet_install_log.txt | for COBOL Server for .NET
  • The log filename and folder name cannot contain spaces
  • The log file folder must exist before beginning the silent install

Examples

  • To silently install Visual COBOL into a directory other than the default:

    start /wait VisualCOBOLVisualStudio20.exe /q /componentargs "Visual COBOL:INSTALLDIR=c:\DirectoryName"

Parent topic: Installation Notes


Installing with the Micro Focus Web Installer

The Micro Focus Web Installer utility makes installing your product easy. It checks your machine for what software is already installed and then guides you through installing any missing prerequisites and the product components.

Note: The Web Installer downloads the product from the internet so an active internet connection is required.

To install this product using the Web Installer:

  1. Ensure your machine is connected to the Internet.
  2. In your product delivery notice, click on the download link that includes Web Installer.
  3. Click Run to start the installer.

    The Installer dialog box lists the prerequisites and the product components, specifying whether each one is installed or missing.

  4. Click Start and follow the instructions.
Parent topic: Installation Notes


Microsoft Terminal Server

You can use this program with Microsoft Terminal Server but note that a separate end-user license is required for each user who accesses it, even if the product is running on a single machine. See your End User License Agreement.

Microsoft Terminal Server is an environment for running multiple instances of a single user product. It is not a platform where a single-user product can be made to perform as a multi-user product.

  • To install onto a terminal server, log on to the physical terminal server with a user ID that has administrator privileges. Then use Control Panel > Add/Remove Programs and follow the instructions on the screen.
  • When you install the product on Microsoft Terminal Server or similar terminal software, do not execute more than one installation at the same time.
  • When you install Microsoft Terminal server, you must assign a unique port address to each user. Then the very first time that each user logs into Visual COBOL and starts the terminal server, he or she should:
    1. Select Options > Project > Port address for Web Server.
    2. Type in the assigned port address.

    This is necessary because the default port address for the Web server is 80. Once this has been allocated to the first user, when the next user attempts to start the Web server, the software recognizes that this port is in use and rejects the attempt. Consequently each user requires an individual port address.

Parent topic: Installation Notes


Installing from a Server

There are two methods for installing this product on users' machines using a server. You can:

  • Install onto the server. Then users run Setup to install from the server onto their own machines.
  • Copy the product onto the server and then use Setup under control of a third-party software distribution package, such as Microsoft's Systems Management Server (SMS), to install the product onto multiple users' machines.

    This method of installation and the associated file are not supported by Micro Focus. They are provided on an "as is" basis and have not been tested in any form. You can use them at your own discretion.

Both methods give you control of what options the user can install and mean you do not have to send the installation media to every user, as they install from the server instead.

Parent topic: Installation Notes


Repairing

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

To repair your installation, use Control Panel > Add/Remove Programs and follow the instructions on the screen.

Parent topic: Installation Notes


Uninstalling

Uninstalling a Micro Focus product that uses Sentinel RMS does not revoke any licenses that you have activated for that product. We recommend that before you uninstall the product, you revoke the licenses that you have activated for it.

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 Control Panel > Add/Remove Programs, on most Windows systems.
  3. Ensure that Show Updates (at the top of the Add or Remove Programs dialog) is checked, so that any hot fixes or WrapPacks are listed.
  4. Select the product.
  5. Click Remove.

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 Visual COBOL and Micro Focus License Manager. Uninstalling only Visual COBOL does not automatically uninstall the other components of the installation or any of the prerequisite software. To completely remove the product you must uninstall the Micro Focus Licensing Manager as well. Optionally, you can remove the prerequisite software.

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


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.

When you have installed, the next time you start the IDE and you open a project you are automatically prompted to apply the latest updates, if there are any. A dialog box provides a link to the Product Updates section of the Micro Focus Product Support page.

If you wish to turn off the automatic check for updates, you can do so in Tools > Options. Navigate to Projects > COBOL Project Settings and disable the checkbox under Product Updates.

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 open the Micro Focus Product Update page from the IDE:

  1. In Visual Studio, click Help > Micro Focus Product Help > Product Updates.

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 can turn on notifications about product updates in Visual Studio. To do this click Tools > Options > Projects > COBOL Project Settings. Check Notify me about updates when they become available.

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 by selecting Help > Welcome > Web Resources.

Parent topic: Product Information


Micro Focus End User License Agreement

IMPORTANT: LICENSOR IS PROVIDING THIS SOFTWARE FOR YOUR USE SUBJECT TO YOUR AGREEMENT TO BE BOUND BY THE TERMS AND CONDITIONS SET FORTH BELOW. IF YOU DO NOT AGREE TO THE TERMS OF THIS AGREEMENT BY CLICKING ON SETUP'S ACCEPT BUTTON, YOU WILL NOT BE ABLE TO USE THE SOFTWARE. BY CLICKING SETUP’S ACCEPT BUTTON YOU ACKNOWLEDGE THAT YOU HAVE READ THIS AGREEMENT, UNDERSTOOD IT, AND AGREE TO BE BOUND BY ITS TERMS AND CONDITIONS.

WHEREAS, Licensor desires to grant to Licensee, and Licensee desires to accept from Licensor, a license to use Licensed Software (as defined herein) upon the terms and conditions hereinafter set forth; NOW, THEREFORE, Licensor and Licensee agree as follows:

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

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

“Core” means a single unit of processing within a computer chip, comprising an arithmetic logic unit, registers, instruction fetcher and data fetcher/storer. “CPU” (Central Processor Unit) means a data processing unit, normally identified with a single microchip mounted on a single circuit board and can comprise several Cores. A computer “box” can contain several CPUs. The “box” is sometimes referred to as a “server” or a “machine” (or possibly a “mainframe”).

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

“Licensed Software” means the object code version of the Licensor computer programs, their accompanying user documentation (“Documentation”) and other supplemental materials as provided to Licensee by Licensor, including but not limited to any software security keys, modifications or additions relating thereto. The Licensed Software shall also include any new releases, updates, revisions, modifications, additions, corrections and fixes of the Licensed Software that Licensee receives under Sections 6 and 7 below or under maintenance for which Licensee has separately contracted and paid. From commencement of this License Agreement, the “Licensed Software” shall also include, and this License Agreement shall apply to, any prior versions of the Licensed Software licensed by Licensee. This License Agreement does not grant Licensee the right to any new releases, updates, revisions, modifications, additions, corrections and fixes of the Licensed Software unless provided by Licensor under Section 6 below. Licensed Software products are available to operate on the Windows, Linux, Unix or other computer platforms and a separate license is required for a Licensed Software product for each computer platform.

“Product Order” means a document that has been (i) executed by Licensee, describing each Licensed Software license purchased and (ii) accepted by Licensor or its authorized distributors. Licensor will accept the Product Order by either confirming Licensor’s acceptance in writing or by delivering the Licensed Software Licensee, whichever occurs first. Each Product Order shall constitute a separate agreement and shall incorporate therein all of the terms and conditions of this License Agreement. In the event of any conflict between the terms of this License Agreement and the terms of any Product Order which have been expressly accepted by a duly authorized signatory of Licensor in writing, such terms of the Product Order shall govern. In no event shall any terms and conditions of Licensee contained in a purchase order or similar document issued by Licensee in connection with this License Agreement or a Product Order apply and any such document issued shall be only for the administrative purposes of identifying the Licensed Software ordered, the number of licenses, and the price to be paid and shall have no other legal effect.

“Disaster Recovery System” is defined as a computer system that is used (i) if a disaster arises and the original production system is unavailable, (ii) for the purposes of disaster recovery testing and/or (iii) for system diagnostics or maintenance of the Disaster Recovery System itself. A Disaster Recovery System does not include any system that is in the same computer cluster as the machine on which the development or production copy of the Licensed Software is installed.

“Virtual Machine” means a software implementation that executes programs like a physical machine where the software running inside the virtual machine is limited to the resources and abstractions provided by the virtual machine.

  1. GRANT OF LICENSE. For payment of the applicable non-refundable license fees identified on the Product Order, Licensor grants solely to Licensee, as an end user, a personal, perpetual, non-transferable, non-sublicensable and non exclusive license to use the Licensed Software subject to the terms and conditions set forth in this License Agreement. Licensee shall have the right to use the Licensed Software solely for its own internal use and benefit. For the avoidance of doubt, the license granted herein does not permit (i) third party contractors (including without limitation outsourcers) to access or use the Licensed Software for Licensee’s internal use and benefit without the prior written consent of Licensor and the payment of an additional license fee, (ii) the public to access or use the Licensed Software (including without limitation, via the internet) except as specifically provided in Annex 1 hereunder, and/or (iii) installation, use or access of the Licensed Software on, in, or from a Virtual Machine except as specifically provided in Annex 1 or Annex 2 hereunder. Where permitted by Licensor pursuant to sections 1(i) and (ii) hereof, Licensee shall be liable to Licensor in respect of any breach of this License Agreement resulting from any access or use by third party contractors and/or the public. Access and/or use of data, results and/or output obtained and/or generated, either directly or indirectly, through the use of any Licensed Software are deemed to be access and/or use of such Licensed Software and such data, results and/or output shall be subject to the licensing terms and restrictions applicable to such Licensed Software. Different license options are available from Licensor as set forth or referred to in Annex 1 (“License Option(s)”), although not all License Options are available for each specific Licensed Software product. The applicable License Option to be purchased by Licensee for the Licensed Software shall be identified in the Product Order. Additional License Options (as appropriate) are required to be purchased by Licensee for use of the Licensed Software on a Disaster Recovery System or for load-balancing, fail-over, training, or testing purposes. Licensed Software purchased for testing purposes will be subject to the Test License Option terms and restrictions set forth in Annex 1.E. Certain Licensed Software may also be subject to additional terms and conditions as set forth in the “Specific Software Terms” located in Annex 2. The Specific Software Terms will prevail in the event of any conflict.
  2. USER RESTRICTION. Licensee agrees not to:
    1. Copy and distribute the Licensed Software, in whole or in part, for internal use without paying Licensor the applicable additional fees, except (i) for making a reasonable number of archival back-up copies; or (ii) as expressly authorized by Licensor in writing; or (iii) for making a reasonable number of copies of the Documentation supplied to Licensee by Licensor in electronic form. Licensee shall reproduce and affix all copyright and other proprietary rights notices appearing in or on the Licensed Software, including the notices of all third party suppliers and all those included in any Third Party Software, as defined below in all such copies thereof.
    2. Copy and/or distribute the Licensed Software, in whole or in part, to third parties without first entering into a separate distribution license agreement with Licensor or permit use or access to all or part of the Licensed Software to any third party except as specifically provided in Annex 1 hereunder. For the avoidance of doubt, third party(ies) include without limitation contractors, outsourcers, Licensee’s customers and the public.
    3. Transfer, ship or use the Licensed Software outside the continent in which it was originally licensed to Licensee, except as otherwise specified in Annex 1 and/or Annex 2.
    4. Install, access or use the Licensed Software on an operating system other than the operating system for which the Licensed Software was originally licensed to Licensee, except as otherwise specified in Annex 1 and/or Annex 2.
    5. Assign, sell, rent, lease, lend, sublicense, outsource or otherwise transfer the Licensed Software to any third party, or authorize or appoint any third party to do so.
    6. Use the Licensed Software for timesharing, facilities management, outsourcing, hosting, service bureau use, other data processing services to third parties or like purposes.
    7. Modify the Licensed Software or provide any person with the means to do the same.
    8. Create derivative works, translate, disassemble, recompile or reverse engineer any Licensed Software or attempt to do so (except to the extent applicable law specifically permits such activity).
    9. Alter, destroy, or otherwise remove any proprietary notices or labels on or embedded within the Licensed Software or Documentation.
    10. Utilize for itself, or permit any third party to utilize, any software application program created, in whole or in part, utilizing any Licensed Software without a valid and properly granted Deployment Product License.
    11. Use the Licensed Software in a manner other than as specifically permitted in this License Agreement.
  3. AUDITS. Licensee agrees to (i) keep records of and provide the location, model and serial number of any and all machines on which the Licensed Software is installed or from which the Licensed Software is accessed, and the names of and how many users are accessing the Licensed Software, (ii) implement a reasonable mechanism or process to ensure that Licensee’s use of the Licensed Software does not exceed the number of licenses granted, (iii) take all necessary steps to destroy or erase all Licensed Software codes, programs and other proprietary information before disposing of any media containing the Licensed Software, and (iv) promptly provide written notice to Licensor if Licensee’s usage exceeds the license granted. Upon Licensor’s reasonable request, but not more frequently than annually without reasonable cause, Licensee shall furnish Licensor with a statement signed by a director and/or auditor, as required by Licensor, verifying the above and shall permit Licensor to audit the use of the Licensed Software at such times as may be mutually agreed upon. In the event Licensee’s usage exceeds the license granted, without prejudice to any other rights or remedies Licensor may have, including without limitation injunctive relief, Licensee agrees to pay Licensor the then current license and maintenance fees for the use of the additional licenses. Further, if such usage exceeds the license granted by more than five percent (5%), Licensee shall also reimburse Licensor for the reasonable cost of such audit in addition to other amounts due.
  4. DOCUMENTATION. One (1) electronic copy of Licensor’s standard Documentation, describing Licensor’s recommended use and application of the Licensed Software, will be furnished free of additional charge to Licensee by Licensor with the Licensed Software. Printed copies of any documentation may be available for purchase from Licensor or its authorized distributors.
  5. TERM OF LICENSE. This License Agreement and Licensee’s license for the Licensed Software is perpetual, unless a subscription/term license has been purchased by Licensee, and is subject to earlier termination as provided in this Section 5. Licensor may terminate this License Agreement and Licensee’s license to the Licensed Software immediately by giving Licensee written notice of termination in the event that either (i) Licensee breaches any term or condition of this License Agreement and Licensee has failed to remedy such breach within ten (10) days of the date of notice from Licensor to Licensee or (ii) Licensee is wound up, has a receiver appointed or enters into liquidation or bankruptcy or analogous process or processes in Licensee’s home country. Termination shall be without prejudice to any other rights or remedies Licensor may have. Licensee may at any time terminate this License Agreement voluntarily by giving written notice of termination to Licensor. In the event of any termination Licensee will have no right to keep or use the Licensed Software or any copy of the Licensed Software for any purpose and Licensee shall destroy and erase all copies of such Licensed Software in its possession or control, and forward written certification to Licensor that all such copies of Licensed Software have been destroyed or erased.
  6. MAINTENANCE. Where Licensee purchases maintenance services, Licensee’s initial maintenance term will begin upon delivery to Licensee of the Licensed Software and continue for one (1) year thereafter unless otherwise specified in the applicable annual maintenance agreement or in the Product Order, or earlier if the license is terminated. Where Licensee purchases maintenance for any Licensed Software product licensed hereunder, Licensee hereby agrees that it shall purchase such support services for all of Licensee’s licensed copies of such Licensed Software product on the relevant computer platform. Maintenance services provided by Licensor will be subject to Licensor’s then current applicable annual maintenance agreement unless otherwise agreed by the parties in writing.
  7. LIMITED WARRANTY. Licensor warrants for a period of ninety (90) days from delivery to Licensee (“Warranty Period”) (i) that the media on which the Licensed Software is supplied is free from defects in materials or workmanship under normal use and (ii) that the copy of the Licensed Software delivered to Licensee conforms in all material respects to the Documentation. As the sole and exclusive remedy for not meeting part (i) of the above warranty, Licensor’s sole obligation shall be to repair or replace free of charge any defective media on which the Licensed Software is delivered if the media is returned to Licensor by Licensee during the Warranty Period. As the sole and exclusive remedy for not meeting part (ii) of the above warranty, Licensor shall repair or replace the Licensed Software free of charge or if Licensor reasonably determines that such remedy is not economically or technically feasible, Licensee shall be entitled to a full refund of the license fee and any maintenance fee paid by Licensee with respect to that particular Licensed Software and Licensee’s license to use such Licensed Software will terminate. The warranty set forth in this Section 7 shall not apply if the defect in the Licensed Software is the result of: (a) the Licensed Software not being used in accordance with the Documentation, this License Agreement or with the platform(s) for which the Licensed Software has been designed and licensed by Licensor; or (b) the Licensed Software having been altered, modified or converted by Licensee or any third party except as may be specified in the Documentation; or (c) the malfunctioning of Licensee’s equipment; or (d) accident or abuse; or (e) service by any unauthorized person; or (f) other software used by Licensee which has not been provided by Licensor or for which the Licensed Software is not designed and licensed for operation; or (g) Third Party Software, as defined below; or (h) any other cause occurring after initial delivery of the media to Licensee unless caused directly by Licensor. The foregoing states the complete and entire remedies that Licensee has under this warranty. Licensor shall have no responsibility for any warranty claims made outside of the Warranty Period.
  8. DISCLAIMER OF WARRANTY. The Licensed Software cannot be tested in every possible operating environment, therefore Licensor does not warrant that the functions contained in the Licensed Software will meet Licensee’s requirements, that operation of the Licensed Software will be uninterrupted, or that the Licensed Software is error free. EXCEPT AS SET FORTH HEREIN AND TO THE EXTENT PERMITTED BY LAW, ALL OTHER WARRANTIES, EXPRESSED OR IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, QUALITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXCLUDED ON THE PART OF LICENSOR AND ITS THIRD-PARTY SUPPLIERS. Licensee acknowledges that Licensee is responsible for the selection of the Licensed Software to achieve Licensee’s intended results and for the installation of, use of and results obtained from the Licensed Software.
  9. LIMITATION OF LIABILITY. ANY LIABILITY OF LICENSOR SHALL BE LIMITED IN THE AGGREGATE TO THE AMOUNTS PAID BY LICENSEE FOR THE LICENSED SOFTWARE. THIS LIMITATION APPLIES TO ALL CAUSES OF ACTION, INCLUDING WITHOUT LIMITATION BREACH OF CONTRACT, BREACH OF WARRANTY, NEGLIGENCE, STRICT LIABILITY, MISREPRESENTATION AND OTHER TORTS. THE LIMITATIONS OF LIABILITY DESCRIBED IN THIS SECTION 9 ALSO APPLY TO LICENSOR’S THIRD-PARTY SUPPLIERS. LICENSOR’S AND ITS THIRD-PARTY SUPPLIERS’ LIMITATIONS OF LIABILITY ARE NOT CUMULATIVE. Licensee’s remedies in this License Agreement are Licensee’s exclusive remedies.

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

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

  10. HIGH-RISK USES. The Licensed Software is not fault tolerant, nor designed, manufactured or intended for use in hazardous environments requiring fail-safe performance (including, without limitation, the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life support machines, or weapons systems) in which failure of the Licensed Software could lead directly or indirectly to death, personal injury or severe physical or environmental damage. Licensor and its suppliers specifically disclaim any express or implied warranty of fitness for a particular purpose and shall have no liability for any use of the Licensed Software in any high-risk situations.
  11. OWNERSHIP. Licensor (or its affiliates) and where applicable Licensor’s third party suppliers have and will retain all ownership rights to the Licensed Software, together with any complete or partial copies thereof. Such ownership rights include without limitation all patent rights, copyrights, trademarks, trade secrets, service marks, related goodwill, and confidential and proprietary information relating thereto. This License Agreement does not convey any proprietary interest to Licensee with respect to the Licensed Software other than the license specified herein. Where the Licensed Software provided under this License Agreement contains or is derived from portions of materials provided by a third-party supplier under license to Licensor, Licensor has assumed responsibility for the selection of such materials and their use in producing the Licensed Software and any such third-party suppliers are intended beneficiaries of this License Agreement.
  12. NOTICE TO U.S. GOVERNMENT END USERS. The Licensed Software is provided to the United States Government with RESTRICTED RIGHTS and its supporting documentation is provided with LIMITED RIGHTS. Use, duplication, or disclosure by the United States Government is subject to the restrictions as set forth in FAR52.227-14 and DFAR252.227-7013 et seq. or the successor as appropriate. Manufacturer is Micro Focus (US), Inc., 9420 Key West Drive, Rockville, MD 20850 as or on behalf of Licensor.
  13. LICENSE FEES, PAYMENT, AND TERMS. Licensee agrees to pay the applicable end user license fees for the Licensed Software within thirty (30) days of the date of invoice or such earlier date as is specified in the Product Order. End user license fees are non-refundable except as provided in Section 7 above, or in the Specific Software Terms below, and shall be paid without deduction, including without limitation, of any withholding tax. End user license fees are exclusive of any applicable transportation charges, value added and other applicable taxes and duties and all such amounts shall be paid or reimbursed by Licensee. Late payments shall accrue interest at the rate of 1.5% per month compounded or, if lower, the maximum rate allowed by law.
  14. RELATED SERVICES. Licensee shall be responsible for obtaining and installing all proper hardware and support software (including operating systems) and for proper installation and implementation of and training concerning the Licensed Software. In the event that Licensee retains Licensor to perform any services with respect to the Licensed Software (for example: installation, implementation, maintenance, consulting and/or training services), Licensee and Licensor agree that such services shall be subject to Licensor’s then current standard terms, conditions and rates for such services unless otherwise agreed in writing by Licensor.
  15. THIRD PARTY SOFTWARE AND COMPONENTS. The Licensed Software may contain certain named third party software programs that Licensee shall license directly from the third party subject to such third party’s terms and conditions (for example Adobe Acrobat or Microsoft Internet Explorer) (“Third Party Software”). All Third Party Software is provided by the licensor of the Third Party Software and solely under such third party’s terms and conditions and not by Licensor. Therefore the obligations, duties and rights of Licensor and Licensee under this License Agreement do not apply to such Third Party Software. Additionally, Licensor has embedded certain run time or other elements provided by third party suppliers to Licensor (“Third Party Components”). Such Third Party Components may also be loaded on the Licensed Software media. Third Party Components are licensed to Licensee pursuant to this License Agreement. Licensee may only access Third Party Components of the Licensed Software in the course of using the Licensed Software. Licensee may not make or attempt any direct access to any such Third Party Components other than with the Licensed Software. The Third-Party Software is the property of its respective third party supplier to Licensor. Such third party suppliers own all copies of the Third-Party Software, however made. Licensee agrees not to contest the ownership of the Third Party Components nor use any trademark or service mark belonging to such third party suppliers. All limitations, restrictions and obligations applicable to the Licensed Software set forth in this License Agreement shall apply to Licensee’s use of the Third Party Components. Licensee agrees that such third party suppliers are intended third party beneficiaries of all terms and conditions of this License Agreement intended to protect intellectual property rights in the Licensed Software (including the Third Party Components) and limit certain uses thereof.
  16. PRIVACY. The Licensed Software may contain features which may allow Licensee to collect data from, control and/or monitor computers running the Licensed Software deployed by Licensee without notice to or knowledge by users of the Licensed Software. Licensee is solely responsible for, and assumes all liability with respect to, the collection of data with respect to its users of the Licensed Software including, without limitation, notifying such users and complying with all data collection, privacy and other regulations, laws, industry standards and rights of others applicable to any such activity. Licensee shall indemnify and hold Licensor harmless from and against any damages, claims, losses, settlements, attorneys' fees, legal fees and court costs and other expenses related to any such activities or any claims in connection therewith. To the extent permitted by law, by entering into this License Agreement, Licensee hereby expressly consents to (i) Licensor sending information to Licensee from time to time advertising the various products that Licensor provides, whether or not such products are provided under this License Agreement; (ii) the use of Licensee’s name in Licensor customer lists, promotional materials and/or press releases; and (iii) the collection and use by Licensor of information about the computer system on which the Licensed Software is installed (e.g. product version, serial number) for internal security and licensing purposes; Licensor does not use this information to identify individuals utilizing such software.
  17. MISCELLANEOUS. Licensor may assign this License Agreement to any member of Licensor’s group of companies or to a purchaser of the intellectual property rights in the Licensed Software, but otherwise neither this License Agreement nor any rights hereunder may be assigned (any change of control merger, sale or other transfer of all, or substantially all, of the assets of Licensee shall be included in the meaning of an assignment) nor duties delegated by either party, and any attempt to do so will be void. If Licensee acquires the Licensed Software in North America, the laws of the state of Maryland govern this License Agreement and it shall be subject to the exclusive jurisdiction of the courts of the State of Maryland. If Licensee acquires the Licensed Software in France, Germany or Japan, this License Agreement is governed by the laws of the country in which Licensee acquired the Licensed Software. In the rest of the world the laws of England govern this License Agreement. The aforesaid applicable law shall apply without regard to conflicts of laws provisions thereof, and without regard to the United Nations Convention on the International Sale of Goods. Other than for North American transactions, this License Agreement shall be subject to the exclusive jurisdiction of the courts of the country determining the applicable law as aforesaid. This License Agreement is in addition expressly made subject to any United States, United Kingdom or European Union laws, regulations and other restrictions regarding export or re-export of computer software and technology. Licensee agrees not to export or re-export any Licensed Software or derivative thereof in contradiction to any such applicable restriction. Except for the Product Order, this License Agreement is the complete and exclusive statement of agreement between the parties relating to the license for the Licensed Software and supersedes all proposals, communications, purchase orders, and prior agreements, verbal or written, including without limitation prior end user license agreements in relation to the Licensed Software between the parties and end user license agreements embedded in such Licensed Software. Upon Licensee’s properly authorized installation of any update and/or upgrade of any Licensed Software licensed hereunder, the license granted to such prior version and/or release shall terminate after a ninety (90) day transition period from such installation and only the license to such updated and/or upgraded Licensed Software shall continue. No employee, agent, or representative of Licensor has the authority to bind Licensor to any oral representation or warranty concerning the Licensed Software. No representation or statement not expressly contained in this License Agreement nor any supplement, modification, or amendment of this License Agreement will be binding on either party unless executed in writing by a duly authorized representative of each party to this License Agreement.

ANNEX 1

A. LICENSE OPTIONS FOR THE FOLLOWING SOFTWARE PRODUCTS:

All Micro Focus Application Development and Application Deployment products, including Net Express®, Net Express® with .NET, Net Express® for Eclipse, Server Express™, Server Express™ for Eclipse, Micro Focus Studio™ Enterprise Edition, Micro Focus Studio™ for COBOL Developers, Micro Focus Studio™ for ISVs, SOA Express, Micro Focus Server™ Enterprise Edition, Micro Focus Server ™ for COBOL, Micro Focus Server™ for .NET, Micro Focus Server ™ for SOA, Extend®, Relativity®, RM/COBOL®, Open PL/I, Open PL/I SQL, Open PL/I Run Time, ReUzeDeveloper, ReUze Server, XDBC, Database Connectors and Xcentrisity® including portions thereof, other products within the same product families and other Software Products where indicated by Licensor.

  1. Development License Options
    1. Named User License. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on either (i) a single machine which may be accessed by the named end users for those licenses or (ii) on a single host machine or server (“Host Server”) which may be accessed by any of the named end users licensed. A Named User License means that only one named person can use each license and that named person has the right to unlimited access to the Licensed Software. A Named User License is not based on concurrent users, but instead on an actual named user basis. Licensor reserves the right at any time to require Licensee to provide a list of the named end users. Licensee may change a named end user provided that the change is made either permanently away from the named end user or temporarily to accommodate the use of the Licensed Software by a temporary worker while the named end user is absent, but in no event more than once every 30 days.
    2. Lines of Code License. Licensed Software provided under the Lines of Code license option requires, as a condition of use, that Licensee use a usage counter containing a credit for the number of lines of code that Licensee has purchased (“Usage Counter”). Licensee shall have sole responsibility for installing, configuring, and administering the Usage Counter. The Usage Counter will allow Licensee to create metering control files in order to track the number of lines of code which Licensee has purchased and which Licensee accesses. Licensee hereby acknowledges and agrees that unless Licensee can demonstrate to Licensor’s satisfaction that the Usage Counter was faulty on delivery to Licensee, Licensee is solely responsible for any lost, damaged, corrupted, destroyed, inaccurate or improperly used metering control files or metering transaction files, and in any such circumstance, may be required to pay an additional license fee on a line of code basis for lines of code which may have been already accessed and recorded using the Usage Counter. Each line of code which Licensee has accessed using the Licensed Software and which has been properly recorded using the Usage Counter may be re-accessed without the need to pay an additional license fee. However, if Licensee creates an additional line of code by updating a line of code source member which has already been accessed and metered by the Licensed Software, then Licensee will need to pay an additional license fee to access such additional line of code using the Licensed Software. Upon exhaustion of prepaid license fees, however, Licensee must purchase more lines of code in order to continue to use the Licensed Software on lines of code not yet accessed by the Licensed Software and properly recorded using the Usage Counter. Any prepaid license fees are non-cancellable and non-refundable.
  2. Deployment License Options
    1. User License for Authorized Users. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on unlimited Host Servers for use by the total number of named individuals for whom Licensee has paid the applicable license fee. The Licensed Software may not be used or accessed by (a) individuals who are not named individuals; or (b) any other software or hardware device that does not require a named individual to use or access it. A named individual means an individual identified by Licensee by name who is authorized to use any device or other software program that may access the Licensed Software, either directly or indirectly through any other software program, regardless of how such access occurs or if such individual uses any hardware or software that reduces the apparent number of users who are using the Licensed Software, such as by using a terminal service. The Licensed Software may not be used or accessed by any other software or hardware device that does not require an individual to use or access it including, without limitation, batch processing (as defined in subsection (b)(ii) below). Licensor reserves the right at any time to require Licensee to provide a list of the named individual(s). Licensee may change a named individual provided that the change is made either permanently away from the named individual or temporarily to accommodate the use of the Licensed Software by a temporary worker while the named individual is absent, but in no event more than once every 30 days.
    2. Server License. There are two options for server-based licenses.
      1. Server License for Concurrent Users. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on the designated Host Server specified in the Product Order for use by the maximum number of Concurrent Users for whom Licensee has paid the applicable license fee. Concurrent Users are individuals who are actively using any device or other software program that may access the Licensed Software either directly, or indirectly through any other software program, regardless of how such access occurs or if such user uses any hardware or software that reduces the apparent number of users who are using the Licensed Software, such as by using a terminal service. The Licensed Software may not be used or accessed by any other software or hardware device that does not require an individual to use or access it including, without limitation, batch processing (as defined in subsection (b)(ii) below). Licensee may change the designated Host Server to an equivalent Host Server for which Licensee has paid the applicable license fee. Licensee may only use the Licensed Software on or access the Licensed Software from one Host Server at any one time. Subject to the prior written consent of Licensor and to payment of additional license fees, Licensee may permit the public and/or Licensee’ customers to access and use the Licensed Software via the internet and/or Licensee’ terminals in connection with Licensee’ internal business purposes (for example to access internet banking from Licensee) but not for the public’ and/or Licensee’ customers’ own internal use.
      2. Server License for CPUs. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on the designated Host Server specified in the Product Order and have the Licensed Software executed by up to the total number of Cores and other processing devices within such Host Server. The Host Server comprises the entire computer system (i.e. combined hardware) that will be running the Licensed Software (e.g. all CPUs, Cores, Blades and other processing devices running an operating system compatible with that which the Licensed Software is designed for and which are contained in, and/or can be accessed by, the same computer system, even if one or more of such CPUs, Cores, Blades or other processing devices are not accessing or running the Licensed Software). Each Core or other processing device on a multi-core or multi-processing device requires its own CPU license. For example a dual core single CPU Host Server will require a 2 CPU license (in the absence of any Blades or other processing devices). The Licensed Software is for use by an unlimited number of Licensee’s internal users, other software devices and hardware devices. A Server License for CPU is the only license authorized for use or access by Licensee for any batch processing. Batch processing is defined as the execution of one or more task, transaction or program by a computer system without the interaction of the end user with the Licensed Software while such tasks, transactions or programs are being executed by the system. Batch processing includes situations where a queue of jobs is processed as resources become available and is in contrast to transaction or interactive processing. Licensor reserves the right at any time to require Licensee to provide a specification of the Host Server. Licensee may change the designated Host Server provided that the total number of CPU and Core licenses required in the new Host Server does not exceed the total number of CPU and Core licenses designated in the Product Order. Licensee may only use or access the Licensed Software from one Host Server at any one time. Licensee is required to purchase a license for each Host Server that accesses or uses the Licensed Software either directly or indirectly through any other software program, regardless of how such access occurs, or if the Host Server, CPU or operator uses any hardware or software that reduces the apparent number of CPU, Cores, blades or other processing devices that are using the Licensed Software, such as by using a terminal service. Subject to the prior written consent of Licensor and to payment of additional license fees, Licensee may permit the public and/or Licensee’ customers to access and use the Licensed Software via the internet and/or Licensee’ terminals in connection with Licensee’ internal business purposes (for example to access internet banking from Licensee) but not for the public’ and/or Licensee’ customers’ own internal use.
  3. reUZE Mainframe Migration Licensing. Micro Focus reUZE software products may be licensed for installation and use solely with computer environments which meet the following criteria, provided Licensee complies with the restrictions set forth in this Subsection 3 in addition to those contained in the License Agreement. The licensing model in this Subsection 3 is only applicable to the reUZE software products and is not available for licensees who exceed one or more of the following limitations: (i) Mainframe Size Limitation: The Micro Focus reUZE software is expressly limited for use where Licensee’s entire mainframe estate (the “Licensee Mainframe System”) does not exceed a collective performance speed of 50 MIPS (million instructions per second). The Licensee Mainframe System shall include all mainframe systems owned, leased and/or operated (either by Licensee or a third party) by, or for the benefit of, Licensee (including but not limited to the system environment which the applicable application is being migrated from). The collective performance speed benchmark test shall be a collective measurement of the total possible performance of all such mainframe system(s). In the event that the Licensee Mainframe System exceeds a collective performance speed greater than 50 MIPS, Licensee shall not be permitted to utilize the reUZE software product and must contact Licensor for proper licensing of its computer system(s); (ii) CPU and Core Requirements: Notwithstanding Subsection 2(b)(ii) of this Annex 1A, a Deployment Product License option for a Server license for CPU shall be limited by the number of CPUs instead of the combination of Cores, Blades, CPUs and other processing devices; and (iii) Application Limitation: The reUZE software is expressly limited for use by Licensee solely with a specific application(s). Such application(s) shall be designated in writing in the Product Order.

B. LICENSE OPTIONS FOR THE FOLLOWING SOFTWARE PRODUCTS:

OnWeb™, RUMBA™, ViewNow™, Modernization Workbench™, Analyzer Express™, Analyzer Architect ™, Business Rule Manager ™, Enterprise View Express ™, Data Express™, Mainframe Express Enterprise Edition Data Express™, Modernisation Workbench Data Express®, OPTIMAL TRACE®, QACENTER®, QADIRECTOR®, QALOAD®, QARUN®, RECONCILE®, TESTPARTNER®, TRACKRECORD®, CARS®, TEST FACTORY™, DEVPARTNER® including portions thereof, other products within the same product families and other Software Products where indicated by Licensor.

  1. Workstation License Licensed Software provided under this License Option gives Licensee the right to install and use one copy of the Licensed Software on one stand-alone workstation. Licensee may not (i) install the Licensed Software on any networked workstation (e.g., a server) that allows more than one user to use a copy of the Licensed Software, or (ii) use the Licensed Software other than on one stand-alone workstation at a time. Licensee may transfer the Licensed Software to another stand-alone workstation and reactivate it for use on such other stand-alone workstation provided that the Licensed Software is removed and all copies of it are deleted from the stand-alone workstation from which it is transferred. Such transfers may not be undertaken more often than once every 30 days.
  2. Named User License Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on either (i) a single machine which may be accessed by the named end users for those licenses or (ii) on one or more host machines or servers which may be accessed by any of the named end users licensed. A Named User License means that only one named person can use each license and that named person has the right to unlimited access to the Licensed Software. A Named User License is not based on concurrent users, but instead on an actual named user basis. Licensor reserves the right at any time to require Licensee to provide a list of the named end users. Licensee may change a named end user provided that the change is made either permanently away from the named end user or temporarily to accommodate the use of the Licensed Software by a temporary worker while the named end user is absent, but in no event more than once every 30 days.
  3. Volume of Data Licensed Software provided under this option gives Licensee the right to utilize the Licensed Software with the volume of data (the number of terabytes) identified in the Product Order for each of the applicable modules or extensions licensed with the Licensed Software. Volume of data is measured as the original volume of Licensee’ production data to be processed utilizing the Licensed Software before any data reduction process by the Licensed Software or otherwise has been applied. The same data source (defined as a database table or a file) and data may be processed multiple times without counting it more than once towards the total volume of data processed by the Licensed Software, however any additional data and/or data sources (that is, new or increased amounts to the original data source) are counted cumulatively towards such total volume of data number.
  4. Concurrent User License Licensed Software provided under this License Option gives Licensee the right to install and use one copy of the Licensed Software on the designated Host Server (as defined above) specified in the Product Order for use by the maximum number of Concurrent Users (defined above) for whom Licensee has paid the applicable license fee. Licensee may connect any number of workstations to the Host Server; however, the total number of users who may access and use the Licensed Software at any given time is limited by the number of Concurrent Users expressly authorized by Licensor in the Product Order. The total number of Concurrent Users is one (1), unless Licensor expressly authorized Licensee to connect more than one Concurrent User.
  5. Concurrent Users with Load Sharing Configuration Licensed Software provided under this License Option gives Licensee the right to install and use one copy of the Licensed Software on each server supported by a single load sharing device. Licensee may connect any number of workstations to the load sharing device and its connected servers; however, the total number of users who may access and use the Licensed Software at any given time is limited by the number of Concurrent Users expressly authorized by Licensor in the Product Order. The total number of Concurrent Users is one (1), unless Licensor expressly authorized Licensee to connect more than one Concurrent User.
  6. Server Based Thin Client License Licensed Software provided under this License Option gives Licensee the right to install and use one copy of the server portion of the Licensed Software on one server. If installation of the server portion of the Licensed Software requires a thin client component to be installed, Licensee may install and use one copy of the thin client portion of the Licensed Software on one workstation per each thin client license that is specified in the Product Order and for which Licensee has paid the applicable license fee.
  7. Processor Capacity License Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on up to the total number of Cores and other processing devices within each CPU on the designated Host Server specified in the Product Order. Licensee may install an unlimited number of copies of the Licensed Software on single-user computers to allow communication with the designated single Host Server. Licensee may not reinstall or operate the Licensed Software on multiple host processors without Licensor’s prior written consent and payment of all applicable fees.

C. LICENSE OPTIONS FOR THE FOLLOWING SOFTWARE PRODUCTS:

CaliberRM™, TeamDefine™, Together®, StarTeam®, Tempo™, TeamDemand®, TeamFocus™, TeamAnalytics®, TeamInspector™, SilkCentral®, Test Manager™, SilkTest®, Silk4J™, SilkPerformer® including portions thereof, other products within the same product families and other Software Products where indicated by Licensor.

Regardless of the type of license, each copy of the Licensed Software contains (i) software that provides services on a computer called a server (“Server Software”) and (ii) software that allows a computer or workstation to access or utilize the services provided by the Server Software (“Client Software”). For any type of license acquired, Licensee may install one copy of the Server Software on a single computer (the computer running the Server Software shall be referred to as the “Server”). The number of Client Software copies that may be installed is determined by the type of license acquired as set forth below.

  1. Named User A Named User license means Licensee may allow only one (1) designated person in Licensee’s organization (“Named User”) to use the Licensed Software per Named User license purchased (each, a “Named User License”). The foregoing Named User Licenses shall be for access and use, only by the equivalent number of Named Users licenses purchased. For each Named User, Licensee may install the Client Software on up to five (5) computers provided that the Named User is the only individual permitted to use the Licensed Software.
  2. Concurrent User A Concurrent User License means Licensee may install the Client Software on a reasonable number of computers or machines, provided that the Licensed Software is used only by as many concurrent users at any given moment in time as Licensee has purchased concurrent licenses and provided further that Licensee’s use of the Licensed Software (both Client Software and Server Software) is only on computers or machines located in the Territory and accessed only by users physically located in the Territory. The foregoing license shall be for access and use, only by the equivalent number of concurrent users for whom Licensee has paid the applicable license fees. As used in this Section, use or in use means that the Licensed Software is "in use" on a computer or machine when it is loaded into random access memory (RAM) of that computer and “access” means the ability to use, copy or operate the Licensed Software . The Licensed Software may not be shared or used concurrently on computers or machines located outside of the Territory or in such a way to enable use or access by users located outside the Territory. ‘Territory’ means the geographical area in which the Licensed Software may be used. The use in the Territory shall be subject to applicable export restrictions. Territory may be any one, and only one, of the following three geographic areas: Americas Territory, EMEA Territory or AsiaPac Territory each as defined below. The Territory shall be based on the primary business location of the Licensor, unless otherwise specified in a Product Order. The geographic Territories are: (i) ‘Americas Territory’ including and limited to those geographical areas found within the boundaries of North and South America. (ii) ‘Europe, Middle East and Africa Territory’ or ‘EMEA Territory’ including and limited to those geographical areas found within the boundaries of Europe, Middle East and Africa, including all the countries which are part of the European Union, Switzerland, Norway, Jersey, Guernsey, Isle of Man, Iceland, Monaco, Andorra, Liechtenstein, San Marino, Albania, all the countries of the former Yugoslavia, Israel, Turkey, countries of the Arab Middle East, all the countries of the former Soviet Union, Africa, Madagascar, and the Islands of the South Indian Ocean. (iii) ‘Asia Pacific Territory’ or ‘AsiaPac Territory’ including and limited to those geographical areas found within the boundaries of Asia and Australia/Pacific including South Korea, Japan, China, Taiwan, Hong Kong, and Macau India, Maldives, Pakistan, Myanmar, Nepal, Bhutan, Bangladesh, Thailand, Laos, Cambodia, Vietnam, Singapore, Malaysia, Indonesia, East Timor, the Philippines, Brunei, Papua New Guinea, the Pacific Ocean Islands, Australia, and New Zealand.
  3. Virtual User (SilkPerformer only) A "Virtual User" represents a simulation of a particular individual user executing a transaction or sequence of operations. Virtual Users are further qualified by class, and may be licensed on either a Node-Locked or Concurrent User basis. If a Virtual User is licensed on a Node-Locked basis (as provided below) (“Node-Locked Virtual User License”), that Virtual User may be associated with a Multi-Machine Controller (“MMC”) component of the Licensed Software only on the particular system for which the Virtual User is licensed. If a Virtual User is licensed on a Concurrent User basis (as provided below) (“Concurrent Virtual User License”), then that Virtual User may be associated with any licensed instantiation of a MMC at any one time, but during the operation of that instantiation, may not be associated with any other instantiation of a MMC at the same time. By way of example; if 50 Virtual Users are licensed on a Concurrent User basis, Licensee may simultaneously associate all 50 with one MMC instantiation; or simultaneously may associate 20 with one MMC instantiation and 30 with a second MMC instantiation; but could not, for example, simultaneously associate 30 with each of the two MMC instantiations. A "Web Virtual User" is a Virtual User limited to performing actions in basic web-based applications making use of the common web protocols set forth in the accompanying release notes. A "Standard Virtual User" is a Virtual User that has all of the rights of a Web Virtual User, and that may additionally make use of certain client-server, database and other protocols as set forth in the accompanying release notes. A "Premium Virtual User" is a Virtual User that has all of the rights of a Standard Virtual User, and that may additionally make use of certain protocols for packaged third-party applications and complex enterprise technologies as set forth in the accompanying release notes. Node-Locked Virtual User Licenses and Concurrent Virtual User Licenses are available for the MMC or Service Analysis Module (“SAM”) component of the Licensed Software. A Node Locked Virtual User License means Licensee may use the Licensed Software in object code form on a production basis on one (1) computer and to permit the Licensed Software to be used and accessed at any one time by no more than the number of users indicated in the applicable Product Order (each a "Node Locked User"). If no number is indicated, the number shall be 1. A Concurrent Virtual User License means the same as the Concurrent User license option above.

Notes (i) Multiplexing software: The use of one or more external tools, including multiplexors or replicators, to reduce the number of users directly connected to the Licensed Software shall not exempt Licensee from acquiring licenses for all users. For example, use of multiplexing or connection pooling software or hardware to reduce the number of users directly connected to the Licensed Software, the number of Named Users or Concurrent Users within Licensee’s organization using the Licensed Software shall be measured as the number of distinct inputs to the multiplexing or connection pooling front end and Licensee shall purchase the equivalent number of Named User or Concurrent User Licenses. If Licensee uses replicator software, Licensee may not use the Licensed Software or share licenses in any way not explicitly provided for in this License Agreement. (ii) APIs: Any user of any third party application that calls any Licensed Software application programming interfaces (“Product APIs”) must have a valid license to connect to the Licensed Software. Licensee shall not, and shall not allow others, to reverse engineer, decompile, or disassemble the Product APIs. Commercial distribution of any products that include Product APIs requires a separate distribution license and such license is not granted by this License Agreement. (iii) TeamInspector: TeamInspector is licensed on a Named User basis only. (iv) Connectors: A license purchased for this Licensed Software allows use of such software in any quantity solely in conjunction with TeamAnalytics that is licensed and ordered separately.

D. LICENSE OPTIONS FOR THE FOLLOWING SOFTWARE PRODUCTS:

All Application Middleware products including AppServer™ and VisiBroker® including portions thereof, other products within the same product families and other Software Products where indicated by Licensor.

  1. Development License Options
    1. Named User: For each Named User License, Licensee may install and execute the Licensed Software on one (1) computer for use by one (1) person in Licensee’s organization solely to develop, compile (including byte code compile), and test, in source or object code form, Licensee’s own application programs and other works ("Works") designed to work with the Licensed Software. Unless Licensee has purchased a valid Deployment License as described below, Licensee may not deploy or use the Licensed Software on a production basis. The Licensed Software contains certain time-out features designed to prevent the Licensed Software from being deployed in a runtime environment for longer than a specified period without Deployment License keys. Deployment License keys will be provided to Licensee at such time as Licensee purchases the requisite Deployment Licenses. WORKS CREATED USING THE LICENSED SOFTWARE MAY REQUIRE THE LICENSED SOFTWARE IN ORDER TO RUN. WITHOUT THE REQUISITE DEPLOYMENT LICENSE KEYS, THE LICENSED SOFTWARE WILL BE DISABLED AND THOSE WORKS MAY NO LONGER RUN. LICENSEE SHOULD THEREFORE TAKE PRECAUTIONS TO AVOID ANY LOSS OF DATA THAT MIGHT RESULT.
  2. Deployment License Options
    1. Concurrent User: For each Concurrent User Deployment License, License may install the Licensed Software, in executable form only, on a server accessed and used by multiple users over a network, provided that the Licensed Software is used only by as many concurrent users at any given moment in time as Licensee has purchased concurrent licenses and provided further that use of the Licensed Software is only in the Territory and accessed only by users physically located in the Territory. The foregoing license shall be for access and use, only by the equivalent number of concurrent users for whom Licensee has paid the applicable license fees, solely to create, compile (including byte code compile), test and deploy, in source or object code form, Works. As used in this Section, use or in use means that the Licensed Software is "in use" on a computer or machine when it is loaded into random access memory (RAM) of that computer. The Licensed Software may not be shared or used concurrently on computers or machines located outside of the Territory or in such a way to enable use or access by users located outside the Territory.
    2. Server/CPU: For each Server/CPU Deployment License Licensee may install and execute the Licensed Software in object code form on a production basis on one (1) server hardware unit that is operating the platform designated in the applicable Product Order and that has no more than the number of CPUs designated in the applicable Product Order and to permit the Licensed Software as so installed to be accessed at any one time by an unlimited number of concurrent users. Licensee may not install or execute the Licensed Software on any type of device that has a greater number of CPUs and Licensee may not, under a given Server/CPU Deployment License, install or execute the Licensed Software on more than one (1) computer. Licensee may use and deploy the Licensed Software either as a Server or as a Client. Use of the Licensed Software as a "Server" means to manage and control the automated exchanges of information with one or more remote computers through various telecommunications channels. Use of the Licensed Software as a "Client" means to operate the Licensed Software on a computer to facilitate communications with the Server. The Client shall not act as or perform the functions of a Server. A Client may make only a maximum of 10 concurrent call backs. A Client shall not have POA (Portable Object Adapter) policies with the following values: LifespanPolicyValue.PERSISTENT; RequestProcessingPolicyValue.USE_SERVANT_MANAGER; RequestProcessingPolicyValue.USE_DEFAULT_SERVANT Subject to these restrictions and limitations and any additional restrictions or limitations that may appear in the applicable Product Order, Licensee may install the Client on an unlimited number of computers. Licensee receives no right to deploy Clients without the purchase of a Server/CPU Deployment License.
    3. Backup Server License Option for AppServer and VisiBroker Licensee may install the Licensed Software on a single backup server and use the Licensed Software in object code form solely for backup or disaster recovery purposes (“Backup Server License”). Licensee may not use the Licensed Software on a production basis except during periods when one or more copies of the Licensed Software for which Licensee has purchased a Deployment License are nonfunctional, and, in such event, only in accordance with the terms of the Deployment License.
    4. Standby Server License Option for AppServer and VisiBroker Licensee may install the Licensed Software on a single standby server and use the Licensed Software in object code form solely in a standby, non-production mode for use in the event the primary server fails (“Standby Server License”). Licensee may not use the Licensed Software on a production basis under a Standby Server License except during periods when one or more copies of the Licensed Software for which Licensee has purchased a Deployment License are nonfunctional, and, in such event, only in accordance with the terms of the Deployment License.

E. OTHER LICENSE OPTIONS

  1. System Partitioning /LPAR/IFL Licensed Software may be licensed for installation and use on computer systems which incorporate logical partitioning (LPAR), and/or Integrated Facility for Linux (“IFL”) provided such rights have been expressly granted to Licensee by Licensor in writing and Licensee complies with the restrictions set forth in this Section. The licensing models in this Section 1 are only applicable to Server type licenses and are not available for computer systems where system resources (e.g. Cores/CPUs) may be scaled down or varied (e.g. “Pay Per Use” or “Pay Per Forecast” models).
    1. Logical Partitioning (LPAR): The licensing requirements of computer systems (e.g. a Host Server) which incorporate hard and/or soft partitioning shall have their licensing requirements determined as follows:
      1. Hard Partitioning: Hard partitioning is established by using a hard physical partition to physically segment a single larger server so that the Host Server utilizing the Licensed Software is a separate and distinct smaller system (that is, each separate system acts as a physically independent, self-contained server with its own CPUs, operating system, separate boot area, memory, input/output subsystem and network resources). Examples of such hard partitioning include: Dynamic System Domains (DSD) -- enabled by Dynamic Reconfiguration (DR), Solaris 10 Containers (capped Containers only), LPAR (adds DLPAR with AIX 5.2), Micro-Partitions (capped partitions only), vPar, nPar, Integrity Virtual Machine (capped partitions only), Secure Resource Partitions (capped partitions only), and Static Hard Partitioning. For computer systems where hard partitioning has been employed to create the Host Server being utilized to operate the Licensed Software, such Host Server shall be licensed pursuant to the terms and conditions set forth in this Section 1 as if such Host Server where a separate and distinct computer system. For example, where the total computer system has 8 Cores/CPUs but only 4 Cores/CPUs have been hard portioned to use the Licensed Software, Licensee shall only be required to license such 4 Cores/CPUs on such hard partitioned system.
      2. Soft Partitioning: Soft partitioning is established by using the computer systems operating system resource manager to segment and limit the number of Cores/CPUs where the Licensed Software is running by creating areas where processor resources are allocated and limited within the same operating system. Examples of such soft partitioning include: Solaris 9 Resource Containers, AIX Workload Manager, HP Process Resource Manager, Affinity Management, Oracle VM, and VMware. For computer systems where soft partitioning has been employed to create the Host Server being utilized to operate the Licensed Software, such Host Server shall be licensed pursuant to the terms and conditions set forth in this Section 1 as if such Host Server where a separate and distinct computer system but the Cores/CPU required to be licensed shall be an “expected” Cores/CPU number calculated as the ratio of the number of Cores/CPUs soft partitioned as a percentage of the entire computer system’ Cores/CPUs, increased by ten percent (10%). For example, on an 8 Core/CPU computer system where soft partitioning has been utilized such that only 4 Cores/CPUs are allocated to use the Licensed Software, a Server License fee charge equal to 60% of the total computer system Cores/CPUs would be required (50%+10% = 60% of an 8 Core/CPU system license fee).
    2. Integrated Facility for Linux (“IFL”): An Integrated Facility for Linux or IFL Host Server is established by using a dedicated Host Server where the IFL Host Server is isolated from general use and is only capable of utilizing the Linux operating system and running Linux applications and cannot run other operating systems or applications. For IFL Host Server computer systems being utilized to operate the Licensed Software, such IFL Host Server shall be licensed pursuant to the terms and conditions set forth in this Section 1 as if such IFL Host Server were a separate and distinct computer system. For example, where the total computer system that has 8 Cores/CPUs but the IFL Host Server is a 4 Cores/CPUs IFL computer system and the IFL system is the only system using the Licensed Software, Licensee shall only be required to license such 4 Cores/CPUs on such IFL Host Server system.
    3. LPAR and IFL Host Server Verification: Licensee shall provide to Licensor, upon commencement of this License Agreement and at such other times as Licensor may reasonably request, confirmation that Licensee’s computer systems comply with the LPAR and/or IFL license requirements set forth in Subsections 1(a) and (b) above. Such confirmation shall be signed by a director or officer of Licensee and shall be accompanied by all information as Licensor reasonably requires to verify that Licensee is utilizing the Licensed Software in compliance with the terms and conditions of the License Agreement. The foregoing is in addition to Licensor’s rights under Section 3 of the License Agreement.
  2. Evaluation License Option Licensed Software provided under this License Option gives Licensee a term license to use the Licensed Software within Licensee’s organization during the evaluation term specified in writing by Licensor, solely for evaluation and testing purposes on a single computer system and not for development, commercial, or production purposes. Licensee may not reproduce or distribute the Licensed Software. Licensee’s results of benchmark or other performance tests run on or using the Licensed Software may not be disclosed to any third party without Licensor’s prior written consent. At any time during the evaluation term or upon completion thereof, Licensee may, upon written notification to Licensor and payment of the applicable license fee, replace the evaluation license with a license to use the Licensed Software pursuant to one of the other applicable options listed in Annex1. In the absence of such notification by Licensee, the evaluation license shall automatically terminate at the end of the evaluation term and Licensee shall return, or, if Licensor so directs, delete and destroy all such Licensed Software and provide Licensor with written confirmation of such deletion and destruction being completed. Licensor may, in its sole discretion, grant Licensee an extension to the evaluation term subject to receiving a written request and reasons for such request from Licensee prior to expiration of the evaluation term. Licensor will specify any such agreed extension in writing to Licensee. Licensed Software provided by Licensor free of license fee charge shall be deemed to be provided pursuant to this Evaluation License Option unless otherwise agreed in writing. In the absence of any contrary period specified in writing by Licensor, the evaluation term shall be deemed to be thirty (30) days. In relation to Licensed Software provided pursuant to this Evaluation License Option, this Section shall prevail over any contrary provisions set forth in this License Agreement.
  3. Test License Option Licensed Software provided under this License Option gives Licensee a limited license to use the Licensed Software solely for Licensee’ internal testing purposes on a single computer system. At no time may Licensee use the Licensed Software for development, commercial, or production purposes, nor may Licensee reproduce or distribute the Licensed Software or any software application programs created with it. The applicable license fee for this License Option will be determined by the access or use to be tested. For example, batch process testing will require the payment of the applicable license fee for a Licensor server license for CPU. Licensee’ results of benchmark or other performance tests run on or using the Licensed Software may not be disclosed to any third party without Licensor’s prior written consent. If Licensee uses the Test Licenses for any purpose other than for Licensee’ internal testing purposes, the Test License shall terminate automatically and without notice. Upon such termination, Licensee may convert the terminated Test License to a standard license type listed above by paying the applicable conversion fee. In relation to Licensed Software provided pursuant to this Test License Option, this Section shall prevail over any contrary provisions set forth in this License Agreement.

ANNEX 2 SPECIFIC SOFTWARE TERMS

The following terms and conditions apply to the applicable Licensed Software products named below and supersede any conflicting terms and conditions set forth elsewhere in this License Agreement:

ALL VERSIONS OF NET EXPRESS®, SERVER EXPRESS™, MICRO FOCUS STUDIO™, MICRO FOCUS SERVER™, EXTEND®, RELATIVITY®, RM/COBOL® , REUZE DEVELOPER, OPEN PL/I AND XCENTRISITY®. For this Licensed Software Licensee has the option to use the Licensed Software licenses purchased either (i) for internal development purposes, or (ii) to reproduce and distribute internally, as both options are described in Annex 1, any software application program created by Licensee using any such Licensed Software product, in whole or in part, as a part of Licensee’ own application software product (“Licensee Application Software”). Where the foregoing option (ii) is selected it is contingent upon Licensee (a) including Licensor’s copyright notice for the Licensed Software on the product label and as a part of the sign-on message for such Licensee Application Software product; and (b) indemnifying, holding harmless and defending Licensor and its third-party suppliers from and against any claims or lawsuits, including attorneys’ fees, legal fees and court costs that arise out of, or result from, the use or distribution of such Licensee Application Software. Licensee can only reproduce and distribute Licensee Application Software to third parties after entering into a separate distribution agreement with Licensor. Usage and distribution of the Licensed Software arises both by the explicit distribution of any Licensee Application Software and by the implicit distribution and usage of any such functionality when linked into a software application program. The grant of license for the Licensed Software does not permit Licensee to either use or reproduce and distribute any files supplied as part of the Licensed Software in order to create a compiler, interpreter or runtime support product. Licensor offers specific production licensing options for distribution to third parties which vary depending upon the license fees paid by Licensee and Licensee should contact its Licensor sales representative for more details.

MAINFRAME EXPRESS® ENTERPRISE EDITION.

  1. Where Mainframe Express Enterprise Edition (all versions and editions including earlier versions such as Mainframe Express) is the Licensed Software, Mainframe Express Enterprise Edition may only be used for development purposes. Licensee may not use Mainframe Express Enterprise Edition for production purposes nor utilize or access any of the Mainframe Access portions of the Licensed Software from any Licensed Software product licensed separately, unless the Licensor product, Mainframe Access, has also been separately licensed from Licensor, in which case, the Mainframe Access product included as part of Mainframe Express Enterprise Edition may be installed on the number of host (mainframe) machines needed to support the number of authorized end-users of Mainframe Express Enterprise Edition.
  2. Where Mainframe Express Enterprise Edition is the Licensed Software, the Licensed Software will contain Component Generator. In order to use the components created using Component Generator, Licensee must pay a license fee. Upon payment of such license fee, Licensor grants Licensee a personal, non-exclusive, non-transferable license to use the components according to the type of license granted. Licensor has and will retain all ownership rights to any application source code generated by a template, wizard or similar functionality, (“Generated Source Code”) supplied as part of the Component Generator including without limitation all patent rights, copyrights, trademarks, trade secrets, service marks, related goodwill, and confidential and proprietary information relating thereto. For the avoidance of doubt, Generated Source Code does not include Application Server Files. Licensee shall have and retain all ownership rights to Licensee’s implementation of the Generated Source Code, provided that nothing in this Section shall be construed as in any way granting Licensee any right to limit or prevent: (i) Licensor from licensing any of its existing or future Licensed Software or providing any of its existing or future services to third parties; or (ii) Licensor or any other users of the Component Generator from generating and using identical or similar implementations of Generated Source Code. Licensor grants Licensee a perpetual, transferable, non-exclusive, royalty-free right to reproduce and distribute the Generated Source Code in object code form together with any implementation Licensee make thereto as a part of Licensee’s application of the Licensed Software product created using the Component Generator and that such Licensee application of the Licensed Software product adds significant and primary functionality to the Generated Source Code.

ALL VERSIONS OF MICRO FOCUS STUDIO, REUZE DEVELOPER AND NET EXPRESS. For this Licensed Software

  1. Redistribution of Internet Shortcut Support DLL (URL.DLL) in Microsoft Win32 SDK. To obtain rights to distribute file "URL.DLL" supplied as part of the Microsoft Win32 SDK that may be included with the Licensed Software, Licensee must print out, sign and return the Microsoft Win32 SDK End User Licensee Software License Agreement (located at \license\win32sdk.txt in the Microsoft Win32 SDK) to Microsoft Corporation, Win32 SDK Program, Building 5-2, One Microsoft Way, Redmond, Washington 98052-6399. URL.DLL may be included as part of a future version of Windows or Windows NT. Upon notification by Microsoft of its inclusion of URL.DLL in Windows or Windows NT, Licensee shall upgrade its application so that it no longer contains URL.DLL, and within a reasonable period after such time, but no later than six (6) months, cease distribution of URL.DLL.
  2. Use of Microsoft Visual Studio Technology and Visual Studio .NET Premier Partner Edition, including VSIP-SDK (“VSN Software”). The VSN Software is provided by and governed under the VSN Software End User License Agreement (“VSN EULA”) enclosed with the Licensed Software. Licensee must agree to be bound by the VSN EULA before use of the VSN Software. Licensee shall not use or enable others to use the information/content of the VSIP-SDK to enable any development environment other than Visual Studio .NET to host packages that use the interfaces documented in the VSIP-SDK or use or enable others to develop or distribute extensions to or wrappers for the VSN Software, or the interfaces between the Licensed Software and the VSN Software.

ACADEMIC EDITIONS/USERS. Where Licensed Software is licensed under Licensor’s ACTION Program, in addition to the above terms and conditions:

  1. Licensee shall not use the Licensed Software for any purpose other than for education, training or academic research activities.
  2. Licensee shall not copy the Licensed Software, nor shall Licensee distribute, transfer or assign the Licensed Software without specific permission from Licensor.
  3. License management: If Licensee is the academic institution using the Licensed Software for teaching purposes, Licensee will manage all student licenses through a license server provided by Licensor in accordance with guidelines provided by Licensor. Licensee agrees to provide reports describing the number of licenses Licensee has issued in each period upon Licensor’s request.
  4. Where CALIBERRM™, TEAMDEFINE™, TOGETHER®, STARTEAM®, TEMPO™, TEAMDEMAND®, TEAMFOCUS™, TEAMANALYTICS®, TEAMINSPECTOR™, SILKCENTRAL®, TEST MANAGER™, SILKTEST®, SILK4J™, SILKPERFORMER® APPSERVER™ OR VISIBROKER is the Licensed Software, the Licensed Software may be used solely for Licensee’s personal use in providing or receiving instruction within the limited scope of guided computer programming and/or software training course(s) in which Licensee is a direct and personal participant, either as student or instructor (“Course(s)”). The Licensed Software may only be used with other participants of the Courses and then only for educational or training purposes. The Licensed Software may not be used for any commercial, business, governmental or institutional purpose of any kind, except to the extent Licensee is an instructor teaching a Course.

NET EXPRESS PERSONAL EDITION. Where Net Express Personal Edition is the Licensed Software, in addition to the above terms and conditions:

  1. Licensee shall not to use the Licensed Software for any purpose other than for personal educational and non-commercial activities. The Licensed Software may not be used for training or teaching purposes.
  2. Licensee shall not use the Licensed Software to compile source code for applications of more than two thousand, two hundred (2200) lines of procedural code (exclusive of lines containing comments and/or blanks) in any one (1) application or to deploy such application to any other machine.
  3. Licensee shall not copy the Licensed Software, nor shall Licensee distribute, transfer or assign the Licensed Software without specific permission from Licensor

ALL VERSIONS OF MICRO FOCUS STUDIO, NET EXPRESS, AND SERVER EXPRESS. This Licensed Software may include or generate limited licenses for Micro Focus Server, Application Server and/or Enterprise Server. If such licenses are included or generated, these limited licenses are provided solely for use by the Named User of the Licensed Software in order to unit test an application developed with any version of Micro Focus Studio, Net Express, or Server Express on the server used to develop the application and may not be used for system testing, production or deployment. Any use of this limited license outside of the development and unit testing of such applications is outside the scope of the license.

ALL VERSIONS OF MICRO FOCUS STUDIO, REVOLVE® ENTERPRISE EDITION, MAINFRAME EXPRESS, NET EXPRESS, AND MICRO FOCUS LICENSE SERVER. Licensee may use the Micro Focus License Server that accompanies the Licensed Software to generate request or access codes for Licensee’s use of the Licensed Software. Licensee may not use the Micro Focus License Server to generate multiple-user request of access codes for the Licensed Software unless Licensee has paid the appropriate license fees for each authorized user accessing the Licensed Software.

MICRO FOCUS STUDIO FOR COBOL DEVELOPERS AND MICRO FOCUS STUDIO ENTERPRISE EDITION. Where Micro Focus Studio is the Licensed Software, Licensee may utilize the Licensed Software on both the Windows platform and one UNIX platform, which will be designated on the Product Order. Use of the Licensed Software on a different UNIX platform than originally licensed or on more than one UNIX platform will require additional licenses and the payment of applicable license fees. Licensee may install the Licensed Software on more than one machine or Host Server, so long as the Licensed Software is only used by the same named user on each machine or Host Server.

MICRO FOCUS REVOLVE ENTERPRISE EDITION. Where Micro Focus Revolve Enterprise Edition is the Licensed Software, Licensee may only utilize the Licensed Software for its own internal benefit and may not use the Licensed Software to process third-party code or to generate reports to be delivered to a third-party for that third party’s benefit without first entering into a separate agreement with Licensor.

MICRO FOCUS DATA EXPRESS™. Where Micro Focus Data Express is the Licensed Software Licensee may utilize both the Data Subset Extraction and the Data Masking modules, however, Licensee may only use other modules that are expressly listed in the relevant Product Order and for which Licensee has paid the separate relevant license fee.

MICRO FOCUS ENTERPRISE VIEW™. Where Micro Focus Enterprise View is the Licensed Software, Licensee may only use those additional modules that are listed in the Product Order and for which Licensee has paid a separate license fee. Where a Micro Focus Enterprise View module has language-specific capability, any licensed languages shall be listed in the Product Order. Support for additional languages is subject to an additional license fee.

MICRO FOCUS ENTERPRISE VIEW - RAPID ASSESSMENT OPTION. Micro Focus Enterprise View – Rapid Assessment Option is provided to Licensee on a fixed term license basis only. The start and ending dates of the term will be set forth in the Product Order. Unless otherwise stated in the Product Order, Micro Focus Enterprise View – Rapid Assessment Option is licensed on a “Line of Code” basis.

MODERNIZATION WORKBENCH SOFTWARE DEVELOPMENT KIT. This Licensed Software may only be utilized for the purpose of creating applications designed to operate with Modernization Workbench. The SDK does not contain any redistributable code and Licensee is not permitted to distribute any part of the SDK. No support is provided for the SDK.

XCENTRISITY BUSINESS INFORMATION SERVER. This Licensed Software is licensed on a concurrent user basis for local area network usage (“LAN”) or wide area network usage (“WAN”). A LAN license may only be installed and used on one server, whereas a WAN license may be installed and used on any number of servers, both subject to the number of concurrent users licensed.

OPTIMAL TRACE, QACENTER, QADIRECTOR, QALOAD, QARUN, RECONCILE, TESTPARTNER, TRACKRECORD, CARS, TEST FACTORY, DEVPARTNER. This Licensed Software may include technology for monitoring authorized use, including the policy files and license keys required to use the Licensed Software (the “License Authorization Server” or “LAS”). The LAS may be installed on a single-specified computer system at the specific site for which Licensee has contracted (the “Designated System”). The LAS, or any part thereof, may not be transferred from the Designated System. Regardless of the installation of the LAS, Licensee must remain compliant with the terms in this License Agreement (including without limitation any license restrictions and number of users permitted pursuant to this License Agreement). The LAS cannot be used or installed on a Virtual Machine.

Licensee may not transfer, ship or use this Licensed Software outside the country in which it was originally licensed to Licensee. Only one copy of the Licensed Software may be installed on a single computer at any one time unless: (A)The Software is designed and intended by Licensor for use in a shared network client server environment, as set forth in the Documentation; or (B) Licensee has purchased a license for each individual user of the Licensed Software and/or for each computer that will have access to the Software. Except for Optimal Trace Enterprise Edition, in the event the Software is designed and intended by Licensor for use in a shared network client server environment, Licensee may only install the Software on a single server.

The following shall only apply if the Licensed Software is device driver development software, used by Licensee to develop application or device driver programs (“User Software”), as specified in the Documentation. The User Software may include run-time components (“RTCs”) that have been extracted by the Software from the library files of the Software, programs to remotely test the User Software, and compiled code examples. These RTCs, examples, and programs are specifically designated as redistributable in the Documentation. Licensee has a worldwide, non-exclusive, royalty-free, restricted license to: (A) modify, compile and distribute the driver code examples; (B) distribute the remote testing program for testing purposes only; (C) embed the RTCs and driver code examples in its User Software, in object code form only; and (D) reproduce and distribute the RTCs and driver code examples embedded in its User Software, in object code form only provided that with respect to each of (A) – (D) inclusive (i) Licensee distributes the RTCs and driver code examples only in conjunction with and as a part of its User Software; (ii) Licensee will be solely responsible to anyone receiving its User Software for any updates, technical and other support obligations, and any other liability which may arise from the distribution of its User Software; (iii) Licensee does not use Licensor’s or its licensors' names, logos, or trademarks to market or distribute its User Software; (iv) Licensee includes Licensor’s and its licensors' copyright and/or proprietary notices and legends within the executable images of its User Software and on Licensee's software media and documentation; and (v) Licensee agrees to indemnify, hold harmless and defend Licensor and its licensors from and against any claims or lawsuits, including attorneys’ fees, that arise or result from the use or distribution of its User Software.

OPTIMAL TRACE, QACENTER, QADIRECTOR, QALOAD, QARUN, QUALITY MANAGER, RECONCILE, TESTPARTNER, TRACKRECORD, TEST FACTORY, DEVPARTNER. This Licensed Software may be used in a Virtual Machine only where licensed for concurrent users. In addition this Licensed Software may be used on any operating system on which the Licensed Software is capable of operating and which is supported by Licensor.

QALOAD. This Licensed Software may be licensed on a Virtual User basis. A "Virtual User" represents a simulation of a particular individual user executing a transaction or sequence of operations. QALoad Virtual users are pooled for use by the total number of licensed QALoad Conductors and one or more licensed QALoad Conductors may use some or all licensed Virtual Users. Virtual Users may be used across all support protocols (Easyscripts).

SILKCENTRAL, TEST MANAGER, SILKTEST, SILK4J, SILKPERFORMER This Licensed Software may include technology for monitoring authorized use, including the policy files and license keys required to use the Licensed Software (the “License Authorization Server” or “LAS”). The LAS may be installed on a single-specified computer system at the specific site for which Licensee has contracted (the “Designated System”). The LAS, or any part thereof, may not be transferred from the Designated System. Regardless of the installation of the LAS, Licensee must remain compliant with the terms in this License Agreement (including without limitation any license restrictions and number of users permitted pursuant to this License Agreement). The LAS cannot be used or installed on a Virtual Machine.

SILK PERFORMER. This Licensed Software may be installed on a reasonable number of Licensee computer systems. Licensee may use the Multi-Machine Controller (also referred to as “Workbench”) (“MMC”) component and related load-test agents on an unlimited number of machines for an unlimited number of users, but solely in connection with the use of SilkPerformer in accordance with the number, type and class of Virtual User Licenses purchased. Premium Virtual User Licenses for SilkPerformer, when ordered in any quantity, include a single Named User limited license to use SilkTest (the “Additional Product”). The Additional Product may be used ONLY in conjunction with the Premium Virtual User Licenses of SilkPerformer and may not be used or transferred on a stand-alone basis. Incremental use of any Additional Product beyond the single Named User license, or stand-alone use, must be licensed and paid for separately.

TEAMANALYTICS 2008. This Licensed Software includes a single Named User limited license to use StarTeam (either StarTeam Enterprise 2006, StarTeam Enterprise Advantage 2006, StarTeam Enterprise 2008 or StarTeam Enterprise Advantage 2008), CaliberRM (either CaliberRM 2006 or CaliberRM 2008) and SilkCentral Test Manager (either SilkCentral Test Manager 2006 or SilkCentral Test Manager 2008) (the “Additional Products”). The Additional Products may be used only in conjunction with the TeamAnalytics 2008 product and may not be used or transferred on a stand-alone basis. Incremental use of any Additional Products beyond the single Named User license, or stand-alone use, must be licensed and paid for separately.

TEAMANALYTICS 2009. This Licensed Software includes a single Named User limited license to use StarTeam, CaliberRM and SilkCentral Test Manager (collectively, the “Additional Products”). The Additional Products may be used ONLY in conjunction with the TeamAnalytics 2009 and may not be used or transferred on a stand-alone basis. Incremental use of any Additional Products beyond the single Named User license, or stand-alone use, must be licensed and paid for separately.

TOGETHER. This Licensed Software may be used solely to create, compile (including byte code compile), test and deploy, in source or object code form, Licensee application programs and other works. This Licensed Software requires registration with Licensor prior to use. Licensee will be prompted to register at the time of installation or first use, at which time Licensee will be notified, or directed to online resources explaining, how registration information provided by Licensee may be used and Licensee will be afforded the opportunity to opt out of certain uses of such information. Licensee may use the License Manager component of the Licensed Software, in executable form only, on a server for use solely in connection with Licensee’s use of the Licensed Software.

TEAMDEFINE. This Licensed Software includes the capability for an unlimited number of users to review the simulation program integrated into the Licensed Software by Licensor or its suppliers. Such users may not otherwise use the Licensed Software. Where an evaluation license option is obtained for this Licensed Software pursuant to Annex 1.E.2 the evaluation period will continue for up to 365 days. During the first 30 days of the evaluation period Licensee will be able to access all functionality of this Licensed Software except “Project Export”. During the remaining evaluation period such functionality will continue except that Licensee will have read only access to “simulations”, “requirements”, “SDK”, “integrations”, “images” and “templates”. Licensee may purchase a full license for this Licensed Software at any time during the evaluation period.

SILKCENTRAL, TEST MANAGER, SILKTEST, SILK4J, SILKPERFORMER, TEAMDEFINE, CALIBER™, TOGETHER, STARTEAM, TEMPO, TEAMDEMAND, TEAMFOCUS, TEAMANALYTICS, TEAMINSPECTOR, APPSERVER, VISIBROKER. This Licensed Software may be used in a Virtual Machine only where a concurrent user license has been granted

APPSERVER, VISIBROKER. For this Licensed Software, regardless of the number of CPU's for which Licensee has purchased a Deployment License: (i) Licensee may not run more than one instance of the deployed Licensed Software on a single computer, and (ii) the Licensed Software may not be accessed at any one time by more than the number of Concurrent Users indicated in the applicable Product Order. In the event Licensee desire additional instances or additional Concurrent Users, Licensee must purchase a separate license applicable to a different computer.

APPLICATION MIDDLEWARE PRODUCTS. Licensee may not include this Licensed Software or any component thereof in any general-purpose software development tool, library, component, or any other product that is generally competitive with or a substitute for the Licensed Software or any other Licensor product offerings; nor may Licensee use the Licensed Software to create a product or operate a service that is generally competitive with the Licensed Software or any other Licensor product offerings, including any general-purpose software development tool. The foregoing restriction does not apply, however, to use of the Licensed Software to develop "plug-ins" (i.e., integrations created using the Licensed Software's open tools API) so long as such plug-ins are designed to provide supplementary functionality to the Licensed Software.

This Licensed Software is not redistributable. Licensee is not permitted to reproduce the Licensed Software for sublicensing, resale, lending, leasing, deployment or distribution to any party, including without limitation, distributing the Licensed Software as part of a VAR, OEM, distributor or reseller arrangement. If Licensee integrates the Licensed Software into a Work and intends to distribute or resell the resulting integrated Work, Licensee must contact Licensor to obtain the appropriate distribution license.

The portions of this Licensed Software identified as VISISECURE, VISITRANSACT, VISINOTIFY, VISITIME and VISITELCOLOG (collectively, the " VISISERVICES") are not redistributable. This License Agreement does not permit Licensee to execute, or otherwise use the VISISERVICES portion of the Licensed Software for any purpose unless Licensee has acquired a separate Development and/or Deployment License for VISISERVICES directly from Licensor before developing or deploying any Work that uses such portion of the Licensed Software. Licensee is not permitted to reproduce VISISERVICES for sublicensing, resale, lending, leasing, deployment or distribution to any party, including without limitation, distributing VISISERVICES as part of a VAR, OEM, distributor or reseller arrangement. If Licensee integrates VISISERVICES into a Work and intends to distribute or resell the resulting integrated Work, Licensee must contact Licensor to obtain the appropriate distribution license.

Notwithstanding the prohibition hereunder against decompiling this Licensed Software, Licensee may use that portion of the Licensed Software identified as "API Decompiler" for inspecting the public application programming interface (API) of the JAVA BEANS COMPONENT LIBRARY, DATAEXPRESS, DBSWING and OPENTOOLS API modules.

The following Java Technology Restrictions are applicable to the component of this Licensed Software identified as SonicMQ if it accompanies the Licensed Software: Licensee may not modify the Java Platform Interface ("JPI", identified as classes contained within the "java" package or any subpackages of the "java" package), by creating additional classes within the JPI or otherwise causing the addition to or modification of the classes in the JPI. In the event that Licensee otherwise create an additional class and associated API(s) which (i) extends the functionality of a Java platform, and (ii) is exposed to third party software developers for the purpose of developing additional software which invokes such additional API, Licensee must promptly publish broadly an accurate specification for such API for free use by all developers. Licensee may not create, or authorize its own licensees to create additional classes, interfaces, or subpackages that are in any way identified as "java", "javax", "sun" or similar convention as specified by sun in any class file naming convention.

This Licensed Software may include certain files, libraries and/or source code specifically designated as “redistributables" by Licensor in the accompanying printed or on-line documentation and that are necessary to use works created using the Product ("Redistributables"). From time to time, Licensor may designate other files as Redistributables. Subject to the terms and conditions of this License Agreement, Licensee may freely redistribute source code or compiled code that is entirely Licensee’s own and does not contain any Redistributables. Subject to the terms and conditions of this License Agreement, Licensor grants Licensee the personal, non-exclusive, non-transferable and limited license to: (a) make exact copies of the Redistributables and distribute those copies solely as components of Licensee’s Works and solely as required for permitting end users of the Works ('End users") to install and execute the Works; (b) install and execute Redistributables, without modification, solely for Licensee’s own internal use; and (c) sublicense to End Users the personal, non-exclusive, non-transferable right to install and execute Redistributables, without modification, solely as components of Works and solely for such End Users' own internal use, subject to End Users' compliance with the restrictions in this License Agreement. These rights granted may not be exercised by others, including co-developers, regardless of how Licensee’s Works are compiled, linked, or packaged. These rights apply only to Redistributables and to no other file, library, source code or other component or derivative work of the Licensed Software. They may be exercised only with respect to works created by Licensee using a duly licensed, properly registered copy of the Licensed Software.

ENDS

END USER LICENSE AGREEMENT SUPPLEMENT

The following terms and conditions shall supersede any conflicting terms and conditions set forth elsewhere in the End User License Agreement:

Where Licensor has expressly granted to Licensee the right to install and use the Licensed Software on a soft partition, the license fee shall be based on an "expected" Cores number calculated as the ratio of the number of Cores allocated to the soft partition to the total number of Cores on the Host Server, increased by a percentage to be determined by Licensor. To be effective, such grant must be set forth in the applicable Product Order or otherwise in writing separate from this License Agreement.

END USER LICENSE AGREEMENT SUPPLEMENT

The following terms and conditions shall supersede any conflicting terms and conditions set forth elsewhere in the End User License Agreement:

With respect to Micro Focus COBOLTM 2010 Runtime, COBOL Server, and all other application deployment products, Licensee may reproduce and distribute internally, in whole or in part, subject to the applicable license option as described in Annex 1 and the applicable Product Order, any software application program created by Licensee using the corresponding development product for the Licensed Software (if separately licensed to Licensee by Micro Focus) that contains any files from such development product and/or the Licensed Software ("Licensee Application Software"). Licensee shall (a) include Licensor's copyright notice for the Licensed Software on any product label and as a part of any sign-on message for such Licensee Application Software product; and (b) indemnify, hold harmless and defend Licensor and its third-party suppliers from and against any claims or lawsuits, including attorneys' fees, legal fees and court costs that arise out of, or result from, the use or distribution of such Licensee Application Software. Licensee can only reproduce and distribute Licensee Application Software to third parties after entering into a separate distribution agreement with Licensor. Usage and distribution of the Licensee Application Software arises both by the explicit distribution of any Licensee Application Software and by the implicit distribution and usage of any of the Licensee Application Software's functionality when linked into another software application program. The grant of license for the Licensed Software does not permit Licensee to either use or reproduce and distribute any files supplied as part of the Licensed Software in order to create a compiler, interpreter or runtime support product. Licensor offers specific production licensing options for distribution to third parties which vary depending upon the license fees paid by Licensee and Licensee should contact its Licensor sales representative for more details.

With respect to all application development products including Visual COBOL®:

  1. Licensee shall not use the Licensed Software, nor reproduce or distribute any files supplied as part of the Licensed Software, in order to create a compiler, interpreter, runtime support product or any other product that is generally competitive with or a substitute for the Licensed Software or any other Licensor product.
  2. This Licensed Software may include or generate limited licenses for Micro Focus COBOLTM 2010 Runtime, COBOL Server, or other deployment product. If such licenses are included or generated, these limited licenses are provided solely for use by the Named User of the Licensed Software in order to unit test an application developed with the Licensed Software on the same machine or server used to develop the application and may not be used for system testing, production or deployment, and (for Visual COBOL® products) may only be used if the Licensed Software is current on support and maintenance. Any use of this limited license outside of the development and unit testing of such applications is not permitted.

With respect to VISUAL COBOL® PERSONAL EDITION products:

  1. Licensee shall not use the Licensed Software for any purpose other than for personal educational and non-commercial activities. The Licensed Software may not be used for training or teaching purposes, and
  2. Licensee shall not use the Licensed Software to compile source code for applications of more than two thousand, two hundred (2200) lines of procedural code (exclusive of lines containing comments and/or blanks) in any one (1) application or to deploy such application to any other machine.
Micro Focus License Agreement 1 November 2009 All products LIC-GEN-17Supp1&2.1
Parent topic: Product Information


Backward Compatibility with Earlier Micro Focus Products

Backward Compatibility with Net Express 5.1 and Net Express with .NET 5.1

Applications developed using Net Express 5.1 or Net Express with .NET 5.1 might require some changes when you move it to Visual COBOL. In particular, Visual COBOL does not include support for the following functionality that was available in Net Express 5.1:

  • Debugging tools:
    • Animator
    • Data Tools (Data File Converter, Data File Editor, Fix File Index, and IMS Database Editor)
      Note: You can separately install the Micro Focus Data Tools which includes the Data File Converter, Data File Editor, and Record Layout Editor. Download the Add Pack from the Micro Focus SupportLine site.
    • FSView
    • H2CPY
    • Remote development
  • Runtime/Deployment support:
    • .lbr, .int, and .gnt files
    • Enterprise Server
    • Single-threaded run-time system
    • Static-linked run-time system
  • Programming features:
    • Btrieve
    • ISAPI
    • Mainframe subsystems (CICS, JCL, and IMS)
    • NSAPI

Backward Compatibility with Earlier Versions of Visual COBOL

Calling RM/COBOL compatible library routines
Previously, to call an RM/COBOL compatible library routine, you had to set the RM"GIVING" Compiler directive, which ensured the correct calling convention was used. This functionality is now set using the DIALECT"RM" Compiler directive, and not RM"GIVING".
ILUSING
If you set this 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.
FLAGCD
This directive is no longer available in Visual COBOL. Remove it from your code, otherwise you receive a COBCH0053 Directive invalid or not allowed here error.

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 aVisual COBOL application or when you use Visual COBOL to edit or create projects and the configuration file it refers to contains entries that are not valid for Visual COBOL.

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

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

  • If the invalid tunable is not needed by another application, remove it from the run-time configuration file.
  • Add the following as the first line in the configuration file:
    set cobconfig_error_report=false
  • Unset COBCONFIG (or 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
The message "Micro Focus License Manager service is not running" can occur when you invoke a Net Express or Studio Enterprise Edition utility from Visual COBOL. This happens when the tool is invoked with Visual COBOL 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. This can also happen when invoking a utility within the Net Express or Studio Enterprise Edition products as an external tool from Visual COBOL.

You can workaround this problem in Visual COBOL as follows:

  1. Create a batch file that unsets COBREG_PARSED before the tool is invoked. The batch file contains:
    Set COBREG_PARSED=
Call [PathToUtility] %1

    Where PathToUtility is the path to the Net Express or Studio Enterprise Edition utility.

  2. In the Visual Studio IDE, add the batch file instead of the utility itself as an external tool.

    This ensures that the proper environment is established when running that tool.

Directives Scan

The default options for directives scan (click Tools > Options > Projects > COBOL Project Settings in the IDE) have been changed since the previous release of Visual COBOL. In this release, all options on the COBOL Project Settings page are enabled by default.

Parent topic: Product Information


Backward Compatibility with Previous Versions of Visual Studio

The following sections describe issues that you might encounter when migrating a project created using a Micro Focus product for a version of Visual Studio earlier than Visual Studio 2010.

Case Preservation

In the previous version of Visual Studio, you could set the project property Preserve Case to false. When you import a project into Visual COBOL for Visual Studio 2010, the directive NOPRESERVECASE is set in the project's properties. This enables teh project to be compiled initially.

When you build with NOPRESERVECASE directive, the following COBOL syntax error can occur:

COBCH1094 ("NOPRESERVECASE not supported with ILGEN. Consider removing NOPRESERVECASE")

We recommend that you remove this directive. However, that removing the directive could result in some build errors because the name of some items would be case sensitive and not folded to upper case.

If you choose to keep the directive, be aware that this can cause build issues in the following areas:

  • new project items added from a template
  • generated code (such as Windows forms, WPF classes, Web forms, and Service references)
  • code added from a COBOL snippet
  • code added using IntelliSense

Changing the Target Framework

When changing the target framework in a project, the hint path for the references does not get changed. This means that for some references the previous framework assembly could still be used.

To resolve this, after changing the target framework check the path and runtime version of all the references in the project. You can find this information by right-clicking a reference in Solution Explorer then clicking Properties. If any of the references point to an incorrect version, delete and add the reference to the project.

Changes in the Template of Web Applications

The template for the MainDetail.aspx file in the COBOL Web applications has changed between versions 2008 and 2010 of Visual Studio. The Language property has been removed, CodeFile has been changed to CodeBehind and Inherits should now include the namespace of the project. As a result, if you try to run or debug managed COBOL Web Applications created with Studio Enterprise Edition in Visual COBOL, you can receive a Compiler error: "829: Could not find method 'Context' with this signature".

To work around this issue, you need to change the MainDetail.aspx in your application as follows:

  1. In Visual COBOL, open the MainDetail.aspx in the editor.
  2. Change the first line in the code from:
    <%@ Page Language="COBOL" AutoEventWireup="true" CodeFile="MainDetail.aspx.cbl" Inherits="MainDetail" %>

    to:

    <%@ Page AutoEventWireup="true" CodeBehind="MainDetail.aspx.cbl" Inherits="namespace.MainDetail" %>
Parent topic: Product Information
Related reference
PRESERVECASE


Third Party Software

These third party products may be required by the software in order to provide full functionality. In most cases you will need to obtain and install them individually.

  • Database Access Support with Native COBOL
  • Database Access Support with .NET Managed COBOL
  • Java Development Kit (JDK)
  • Team Foundation Server Support
    Extra information about and requirements for Team Foundation Server.
Parent topic: Product Information


Database Access Support with Native COBOL

Before you can use this product to deploy SQL applications developed with COBSQL, DB2 ECM or OpenESQL, ensure any third party software prerequisites are installed and the environment is set properly.

Certification of RDBMS Precompilers
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 RDBMS documentation:
Oracle
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.
HCO for DB2 LUW
IBM document certification information for DB2/COBOL applications within the Information Center for DB2, in the topic Support for database application development in COBOL.
COBSQL
COBSQL supports the following database preprocessors:
  • Sybase Open Client Embedded SQL/COBOL Version 11.1 or later
  • Oracle Pro*COBOL Version 10gR1 or later
  • Informix Embedded SQL/COBOL Version 7.3 or later

COBSQL is supported in both 32-bit and 64-bit environments.

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.

DB2 ECM
DB2 ECM supports the following database preprocessors:
  • IBM DB2 LUW Version 9.1 or later
  • IBM DB2 Connect Version 9.1 or later

Applications compiled with the DB2 ECM are supported in 32-bit environments only.

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

OpenESQL is supported in both 32-bit and 64-bit environments.

Parent topic: Third Party Software
Related concepts
Database Access


Database Access Support with .NET Managed COBOL

OpenESQL
  • Database access is supported using the OpenESQL preprocessor with applications compiled as .NET managed code to access 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.
  • OpenESQL has been tested against the following ADO.NET data providers:
    • Microsoft provider for SQL Server
    • Microsoft provider for Oracle
    • IBM DB2
    • Oracle Data Provider for .NET (ODP.NET)
    • OleDb
    • Managed ODBC .NET providers
  • Dynamic SQL using the SQL Descriptor Area (SQLDA) is not currently supported for OpenESQL applications compiled with the SQL(DBMAN=ODBC) directive.
SQL CLR Integration
The following software is required to use the SQL CLR integration feature:
  • Microsoft SQL Server 2008 R2
  • Microsoft .NET Framework 3.5 or earlier. SQL Server 2008 R2 cannot run SQL CLR assemblies created using .NET Framework 4.0.
Parent topic: Third Party Software
Related concepts
Database Access
Prerequisites for SQL CLR Integration


Java Development Kit (JDK)

The Java Development Kit (JDK) is required for compiling Java.

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

Parent topic: Third Party Software
Related information
Setting Up the Environment for Java and COBOL


Team Foundation Server Support

Extra information about and requirements for Team Foundation Server.

Restarting

When you install this COBOL development system on top of Team Build, you need to restart your machine after the installation. This sets the environment properly and enables Team Build to track changes. You do not need to restart if you install Team Build later.

Web Access

If you are using Team System Web Access you may find that merge and annotate commands are disabled for certain file types in your COBOL project (such as .cbl,.cpy ). To enable the commands, you need to add the extensions to MimeMap.xml in webaccess_install_dir\Web\App_Data. Edit the file with a text editor and add the extensions to the <Extensions> section with content type "text/plain". Finally, reset the application pool.

Multiple check out

You can enable multiple check out and merge for certain file types in your COBOL project. In order to do this, right-click your server in Team Explorer and choose Team Foundation Server Settings > Source Control File Types. Add the extensions of the files to the list and enable multiple check out and merge as required.

Parent topic: Third Party Software


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

  • COBOL Programming
  • Compatibility
  • Data Access
  • .NET Code
  • Problem Determination and Diagnostic Tools
  • Visual Studio IDE
Parent topic: Product Information
Related information
Updates and Product Support


COBOL Programming

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


Arithmetic Calculation

Exact equality of arithmetic results from managed and unmanaged code is not guaranteed. [573761]

Parent topic: COBOL Programming


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


Enhanced ACCEPT/DISPLAY Syntax (Adis)

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

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

Parent topic: COBOL Programming


Filenames

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

Parent topic: COBOL Programming


IDXFORMAT 8 File Size Limits

File size limits for IDXFORMAT 8 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


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 or re-installing RM/COBOL.
Parent topic: COBOL Programming
Parent topic: .NET Code


Unsupported Features

Projects compiled to .int, .gnt and .lbr files

The preferred executable file formats with Visual COBOL are .dll and .exe. The .int and .gnt file formats are still supported by the Compiler and the debugger but cannot be created directly by the IDE.

You can use the Net Express Project Import Wizard to convert existing Net Express projects into Visual Studio projects, and to import the COBOL source into the IDE. If you convert a project containing these code configurations, the following will happen:
  • Any configurations that have .int, .gnt or .lbr will be automatically converted to .exe.
  • A message will display confirming that the settings have been changed.

Run-time Features

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

  • Dialog System (Character and GUI)
  • GUI Class Library
  • HyHelp
  • Panels Version 2

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

Parent topic: COBOL Programming


Compatibility

  • Co-existing with Earlier Micro Focus Products
  • Installation
  • Microsoft SQL Server Express Edition
Parent topic: Known Errors and Restrictions


Co-existing 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 aVisual COBOL application or when you use Visual COBOL to edit or create projects and the configuration file it refers to contains entries that are not valid for Visual COBOL.

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

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

  • If the invalid tunable is not needed by another application, remove it from the run-time configuration file.
  • Add the following as the first line in the configuration file:
    set cobconfig_error_report=false
  • Unset COBCONFIG (or 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
The message "Micro Focus License Manager service is not running" can occur when you invoke a Net Express or Studio Enterprise Edition utility from Visual COBOL. This happens when the tool is invoked with Visual COBOL 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. This can also happen when invoking a utility within the Net Express or Studio Enterprise Edition products as an external tool from Visual COBOL.

You can workaround this problem in Visual COBOL as follows:

  1. Create a batch file that unsets COBREG_PARSED before the tool is invoked. The batch file contains:
    Set COBREG_PARSED=
Call [PathToUtility] %1

    Where PathToUtility is the path to the Net Express or Studio Enterprise Edition utility.

  2. In the Visual Studio IDE, add the batch file instead of the utility itself as an external tool.

    This ensures that the proper environment is established when running that tool.

Parent topic: Compatibility


Installation

  • A bug in Windows 7 x64 may cause the display of the Compatibility Assistant dialog during the installation of the product showing incorrectly that aslmpclocate.exe and init2aslm.exe are not compatible. The two utilities run properly and the install is successful. To avoid receiving this notification, run Windows update and install update KB978637 before installing this product.
  • If, when you start Visual Studio, you receive a message box about Micro Focus package load failures, check that the Packages folder is on the PATH. If it is not, click NO to disable loading the packages.

    If you accidently click YES, you need to re-enable loading the packages, as follows:

    1. Open a Visual Studio command prompt from the Start menu.
    2. Enter the command:
      devenv /ResetSkipPkgs

    When you reboot the machine, the problem is resolved, the PATH is set up correctly and the packages are found.

  • Installing this release as an upgrade to a previous version of the product might take longer in relative terms compared to a clean install.
Parent topic: Compatibility


Microsoft SQL Server Express Edition

  • To install successfully Microsoft SQL Server Express Edition on Windows XP, you need to have Microsoft Installer 4.5 and PowerShell 1.0 installed. You can install Microsoft Installer 4.5 from the Autorun. Download PowerShell 1.0 from the Microsoft website.
Parent topic: Compatibility


Data Access

  • COBSQL
  • DB2
  • File Handling
  • Records with Alternate Keys
  • OpenESQL
Parent topic: Known Errors and Restrictions


COBSQL

  • COBSQL cannot process directives within a $SET statement. Any of the COBOL directives that COBSQL processes should be placed either within the build/project settings, or in a directives file (for example, cobol.dir ).

  • 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

    Note that the program logic is altered because Pro*Cobol has commented out a COBOL line. It is recommended, 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.
Parent topic: Data Access


DB2

  • Visual COBOL supports all versions of DB2 LUW that are currently supported by IBM. We do not support versions of DB2 UDB or DB2 LUW that are no longer supported by IBM.
  • If the location of the \sqllib\bin folder entered in your PATH environment variable is more than 255 bytes into the string, an error occurs when compiling DB2 applications. To prevent this error, edit your PATH statement so that the \sqllib\bin folder is referenced nearer to the start of the string.
Parent topic: Data Access


File Handling

  • Using Btrieve, a START operation cannot be performed with a part-key. The whole key must be used.
  • In Visual COBOL, if you attempt to open a data file located on a Novell Netware drive you may receive a file status 9/181 message, which indicates that you have used an invalid parameter.

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

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

    [XFH-DEFAULT]
IDXFORMAT=4
FILEMAXSIZE=4
Parent topic: Data Access


Records with Alternate Keys

  • 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


OpenESQL

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.
SQL CLR Stored Procedures
  • If you use the Stored Procedure Definition (SPD) Generator to generate a COBOL wrapper program for a stored procedure that contains a DECIMAL parameter and is defined as GENERAL WITH NULLS, the generated program produces the following error when you try to deploy the SQL CLR stored procedure:
    [ : StoredProcedures::<stored ProcedureName>][mdToken=0x6000008][offset 0x0000016B][found
Int32][expected value 'System.Decimal'] Unexpected type on the stack.
An error occurred while the batch was being executed

    To avoid this error, either define the stored procedure as GENERAL or modify the generated wrapper program to use floating-point data types.

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 either the ODBC Data Source Administrator (32-bit) or the ADO.NET Connection editor. The execution process continues to use the 64-bit DSN.
Runtime
  • OpenESQL applications are now optimized for performance by default, with OpenESQL now implicitly setting the BEHAVIOR compiler directive to MAINFRAME; 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 MAINFRAME 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 MAINFRAME 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.
Parent topic: Data Access


.NET Code

  • ASP.NET
  • Checker
  • Compiler Directives
  • File Handler
  • Fileshare
  • Language Service and IntelliSense
  • OpenESQL
  • Remote Debugging
  • Security
  • Web Projects
  • Web Reference Generation
  • XML Extensions
Parent topic: Known Errors and Restrictions


ASP.NET

  • Packages are not loaded when you try to run and debug an ASP.NET application or Web service.
  • Building an ASP.NET Web site on Windows XP results in an error caused by the IDE trying to create a file in a temporary directory. To resolve this, from a Visual Studio 2010 command prompt change the TMP and TEMP environment variables to point to a different directory. If you then start Visual Studio 2010 from the command prompt, you'll be able to build the Web site.
  • It is not possible to run ASP.NET Web Sites or Web Services on a production machine (one that has Micro Focus COBOL Server installed) without an additional setup. This is because the production machine does not contain development tools such as the COBOL Compiler. To workaround this, you need to do the following steps:
    1. Precompile the site before you deploy it using the Publish Web Site command in Visual Studio.
    2. Edit the .asmx file of the Web service project or the .aspx file of the Web site and delete the Language="COBOL" statement.
    3. Edit the Web.config file with a text editor and delete the line which contains: <compiler language="COBOL"...
    4. Ensure that a .NET Server license is installed using Apptrack.

    -1080101

Parent topic: .NET Code


Checker

Calling methods
The COBOL compiler no longer supports calling a method with "self" as a parameter, when the method parameter definition is "by reference" (explicit or implicit). Instead, the method parameter definition should be "by value". This brings the COBOL compiler in line with C#.

Note that you might need to update your code so that it defines the method parameters “by value”.

For example, the following construct is no longer correct and generates error COBCH0829:

       method-id myMethod using x as myClassName.
       …
       invoke myMethod(self).

The correct way to define the method parameters is “by value”:

       method-id myMethod using by value x as myClassName.
Group typedef
Defining a group typedef in one program scope and then using it in declarations in another program scope could lead to incorrect execution results when fields within that structure are accessed. For examples of this problem see: http://kb.microfocus.com/display/4/kb/article.aspx?aid=31432.
Parent topic: .NET Code
Related reference
COBCH0829 Could not find method new with this signature


Compiler Directives

The following compiler directives are not currently supported in the .NET environment:

  • AMODE
  • CANCELLBR
  • COPYLBR
  • DATA
  • DATA-CONTEXT
  • DB2
  • DEFAULTCALLS
  • HOST-NUMCOMPARE
  • HOST-NUMMOVE
  • HOSTARITHMETIC
  • NATIVE-FLOATING-POINT
  • NOPRESERVECASE
  • ODOOSVS
  • PC1
  • PROFILE
  • SIGN-FIXUP
  • STICKY-LINKAGE
  • STICKY-PERFORM
  • TESTCOVER
Parent topic: .NET Code


File Handler

The IDXNAMETYPE file-handler configuration option does not work correctly when used in a managed .NET application and the filename (including the specified path) of the file being opened includes one or more space characters. The file will not be opened and an error file-status or RTS error message will be generated.

Parent topic: .NET Code


Fileshare

Managed-code applications that are compiled using the ILVERIFY directive are unable to perform file handling using Fileshare. Applications that need to use Fileshare should be compiled without the ILVERIFY directive.

Parent topic: .NET Code


Language Service and IntelliSense

  • The Language Service reads from assemblies referenced by your project to provide IntelliSense and error reporting while you are editing code. The Language Service is unable to reread an assembly that has changed. So if you have a project with references to other projects or assemblies which change, the Intellisense and error reporting can become inaccurate. Currently, the only way to refresh this information is to close down the IDE and restart it.
  • 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: .NET Code


OpenESQL

  • Dynamic SQL using the SQL Descriptor Area (SQLDA) is not supported in .NET managed code in the following scenarios:
    • By OpenESQL applications compiled with the DBMAN=ODBC directive.
    • On 64-bit platforms, by OpenESQL applications compiled with the DBMAN=ADO directive, where the Project property Platform Target is set to anything other than x86.
  • OpenESQL applications built as managed code with DBMAN=ODBC are only supported when targeting the 4.0 .NET Framework. Targeting earlier versions of the .NET Framework results in build errors.
  • SQL CLR Integration does not support the use of the - (hyphen) character in parameter names. If you code a hyphen into a parameter name, the following message is returned when attempting to deploy:
    (144,0): error: .Net SqlClient Data Provider: Msg 102, Level 15, State 1,
Procedure procName, Line lineNo Incorrect syntax near '-'.
  • If your COBOL stored procedure definition (i.e., your CREATE PROCEDURE statement) contains any INOUT parameters, you must modify every application call to that stored procedure to explicitly declare the direction of all the parameters passed to that stored procedure. For complete information on coding CALL statements, see the CALL topic.
  • If your COBOL stored procedure uses a CHAR(n) parameter that is copied to or from a group item (such as an SQLCA structure), then you must declare the parameter as BINARY(n) in the CREATE PROCEDURE statement of your stored procedure, and as SQL TYPE BINARY(n) in the client application.
  • The SQL TRACELEVEL directive is no longer supported in applications compiled using DBMAN=ADO.
  • OpenESQL applications are now optimized for performance by default, with OpenESQL now implicitly setting the BEHAVIOR compiler directive to MAINFRAME; 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 MAINFRAME 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 MAINFRAME 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.
Parent topic: .NET Code
Related reference
CALL
BINARY SQL Type


Remote Debugging

Remote debugging does not work for managed code if you set the project properties to start a remote application via a network drive (for example, remote debug machine = \\nwb-csdserv). This will trigger Code Access Security exceptions in the COBOL run time.

You can instead use Debug/Attach to process and select the machine name in the dialog box. This allows you to attach to an already running process on the remote machine. Obviously, the process needs to be running either in a loop or by manually adding a CBL_DEBUGBREAK in order to allow time to attach before the program terminates.

Parent topic: .NET Code


Security

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

Parent topic: .NET Code


Web Projects

  • Multi-targeting for Web site projects is not currently supported. When you create a Web project you need to ensure that you use version 4.0 of the .NET framework.
Parent topic: .NET Code


Web Reference Generation

When adding a web reference to a project, you must ensure the web reference name does not contain a hyphen. The web reference name is used as part of the name of the classes being generated. If the name contains a hyphen, you will get a class name not compliant error at run time.

You can change the name in the Web reference name field in the Add Web Reference dialog.

Parent topic: .NET Code


Problem Determination and Diagnostic Tools

  • Debugging in Visual Studio
  • Error Markers
  • Language Service
  • Test Coverage
Parent topic: Known Errors and Restrictions


Debugging in Visual Studio

  • You might experience a slight delay when initiating a debug session for a COBOL project. This is caused by the out-of-date checking to determine whether the project requires a rebuild.
  • The debugger does not fully support native OO programs. For example, QuickWatch or entering data names in the Watch window displays an error.
  • If your application receives a raceOnRCWCleanup (managed code debugger assistant) while debugging, this could be because your WPF application is not performing any closed/shutdown handling. To resolve this, add the following method in the App.xaml.cbl source:
           method-id OnExit protected override.

       procedure division using by value e as type ExitEventArgs.
           invoke super::OnExit(e)
      *>   Insert any other closedown code before the stop run statement.

           stop run.

       end method.

    For more information see http://msdn.microsoft.com/en-us/library/ms743714.aspx#Application_Shutdown

  • When stepping through a managed code program, the program might suddenly zoom. This appears to be a problem with Oracle VM VirtualBox® and Microsoft Visual Studio 2010.
  • It is not possible to add a watch on a local variable.
  • A core dump file is not created for a stack overflow condition.
  • If your project includes more than one program and you hover data items in a program that is not the current program being debugged, you may get the wrong values in the debug tooltip or no debug tooltip at all. This is because the context is the current program being debugged. This is expected and is the default Visual Studio behavior.

    To point which program is the current context:

    1. Start debugging your project and step into the code.
    2. Click Debug > Call Stack to display the call stack.

      The program being debugged is indicated by a yellow arrow. This program is also the current context.

    3. Continue stepping the code till the call stack list is populated with the other programs in your application.
    4. Double-click the program you wish to query in the call stack list.

      This adds a green arrow in front of the program in the list to indicate it is the current context.

    5. In the editor, open the program or the copybook which contains a reference to the item you want to query.
    6. Hover a data item.

      The debug tooltip should display the correct value.

Parent topic: 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. Expand Text > Micro Focus COBOL Project Types. Add the file extensions in the File association pane.

Parent topic: 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: 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: Problem Determination and Diagnostic Tools


Visual Studio IDE

  • Examples and Demonstrations
  • Fonts and Colors Dialog Box
  • Licensing
  • General Visual Studio IDE Issues
  • Visual Studio Shell
  • Visual Studio Team System
  • Windows Communication Foundation (WCF)
  • Windows Forms
Parent topic: Known Errors and Restrictions


Examples and Demonstrations

  • Some examples and demonstrations do not work in Visual Studio Shell, due to the limited support in the Shell.
  • When you run the Visual COBOL sample "Web Application Book" on Windows XP the data file is not found. To resolve this problem you must edit the Web.config file in the BookDemoWebApplication project by changing the dd_bookfile value to specify the absolute path of the bookfile.dat file. For example: <add key="dd_bookfile" value="\BookData\bookfile.dat" />
Parent topic: Visual Studio IDE


Fonts and Colors Dialog Box

The Fonts and Colors dialog box might not show COBOL entries. If this is the case, open a Visual Studio command prompt and execute devenv /setup .

Parent topic: Visual Studio IDE


Licensing

  • When you create a new project in Visual Studio with a timed license, a Licensing window appears explaining when the license is due to expire. If you press Exit, the license is considered invalid. You might get an error message saying this. You cannot continue working in Visual Studio.

    To avoid this problem, do not press Exit.

    To recover from this problem, if you pressed Exit, exit Visual Studio and restart it. If your license has expired, contact Micro Focus for a new licence.

  • Stopping the Micro Focus CES daemon or ignoring a warning that it is not running may cause the IDE to crash or stop responding.
Parent topic: Visual Studio IDE


General Visual Studio IDE Issues

  • 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.
  • If you use an explorer mouse with navigation buttons, these will not function when editing COBOL source files in the Visual Studio editor. You can use the navigation buttons on the standard toolbar instead.
  • In Visual Studio, the controls on the COBOL page in the project properties are not displayed for a WPF project. To workaround this issue, open the Application page in the project properties and from the drop-down list under Output type choose the same output type that was already selected. Close the project property pages and save the project. The next time you open the project properties, the COBOL page is properly displayed.
Parent topic: Visual Studio IDE


Visual Studio Shell

The following restrictions apply if you are using the Visual Studio shell:

  • WCF is not supported and so the WCF demonstration programs do not work. In addition, the project templates for WCF are not installed.
  • There is no integrated designer for icon and bitmap files
  • The Windows SDK must be installed.
  • Examples and demonstration programs that use languages other than COBOL do not work, because Visual Studio Shell doesn't support any other languages. This applies to the following demonstrations:
    • CursorDemo
    • InterfacingWithStdCOBOL
    • LobDemo
    • OrderStatusDemo
  • On Windows XP, when building a managed COBOL application in Visual Studio, a dialog may pop up with error "The application failed to initialize properly (0xc0000005)". If you are running Symantec antivirus runtime protection then this might be the cause for this issue. To resolve it, follow the instructions provided here.
Parent topic: Visual Studio IDE


Visual Studio Team System

If you are using Visual Studio Team System, note that Code Analysis and Code Metrics do not work for COBOL projects.

Parent topic: Visual Studio IDE


Windows Communication Foundation (WCF)

WCF is not supported in the Visual Studio Shell but adding service references for client applications is supported.

Parent topic: Visual Studio IDE


Windows Forms

  • The controls on Windows Forms created with earlier versions of this product may use the old visual styles. To apply the latest Visual Studio 2010 styles, edit the main program of the project, which in the project template is the program1.cbl file, and add the following line of code as the first line of the procedure division for the static main method:
    invoke type System.Windows.Forms.Application::EnableVisualStyles()
  • If your managed projects contain ActiveX references, you must not build them for Any CPU. Instead, set the particular target platform to either x86 or x64 to match the targeting of the ActiveX control.
Parent topic: Visual Studio IDE


Contacting Micro Focus

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

  • Further Information and Product Support
  • Information We Need
  • Creating Debug Files
Parent topic: Product Information


Further Information and Product Support

Additional technical information or advice is available from several sources.

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

  • The WebSync service, where you can download fixes and documentation updates.
  • The Knowledge Base, a large collection of product tips and workarounds.
  • Examples and Utilities, including demos and additional product documentation.

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

Note: Some information may be available only to customers who have maintenance agreements.

If you obtained this product directly from Micro Focus, contact us as described on the Micro Focus Web site, www.microfocus.com. If you obtained the product from another source, such as an authorized distributor, contact them for help first. If they are unable to help, contact us.

Parent topic: Contacting Micro Focus
Related information
Knowledge Base
Examples and Utilities
Community Forums
White Papers and Webcasts


Information We Need

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

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

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.

Parent topic: Contacting Micro Focus


Getting Started

This book shows you how to start using Visual COBOL to develop COBOL applications. The tutorials introduce the major features of Visual COBOL within Microsoft Visual Studio.

  • 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.
  • 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.
  • Moving Existing Native COBOL Applications into Visual COBOL IDE
    Visual COBOL provides a number of ways to import and edit existing native COBOL code.
Parent topic: Welcome
Related concepts
Tutorials on COBOL in the Visual Studio IDE


Native COBOL Tutorials

This section contains tutorials covering the production of native COBOL.

  • Tutorial: Developing and Debugging a Native COBOL Application
  • Tutorial: Debugging COBOL Applications Remotely
Parent topic: Getting Started


Tutorial: Developing and Debugging a Native COBOL Application

Overview

This tutorial introduces the Visual Studio Integrated Development Environment, shows how to create and build a native COBOL console application, and demonstrates some of the features you can use when debugging native code.

Starting Visual Studio

To run this tutorial, you must have both Microsoft Visual Studio and Visual COBOL installed.

To start Visual Studio:

  1. On the Start menu, click Start > All Programs > Micro Focus Visual COBOL > Visual COBOL for Visual Studio 2010.
  2. You might be prompted to set the environment, depending on the version installed. If you are prompted, choose General development environment. In this setup Visual Studio is customized for work with COBOL projects.

The IDE is shown in the figure below, although the information displayed in the large pane will be different.

The large pane is where your solutions and projects will be opened. At the moment, this shows the Start Page, with up-to-date information on Visual Studio. When you start work, this pane is where your code is displayed.

The pane at the bottom is the Output window, where messages from the IDE and Compiler are displayed.

The right-hand pane is the Solution Explorer, which displays the structure of your solution and projects. At the bottom of the Solution Explorer pane are some tabs. Solution Explorer appears by default.

If any of these panes is hidden, you can show it from the View menu.

Creating a Solution and a Project

The first task is to create a solution and a project. A solution is a container holding one or more projects that work together to create an application. The solution has the extension .sln, and is a readable text file. Microsoft recommends you do not edit the file outside of Visual Studio.

A COBOL project has the extension .cblproj, and again this is a readable file, but Microsoft recommends that you do not edit it. Different types of project have different extensions, so for example a C# project has the extension .csproj.

In this section, you create a project and solution, as follows:

  1. In Visual Studio, create a new project by clicking File > New > Project.
  2. In the New Project dialog, in the Installed Templates pane, expand COBOL and click Native.
  3. Select the Console Application template.
  4. In the Name field, specify a name for the project such as NativeApplication.

    Notice that the Name and Solution name fields have the same name

  5. In the Location field, browse to a directory where you want to put this tutorial.

    For example, if you create a folder on your c: drive called tutorials, change the location field to c:\tutorials. The solution will be stored in a subdirectory NativeApplication, according to the project name.

  6. Click OK.

This creates a solution and a project. The Solution Explorer shows the NativeApplication project. It contains:

  • Program1.cbl, which is a newly created skeleton program.
  • Properties folder, which displays the project's properties when you double-click it.
  • References folder, which enables you to add references to .NET assemblies, COM objects registered on your machine as well as other projects that your code refers to.

Edit the Project

For the purposes of this demonstration you will use a sample program that sets a pointer to the memory address of a variable.

  1. Edit Program1.cbl and type the following code in it:
           program-id. Program1.

       working-storage section.
       01 fred     pic x(100) value "start".
       01 fred-pointer pointer.

       procedure division.
           set fred-pointer to address of fred
           display "hello"
           move "testdata" to fred
           display "hello again"
           if fred = "middle"
               move "end" to fred
           end-if
           move "Richard Nixon" to fred
           display "fred contains " fred
           goback.

       end program Program1.
    Note: If, instead of typing the code, you copy and paste it into the editor, you need to do the following to trigger background parse and evaluate the code:
    1. Right-click in the editor.
    2. Click Update Syntax Reporting.
  2. Click File > Save All.
  3. Add COBOL watchpoints for the data items in the programs:
    1. Right-click fred in the editor.
    2. Click Add COBOL Watchpoint.

      This opens the Watchpoints window and adds the data item to it.

    3. Add fred-pointer to the Watchpoints window in the same way.

Build and Run the Application

There are two default build configurations for each project type: Debug and Release. These configurations define how to build the project for the different situations.

To build the project for debugging and to run it:

  1. Check the build configuration in use, by clicking Build > Configuration Manager.
  2. In Active solution configuration, choose Debug and click Close.

    Notice in the Standard toolbar at the top of the IDE, that Debug shows as the active configuration.

  3. Build the project, by clicking Build > Build Solution.

    The Build option builds only those files that have changed since they were last built, whereas the Rebuild option builds all the files in the project, regardless of whether they have changed since they were last built.

  4. Check that the project compiled successfully by looking in the Output window. To display this view, click View > Output.
  5. Run the application, by clicking Debug > Start Without Debugging or [image].

    A console window opens, showing the output from the execution of the sample application.

  6. Press any key to close the console.

Project Properties

Project properties define characteristics of the project and enable you to control a project's behavior among other things. Different properties are set by default for different types of projects.

  1. To see a summary of the project properties, select the project or solution in the Solution Explorer. By default, the Properties window is displayed below the Solution Explorer.

    If the Properties window is not visible, you can show it by clicking View (> Other Windows) > Properties Window.

    A description of the selected property is displayed dynamically at the bottom of the Properties window. To turn this description on and off, right-click in the description.

  2. To display the full project properties, right-click the project in Solution Explorer and click Properties.
  3. Go to the COBOL page of the properties, to display the selected properties for building the project. Notice that:
    • Configuration is set to Active (Debug)
    • Compile for debugging is checked
    • COBOL dialect is set to non-mainframe
    • Output path shows where the build files will be put
  4. Go to the Debug page and notice that Start project is checked, so that the application starts debugging in the current project.
  5. Browse the other properties pages to see what is available and what is set by default for a console application.

Debug the COBOL Project

The IDE provides debugging facilities, such as stepping, examining data item values and setting breakpoints. To see some of these facilities:

  1. Click Debug > Start Debugging, or press F5.

    Visual Studio enters debug mode and stops on the line for display "hello". This is because you set watchpoints for the two variables in the program and the value of one of them, fred-pointer, has changed. The debugger breaks the execution and stops on the first line after the one on which the value of the data item changed.

    Notice that the Watchpoints window indicates the change by emboldening the data item and highlighting the changed value in red:

  2. You can now click Debug > Restart to start debugging the program again.
  3. Click Debug > Step Into, or press F11.

    A console opens for running the built program. In the IDE, the first statement in the PROCEDURE DIVISION of the source code is highlighted and the cursor is positioned on it. This is the statement that will be executed next. The statement sets the pointer fred-pointer to the memory of address of the variable fred.

    The IDE enables you to watch the memory and how the values of variables change during the execution of the program. The next steps describe how to enable the Memory and Watch windows, and add watches to the two variables.

  4. Click Debug > Windows > Memory > Memory 1 to open the Memory window.
  5. You will use the Memory window to watch the memory address of the variable fred. To do this, enter any of the following strings in the Address field and press Enter:
    • address of fred - this locates the memory address of fred
    • fred-pointer - same as above after the program sets this variable to point to the memory address of fred
    • The HEX address of fred in the form of H"nnnnnnnn" - you do not know this value yet
  6. Click Debug > Windows > Watch > Watch 1 to display the Watch window.
  7. Add watches to fred and fred-pointer as follows:
    1. Right-click either one of the variables in the editor and choose Add Watch.
    2. Repeat the same for the other variable.
  8. Pin the DataTips for the two variables to the editor window as follows:
    1. In the editor, right-click either one of the variables and select Pin To Source.
    2. Repeat the same for the other variable.
  9. Click Debug > Step Into, or press F11 to step into the first statement.

    This sets the pointer fred-pointer to the memory address of fred. The value of fred-pointer changes and you can see the new one in the DataTip and in the Watch window. The new value is the HEX address of fred.

  10. Enter the HEX address in the Address field of the Memory window as H"nnnnnnnn" and press Enter.
  11. Continue stepping through the code and note how the memory at the specified address changes:

  12. If you want to edit the memory at the address of fred, you can do this directly in the Memory window:
    1. Right-click a number in the HEX view and click Edit Value.
    2. Enter a new HEX number and press Enter.

      Or,

    3. Right-click the test string, edit the string and press Enter.
  13. Continue stepping the program in the same way and watch how the values of the two variables change.

After you have finished debugging, you can close Visual Studio. You do not need to explicitly save anything, because the files are automatically saved when you build them.

Parent topic: Native COBOL Tutorials


Tutorial: Debugging COBOL Applications Remotely

Overview

This tutorial uses the COBOL Snake game from the Samples to show how to build a native COBOL application on a local machine, copy the application files to a remote machine and debug the application from the local machine.

The process of building the application through to debugging it remotely is as follows:

  1. Build the native COBOL sample on your local Windows machine.
  2. Copy the application and the symbols file to a remote Windows machine.
  3. On the remote machine, start a cobdebugremote or cobdebugremote64 process at a specified port.
  4. Configure the Firewall to allow the Micro Focus Debugger Proxy V2.
  5. In your Visual Studio project, specify properties for remote debugging and configure the symbols paths.
  6. Debug the remote application on the local machine

Prerequisites

To complete this tutorial, you need two machines with the following software installed:

  1. On the local machine - Windows OS and Visual COBOL.
  2. On the remote machine - Windows OS and either Visual COBOL or COBOL Server.
Note: See Product Information for details about the system and software requirements for Visual COBOL and COBOL Server.

Build the Source Code on the Local Machine

Build the COBOL Snake sample on the local machine as follows:

  1. Click Start > All Programs > Micro Focus Visual COBOL > Samples.
  2. Click Games in the list in the left-side pane.
  3. Select COBOL Snake and click Open Sample in Visual Studio.
  4. In Solution Explorer, right-click the project and select Properties.
  5. Click the COBOL tab.
  6. Ensure Configuration is set to Active (Debug).
  7. Click Build > Build Solution.

Copy the Application to the Remote Machine

From your local machine copy the contents of the debug subfolder in your project directory and any data files used by the application to the remote machine as follows

  1. In Solution Explorer, right-click the project and choose Open Folder in Windows Explorer.
  2. Navigate to the \bin\x86\debug subfolder in the project directory.
  3. Copy COBOLSnake.exe and COBOLSnake.idy.
  4. On the remote machine, create a folder for storing the demonstration files such as c:\tutorials\remotedebug.
  5. Copy the files to the new folder on the remote machine.
Note: Make sure you synchronize any changes you make to the application locally with the remote machine by uploading an up-to-date version of the .exe and the .idy files.

Open a Port for Remote Connection

To do this, you need to start a cobdebugremote or cobdebugremote64 process at a specified port as follows:

  1. On the remote machine, start a COBOL command environment by clicking Start > All Programs > Micro Focus Visual COBOL> Tools > Product Name Command Prompt (32-bit) or Start > All Programs > Micro Focus COBOL Server > Tools > Product Name Command Prompt (32-bit).
  2. Start the cobdebugremote or cobdebugremote64 process by typing one of the following commands at the prompt:

    32-bit:

    cobdebugremote port=nnnn repeat

    64-bit:

    cobdebugremote64 port=nnnn repeat

    where nnnn is the port number on which the daemon will listen for connection requests. It is recommended that you use a port number greater than 1024 as numbers below this one are for system use. For example, you can use a port number such as 56789.

    The console displays a message that the remote machine waits for a connection at the specified port.

    Note:
    • You can start the cobdebugremote or cobdebugremote64 process without specifying a port number by entering only cobdebugremote or cobdebugremote64 at the command line. This opens a random port for remote connections. Check the console to see which number has been assigned for the connection.
    • Normally, after the debug session has been completed, cobdebugremote or cobdebugremote64 stops and closes the remote connection. The process would have to be started again to allow a new debug session. The repeat option helps avoid doing this manually and when the debug session has been completed, the cobdebugremote or cobdebugremote64 process starts listening for another connection.

Configure the Firewall on the Remote Machine

  1. Ensure the Firewall on the remote machine allows the Micro Focus Debugger Proxy V2.
  2. Alternatively, you can open a TCP port in the Firewall for communications. The port number you add should be the one you specified on the command line.

Prepare for Remote Debugging on the Local Machine

  1. Specify properties for remote debugging:
    1. In Solution Explorer, right-click the Properties folder of the project and click Open.
    2. Click the Debug tag.
    3. Click Start external program.
    4. In the adjacent field, enter the path to the application executable on the remote machine and the filename: c:\tutorials\remotedebug\cobolsnake.exe.
    5. On the same page, check Use remote machine.
    6. Type the name or the IP address of the remote machine in the adjacent field.
    7. Specify the port number in the respective field.
    8. Click File > Save All.
  2. Configure the Symbols Paths:
    1. Click Debug > Options and Settings.
    2. In the left-hand pane, click Debugging > Symbols.
    3. Click [image] and enter the path to the symbols (.idy) file on the remote machine: c:\tutorials\remotedebug.
      Note: If your program includes more than one COBOL programs (and .idy files respectively), you need to configure the Symbols Paths for each .idy file on the remote machine.
    4. Click OK.

Debug the Application

  1. On your local machine, click Debug > Start Debugging or Debug > Step Into.

    Visual Studio on your local machine enters a debug session. On the remote machine, the cobdebugremote or cobdebugremote64 process displays a message in the console that a connection with your local machine has been established. The application on the remote machine starts running.

  2. On your local machine, click Debug > Windows > Modules in the IDE.

    The Modules window displays the .dll and .exe files that are used by the application. This can help you see whether the symbols are loaded for debugging or if the program is using the files you expect.

  3. Debug the application in the usual way.

Stop Debugging

  1. On your local machine, click Debug > Stop Debugging in the IDE.
  2. On the remote machine, if you wish to close the cobdebugremote or cobdebugremote64 process and the port, type Q in the cobdebugremote console.

    Before you can debug again, you need to restart the cobdebugremote or cobdebugremote64 process on the remote machine.

Parent topic: Native COBOL Tutorials


Managed COBOL Tutorials

This section contains tutorials covering the production of managed COBOL.

  • Tutorial: Developing .NET Managed COBOL
    This tutorial introduces the Visual Studio IDE.
  • Tutorial: Creating Windows Forms in COBOL
  • Tutorial: Developing Web Application Projects
  • Tutorial: Creating Web Forms in COBOL
  • Tutorial: Creating and Accessing WCF COBOL Services
    Shows how to create and access WCF services in COBOL.
Parent topic: Getting Started


Tutorial: Developing .NET Managed COBOL

This tutorial introduces the Visual Studio IDE.

Overview

This tutorial introduces the Visual Studio IDE, and shows how to create a solution for a Windows application with a Windows form that says "Hello World".

Starting Visual Studio

To run this tutorial, you must have both Microsoft Visual Studio and Visual COBOL installed.

To start Visual Studio:

  1. On the Start menu, click Start > All Programs > Micro Focus Visual COBOL > Visual COBOL for Visual Studio 2010.
  2. You might be prompted to set the environment, depending on the version installed. If you are prompted, choose General development environment. In this setup Visual Studio is customized for work with COBOL projects.

The IDE is shown in the figure below, although the information displayed in the large pane will be different.

The large pane is where your solutions and projects will be opened. At the moment, this shows the Start Page, with up-to-date information on Visual Studio. When you start work, this is the pane where your code is displayed.

The pane at the bottom is the Output window, where messages from the IDE and Compiler are displayed.

The right-hand pane is the Solution Explorer, which displays the structure of your solution and projects. At the bottom of the Solution Explorer pane are some tabs. Solution Explorer appears by default.

If any of these panes is hidden, you can show it from the View menu.

Creating a Solution and a Project

The first task is to create a solution and a project. A solution is a container holding one or more projects that work together to create an application. The solution has the extension .sln and is a readable text file. Microsoft recommends that you do not edit the file outside of Visual Studio.

A COBOL project has the extension .cblproj and again is human readable but Microsoft recommends that you do not edit it. Different types of project have different extensions, so for example a C# project has the extension .csproj.

In this section, you create a project and solution, as follows:

  1. Start Visual Studio.
  2. Create a new project by clicking File > New > Project.
  3. In the New Project dialog, in the Installed Templates pane, expand COBOL and click Managed.
  4. In the Templates pane, select Windows Forms Application.

    The drop-down list above the Templates pane allows you to change the version of the target framework. Select the framework your clients are using to ensure your application includes classes and methods supported by it. You can leave the default .NET Framework for this demonstration.

  5. In the Name field at the bottom of the window, specify WinHello as the name of the project.

    Notice that the Name and Solution Name fields have the same name. Changing either of these automatically changes the other.

  6. In the Location field, browse to a directory where you want to put this tutorial.

    For example, if you create a folder on your c: drive called "Tutorials," change the location field to c:\tutorials. The solution will be stored in a subdirectory WinHello, according to the project name.

  7. Click OK.

This creates a solution, a project and an empty form, which is opened in the form designer. The Solution Explorer pane shows the WinHello project, which contains:

  • Properties, which contains the full project properties, including the resources for the form and references to some system packages, such as System.Windows.Forms, which support the system classes that the project uses.
  • References, which contains the references to assemblies containing classes that are used by the project and which enables you to add references to other .NET assemblies, COM objects registered on your machine as well as other assemblies that your .NET code refers to.
  • Form1.cbl, which contains your code for the form. Under the expanded Form1.cbl is Form1.Designer.cbl, which is created by the form designer. Don't edit this code, because this defines the form, and if you change it you might not be able to open the Design window. Also, any changes you make might be overwritten by the form designer.
  • Main.cbl, which contains the trigger program that displays the main form.

If you need to view the contents of the project directory, you can open it from the IDE as follows:

  • In Solution Explorer, right-click the WinHello project and choose Open Folder in Windows Explorer.

Painting a Button and a Label

This section "paints" a button and a label on the page or form.

  1. Paint a button as follows:
    • Click [image] or View > Toolbox.
    • If the Button object isn't listed, click Common Controls in the Toolbox.
    • Point to the Button object and drag it onto the page or form.
  2. Change the text on the button to "Say Hello", by editing the button's Text property, as follows:
    • Click on the button.
    • In the Appearance section of the Properties pane, scroll to the Text property.
    • Edit the text to Say Hello and press Enter.

      Notice that the Name property of the button (in the Design section of the Properties pane) is, and remains, "button1."

  3. Paint a label somewhere on the form by dragging the Label object in the same manner as you did the Button object.
  4. Clear the default text in the label, by deleting the text in the Text property field and pressing Enter.

    The label essentially disappears upon this action, but remains on the form, as you will see when you build and run the application. Notice that the name property of the label control is, and remains, Label1 (or label1).

Adding a Click Event Handler

Now, you add an event handler to display "Hello World" when the button is clicked.

  1. Create a click event handler for the button by double-clicking the button.

    This generates a method called button1_Click in the code.

    Look at the code for the button1_Click method. It is just a skeleton and does nothing. The procedure division is empty. We will look at the rest of the code when we have run the application.

  2. In the procedure division of the button1_Click method, insert the following line:
    move "Hello World!" to self::label1::Text
  3. or you could equally write:
    set self::label1::Text to "Hello World!"

    This moves the text "Hello World" into the Text property of the label you painted.

Building and Running the COBOL Application

There are two default build configurations for each project type: Debug and Release. These configurations define how to build the project for the different situations.

To build the project for debugging and to run it:

The Build menu offers the choice of building and rebuilding the solution, as well as building and rebuilding our project. The Build option builds only those files that have changed since they were last built. Whereas the Rebuild option builds all the files in the project, regardless of whether they have changed since they were last built.

To build and run the project:

  1. Check the build configuration in use, by clicking Build > Configuration Manager.
  2. In Active solution configuration, ensure Debug is selected and click Close.

    Notice in the Standard toolbar at the top of the IDE, that Debug shows as the active configuration.

  3. Click Build > Build WinHello.
  4. Check that the project compiled successfully by looking in the Output pane. To display this pane, click View > Output .
  5. Run the application, by clicking Debug > Start Without Debugging or [image].
  6. When the page or form displays, click the Say Hello button.

    The label should now say "Hello World!"

  7. Click the X at the top right to close the page or form.

Project References

When you create a project, the full project properties contain the references to assemblies containing classes that are used by the project, such as the System assembly and, for our Windows application, System.Windows.Forms. You can see this on the References page of the full project properties.

If you write code that uses other classes in other assemblies, you add the assemblies as references as follows:

  1. Right-click the WinHello project in Solution Explorer.
  2. Click Add Reference, or double-click the Properties folder in Solution Explorer and on the References tab, click Add.
  3. On the .NET tab in the Add Reference dialog box, you can select .NET Framework assemblies or other .NET assemblies. Scroll to MicroFocus to see the available Micro Focus assemblies.
  4. On the COM tab, you can select the COM objects that you have registered on your machine.
  5. On the Projects tab, you can select other assemblies that your .NET code refers to. There are currently none available to the project in this tutorial.
  6. Click OK when you have completed your selections.

For more information, see the Visual Studio Help.

Project Properties

Project properties define characteristics of the project and enable you to control a project's behavior, among other things.

Brief project properties are by default dynamically displayed in the Properties pane, below the Solution Explorer. Here are some tips on viewing brief project properties:

  • To see brief project properties, select the project or solution in the Solution Explorer. The Properties pane is displayed below the Solution Explorer, by default.
  • If the Properties pane is not visible, you can show it by clicking View (> Other Windows) > Properties Window.
  • A description of the selected property is displayed dynamically at the bottom of the Properties pane. To turn this description on and off, right-click in the toolbar of the Properties pane.

Full project properties are available by selecting the project in Solution Explorer and clicking Project > ProjName Properties. The full properties that you can specify for your native or managed project can apply to all configurations or only to the selected configuration, such as Debug or Release.

Assemblies

Each project is built into a code assembly.

Assemblies are documented in the Visual Studio Help, which describes them as "a collection of one or more files that are versioned and deployed as a unit. An assembly is the primary building block of a .NET Framework application. All managed types and resources are contained within an assembly and are marked either as accessible only within the assembly or as accessible from code in other assemblies.

Assemblies also play a key role in security. The code access security system uses information about the assembly to determine the set of permissions that code in the assembly is granted". For the basic concepts on assemblies see the Visual Studio Help.

Assemblies are created automatically when you build projects. You need to create a strong-named assembly if you want to include it in the Global Assembly Cache (GAC), which makes it secure and shareable among all the applications on your machine.

Examining the Generated Code

The form designer creates broadly-speaking two partial classes for the page or form. One partial class contains the generated code for your application, and you can edit and add to this. The other partial class is in the file Form1.Designer.cbl. It contains code owned by the designer, and you must not edit it.

The partial class containing the generated code contains, among other things:

  • A declaration of the class as a partial class such as the following for a Windows form:
       class-id WinHello.Form1 is partial
             inherits type System.Windows.Forms.Form.
  • The object Working Storage section. This allocates storage for the controls for the form, or more precisely, for object references for the controls.
  • The New method, which invokes the InitializeComponent method in the designer-owned partial class.
  • The button1_Click method, which you edited to say "Hello World."

Examining the Event Handlers in the Design View

When you double-click a control in the Design view, a click event handler is created and a method is inserted in the generated code. You created the Button1_Click event handler in this way.

You can rename the event handler and add and delete others.

Note: You must do this in the Design view and not in your application code. If you do it in the code, it might get overwritten when the code is regenerated from the design.

To change the name of the event handler:

  1. Display the Design view. One way to do this is to select the page or form in Solution Explorer, and then click View > Designer or View Design.
  2. Select the Say Hello button.
  3. In the Properties pane, display the events, by clicking [image].

    (The events are found in the Action section of this pane.) You can scroll through the events to see what is available.

  4. Change the name of the click event handler to readButton1_Click then press Enter.

    This adds a new method for readButton1_Click in Form1.cbl.

  5. Display the Design view again.
  6. Check the event handlers for Say Hello button.

    Note that there are now two click event handlers for the button in the drop-down list. You need to remove button1_Click event handler and move its functionality to readButton1_Click.

  7. Edit Form1.cbl and move the following code from the method for button1_Click to the procedure division of the method for readButton1_Click:
    set self::label1::Text to "Hello World!"
  8. Delete the method for button1_Click and save the file.
  9. Display the Design view again.
  10. There is now only one click event handler for Say Hello button - readButton1_Click.

Similarly, if you double-click a control by mistake (say on the label control), you generate an unwanted event handler. You cannot simply delete this event handler in the code view, because some event handler code is also in the design. Instead you need to delete the event handler in the design view. Do this in much the same way as you edited the name of the event handler, but instead delete the name.

Changing the Startup Form

This section adds another form and uses this as the startup form.

Notice that the form you created was called Form1. This form is opened when you run the application. If you rename the form, you also need to change the name of the form that starts the application. Similarly, if you delete this form, you need to specify another form as the startup form.

To demonstrate this, add another form and use this as the startup form, as follows:

  1. Create a second form similar to the first, as follows:
    1. Right-click the project in Solution Explorer.
    2. Click Add > New item.
    3. In the Add New Item dialog, click Managed under COBOL Items.
    4. Choose Windows Form and specify a name for the form, such as "HelloAgain."
    5. Click Add.
    6. Paint the form however you wish and add an event handler. You could paint a form similar to the Hello World one, but with slightly different text, such as "Hello again."
  2. Set the main form to the new form, by editing the lines that define and create the main form in the program main.cbl, as follows:
    1. Double-click Main.cbl in Solution Explorer.
    2. In the local-storage section, change from:
      01 mainForm type WinHello.Form1.

      to:

      01 mainForm type WinHello.HelloAgain.
    3. In the procedure division, change from:
      set mainForm to new WinHello.Form1()

      to:

      set mainForm to new WinHello.HelloAgain()
  3. Build and run the application.

Debugging the COBOL Project

The IDE provides debugging facilities, such as stepping, examining data item values and setting breakpoints. To see some of these facilities:

  1. On the toolbar, click Debug > Step Into , or Step Into button.

    If you are prompted to rebuild the project configurations, click Yes.

  2. You can see a yellow arrow at the left of the window pointing to the first line to be executed. Click Debug > Continue (or the green Continue arrow on the toolbar).

Close the IDE window now. You do not need to explicitly save anything, because the files are automatically saved when you build them.

Parent topic: Managed COBOL Tutorials


Tutorial: Creating Windows Forms in COBOL

Overview

This tutorial shows how to create a Windows form and how to make this interact with an existing COBOL program. The form is generated in managed COBOL. The form calls an intermediary program to map .NET data types onto COBOL data types. The intermediary program then calls the existing COBOL program to perform the business logic.

The solution has three programs:

  • Windows form. The Microsoft form designer enables you to create a Windows form in any .NET language, such as C# and COBOL. This tutorial shows how to generate these forms in .NET COBOL.
  • Existing COBOL program, the Book program. This program simulates a pre-existing COBOL program, which contains the business logic and which remains unchanged. This program is supplied and this tutorial adds it to the solution so that it is recompiled as managed code and exposed as a class that can be called by .NET managed code without needing any changes to the source.
  • Intermediary COBOL class, the BookWrapper program. This program acts as an interface between the client form and the pre-existing COBOL program. This intermediary class interfaces with the .NET client form using objects, and it interfaces with the existing COBOL using the standard COBOL PIC X data types. This intermediary class is supplied and this tutorial adds it to the solution.

Prerequisites

As a prerequisite step for this tutorial, you need to build the BookWrapper and LegacyBook projects that are part of the WinBook sample as follows:

  1. Click Start > All Programs > Micro Focus Visual COBOL > Samples to start the Samples Browser.
  2. Click Windows Forms in the left pane and then Win Book.
  3. Click Open sample in Visual Studio.
  4. In Solution Explorer, right-click WinBook solution and choose Build Solution.

The build creates two binaries, BookWrapper.dll and LegacyBook.dll, in the bin subfolder of the WinBook solution.

Start Painting the Form

In this section, you create a Windows form and then you paint the form. You can also examine the code generated.

  1. Create a managed Windows Forms project for .NET Framework 4.0 and choose or specify:
    • COBOL Managed Projects and Windows Forms Application
    • WinFormBook as the project name
    • Tutorials as the project location
    • WinBook as the solution name and check Create a directory for the solution
  2. Open main.cbl in the source editor.
  3. Add the following line of code as the first line of the procedure division for the static main method:
    invoke type System.Windows.Forms.Application::EnableVisualStyles()

    This applies the Visual Studio 2010 styles to your Windows form.

  4. Open the form in the designer.
  5. Paint four labels, three text boxes and one button on the form.
  6. Edit the properties of the controls, being careful to not double-click any of the controls. Double-clicking creates an event for the control, which we don't want to do till the next step. Edit the properties to the following values:
    Control | Name Property | Text Property
    Label | label1 | Stock Number
    TextBox | textBoxStockNo (the case is significant) | (blank)
    Label | label2 | Title
    TextBox | textBoxTitle (the case is significant) | (blank)
    Label | label3 | Price
    Label | label4 (the case is significant) | (blank)
    TextBox | textBoxPrice (the case is significant) | (blank)
    Button | button1 (the case is significant) | Read

    To display the properties right-click the label and then click Properties. You can then scroll to the relevant property and edit it.

  7. Create a click event for the Read button. Do this by double-clicking the button, which creates an event called button1_Click , and then displays the code that is generated for the form.
  8. Notice that the code for the button1_Click method doesn't do anything yet; the procedure division is empty. You can scroll through and review the rest of the generated code.
  9. You can build the form, by clicking Build > Build WinFormBook . You should have no errors.

For more information on the generated code, see the tutorial Tutorial: Developing .NET Managed COBOL.

Handle the Click Events

Now you need to add the code for the button click, which needs to call the legacy COBOL program and to populate the form with the information returned.

  1. In code view, find the button1_Click method. Update the code so that it reads as follows:
           method-id  button1_Click final private.
       local-storage section.
       01 input-string string.
       01 my-exception type System.Exception.
       procedure division using by value sender as object e as type System.EventArgs.
           set input-string to textBoxStockNo::Text
           try
               set my-book to type BookWrapper.Book::Read(input-string)
               invoke self::PopulateForm(my-book)
           catch my-exception
               invoke self::DisplayException(my-exception)
           end-try
       end method.
  2. Notice the red squigglies underlining some words. These indicate a syntax error from automatic parsing happening in the background. Hover over an underlined word and read the popup that gives information on the error. Notice that the status bar tells you the number of background parsing errors.
  3. Hover over the words error-message and display the popup, which says that it cannot find the PopulateForm method. Add the following methods to your code, after the button1_Click method and before the end class statement.
           method-id  PopulateForm final private.
       procedure division using my-book as type BookWrapper.Book.
           if my-book <> null
               set textBoxStockNo::Text      to my-book::StockNumber
               set textBoxTitle::Text        to my-book::Title
               set textBoxPrice::Text        to type System.Convert::ToString(my-book::RetailPrice)
           else
               set textBoxStockNo::Text      to "****"
               set textBoxTitle::Text        to "*************************************"
               set textBoxPrice::Text        to "****"
           end-if
       end method.
           method-id DisplayException private.
       procedure division using by value ex as type System.Exception.
           set label4::Text to ex::Message
           set my-book to null
           invoke self::PopulateForm(my-book)
       end method.

The remaining errors are all associated with my-book. We will clear when we have added the legacy code.

Add the Legacy Code and the Wrapper Code

You now need to add the existing COBOL code that contains the business logic, so that the form can use it. This code is supplied in a LegacyBook project containing book.cbl.

In addition, you need some wrapper code to convert the data from .NET types to COBOL types. The Windows form uses .NET data types; these are System.String objects in our case. The book program uses COBOL types such as PIC X and PIC 99V99. The supplied program BookWrapper.cbl does this conversion, and you need to add this to the solution.

The supplied files are in the %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples folder in the Forms subfolder. 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\<product name>\Samples.

To add book.cbl and BookWrapper.cbl:

  1. Copy the supplied LegacyBook and BookWrapper folders from the Forms folder into your tutorials directory.
  2. Add the BookWrapper project to the solution, as follows:
    1. Right-click the solution in the Solution Explorer.
    2. Click Add > Existing project.
    3. Browse to the BookWrapper folder, which is in the Forms folder.
    4. Select the project file BookWrapper.cblproj.
  3. Now add the LegacyBook project in the same way.
  4. Add a reference to the BookWrapper project in the WinFormBook project. To do this:
    1. Right-click the WinFormBook project in the Solution Explorer.
    2. Click Add Reference.
    3. Go to the Projects tab.
    4. Select BookWrapper and click OK.
  5. Confirm that when the two supplied projects are built, their built .dll files are stored in the bin directory for the project WinFormBook. For the BookWrapper project and then the LegacyBook project:
    1. In Solution Explorer, double-click the Properties folder in the project.
    2. Click the COBOL tab in the properties.
    3. Confirm that the Output Path is ..\bin\. You might need to adjust this relative path if your BookWrapper or LegacyBook directories are not siblings to the WinFormBook directory. Alternatively you can specify absolute paths.

Provide Access to the Legacy Code

You now need to add some code to the form to call the wrapper code and to clear the last of the red squigglies to do with my-book.

  1. Declare the data item my-book in object working storage, as follows:
           01 my-book   type BookWrapper.Book.

  2. You should now have no parsing errors, now that BookWrapper is declared. If you do have errors, check the supplied demonstration in Forms\ WinBook to see where yours differs.

  3. Set up an environment variable to point to the bookfile.* data files, which are supplied in BookData. To do this:
    1. Right-click the project WinFormBook and click Add > New Item.
    2. Click COBOL > managed in the Installed Templates pane.
    3. Select Application Configuration File.
    4. Click Add.

      This adds an App.config file to the WinFormBook project.

    5. In Solution Explorer, right-click App.config and choose Edit.
    6. Enter the following details on the Environment tab of the Application Settings dialog:
      • Enter dd_bookfile in the Name field, which is the prefix dd_ followed by the name of the data file as declared in the program book.cbl.
      • In the Value field, enter the path and filename for bookfile.dat. For example, enter:
        • A hardcoded path such as %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples\BookData\bookfile.dat.

          See Start > All Programs > Micro Focus Visual COBOL > Samples for the exact location of the samples on your machine.

    7. Click Set.
    8. Click OK.
    9. Click Yes in the dialog that appears to reload the App.config file in your solution.

Run the Application

You can now run the application.

  1. Build the project. Set the form project as the starting project.

    To do this right-click the WinFormBook project in the Solution Explorer and click Set as StartUp Project.

  2. Click Debug > Start without Debugging.
  3. Experiment entering information and using the Read button.

    You can read data for stock numbers 1111 and 2222.

Examine the Sample Code

The sample code is available in the Samples folder, with all the Visual Studio and .NET examples, and in the Forms subfolder.

Client Windows Form

The client Windows form Form1.cbl is generated as COBOL. The user enters data into the form and receives the return data there. The client form does the following:

  1. Extracts the input data from text boxes on the form as System.Strings.
  2. Calls BookWrapper passing it the string objects.
  3. Populates the text boxes on the form with the System.Strings.

Book Wrapper Program

The BookWrapper.cbl program acts as an intermediary between the pre-existing COBOL program book.cbl and the Windows form. This enables you to leave the pre-existing COBOL unchanged.

The important point here is that you need to use compatible types when mixing languages. The Windows form stores the data as .NET types and yet the Book program expects data as COBOL types.

The purpose of the BookWrapper program is to map your COBOL PICTUREs to .NET System.Strings. The program receives data from the Windows form as System.Strings, and maps them onto standard COBOL data types before passing them to the pre-existing book program.

The working storage declares the data items in a book record by using a copybook, as follows:

working-storage section.
        copy "book-rec-dotnet.cpy" replacing == (prefix) == by == book ==.
    ...

The copybook book-rec-dotnet.cpy declares the book-details record. It declares book-title and book-stockno as COBOL pictures and also as properties so that Getter/Setter methods can be used to access them. The copybook contains:

    01 (prefix)-details.
        03 (prefix)-text-details.
            05 (prefix)-title  pic x(50) property as "Title".
        ...
        03 (prefix)-stockno pic x(4) property as "StockNumber".

The following get property method gets a pointer to the book-details record:

       method-id get property "BookDetails".
       procedure division returning bookDetailsAddress as pointer.
           set bookDetailsAddress to address of book-details
           goback.
       end method.

The Read method is implemented as follows:

       method-id Read.
       local-storage section.
       01 file-status pic xx.
       procedure division using by value stockno-in as string
                          returning      myBook     as Book.

           set myBook to new  Book()
           set myBook::StockNumber to stockno-in

           call BookLegacy using by value readRecord
                                   by value myBook::BookDetails
                                   by reference file-status

           invoke RaiseExceptionIfError using file-status
           goback.
       end method.

Where:

  • procedure division using ...

    shows a .NET System.String, stockno-in, being passed in from client form. It also shows an instance of the Book class being returned. BookWrapper.cbl defines a new .NET type, Book, which can be used by programs written in any .NET language.

  • set myBook to new Book()

    creates a new instance of the BookWrapper class.

  • set mybook::StockNumber

    takes the data from the .NET System.String (stockno-in) and stores it as the StockNumber property of myBook. This property is declared in the copybook as a picture string, and so the data is stored as a standard COBOL data type in book-stockno. The COBOL Compiler implicitly converts the data from the .NET string into a COBOL usage display item (pic x).

  • call BookLegacy using ...

    calls the legacy program, book.cbl. It passes it the “BookDetails” property of myBook. If you look at the code in BookWrapper.cbl, you can see that what BookDetails does is pass a pointer to the BookRecord structure defined in book-rec-net.cpy. This structure matches the structure in the old book-rec.cpy, so what the legacy Book program sees is a book record being passed in by reference – which is what it expects. Book reads the stock number from this record, reads a record from the indexed file, and then puts the data in the other fields of the record.

  • invoke RaiseExceptionIfError using file-status

    checks the file status returned from reading the file, and raises a .NET exception if there was an error. Exceptions are the standard .NET mechanism for signaling error conditions.

Legacy Book Program

The book.cbl program is a long-standing demonstration program that has been shipped with Micro Focus products for several years. It is written in procedural COBOL. The program reads and writes to an indexed file containing book records.

In this solution, the Book program is recompiled to managed code without any changes. Recompiling the program exposes it as a class and exposes its main entry point as a static method.

The program's Linkage section defines data as standard COBOL types, such as PIC X, which non-COBOL client programs will not understand. These types need to be mapped to .NET compatible types before communication with the client program. This mapping is done by the intermediary program BookWrapper.cbl.

Parent topic: Managed COBOL Tutorials
Related concepts
Windows Forms


Tutorial: Developing Web Application Projects

Overview

This tutorial shows how to create a Web application project and how to make it interact with an existing COBOL program. The project includes a page that is generated in managed COBOL. The page calls an intermediary program to map .NET data types onto COBOL data types. The intermediary program then calls the existing COBOL program to perform the business logic.

The Web application project has three programs:

  • A Web page. The Microsoft form designer enables you to create a Web page (also known as a Web form) in any .NET language, such as C# and COBOL. This tutorial shows how to generate these forms in .NET COBOL.
  • Existing COBOL program, the Book program. This program simulates a pre-existing COBOL program, which contains the business logic and which remains unchanged. This program is supplied and this tutorial adds it as a reference to the Web application project so that it is recompiled as managed code and exposed as a class that can be called by .NET managed code without needing any changes to the source.
  • Intermediary COBOL class, the BookWrapper program. This program acts as an interface between the client form and the pre-existing COBOL program. This intermediary class interfaces with the .NET client form using objects, and it interfaces with the existing COBOL using the standard COBOL PIC X data types. This intermediary class is supplied and this tutorial adds it as a reference to the Web application project.

Create a Web Application Project

The first task is to create a Web Application Project, which you do as follows:

  1. Start Visual Studio.
  2. Create a new Web Application Project by clicking File > New > Project.
  3. Click COBOL in the Installed Templates pane and choose Web.
  4. Ensure .NET Framework 4 is selected in the dropdown list above the Installed Templates pane.
  5. Select ASP.NET Web Application.
  6. Specify a name such as BookDemoWebApplication.
  7. Specify a location to store the project on your file system such as c:\tutorials.
  8. Uncheck Create Directory for Solution.
  9. Click OK.

This creates the BookDemoWebApplication project, which is shown in the Solution Explorer. The project includes:

  • App_Data, which is an empty folder for holding application data
  • Default.aspx, which is the trigger program that displays the main form
  • Default.aspx.cbl, which contains your code for the form
  • Web.config, which is the application configuration file

Add the Legacy Code and the Wrapper Code

You now need to add the existing COBOL code that contains the business logic, so that the form can use it. This code is supplied in a LegacyBook project containing book.cbl.

In addition, you need some wrapper code to convert the data from .NET types to COBOL types. The project uses .NET data types; these are System.String objects in our case. The book program uses COBOL types such as PIC X and PIC 99V99. The supplied program BookWrapper.cbl does this conversion, and you need to add this to the solution.

The supplied files are in the %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples and in the Forms subfolder. 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\<product name>\Samples.

To include dependant code in your Web application project, you need to add a reference to the code in your solution as follows:

  1. Right-click the solution in Solution Explorer.
  2. Click Add > Existing Project.
  3. Navigate to the Forms\BookWrapper subfolder in the Samples directory.
  4. Select the .cblproj file and click Open.
  5. Similarly, add the LegacyBook project from the Forms\LegacyBook subfolder in the Samples.
  6. Add the two projects as references to the BookDemoWebApplication project as follows:
    • Right-click BookDemoWebApplication in Solution Explorer.
    • Click Add > Add Reference.
    • Click the Projects tab.
    • Select BookWrapper and click OK.
    • Add LegacyBook to the project references in the same way.

Provide Access to the Legacy Code

You now need to add some code to the form to call the wrapper code and to clear the last of the red squigglies to do with my-book.

  1. In the Default.aspx.cbl file, declare the data item my-book in the working storage, as follows:
           01 my-book   type BookWrapper.Book.
  2. Rebuild the entire solution.

    You should have no parsing errors, now that BookWrapper is declared. If you do have errors, check the supplied demonstration in the Forms\BookDemoWebApplication subfolder of the Samples to see where yours differs.

  3. In Solution Explorer, right-click the Web.config file in the BookDemoWebApplication project.
  4. Click Open.
  5. In the Web.config file, add the following configuration sections after the opening tag line that starts with <configuration>:
    <!--The following code declares a section group for application configuration -->
  <configSections>
    <sectionGroup name="MicroFocus.COBOL.Application">
      <section name="Switches" type="System.Configuration.NameValueSectionHandler" />
      <section name="Environment" type="System.Configuration.NameValueSectionHandler" />
    </sectionGroup>
    <sectionGroup name="MicroFocus.COBOL.Runtime">
      <section name="Tunables" type="System.Configuration.NameValueSectionHandler" />
      <section name="Switches" type="System.Configuration.NameValueSectionHandler" />
    </sectionGroup>
  </configSections>
  6. Set up an environment variable to point to the bookfile.* data files, which are supplied in the Samples\BookData directory. To do this:

    In the Web.config file, add the following text immediately after the </configSections> line:

    <appSettings />
<MicroFocus.COBOL.Application>
      <Switches/>
      <Environment>
         <add key="dd_bookfile" value="MyPath\bookfile.dat"/>
      </Environment>
   </MicroFocus.COBOL.Application>

    Where MyPath is the full path to the data file bookfile.dat, which is in the BookData subfolder in the Samples directory.

Start Painting the Form

In this section, you paint the form. You can also examine the code generated. For basic help on painting a form, see the tutorial Tutorial: Developing .NET Managed COBOL.

  1. Display the empty form by right-clicking Default.aspx in the Solution Explorer and clicking View Designer.
  2. Paint a number of labels, text boxes and a button as detailed in the table below.

    To lay out the Web form, use spaces and new lines, in the same way as you do in a text editor or in HTML.

  3. Edit the properties of the controls, being careful to not double-click any of the controls. Double-clicking creates an event for the control, which we don't want to do till the next step. Edit the properties to the following values:
    Control | ID Property | Text Property
    Label | label1 | CATALOG SEARCH
    Label | catalogueNumberLabel | Catalog Number
    TextBox | textBoxStockNo (the case is significant) | (blank)
    Button | searchButton | (blank)
    Label errorLabel File Status

    Also, set the Visible property to False.

    TextBox errorField (blank)

    Also, set the Visible property to False.

    Label | label2 | RESULTS
    Label | titleLabel | Title
    TextBox | textBoxTitle (the case is significant) | (blank)
    Label | authorLabel | Author
    TextBox | textBoxAuthor | (blank)
    Label | typeLabel | Type
    TextBox | textBoxType | (blank)
    Label | priceLabel | Price
    TextBox | textBoxPrice (the case is significant) | (blank)
    Label | soldLabel | Sold
    TextBox | textBoxSold | (blank)
    Label | onHandLabel | On Hand
    TextBox | textBoxOnhand | (blank)
    Label | stockValueLabel | Stock Value
    TextBox | textBoxStockValue | (blank)

    To display the properties right-click the label and then click Properties. You can then scroll to the relevant property and edit it.

  4. Create a click event for the Search button. Do this by double-clicking the button, which creates an event called searchButton, and then displays the code that is generated for the form.
  5. Notice that the code for the searchButton method doesn't do anything yet; the procedure division is empty. You can scroll through and review the rest of the generated code.
  6. You can build the solution, by selecting it in Solution Explorer and choosing Build > Build Solution. You should have no errors.

Handle the Click Events

Now you need to add the code for the button click, which needs to call the legacy COBOL program and to populate the form with the information returned.

  1. In code view, find the searchButton method. Update the code so that it reads as follows:
           method-id searchButton_Click protected.
       working-storage section.
       01 aBook type BookWrapper.Book.
       01 anException type System.Exception.

       local-storage section.

       procedure division using by value lnkSender as object by value lnkEvent as type EventArgs.
       try
           set aBook to type BookWrapper.Book::Read(textBoxStockNo::Text)
           invoke self::PopulateForm(aBook)
       catch anException
           invoke self::DisplayException(anException)
       end-try

       end method.
  2. Notice the red squigglies underlining some words. These indicate a syntax error from automatic parsing happening in the background. Hover over an underlined word and read the popup that gives information on the error. Notice that the status bar tells you the number of background parsing errors.
  3. Notice that the above code invokes the PopulateForm and the DisplayException method. Add the following methods to your code, after the searchButton method and before the end class statement.
           method-id  PopulateForm final private.
       procedure division using aBook as type BookWrapper.Book.

           if aBook <> null
               set errorLabel::Visible to false
               set errorField::Visible to false
               set textBoxStockNo::Text    to aBook::StockNumber
               set textBoxTitle::Text      to aBook::Title
               set textBoxAuthor::Text     to aBook::Author
               set textBoxType::Text       to aBook::Type
               set textBoxPrice::Text      to type System.Convert::ToString(aBook::RetailPrice)
               set textBoxOnhand::Text     to type System.Convert::ToString(aBook::NumberOnHand)
               set textBoxSold::Text       to type System.Convert::ToString(aBook::NumberSold)
               set textBoxStockValue::Text to type System.Convert::ToString(aBook::StockValue)
           else
               set textBoxStockNo::Text    to "****"
               set textBoxTitle::Text      to "*************************************"
               set textBoxAuthor::Text     to "*************************************"
               set textBoxType::Text       to "****"
               set textBoxPrice::Text      to "****"
               set textBoxOnhand::Text     to "****"
               set textBoxSold::Text       to "****"
           end-if

       end method.
           method-id DisplayException private.
       procedure division using by value lnkException as type System.Exception.
           set my-book to null
           set errorLabel::Visible to true
           set errorField::Visible to true
           set errorField::Text to lnkException::Message
           invoke self::PopulateForm(my-book)
       end method.

Run the Application

You can now run the application.

  1. Right-click BookDemoWebApplication in Solution Explorer.
  2. Select Rebuild.
  3. Click Debug > Start Without Debugging.
  4. Experiment entering information and using the Search button.

    You can search for data for catalog numbers 1111 and 2222.

Examine the Sample Code

The sample code is available in the Samples folder, with all the Visual Studio and .NET examples, and in the Forms subfolder.

Legacy Book Program

The book.cbl program is a long-standing demonstration program that has been shipped with Micro Focus products for several years. It is written in procedural COBOL. The program reads and writes to an indexed file containing book records.

In this solution, the Book program is recompiled to managed code without any changes. Recompiling the program exposes it as a class and exposes its main entry point as a static method.

The program's Linkage section defines data as standard COBOL types, such as PIC X, which non-COBOL client programs will not understand. These types need to be mapped to .NET compatible types before communication with the client program. This mapping is done by the intermediary program BookWrapper.cbl.

Client Web Form

The client Web form Default.aspx.cbl is generated as COBOL. The user enters data into the form and receives the return data there. The client form does the following:

  1. Extracts the input data from text boxes on the form as System.Strings.
  2. Calls BookWrapper passing it the string objects.
  3. Populates the text boxes on the form with the System.Strings.

Book Wrapper Program

The BookWrapper.cbl program acts as an intermediary between the pre-existing COBOL program book.cbl and the Web form. This enables you to leave the pre-existing COBOL unchanged.

The important point here is that you need to use compatible types when mixing languages. The Web form stores the data as .NET types and yet the Book program expects data as COBOL types.

The purpose of the BookWrapper program is to map your COBOL PICTUREs to .NET System.Strings. The program receives data from the Web form as System.Strings, and maps them onto standard COBOL data types before passing them to the pre-existing book program.

The working storage declares the data items in a book record by using a copybook, as follows:

working-storage section.
        copy "book-rec-dotnet.cpy" replacing == (prefix) == by == book ==.
    ...

The copybook book-rec-dotnet.cpy declares the book-details record. It declares book-title and book-stockno as COBOL pictures and also as properties so that Getter/Setter methods can be used to access them. The copybook contains:

    01 (prefix)-details.
        03 (prefix)-text-details.
            05 (prefix)-title  pic x(50) property as "Title".
        ...
        03 (prefix)-stockno pic x(4) property as "StockNumber".

The following get property method gets a pointer to the book-details record:

       method-id get property "BookDetails".
       procedure division returning bookDetailsAddress as pointer.
           set bookDetailsAddress to address of book-details
           goback.
       end method.

The Read method is implemented as follows:

       method-id Read.
       local-storage section.
       01 file-status pic xx.
       procedure division using by value stockno-in as string
                          returning      myBook     as Book.

           set myBook to new  Book()
           set myBook::StockNumber to stockno-in

           call BookLegacy using by value readRecord
                                   by value myBook::BookDetails
                                   by reference file-status

           invoke RaiseExceptionIfError using file-status
           goback.
       end method.

Where:

  • procedure division using ...

    shows a .NET System.String, stockno-in, being passed in from client form. It also shows an instance of the Book class being returned. BookWrapper.cbl defines a new .NET type, Book, which can be used by programs written in any .NET language.

  • set myBook to new Book()

    creates a new instance of the BookWrapper class.

  • set mybook::StockNumber

    takes the data from the .NET System.String (stockno-in) and stores it as the StockNumber property of myBook. This property is declared in the copybook as a picture string, and so the data is stored as a standard COBOL data type in book-stockno. The COBOL Compiler implicitly converts the data from the .NET string into a COBOL usage display item (pic x).

  • call BookLegacy using ...

    calls the legacy program, book.cbl. It passes it the “BookDetails” property of myBook. If you look at the code in BookWrapper.cbl, you can see that what BookDetails does is pass a pointer to the BookRecord structure defined in book-rec-net.cpy. This structure matches the structure in the old book-rec.cpy, so what the legacy Book program sees is a book record being passed in by reference – which is what it expects. Book reads the stock number from this record, reads a record from the indexed file, and then puts the data in the other fields of the record.

  • invoke RaiseExceptionIfError using file-status

    checks the file status returned from reading the file, and raises a .NET exception if there was an error. Exceptions are the standard .NET mechanism for signaling error conditions.

Parent topic: Managed COBOL Tutorials
Related concepts
Web Application Projects


Tutorial: Creating Web Forms in COBOL

Overview

This tutorial shows how to create a Web page and how to make this interact with an existing COBOL program. The page is generated in managed COBOL. The page calls an intermediary program to map .NET data types onto COBOL data types. The intermediary program then calls the existing COBOL program to perform the business logic.

The Web Site has three programs:

  • Web page. The Microsoft form designer enables you to create a Web page (also known as a Web form) in any .NET language, such as C# and COBOL. This tutorial shows how to generate these forms in .NET COBOL.
  • Existing COBOL program, the Book program. This program simulates a pre-existing COBOL program, which contains the business logic and which remains unchanged. This program is supplied and this tutorial adds it to the Web Site so that it is recompiled as managed code and exposed as a class that can be called by .NET managed code without needing any changes to the source.
  • Intermediary COBOL class, the BookWrapper program. This program acts as an interface between the client form and the pre-existing COBOL program. This intermediary class interfaces with the .NET client form using objects, and it interfaces with the existing COBOL using the standard COBOL PIC X data types. This intermediary class is supplied and this tutorial adds it to the Web Site.

Prerequisites

As a prerequisite step for this tutorial, you need to build the BookWrapper and LegacyBook projects that are part of the WinBook sample as follows:

  1. Click Start > All Programs > Micro Focus Visual COBOL > Samples to start the Samples Browser.
  2. Click Windows Forms in the left pane and then Win Book.
  3. Click Open sample in Visual Studio.
  4. In Solution Explorer, right-click WinBook solution and choose Build Solution.

The build creates two binaries, BookWrapper.dll and LegacyBook.dll, in the bin subfolder of the WinBook solution.

Create a Web Site

The first task is to create a Web Site, which you do as follows:

  1. Start Visual Studio.
  2. Create a new Web Site by clicking File > New > Web Site.
  3. Click COBOL in the Installed Templates pane.
  4. Ensure .NET Framework 4 is selected in the dropdown list above the Installed Templates pane.
  5. Select ASP.NET Web Site.
  6. In the Web location field, select File System and browse to a directory where you want to put this tutorial, and specify the directory WebBook.
  7. Click OK.

This creates the WebBook Web Site, which is shown in the Solution Explorer. The Web Site contains:

  • App_Data, which is an empty folder for holding application data
  • Default.aspx, which is the trigger program that displays the main form
  • Default.aspx.cbl, which contains your code for the form
  • Web.config, which is the application configuration file

A Web Site appears in the solution explorer in a similar way to a project, but a Web Site is not a project. It is a directory, which enables you to publish the Web Site simply. For full details see the Visual Studio Help, such as the topic .NET Development\Web Applications. This tutorial shows some of the other differences, which include:

  • A Web Site does not have extensive project properties, but has Web configuration settings in the Web.config file. You use the Web.config file to specify the location of copybooks, copypath, which is added to the directives file or to the COBCPY environment variable.
  • To include dependant code in your Web Site, you add a reference to the code in the usual way, but the code appears in a Bin folder in your Web Site, rather than as a reference in your solution.
  • You can add Web pages of any language to the Web Site, because it is not a project and is therefore language independent.

Start Painting the Form

In this section, you paint the form. You can also examine the code generated. For basic help on painting a form, see the tutorial Tutorial: Developing .NET Managed COBOL.

  1. Display the empty form by right-clicking Default.aspx in the Solution Explorer and clicking View Designer.
  2. Paint four labels, three text boxes and one button on the form.

    To lay out the Web form, use spaces and new lines, in the same way as you do in a text editor or in HTML.

  3. Edit the properties of the controls, being careful to not double-click any of the controls. Double-clicking creates an event for the control, which we don't want to do till the next step. Edit the properties to the following values:
    Control | ID Property | Text Property
    Label | label1 | Stock Number
    TextBox | textBoxStockNo (the case is significant) | (blank)
    Label | label2 | Title
    TextBox | textBoxTitle (the case is significant) | (blank)
    Label | label3 | Price
    Label | label4 (the case is significant) | (blank)
    TextBox | textBoxPrice (the case is significant) | (blank)
    Button | button1 (the case is significant) | Search

    To display the properties right-click the label and then click Properties. You can then scroll to the relevant property and edit it.

  4. Create a click event for the Search button. Do this by double-clicking the button, which creates an event called button1_Click , and then displays the code that is generated for the form.
  5. Notice that the code for the button1_Click method doesn't do anything yet; the procedure division is empty. You can scroll through and review the rest of the generated code.
  6. You can build the form, by clicking Default.aspx in Solution Explorer and choosing Build > Build Page. You should have no errors.

Handle the Click Events

Now you need to add the code for the button click, which needs to call the legacy COBOL program and to populate the form with the information returned.

  1. In code view, find the button1_Click method. Update the code so that it reads as follows:
           method-id  button1_Click protected.
       local-storage section.
       01 input-string string.
       01 my-exception type System.Exception.
       procedure division using by value lnkSender as object lnkEvent as type System.EventArgs.
           set input-string to textBoxStockNo::Text
           try
               set my-book to type BookWrapper.Book::Read(input-string)
               invoke self::PopulateForm(my-book)
           catch my-exception
               invoke self::DisplayException(my-exception)
           end-try
       end method.
  2. Notice the red squigglies underlining some words. These indicate a syntax error from automatic parsing happening in the background. Hover over an underlined word and read the popup that gives information on the error. Notice that the status bar tells you the number of background parsing errors.
  3. Notice that the above code invokes the PopulateForm and the DisplayException method. Add the following methods to your code, after the button1_Click method and before the end object statement.
           method-id  PopulateForm final private.
       procedure division using my-book as type BookWrapper.Book.
           if my-book<>null
               set textBoxStockNo::Text      to my-book::StockNumber
               set textBoxTitle::Text        to my-book::Title
               set textBoxPrice::Text        to type System.Convert::ToString(my-book::RetailPrice)
           else
               set textBoxStockNo::Text      to "****"
               set textBoxTitle::Text        to "*************************************"
               set textBoxPrice::Text        to "****"
           end-if
       end method.
           method-id DisplayException private.
       procedure division using by value lnkException as type System.Exception.
           set label4::Text to lnkException::Message
           set my-book to null
           invoke self::PopulateForm(my-book)
       end method.

Add the Legacy Code and the Wrapper Code

You now need to add the existing COBOL code that contains the business logic, so that the form can use it. This code is supplied in a LegacyBook project containing book.cbl.

In addition, you need some wrapper code to convert the data from .NET types to COBOL types. The Web page uses .NET data types; these are System.String objects in our case. The book program uses COBOL types such as PIC X and PIC 99V99. The supplied program BookWrapper.cbl does this conversion, and you need to add this to the solution.

  1. Create a bin directory for the WebBook Web Site. To do this, right-click the Web Site in the Solution Explorer and click Add ASP.NET Folder > Bin.
  2. Add the prebuilt files for the supplied LegacyBook and BookWrapper programs. To do this, right click Bin in the Solution Explorer, click Add Existing Item and browse to Forms\WinBook\bin folder within the samples folder. Select the .dll files, and also the .pdb files in case you want to debug the application. The programs are now part of the Web Site.

Provide Access to the Legacy Code

You now need to add some code to the form to call the wrapper code and to clear the last of the red squigglies to do with my-book.

  1. Declare the data item my-book in object working storage, as follows:
           01 my-book   type BookWrapper.Book.

  2. You should now have no parsing errors, now that BookWrapper is declared. If you do have errors, check the supplied demonstration in Forms\WebBook to see where yours differs.

  3. In the Web.config file, add the following configuration sections after the opening tag line that starts with <configuration>:
    <!--The following code declares a section group for application configuration -->
  <configSections>
  <sectionGroup name="MicroFocus.COBOL.Application">
    <section name="Switches" type="System.Configuration.NameValueSectionHandler" />
    <section name="Environment" type="System.Configuration.NameValueSectionHandler" />
  </sectionGroup>
  <!--The following code declares a section group for run-time configuration -->
  <sectionGroup name="MicroFocus.COBOL.Runtime">
    <section name="Tunables" type="System.Configuration.NameValueSectionHandler" />
    <section name="Switches" type="System.Configuration.NameValueSectionHandler" />
  </sectionGroup>
</configSections>
  4. Set up an environment variable to point to the bookfile.* data files, which are supplied in WinBook. To do this:

    In the Web.config file, add the following text immediately after the </configSections> line:

    <appSettings />
<MicroFocus.COBOL.Application>
      <Switches/>
      <Environment>
         <add key="dd_bookfile" value="MyPath\bookfile.dat"/>
      </Environment>
   </MicroFocus.COBOL.Application>

    Where MyPath is the path to the data file bookfile.dat, which is in the bin subfolder of the WinBook sample. See the \Forms\WinBook\bin subfolder in the samples.

Run the Application

You can now run the application.

  1. Build the Web Site.
  2. Click Debug > Start without Debugging.
  3. Experiment entering information and using the Search button.

    You can search for data for stock numbers 1111 and 2222.

Examine the Sample Code

The sample code is available in the Samples folder, with all the Visual Studio and .NET examples, and in the Forms subfolder.

Legacy Book Program

The book.cbl program is a long-standing demonstration program that has been shipped with Micro Focus products for several years. It is written in procedural COBOL. The program reads and writes to an indexed file containing book records.

In this solution, the Book program is recompiled to managed code without any changes. Recompiling the program exposes it as a class and exposes its main entry point as a static method.

The program's Linkage section defines data as standard COBOL types, such as PIC X, which non-COBOL client programs will not understand. These types need to be mapped to .NET compatible types before communication with the client program. This mapping is done by the intermediary program BookWrapper.cbl.

Client Web Form

The client Web form Default.aspx.cbl is generated as COBOL. The user enters data into the form and receives the return data there. The client form does the following:

  1. Extracts the input data from text boxes on the form as System.Strings.
  2. Calls BookWrapper passing it the string objects.
  3. Populates the text boxes on the form with the System.Strings.

Book Wrapper Program

The BookWrapper.cbl program acts as an intermediary between the pre-existing COBOL program book.cbl and the Web form. This enables you to leave the pre-existing COBOL unchanged.

The important point here is that you need to use compatible types when mixing languages. The Web form stores the data as .NET types and yet the Book program expects data as COBOL types.

The purpose of the BookWrapper program is to map your COBOL PICTUREs to .NET System.Strings. The program receives data from the Web form as System.Strings, and maps them onto standard COBOL data types before passing them to the pre-existing book program.

The working storage declares the data items in a book record by using a copybook, as follows:

working-storage section.
        copy "book-rec-dotnet.cpy" replacing == (prefix) == by == book ==.
    ...

The copybook book-rec-dotnet.cpy declares the book-details record. It declares book-title and book-stockno as COBOL pictures and also as properties so that Getter/Setter methods can be used to access them. The copybook contains:

    01 (prefix)-details.
        03 (prefix)-text-details.
            05 (prefix)-title  pic x(50) property as "Title".
        ...
        03 (prefix)-stockno pic x(4) property as "StockNumber".

The following get property method gets a pointer to the book-details record:

       method-id get property "BookDetails".
       procedure division returning bookDetailsAddress as pointer.
           set bookDetailsAddress to address of book-details
           goback.
       end method.

The Read method is implemented as follows:

       method-id Read.
       local-storage section.
       01 file-status pic xx.
       procedure division using by value stockno-in as string
                          returning      myBook     as Book.

           set myBook to new  Book()
           set myBook::StockNumber to stockno-in

           call BookLegacy using by value readRecord
                                   by value myBook::BookDetails
                                   by reference file-status

           invoke RaiseExceptionIfError using file-status
           goback.
       end method.

Where:

  • procedure division using ...

    shows a .NET System.String, stockno-in, being passed in from client form. It also shows an instance of the Book class being returned. BookWrapper.cbl defines a new .NET type, Book, which can be used by programs written in any .NET language.

  • set myBook to new Book()

    creates a new instance of the BookWrapper class.

  • set mybook::StockNumber

    takes the data from the .NET System.String (stockno-in) and stores it as the StockNumber property of myBook. This property is declared in the copybook as a picture string, and so the data is stored as a standard COBOL data type in book-stockno. The COBOL Compiler implicitly converts the data from the .NET string into a COBOL usage display item (pic x).

  • call BookLegacy using ...

    calls the legacy program, book.cbl. It passes it the “BookDetails” property of myBook. If you look at the code in BookWrapper.cbl, you can see that what BookDetails does is pass a pointer to the BookRecord structure defined in book-rec-net.cpy. This structure matches the structure in the old book-rec.cpy, so what the legacy Book program sees is a book record being passed in by reference – which is what it expects. Book reads the stock number from this record, reads a record from the indexed file, and then puts the data in the other fields of the record.

  • invoke RaiseExceptionIfError using file-status

    checks the file status returned from reading the file, and raises a .NET exception if there was an error. Exceptions are the standard .NET mechanism for signaling error conditions.

Parent topic: Managed COBOL Tutorials
Related concepts
Web Forms


Tutorial: Creating and Accessing WCF COBOL Services

Shows how to create and access WCF services in COBOL.

Overview and Demonstration Applications

The tutorial is based on the BookWrapper demonstrations supplied with this COBOL development system. The BookWrapper is an intermediary program which maps .NET data types onto COBOL data types. It then calls the existing COBOL program, book.cbl, to perform the business logic.

In this tutorial you expose the functionality of the BookWrapper program as a WCF service and use a console application as a client to communicate with it.

A more sophisticated version of the demonstration shown here is supplied in the Visual COBOL samples. To check the code, start Samples Browser and open the WCF Book Service and Client demonstration in the Windows Communication Foundation category.

Prerequisites

  • You need a complete version of Microsoft's Visual Studio 2010 as the Visual Studio 2010 Shell does not support WCF.

As a prerequisite step for this tutorial, you need to build the BookWrapper and LegacyBook projects that are part of the WinBook sample. To do this:

  1. Click Start > All Programs > Micro Focus Visual COBOL > Samples to start the Samples Browser.
  2. Click Windows Forms in the left pane and then Win Book.
  3. Click Open sample in Visual Studio.
  4. In Solution Explorer, right-click WinBook solution and choose Build Solution.

The build creates two binaries, BookWrapper.dll and LegacyBook.dll, in the bin subfolder of the WinBook solution.

Outline

In order to create and configure a WCF service and then use a client to access it, you need to:

  1. Create the WCF service.
  2. Define a service contract.
  3. Implement the service.
  4. Host and test the service.
  5. Create and configure a COBOL client application.
  6. Run the client and access the service.

Create a WCF Service Project

To start you need to create a solution to hold your WCF service and the client application:

  1. Click File > New > Project.
  2. Select COBOL > Managed in the Installed Templates pane.
  3. Select WCF Service Library.
  4. Specify a name such as WCFBook.
  5. Specify a location for your project and click OK.

Add the BookWrapper and the LegacyBook Demonstrations to the Solution

You need to add the program that includes the functionality to expose as a service to your solution. To do this:

  1. In Solution Explorer, right-click your solution and select Add > Existing Project.
  2. Navigate to the Forms\BookWrapper subfolder in the Visual COBOL samples.
  3. Select BookWrapper.cblproj and click OK.
  4. In a similar way, add the LegacyBook demonstration which is installed in the Forms\LegacyBook subfolder in the samples to your solution.

Add the BookWrapper and the LegacyBook projects as references in the WCFBook Project

To enable your service to access the functionality in the BookWrapper and the LegacyBook projects, you must add them as project references to the WCFBook project:

  1. In Solution Explorer, right-click the References folder in your WCFBook project.
  2. Select Add Reference.
  3. Click the Projects tab.
  4. Select the BookWrapper project and click OK.
  5. Add a reference to the LegacyBook in the same way.

Define the WCF Service Contract and Create the Service

  1. Rename the COBOL files in the WCFBook project as follows:
    • Service1.cbl to BookService.cbl
    • IService1.cbl to IBook.cbl
  2. Paste the code below in the IBook.cbl file. This defines the service and data contracts.
    • The methods that are marked with the System.ServiceModel.OperationContract() attribute define the operations from the BookWrapper program that are exposed through the service endpoints.
    • The WCFBookWrapper.Book class that is marked with the DataContract attribute exposes the data from the BookWrapper program.
           interface-id WCFBook.IBook
                     attribute System.ServiceModel.ServiceContract().

       method-id GetData public
           attribute System.ServiceModel.OperationContract().
       procedure division using by value the-value as binary-long
                          returning return-value as string.
       end method.

       method-id GetDataUsingDataContract public
           attribute System.ServiceModel.OperationContract().
       procedure division using by value stockNumber as string
                          returning return-value as type WCFBookWrapper.Book.

       end method.

       method-id Read public attribute System.ServiceModel.OperationContract().
       procedure division using by value stockNumber as string returning theBook as type WCFBookWrapper.Book.
       end method.

       end interface.

       class-id WCFBookWrapper.Book attribute DataContract().

       working-storage section.
       01 BookTitle string property as "Title" attribute DataMember().
       01 BookType string property as "Type" attribute DataMember().
       01 BookAuthor string property as "Author" attribute DataMember().
       01 BookStockno string property as "StockNumber" attribute DataMember().
       01 BookRetail decimal property as "RetailPrice" attribute DataMember().
       01 BookOnhand binary-long property as "NumberOnHand" attribute DataMember().
       01 BookSold binary-long property as "NumberSold" attribute DataMember().
       01 StockValue float-short property as "StockValue" attribute DataMember().

       method-id New.
       working-storage section.
       01 newBook type WCFBookWrapper.Book.
       procedure division using by value stdbook as type BookWrapper.Book.
           set BookTitle to stdbook::Title
           set BookType to stdbook::Type
           set BookAuthor to stdbook::Author
           set BookStockno to stdbook::StockNumber
           set BookRetail to stdbook::RetailPrice
           set BookOnhand to stdbook::NumberOnHand
           set BookSold to stdbook::NumberSold
           set StockValue to stdbook::StockValue
           goback.
       end method.

       end class.
  3. Paste the code below into the BookService.cbl file. This is the actual WCF service.
           class-id WCFBook.Service1
                 implements type WCFBook.IBook.

       working-storage section.

       method-id GetData public.
       procedure division using by value the-value as binary-long
                          returning return-value as string.
           set return-value to string::Format("You entered {0}" the-value)
           goback.
       end method.

       method-id GetDataUsingDataContract public.
       working-storage section.
       01 book type BookWrapper.Book.
       01 bookException type BookWrapper.BookException.
       procedure division using by value stockNumber as string
                          returning theBook as type WCFBookWrapper.Book.

           try
               set book to type BookWrapper.Book::Read(stockNumber)
               set theBook to new WCFBookWrapper.Book(book)
           catch bookException
               raise new System.ServiceModel.FaultException(bookException::Message)
           end-try
           goback.
       end method.

       method-id Read public.
       working-storage section.
       01 book type BookWrapper.Book.
       01 bookException type BookWrapper.BookException.
       procedure division using by value stockNumber as string returning theBook
as type WCFBookWrapper.Book.
           try
               set book to type BookWrapper.Book::Read(stockNumber)
               set theBook to new WCFBookWrapper.Book(book)
           catch bookException
               raise new System.ServiceModel.FaultException(bookException::Message)
           end-try
           goback.
       end method.

       end class.

Provide Access to the Legacy Code

Additionally, you need to configure your WCF the service to call the BookWrapper code as follows:

  1. Right-click the App.config file in your WCF service project and select Edit.
  2. Add the code below immediately after the opening <configuration> tag:
      <configSections>
    <!--The following code declares a section group for application configuration -->
    <sectionGroup name="MicroFocus.COBOL.Application">
      <section name="Switches" type="System.Configuration.NameValueSectionHandler" />
      <section name="Environment" type="System.Configuration.NameValueSectionHandler" />
    </sectionGroup>
    <!--The following code declares a section group for run-time configuration -->
    <sectionGroup name="MicroFocus.COBOL.Runtime">
      <section name="Tunables" type="System.Configuration.NameValueSectionHandler" />
      <section name="Switches" type="System.Configuration.NameValueSectionHandler" />
    </sectionGroup>
  </configSections>
  <MicroFocus.COBOL.Application>
    <Switches />
    <Environment>
      <add key="dd_bookfile" value="%Public%\Documents\Micro Focus\Product Name\Samples\BookData\bookfile.dat" />
    </Environment>
  </MicroFocus.COBOL.Application>
  3. Save and close the App.config file.
  4. Build the WCFBook project.

Configure the service endpoints

You need to configure the service endpoint details as follows:

  1. Right-click the App.config file in your WCF service project select Edit WCF Configuration.
  2. In the Microsoft Service Configuration Editor, expand WCFBook.Service1.
  3. Click Host.

    Note that the default base address of the service is localhost - Visual Studio hosts the service on your machine.

  4. Expand Endpoints and click on the first item in the group.

    This displays the general details of the endpoint - the address of the service, its binding and the service contract you want to expose - all known as the ABC of the endpoint. You need to configure the endpoint to use the IBook contract you defined earlier.

  5. On the General tab, click [image] on the row for Contract.
  6. Navigate to the \bin\Debug subfolder in the WCFBook project directory.
  7. Double-click the WCFBook.dll file.
  8. Select the WCFBook.IBook contract and click Open.
  9. Click the second item under Endpoints.

    This is the default endpoint that exposes metadata details about your service through the IMetaData Exchange contract.

  10. Click File > Save in the Configuration Editor and close the window.

Start and Test the Service

Visual Studio provides a built-in WCF Service Host application and a WCF Test Client application to help you test your service without your own client application. This is enabled by default on the WCF Options tab in the project properties.

  1. In Solution Explorer, right-click the WCFBook project and select Set as StartUp Project.
  2. Click Debug > Start Without Debugging.

    Visual Studio hosts your service in the WCF Service Host and loads it in the WCF Test Client application. The test client displays the endpoint for your service and the operations that are exposed.

  3. Double-click the GetDataUsingDataContract() operation.

    This displays the operation details and enables you to test the operation with various parameters.

  4. In the Request pane, change the value for stockNumber from null to 1111 and press Enter.
  5. Click Invoke.

    This displays the details about record 1111 in the BookWrapper application in the Response pane.

  6. Test the Read operation with other stock numbers. The valid numbers are 1111, 2222 and 3333.
  7. Close the WCF Test Client application.

Create a WCF Client Application

In the real world, you use various client applications to access services through their available endpoints. As part of this tutorial, you will create a simple managed console application that accesses the BookWrapper application through the WCF service contract and reads the records that it contains:

  1. In Solution Explorer, right-click the solution and select Add > New Project.
  2. Select the managed Console Application template.
  3. Specify a name such as WCFClient and click OK.

Add the WCF Service as a Service Reference to the Client

Visual Studio provides an easy way to use a WCF service in a client application. The Add Service Reference functionality adds the service to the client project and generates a proxy for the client to use.

  1. Start the WCF Service.
  2. Right-click the project for the client and choose Add Service Reference.
  3. Click Discover in the Add Service Reference dialog to locate the WCF service.
  4. In the Namespace field, rename the namespace for the service to WCFBook.
  5. Click OK.

Edit the Client Application

You need to program your WCF client so that it uses the exposed operations of the WCF service reference. In this tutorial, the client uses the Read operation to access the information in the BookWrapper application and displays the record for a specified stock number.

  1. Edit Program1.cbl in the project for the client application.
  2. Replace the code in the COBOL program with the following:
           program-id. Program1 as "WCFClient.Program1".

       data division.
       working-storage section.
       01 stock-no              string.
       01 bookClient            type WCFBook.BookClient.
       01 myBook                type WCFBook.Book.

       procedure division.

       invoke type System.Console::WriteLine("Enter a stock number and press Enter.")

       set stock-no to type System.Console::ReadLine()
       set bookClient to new WCFBook.BookClient
       set myBook to bookClient::Read(stock-no)

       invoke type System.Console::WriteLine(myBook::Title)
       invoke type System.Console::WriteLine(myBook::Type)
       invoke type System.Console::WriteLine(myBook::Author)
       invoke type System.Console::WriteLine(myBook::StockNumber)
       invoke type System.Console::WriteLine(myBook::RetailPrice)
       invoke type System.Console::WriteLine(myBook::NumberOnHand)
       invoke type System.Console::WriteLine(myBook::NumberSold)
       invoke type System.Console::WriteLine(myBook::StockValue)

       invoke type System.Console::WriteLine("Press Enter to exit.")
       invoke type System.Console::ReadLine()

                  goback.

       end program Program1.
  3. Click File > Save.

Configure the Client Endpoints

You need to configure the client so that it uses the WCF service endpoint and the service contract:

  1. Right-click the app.config file in the WCFClient project.
  2. Click Edit WCF Configuration.
  3. In the Configuration pane, expand Client and then Endpoints.
  4. Click WCHttpBinding_IBook.
  5. In the Client Endpoint pane and on the General tab, click [image] on the row for the Contract.
  6. Navigate to the \bin\Debug subfolder in the directory of the WCFService project.
  7. Double-click WCFBook.dll.
  8. Select the WCFBook.IBook contract and click Open.
  9. In the Microsoft Service Configuration Editor window, click File > Save.
  10. Close the configuration editor.

Use the Client to Access the Service

  1. Set the WCFClient project as the StartUp project for the entire solution.
  2. Click Debug > Start Debugging.

    This hosts the service in the WCF Service Host and starts the client.

  3. In the console, enter a valid stock number and press Enter.

    The record for that stock number is displayed.

Parent topic: Managed COBOL Tutorials
Related concepts
WCF and 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. Managed COBOL is the collective term for .NET COBOL and JVM 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: .il for the .NET framework.

Managed Code and Native Code

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

The compiler has now created an intermediate language (.il).

COBOL and all other .NET languages (for example C# and VB) compile to this format, which makes mixed language applications easy to write.

You can also create native code applications. In Visual Studio there are native COBOL project templates.

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 intermediate language (.il files) can be deployed to a Windows platform running Microsoft's Common Language Runtime (CLR) for execution.

All programs written for the .NET Framework are executed by the Microsoft's Common Language Runtime (CLR) which makes mixed language application programming seamless.

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

Developing Native and Managed Applications

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

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

.NET COBOL applications are deployed to Windows platforms running Microsoft's CLR.

Parent topic: Getting Started


Moving Existing Native COBOL Applications into Visual COBOL IDE

Visual COBOL provides a number of ways to import and edit existing native COBOL code.

Native COBOL applications developed and built using previous Micro Focus products can be developed and built with Visual COBOL.

Generally, the process of moving existing native COBOL code into Visual COBOL is as follows:

  1. You create a native Visual Studio project to hold your source code or add the files to an existing native project. These are the tools and commands that you can use for this:
    Net Express Project Import Wizard
    Helps you convert existing Net Express projects into Visual Studio solutions. To invoke the wizard, click File > New > Solution from Net Express Project.
    Create Project from Existing Files wizard
    Guides you step by step in choose the type of project to hold your existing code and lets you specify the files to import. During the import, the IDE scan the files to determine whether they are COBOL programs or copybooks, and sets directives for each imported file as appropriate.
    To invoke the wizard, click File > New > Project From Existing Code.
    Add Existing COBOL Items dialog
    Enables you to add your COBOL files and copybooks to an existing project. During the import, the IDE scan the files to determine whether they are COBOL programs or copybooks, and sets directives for each imported file as appropriate.
    To invoke the dialog, right-click the project in Solution explorer and select Add Existing COBOL Items.
    Add Existing Items command
    Enables you to add your source files to an existing native project but does not set any directives on them.
    Right-click the project in Solution Explorer and select Add > Existing Item.
  2. Resolve any compiler errors caused by your source code. The following window can help you track and resolve issues in the files:
    Project Details Window
    Shows a list of the files in the project or the entire solution. Lets you sort the files by various file details to help track any issues
    Right-click the project or the solution in Solution explorer and select Project Details.
  3. Subdivide your project into several projects if needed with the help of the following dialog:
    Create Project from Selection dialog
    Use this to create new projects in your solution and move some of the source files to them. This can be helpful if you need to move code to a dynamic library project.
    In Solution Explorer, select the files which you want to move in a new project, right-click the selection and choose Create Project.
  4. Configure the project and the file properties as needed.
  5. Build and debug the project.
Parent topic: Getting Started
Related concepts
Creating COBOL Projects from Existing Code
Adding Existing COBOL Items to a Project
Building COBOL Applications
Debugging Native COBOL Programs
Exploring Your COBOL Projects and Solutions
To set COBOL project properties
To specify file properties
To reset the directives on COBOL files
Importing Net Express Projects into Visual COBOL for Visual Studio


Managing Licenses

To manage your product licenses you need to use the Micro Focus Licensing Administration tool. The tool allows you to authorize, view and revoke licenses. You can set up your license locally or request a license from, if your site is using one, a central license server.

Depending on your product configuration, you might, when you first install your product, have a trial license. During this period, if you have not already authorized your product with your authorization code, a dialog box will be displayed on product startup providing the opportunity to authorize your product. You can use the Micro Focus Licensing Administration tool to find out how many days remain on your license. You will not be able to use your product if, at the end of the trial license period, you have not authorized it with your authorization code.

If your product does not have a trial license, you must authorize it before you can use it.

Some licensing tasks require Internet connectivity from your computer. For example, when you authorize your product a connection is made with a Micro Focus server to verify the authorization code you have used and return a license code string. Similarly, the revoke license process uses a Micro Focus server to revoke the existing license and then provide a new authorization code. Where Internet connectivity is required, it is highlighted in the relevant task help.

For more on licensing, see Licensing in the Visual COBOL help.

Parent topic: Welcome
Related concepts
Licensing


Samples Browser

Samples Browser provides quick access to all samples shipped with your COBOL development system.

To open Samples Browser, click Start > All Programs > Micro Focus Visual COBOL > Samples.

The Samples Browser Interface

  • 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 in Visual Studio to load the sample in Visual Studio so you can build and experiment with it.
  • Click Open sample folder to open the directory containing the files of the sample in Windows Explorer.

The Samples Browser Demonstration

You can explore the code of the application as Samples Browser is also provided as a demonstration program in the Samples folder (%PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples on Windows Vista and Windows 7).

See the following for how to build the Samples Browser project in the Samples and how to add it as a menu command to the Visual Studio Tools menu:

  • To build the Samples Browser demonstration
  • To add Samples Browser to the Visual Studio Tools menu
Parent topic: Welcome
Related information
Demonstrations of .NET COBOL
Demonstrations of Native COBOL
Tutorials on COBOL in the Visual Studio IDE
To build the Samples Browser demonstration
To add Samples Browser to the Visual Studio Tools menu


To build the Samples Browser demonstration

  1. Start Visual Studio.
  2. Click Start > All Programs > Micro Focus Visual COBOL > Samples.
  3. Click Windows Forms in the left pane and then Samples Browser.
  4. Click Open sample in Visual Studio.
  5. Choose Debug > Start Without Debugging.

    Visual Studio builds the solution and starts the Samples Browser dialog form.

Parent topic: Samples Browser
Related information
To add Samples Browser to the Visual Studio Tools menu
Samples Browser


To add Samples Browser to the Visual Studio Tools menu

  1. Build Samples Browser which is supplied with the Samples - see To build the Samples Browser demonstration.

    The build creates an executable file, SamplesBrowser.exe, in the \debug\bin subfolder in the directory of the Samples Browser solution.

  2. In Visual Studio, choose Tools > External Tools.
  3. Click Add on the External Tools dialog.
  4. Type a name for your custom tool such as MF Samples Browser, in the Title field.
  5. Click [image] next to the Command field.
  6. Browse to the \debug\bin subfolder of the Samples Browser project.
  7. Select SamplesBrowser.exe and click Open.
  8. Ensure Prompt for arguments is not checked.
  9. Click OK.
  10. Open the Tools menu.

    MF Samples Browser is now available as a menu item.

  11. Choose Tools > MF Samples Browser to start Samples Browser.
Parent topic: Samples Browser
Related information
To build the Samples Browser demonstration
Samples Browser


Demonstrations of .NET COBOL

We provide a number of demonstration programs designed to help you to better understand some of the concepts involved when working with COBOL projects in Visual Studio.

The demonstration programs are installed in subfolders under %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples 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\<product name>\Samples.

You can access the demonstrations with the help of Samples Browser - click Start > All Programs > Micro Focus Visual COBOL > Samples.

To view the demonstrations for managed code, select Show managed only from the list in the upper left corner of Samples Browser.

The following demonstrations are supplied:

COBOL Book
C# WinBook
Demonstrates how C# can interoperate with managed COBOL. The SmartLinkage functionality enables you to expose COBOL group items as managed types so that other managed languages can interoperate with them.
WCF Book Service and Client
Demonstrates how to create a WCF service and a COBOL client that accesses the service.
Web Application Book
A Web Application project which contains a Web form. The form provides a .NET interface to an existing COBOL program. The BookClass project provides a proxy COBOL program that calls the existing COBOL Book program.
Web Site Book
Shows how to create a Web Forms page to provide a .NET interface to an existing COBOL program. The BookClass project provides a proxy COBOL program that calls the existing COBOL Book program.
Win Book
Shows how to create a Windows form to provide a .NET interface to an existing COBOL program. The BookClass project provides a proxy COBOL program that calls the existing COBOL Book program.
WPF Book
Demonstrates the use of Windows Presentation Foundation (WPF).
COBOL for .NET
Core.Net
Core.NET introduces some of the standard features of the .NET Framework you need to be aware of, and any new COBOL syntax in order to support these features.
All other samples for COBOL for .NET
Each of the demonstrations shows how to use the corresponding COBOL feature within the .NET framework.
Convert ACU and RM to MF
ACU to MF Data Conversion
The solution builds the ACU2MFDataMigration.exe - a utility that converts an ACU Vision indexed file or directory of files to Micro Focus indexed files. You can use executable as delivered, or modify and rebuild the source code as desired.
RM to MF Data Conversion
The solution builds to RMMFDataMigration.exe and RM2MFconvert.dll which enable you to convert an RM/COBOL indexed file or directory of files to Micro Focus indexed files. You can use the executables as delivered, or modify and rebuild the source code as desired.
Games
COBOL Blitz
Demonstrates the use of Windows forms, enumeration types, inheritance, and of sounds and graphics.
COBOLDoKu
Demonstrates Windows Forms using a .NET user control.
COBOL Tic-Tac-Toe
Demonstrates how to use WPF from aVisual COBOL application.
Help Generation
Sandcastle Integration
Demonstrates how to integrate the Microsoft Sandcastle utility in the build process and generate a CHM help file from the XML documentation comments in your managed source code. Before running this demonstration you must have Sandcastle installed. Download the utility from the Microsoft Download Center.
SQL
SQL (Managed OESQL) - Getting Started
Demonstrates how to use static SQL with OpenESQL under ADO.NET, performing a variety of SQL operations. It also demonstrates the use of different styles of CONNECT statement.
SQL (Managed OESQL) - Connected Demo
Fills a DataSet from a data source, modifies the DataSet and then synchronizes the changes in the DataSet with the data source. The modified contents of the DataSet are displayed in the Output Window. To execute this demonstration, you must first download and install the SQL Server Northwind database from the Microsoft Web site, http://www.microsoft.com. Once there, enter the following search criteria to locate the appropriate download page: northwind pubs database download
SQL (Managed OESQL) - Cursor Demo
Demonstrates how to mix OpenESQL with direct calls to ADO.NET.
SQL (Managed OESQL) - Disconnected Demo
Manipulates offline data in a DataSet. The results of the data manipulation are displayed in the Output Window.
SQL (Managed OESQL) - LOB Demo
Demonstrates how ADO.NET can be used in mixed language projects to insert and select large objects (LOBs). LobDemo shows OpenESQL working with LOB columns in a SQL Server table.
SQL (Managed OESQL) - OrderStatus Demo
Demonstrates how ADO.NET can be used in mixed language projects, and uses COBOL and C#.
SQL (Managed OESQL) - Web Application Book
Includes a COBOL Web Application Project which contains a Web form. The form calls an intermediary program, SqlBookWrapper.cbl, which maps .NET data types onto COBOL data types. The intermediary program then calls the existing COBOL program, sqlbook.cbl, to perform the business logic.
SQL (Managed OESQL) - WPF Book
Includes a Windows Presentation Foundation (WPF) interface written in managed COBOL that interacts with an existing COBOL program. The form calls an intermediary program, SqlBookWrapper.cbl, which maps .NET data types onto COBOL data types. The intermediary program then calls the existing COBOL program, sqlbook.cbl, to perform the business logic.
SQL (Native OESQL) - Getting Started
Demonstrates how to use static SQL with OpenESQL, performing a variety of SQL operations. It also demonstrates the use of different styles of CONNECT statement.
SQL (Native OESQL) - Behavior Demo
Illustrates the use of OpenESQL compiler directives to assist in migrating database applications from the mainframe. The use of the SQL(TRACELEVEL) compiler directive creates an OpenESQL trace file, OpenESQL.processID.log, within the project directory.
SQL (Native OESQL) - Catalog Demo
Displays information about all the data types supported by the data source, a list of all tables in the data dictionary, and information about columns in the table 'orders'.
SQL (Native OESQL) - Connect Demo
A simple example of using static SQL with OpenESQL, performing a variety of SQL operations.
SQL (Native OESQL) - Dynamic Demo
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 Static sample.
SQL (Native OESQL) - Select Demo
A simple example of using both singleton SELECT and cursor-based FETCH statements with OpenESQL.
SQL (Native OESQL) - Whenever Demo
Illustrates how to use EXEC SQL WHENEVER syntax with error handling. It also uses the MFSQLMESSAGETEXT variable for retrieving errors messages longer than the 70 bytes available within the SQLERRMC field.
SQL (DB2 ECM) - Connect Demo
Shows the syntax variants supported by IBM DB2 LUW for connecting to and disconnecting from a DB2 database using Type 1 CONNECTs.
SQL (DB2 ECM) - Dynamic Demo
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 require the table to already exist or a compile error will result.
SQL (DB2 ECM) - LOB Demo
Illustrates the use of LOB LOCATOR and VALUES functions to retrieve Lob data from DB2 LUW.
SQL (DB2 ECM) - Select Demo
A simple example of using both singleton SELECT and cursor-based FETCH statements with IBM DB2 LUW.
SQL (DB2 ECM) - Whenever Demo
Illustrates the use of EXEC SQL WHENEVER statements for error handling, and using the DB2(MSGAREA) compiler directive to specify a COBOL variable for retrieving error message text larger than the 70 bytes provided in SQLERRMC.
SQLCLR
You need to run the following samples with administrator's rights:
SQLCLR - EmailAddress Type
Shows how to create a Microsoft SQL Server User Defined Type.
SQLCLR - HelloWorld
Shows how to create a simple Microsoft SQL Server stored procedure.
SQLCLR - RecordSet Procedure
Shows how to create a simple Microsoft SQL Server stored procedure that returns a row.
SQLCLR - RegEx User Functions
Shows how to create a simple Microsoft SQL Server stored function and how it can be used to perform field validation.
SQLCLR - TableValue Functions
Shows how to create a Microsoft SQL Server table value function and how it can be used to return multiple rows.
Web Applications
Web Application Book
A Web Application project which contains a Web form. The form provides a .NET interface to an existing COBOL program. The BookClass project provides a proxy COBOL program that calls the existing COBOL Book program.
Web Sites
SendHttp Console Application
Demonstrates interaction with .NET classes for interacting with http requests and responses.
Syndication Service Library Custom Items
Shows how to create custom syndication feeds using WCF components.
Syndication Service Library Example
Shows how to use WCF components to create a custom syndication feed that uses an existing feed as its data source.
WCF Book Service and Client
Demonstrates how to create a WCF service and a COBOL client that accesses the service.
WCF Read from a File
Shows how to use WCF services.
Web Site Book
Shows how to create a Web Forms page to provide a .NET interface to an existing COBOL program. The BookClass project provides a proxy COBOL program that calls the existing COBOL Book program.
Web Site Hello
Shows how to use Web Forms to say "Hello World".
Web WCF Service
Demonstrates the use of Windows Communication Foundation (WCF) services. To run this demonstration you need to have Microsoft’s Visual Web Developer 2010 installed.
Windows Communication Foundation
Syndication Service Library Custom Items
Shows how to create custom syndication feeds using WCF components.
Syndication Service Library Example
Shows how to use WCF components to create a custom syndication feed that uses an existing feed as its data source.
WCF Book Service and Client
Demonstrates how to create a WCF service and a COBOL client that accesses the service.
WCF Read from a File
Shows how to use WCF services.
Web WCF Service
Demonstrates the use of Windows Communication Foundation (WCF) services. To run this demonstration you need to have Microsoft’s Visual Web Developer 2010 installed.
Windows Forms
C# WinBook
Demonstrates how to call COBOL from a C# application.
COBOL Blitz
Demonstrates the use of Windows forms, enumeration types, inheritance, and of sounds and graphics.
COBOLDoKu
Demonstrates Windows Forms using a .NET user control.
LoginFormApplication
This demonstration is a Visual Studio solution containing a login form created from the Login Form template. It contains classes that check whether the entered user name and password are correct.
Samples Browser
Shows a list of the samples installed with your COBOL development system. You can select a sample from the list and view its readme. Click one of the available links to open the sample in Visual Studio, open the directory that stores the sample's files or open its readme.
Win Book
Shows how to create a Windows form to provide a .NET interface to an existing COBOL program. The BookClass project provides a proxy COBOL program that calls the existing COBOL Book program.
Win Hello
Shows how to use Windows Forms to say "Hello World".
Windows Presentation Foundation
COBOL TicTacToe
Demonstrates how to use WPF from aVisual COBOL application.
Trackball Demo
Demonstrates 3D rendering using WPF components.
WPF Book
Demonstrates the use of Windows Presentation Foundation (WPF).
Uncategorized Samples
Interfacing With Std COBOL
Demonstrates how to use compatible types to interface with standard COBOL, and in particular how to manipulate group items and occurs structures.
Multithreading
Introduces some key aspects of Multithreaded programming using COBOL syntax and the run-time threading APIs.
Platform Invoke
Demonstrates that COBOL can be used to read and write XML documents and shows the use of the treeview and property grid Windows Forms objects.
\COBOL for .NET
\Core.Net
Core.NET introduces some of the standard features of the .NET Framework you need to be aware of, and any new COBOL syntax in order to support these features.
All other subdirectories under \COBOL for .NET
Each of the demonstrations shows how to use the corresponding COBOL feature within the .NET framework.
\Forms
\CobolDoKu
Demonstrates Windows Forms using a .NET user control.
\BookDemoWebApplication
A Web Application project which contains a Web form. The form provides a .NET interface to an existing COBOL program. The BookClass project provides a proxy COBOL program that calls the existing COBOL Book program.
\BookWrapper
A managed wrapper (written in COBOL .NET), over the Legacy Book library. The WinBook program uses the BookWrapper library to read and write data from the bookfile.dat.
\LegacyBook
A native COBOL library which needs data records from a data (.dat) file.
\LoginFormApplication
This demonstration is a Visual Studio solution containing a login form created from the Login Form template. It contains classes that check whether the entered user name and password are correct.
\WebBook
Shows how to create a Web Forms page to provide a .NET interface to an existing COBOL program. The BookClass project provides a proxy COBOL program that calls the existing COBOL Book program.
\WebHello
Shows how to use Web Forms to say "Hello World".
\Winbook
Shows how to create a Windows form to provide a .NET interface to an existing COBOL program. The BookClass project provides a proxy COBOL program that calls the existing COBOL Book program.
\WinHello
Shows how to use Windows Forms to say "Hello World".
\SendHTTP
Demonstrates interaction with .NET classes for interacting with http requests and responses.
\InterfacingWithStdCOBOL
Demonstrates how to use compatible types to interface with standard COBOL, and in particular how to manipulate group items and occurs structures.
\MultiRunUnits
Demonstrates why and how procedural COBOL is compiled and invoked in a multiple user environment. The application is an ASP.NET Web Service and you invoke it through the ASP.NET Development Server.
\Multithreading
Introduces some key aspects of Multithreaded programming using COBOL syntax and the run-time threading APIs.
\ConnectedDemo
Fills a DataSet from a data source, modifies the DataSet and then synchronizes the changes in the DataSet with the data source. The modified contents of the DataSet are displayed in the Output Window. To execute this demonstration, you must first download and install the SQL Server Northwind database from the Microsoft Web site, http://www.microsoft.com. Once there, enter the following search criteria to locate the appropriate download page: northwind pubs database download
\CursorDemo
Demonstrates how to mix OpenESQL with direct calls to ADO.NET.
\DisconnectedDemo
Manipulates offline data in a DataSet. The results of the data manipulation are displayed in the Output Window.
\LobDemo
Demonstrates how ADO.NET can be used in mixed language projects to insert and select large objects (LOBs). LobDemo shows OpenESQL working with LOB columns in a SQL Server table.
\OrderStatusDemo
Demonstrates how ADO.NET can be used in mixed language projects, and uses COBOL and C#.
\ConnectedDemo
Fills a DataSet from a data source, modifies the DataSet and then synchronizes the changes in the DataSet with the data source. The modified contents of the DataSet are displayed in the Output Window. To execute this demonstration, you must first download and install the SQL Server Northwind database from the Microsoft Web site, http://www.microsoft.com. Once there, enter the following search criteria to locate the appropriate download page: northwind pubs database download
\CursorDemo
Demonstrates how to mix OpenESQL with direct calls to ADO.NET.
\DisconnectedDemo
Manipulates offline data in a DataSet. The results of the data manipulation are displayed in the Output Window.
\LobDemo
Demonstrates how ADO.NET can be used in mixed language projects to insert and select large objects (LOBs). LobDemo shows OpenESQL working with LOB columns in a SQL Server table.
\OrderStatusDemo
Demonstrates how ADO.NET can be used in mixed language projects, and uses COBOL and C#.
\Samples Browser
Shows a list of the samples installed with your COBOL development system. You can select a sample from the list and view its readme. Click one of the available links to open the sample in Visual Studio, open the directory that stores the sample's files or open its readme.
\WCF
Demonstrates the use of Windows Communication Foundation (WCF) services. To run this demonstration you need to have Microsoft’s Visual Web Developer 2010 installed.
\WPF
Demonstrates the use of Windows Presentation Foundation (WPF).
\CobolAddin
Demonstrates the use of COBOL to develop an add-in for the Visual Studio IDE.
Parent topic: Welcome
Related information
Demonstrations of Native COBOL
Samples Browser
Tutorials on COBOL in the Visual Studio IDE


Demonstrations of Native COBOL

We supply a number of demonstration programs to help you better understand some of the concepts involved when working with COBOL projects in Visual Studio. You can access the demonstrations with the help of Samples Browser - click Start > All Programs > Micro Focus Visual COBOL > Samples.

The demonstration programs are installed in subfolders under %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples 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\<product name>\Samples.

The following demonstrations of native code are available:

CGI
Simple CGI application
Demonstrates how to use native COBOL to create CGI programs which accept data from a form on a Web page and then redisplay that data in another Web page.
Complex CGI application
Demonstrates how to use native COBOL to create CGI programs which accept data from a form on a Web page and then redisplay that data in another Web page.
Games
COBOL Minesweeper
Demonstrates how to create a random generator in native COBOL and how to use advanced console operations such as capturing mouse events in the console.
COBOL Snake
Demonstrates how to create a random generator in native COBOL, dynamic memory allocation and advanced console operations.
Parent topic: Welcome
Related information
Demonstrations of .NET COBOL
Samples Browser
Tutorials on COBOL in the Visual Studio IDE


Help on Help

The latest up-to-date Help is available on the Micro Focus Infocenter on the Web, at http://documentation.microfocus.com. Alternatively, you can display the Help locally from the Help menu in the IDE, or from the Start menu.

Help in the Infocenter

Tips on using the Infocenter Help:

  • You can specify the scope of Help to search, by creating your own search lists. To do this, click Search scope and follow the wizard instructions.
  • The Help topic being displayed can get out of step with the contents, such as when you choose the topic from a search or when you link to it from another topic. To show where the topic appears in the contents, click Show in Table of Contents on the toolbar.
  • This Help is in Eclipse format. For full details of the Help system, see the Eclipse Workbench User's Guide

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.

Help in Microsoft Visual Studio

The Microsoft Help on using Visual Studio is comprehensive and detailed and includes many samples as well as extensive reference material and more. If you are new to Visual Studio, we recommend that you explore the Microsoft Help and follow the tours and introductory material there.

Tips on using Help in Visual Studio Help format:

  • To view the help, ensure that the Visual Studio Help Library is pointing to local help. From the Visual Studio menu click Help > Manage Help Systems > Choose online or local help and check the I want to use local help button.
  • The first release of Visual Studio 2010 has a browser-based help system, Microsoft Help Viewer 1.0, which does not include an index for the locally-installed help. Navigation of the content is only available using the table of contents and Search and the help contents for the Help system does not expand and collapse in the same way as previous Help systems.

    Visual Studio 2010 SP1 provides an upgrade of the help system, Microsoft Help Viewer 1.1, which provides a stand-alone help viewer with an index and a fully expandable table of contents.

    Tip: If you do not wish to install Visual Studio 2010 SP1, you can enable the index or fully expanding table of contents with the help of the following third-party tools:
    • Microsoft Help Viewer Power Tool - can be used either as a standalone Help viewer or embedded in the VS IDE.
    • Help Viewer Keyword Index- displays the index in the browser-based help or, optionally, embedded in the Visual Studio IDE.
    • Microsoft Help 3 Viewer - a standalone Help viewer that provides an index and a fully expanding table of contents.
  • For full details of the Help system, see the Microsoft Help System Documentation, which is available from Help menu in the IDE.
Parent topic: Welcome


Developing COBOL Applications

This COBOL system enables you to develop native and managed COBOL applications. You use the Microsoft Visual Studio Integrated Development Environment to develop, compile as either native unmanaged or managed code and debug your applications. You can then deploy and further debug the application under the Micro Focus COBOL run-time system.

  • Visual Studio and COBOL
  • Solutions and Projects in Visual Studio
  • Building COBOL Applications
  • Debugging Native COBOL Programs
  • Running Native COBOL Applications
  • Test Coverage for Native COBOL
  • Deploying COBOL Applications
Parent topic: Micro Focus Visual COBOL for Visual Studio 2010


Visual Studio and COBOL

This COBOL Development system is integrated into Microsoft Visual Studio. You use the Microsoft Visual Studio IDE to develop, build and debug COBOL applications, as either native COBOL or .NET managed COBOL.

  • Introduction to Visual Studio and COBOL
  • Tips and Tricks with the IDE
  • Differences between Visual COBOL and Earlier Products
    COBOL applications developed and built using previous Micro Focus IDEs, such as Net Express or Server Express, can now be developed and built with Visual COBOL. However there are some differences in behavior and in terminology, which are described here.
Parent topic: Developing COBOL Applications


Introduction to Visual Studio and COBOL

Visual COBOL enables you to develop native COBOL applications as well as .NET managed code applications.

You use the Microsoft Visual Studio IDE to develop, build and debug your applications. You can then deploy and further debug the application under the run-time system provided by COBOL Server.

You use the Visual Studio integrated development environment (IDE) to develop, build and debug COBOL applications, whether they are built as native or managed COBOL. The IDE provides all the functionality to manage projects and debug applications. It includes:

  • Templates for creating COBOL projects such as Windows applications and console applications, and also your own COBOL project types
  • Colorization of the COBOL language when editing and debugging
  • Background parsing of COBOL
  • Information provided when hovering over COBOL variables
  • Debugging that is sensitive to COBOL and includes all the usual features such as stepping, watch windows and breakpoints
  • Querying 64-bit execution environments

For native COBOL, programs compile to .exe or .dll and they execute under the COBOL Server.

.NET COBOL compiles to Microsoft Intermediate Language (MSIL), and they execute in conjunction with the CLR, just like programs in other .NET languages, such as C#. Applications written in .NET COBOL need the COBOL Server as it enables them to run in the .NET environment.

Both new and existing COBOL can be compiled as .NET managed code. This enables you to:

  • Reuse existing COBOL business logic and data access across the .NET environment
  • Access .NET Framework classes and features from COBOL applications including Windows Forms and Web Forms
  • Create and extend composite applications consisting of COBOL, C#, VB.NET, C++ and ASP.NET
  • Reuse and extend Open ESQL applications

Both procedural and OO COBOL are supported within the .NET. OO COBOL classes can inherit classes written in other Microsoft .NET languages and vice versa.

The COBOL syntax includes a number of extensions to support .NET features. For example, the TRY ... CATCH syntax is now included to enable exception handling in COBOL.

There are some programming techniques, COBOL syntax and functionality that are applicable to unmanaged COBOL only and not to .NET managed COBOL.

Parent topic: Visual Studio and COBOL
Related concepts
Using OpenESQL with ADO.NET
OpenESQL Assistant
Managed Code Concepts
Managed COBOL Restrictions


Tips and Tricks with the IDE

  • Editing COBOL
  • Building COBOL
  • Debugging COBOL
  • IntelliSense and COBOL
  • Code Snippets
  • Smart Tags in COBOL
  • Overriding the Members of an Inherited Class
Parent topic: Visual Studio and COBOL


Editing COBOL

Here are some tips on editing COBOL code in the Visual Studio IDE:

Bookmark Window
Shows the bookmarks added to source code in your solution. Choose View > Bookmark Window to display the window.
Bookmarks
To add a bookmark, position the cursor on a line in the code and choose Edit > Bookmarks > Toggle Bookmark. View > Bookmark Window.
Background Syntax Checking
The COBOL code is checked in the background, as you type it. Any errors are underlined with wavy red lines. You can turn this setting off or on the Miscellaneous page in Tools > Options > Text Editor. Generally, we recommend that you leave Background Syntax Checking turned on. You might consider turning it off only when editing exceptionally large files.
COBOL Margins
The editor provides colorized margins for fixed and variable COBOL source code. Configure the margins on the Miscellaneous page in Tools > Options > Text Editor > COBOL. The margins are automatically updated according to your preferences if the background parse is turned on.
Class View Window
Shows an outline of the classes used in your solution and their members. To display the window choose View > Class View. This applies to managed projects only.
COBOL Reserved Words
To configure the case of the COBOL reserved words used in the code snippets for COBOL choose Tools > Options > Text Editor > COBOL > Miscellaneous and set the case in the Case Format for Reserved Words field.
Code Definition Window
If you position the cursor on an object in the source code, the Code Definition Window automatically displays the section of the code implementing the objects referenced on that line. To display the window choose View > Code Definition Window.
Code Snippets
Insert the code constructs for elements of the .NET COBOL language, for example for classes, methods, delegates. To insert a snippet choose Edit > IntelliSense > Insert Snippet, or right-click in the editor and select Insert Snippet, or type the shortcut for the particular snippet (for example, class-id, method-id) and press Tab. This inserts an outline of the syntax for you to fill in. Available in managed code only.
To configure the case in which the code snippets are displayed choose Tools > Options > Text Editor > COBOL > Miscellaneous and set the case in the Case Format for Identifiers field.
Comments
Start end-of-line comments in the code using *>. For fixed or variable source format of code, enter * in column 7 to comment out an entire line.
Editor Zoom
Zoom in or out the text in the COBOL editor by pressing CTRL and scrolling with the mouse.
Errors Window
Shows the errors, warning and messages created when editing or compiling. Double-click on an item in the errors list to position the cursor on the line of code that causes the error. You can get help on the error by pointing to the relevant error number and pressing F1.
Find All References
In the editor, right-click a COBOL data item, a section or a paragraph name in the code and select Find All References. A list of all places in the solution that contain the reference to the item is displayed in the Find Symbol Results window. Double-clicking on an item in the list positions the cursor on the line of code that includes the element. The default shortcut for invoking Find All References is Shift+F12.
Find Symbol Results Window
To display the window, click View > Find Results > Find Symbols Results. Displays the results of Find All References command in the editor. Double-click an item in the list to position the cursor on the line that includes the referenced item.
Go To Definition (F12)
Pointing to a variable in the editor and pressing F12 positions the cursor on the definition of that variable.
Performing Go To Definition on a copybook name opens the copybook in the editor.
Go To Procedure Division
Go To Procedure Division button, [image], is located on the COBOL toolbar. To display the toolbar choose Tools > Customize > Toolbars and select COBOL. Click [image] to move the cursor following these rules:
  • For procedural programs, the cursor moves to the first line of the Procedure Division of the COBOL source.
  • For Object-Oriented programs, if the cursor is inside a class and before the method definitions, the command moves it to the first line of the Procedure Division of the first method.

    If the cursor is inside the methods declarations but outside a method, the command moves it to the first line of the Procedure Division of the preceding method.

    If the cursor is after a class, the command moves it to the first line of the Procedure Division of the last method of the class.

  • If the cursor is in a copybook file which you opened from Solution Explorer, the command moves it to the first line of the Procedure Division of the first COBOL source that includes the copybook. If the copybook file was opened from a particular COBOL file, the command moves it the first line of the Procedure Division of that COBOL file.
Go To Location Toolbar
To display the toolbar choose Tools > Customize > Toolbars and select COBOL. The Go To Location toolbar is indicated by [image] and enables you to locate the definition of a variable by typing the variable name or an expression in which it is used. Equivalent to pointing to the variable in the editor and pressing F12. The toolbar keeps a history of your searches. To return to where you were in the code, click "Navigate Backwards", [image].
IntelliSense
Displays lists of the namespaces, types, members and parameters that are available when you type an object name followed by a space, dot, double colon or an opening bracket. The IntelliSense information is updated as you type.
Navigate To
Choose Edit > Navigate To. Enables you to search for symbols and filenames and navigate to different locations of the current solution. Double-click an item in the result to view the definition in the code.
Note that for managed projects Navigate To search works only if at least one of the COBOL source programs has been opened in the IDE. For native projects, Navigate To search works only for the COBOL source programs that have been opened once in the IDE.
Navigation Bar
The navigation bar at the top of the COBOL editor displays lists of the objects and procedures used in the current program and enables you to position the cursor on any of them. This is available for managed code only.
Outlining
Enables you to hide portions of the code. Choose Edit > Outlining > Toggle Outlining Expansion.
Override Class Members Wizard
A user interface that facilitates you in overriding the members of an inherited class. To invoke the wizard, right-click inside a class in the editor and choose Override Class Members. The wizard displays the members that you can override and which class they belong to. Select the members you want to override and click OK. This adds the selected methods with the override modifier at the end of the class . Works with managed code only.
Project Details Window
Displays a full list of the files in your project or solution with file details such as the file type, the COBOL dialect, number of errors in the files.
To open the window, select your project or solution in Solution Explorer and click Projects > Project Details Window.
References
Enable you to add references to .NET assemblies, COM objects, projects and files. To add a reference choose Project > projectProperties, open the References tab and click Add > Reference or Add > Web Reference. This applies to managed projects only.
Smart Tags
Smart tags are a feature of the Visual Studio editor that helps you implement different constructs of code more easily. The indication for a smart tag ( [image]) appears underneath at the beginning of the declaration of a construct that is not fully implemented. When you place the cursor over the tag, the [image] icon appears. Click the arrow in the icon and select an action from the drop-down list. This adds the required construct to your code.
Syntax Colorizing
Colorizes the members of the COBOL language, for example data items, statements, comments, level 78 words, in different colors. To configure the colors for the COBOL language, choose Tools > Options > Environment and click Fonts and Colors. The items related to COBOL are prefixed with "COBOL".
Syntax Help
In the editor, point to a COBOL reserved word and press F1 to display the syntax Help for that word.
WCF Service References
Enable you to add and use WCF services in client applications. WCF Service References automatically set the details that are needed to invoke the service like the service address, the binding, the service name and contract.
To add a service reference, select your project in Solution Explorer and click Project > Add Service Reference. Click Discover to locate the available WCF services.
XML Documentation Comments
Insert XML documentation comments immediately before all your classes and methods to provide a description of what they do. Start each line of the documentation comment with *>>. When you type code IntelliSense shows the classes and methods you can use, the definitions are displayed as tool-tips for your classes and methods.
Parent topic: Tips and Tricks with the IDE


Building COBOL

Here are some tips on handling projects and building COBOL applications in the Visual Studio IDE:

Add Files to the Project
Right-click the project in Solution Explorer. Choose Add > New Item to create a new file from the supported types in the project directory. To add an existing non-COBOL file, choose Add > Existing Item and browse to the location of the file to select it. This adds a link in the project to the file but does not copy it in the project directory. To add an existing COBOL file, choose Add Existing COBOL Items.
Application Configuration File
Includes the environment variables and COBOL programmable switches used by your native COBOL application at run time. Right-click the project in Solution Explorer and choose Add > New Item > Application Configuration File. To edit the file, right-click it in Solution Explorer and choose Edit. This applies to native projects only.
Assembly / Output name
Choose Project > projectProperties and go to the Application tab. Specify the name of the target file to build and the name of the output assembly in the Assembly name/Output name field.
Build Configuration and Settings
The Visual Studio standard toolbar shows the active build configuration for your project, for example Debug or Release. You can specify settings for a particular configuration on the COBOL tab in your project properties. To create new build configurations or edit the existing ones, choose Build > Configuration Manager.
COBOL Settings
Use this to set the dialect, the source format and directives for the whole project. Choose Project > projectProperties and select the COBOL tab.
Compiler Directives

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. To set directives, choose Project > projectProperties and select the COBOL tab. Click in the Additional Directives field and type the directives, separated with a space.

Copybook Paths
The locations in which the project searches for copybook files. To add copybook paths to the project, choose Project > projectProperties and select the Copybook paths tab.
Entry Point/Startup Object
Defines the method entry of the application. Choose Project > myProject Properties and select the Application tab. Specify an entry point for your project in the Entry point/Startup object field.
Errors Window
Shows the errors, warning and messages created during edit or compile. Double-click on an error to position the cursor on the line of code that causes the error. You can get Help on the error if you point to the error number in the list and press F1.
Link and Run-Time Environment Settings
Go to the COBOL Link tab in your project properties. This is available only for native code.
Output window
Displays the status messages for the executed commands at build time. Display it from View > Output.
Step into inline PERFORM statements when using Step Over
Enable in Tools > Options > Debugging > COBOL Debugging Settings. The default behavior for Step Over (F10) is to skip inline PERFORM statements. Works with native code only.
Stop a Build
Choose Build > Cancel.
Resource Definition Script File
Enables you to add non-executable binary data such as icons, version info, to your executable files. Create the resource script file (.rc) outside of Visual Studio and to add it to your project right-click the project in Solution Explorer and choose Add > Existing Item. This applies to native projects only.
Parent topic: Tips and Tricks with the IDE
Related concepts
COBOL Properties


Debugging COBOL

Here are some tips and tricks on debugging COBOL applications in the Visual Studio IDE:

Add a Watch
Right-click a variable in the editor and choose Add Watch.
Attach to a Running Process
See To attach to a running process and debug.
Attach to a 64-bit Running Process
See To attach to a 64-bit running process and debug.
Autos Window
Displays the variables used in the current and in the previous statements and enables you to change their values or add watches to them. To display the window, click Debug > Windows > Autos.
Breakpoint-Setting
Double-click in the left margin of editor next the a line of code, or position the cursor on the line and press F9. You can also choose Debug > Toggle Breakpoint or choose Breakpoint > Insert Breakpoint from the editor context menu.
Note: Tracepoints are supported only when debugging managed code.
Breakpoints Window
Displays a list of all breakpoints and tracepoints set in the code. Double-click on a breakpoint in the window to position the cursor on the line for which it has been added.
Break on Data Change
Works with COBOL watchpoints. When the value of a data item on which a watchpoint has been set changes, the debugger breaks the execution of the program and highlights the line after the data change. The IDE opens the COBOL Watchpoints window and highlights the data item that was changed in it. Works for native code only.
COBOL Watchpoint-Setting
Note: COBOL watchpoints are supported in native COBOL only.
To add a watchpoint from the editor, right-click a data item and select Add COBOL Watchpoint. Alternatively, you can add watchpoints from the Watchpoints (Native COBOL) window. To disable or remove the watchpoints, choose Debug > COBOL Watchpoints > Disable/Delete All Watchpoints.
DataTips and Pin To Source
Provide information about the variables in the source code. To display the DataTip for a variable, you can hover it. This works only in break mode when the execution stops and with variables that are used at run time.

If you need to keep the DataTip for a variable open, right-click on the variable in the code and choose Pin To Source.

Debug Tooltip for Subscripted OCCURS Items
Shows all items in an array or the value of an expression. To configure the tooltip style, select Tools > Options > Text Editor > COBOL > Miscellaneous and specify your preference for the Debug tooltip style for OCCURS items setting. Use the following default key sequence to change the style of the tooltip in the editor - ALT+T, T.
Find All References
In the editor, right-click a COBOL data item, a section or a paragraph name in the code and select Find All References. A list of all places in the solution that contain the reference to the item is displayed in the Find Symbol Results window. Double-clicking on an item in the list positions the cursor on the line of code that includes the element.
Find Symbol Results Window
To display the window, click View > Find Results > Find Symbols Results. Displays the results of Find All References command in the editor. Double-click an item in the list to position the cursor on the line that includes the referenced item.
Go To Location Toolbar
To display the toolbar choose Tools > Customize > Toolbars and select COBOL. The Go To Location toolbar is indicated by [image] and enables you to locate the definition of a variable by typing the variable name or an expression in which it is used. Equivalent to pointing to the variable in the editor and pressing F12. The toolbar keeps a history of your searches. To return to where you were in the code, click "Navigate Backwards", [image].
Just-In-Time Debugging

Enables just-in-time debugging for when an application causes an error. To enable Just-In-Time Debugging for native COBOL code, click Tools > Options > Debugging > Just-In-Time Debugging. Check Micro Focus Native Debugger. Works with native code only.

Memory Window
Allows you to see the contents of memory for a given address. This can be a pointer reference, the address of data-item or an integer value. To display the window, click Debug > Windows > Memory > Memory n. Works for native COBOL only.
Program Breakpoints
Note: Program breakpoints are supported in native COBOL only, and are not supported with nested programs.
You can break into a program whenever it or one of its entry points is called.
In the Program Breakpoints (Native COBOL) window, click New and type the name of the source file, without the extension. For multi-program source files, to set a break for a sub-program, use its program-id.
To display the Program Breakpoints (Native COBOL) window, click Debug > Windows > Program Breakpoints (Native COBOL).
Remote Debugging
You can debug a process running on a remote system if the machines are connected using TCP/IP. See Remote Debugging.
Ensure that the local and remote systems are networked using TCP/IP. To connect to the remote machine and debug a program, choose Project > projectProperties and go to the Debug tab. Check Enable remote machine and fill in the name or the IP address of the remote machine and the TCP port number.
Run To Cursor
Right-click a line of code in the editor and select Run To Cursor. This starts a debugging session and executes the code till the line on which you positioned the cursor.
Start Debugging
Choose Debug > Start Debugging or, alternatively, press F5 or F11. F5 starts debugging and runs the application until a breakpoint or an error occurs. F11 starts debugging and breaks on the first statement that can be debugged.
Stop Debugging
Choose Debug > Stop Debugging. You can also click [image] in the Debug toolbar.
Threads Window
Shows all threads that are running in the process. To display the window, choose Debug > Windows > Threads.
Tracepoint-Setting
Tracepoints are conditional breakpoints. When the debugger hits a tracepoint, it performs an action instead of or before stopping the execution. To set a tracepoint, click on the line of code where you need to set one and choose Debug > Toggle Tracepoint or from the context menu choose Breakpoint > Insert Tracepoint and specify the action to perform. Tracepoints are supported only when debugging managed code.
Variable Windows
Include windows, such as for example Autos, Locals, Quick Watch, Watch, for monitoring and editing values and expressions.
Watchpoints (Native COBOL) Window
Enables you to add data items as watchpoints, and monitor their values in a decimal or hexadecimal display. To open the window, click Debug > Windows > COBOL Watchpoints.
Parent topic: Tips and Tricks with the IDE
Related concepts
To attach to a native running process and debug
Remote Debugging of Native COBOL Applications
Using the Memory Window in Native COBOL
To enable just-in-time debugging for when the application fails for Native COBOL
Related information
Overview - Debugging Native COBOL Programs


IntelliSense and COBOL

Note: The following applies to .NET managed code only.

IntelliSense is a feature of Visual Studio that provides easy access to language elements. It is also available when coding COBOL programs. IntelliSense shows lists of methods, fields, properties, parameters, classes and so on that are available when you type an object name followed by a double colon, an opening bracket or a double quote. You can choose an item from the list to complete the code rather than typing it yourself. Users of procedural COBOL can also gain IntelliSense on their programs.

The following are examples of where IntelliSense pops up:

  • Type Listings - When you start declaring a type, such as 01 my-string type , IntelliSense pops up a list of the namespaces and types available to your program, as soon as you type the ". These namespaces are obtained from each of the references you’ve added to your project. As you type a namespace, IntelliSense shows all the types within that namespace. For example, when you type:
    • 01 my-string type - all the available namespaces are listed
    • 01 my-string type System. - all the types within the System namespace are listed
    • 01 my-string type System.IO. - all the types within the System.IO namespace are listed.
  • Member Listings - When you invoke an object, IntelliSense 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 colons ::), such as:
    invoke my-string::
  • Parameter Listings - When you type either USING or an opening a bracket for the parameters of an inline invoke, IntelliSense pops up a list of the parameters available for the method you’re invoking. It also displays any overloaded methods which you can scroll through using the arrow keys.
Parent topic: Tips and Tricks with the IDE


Code Snippets

Intellisense code snippets are portions of code that you can quickly insert in your applications.

  • To insert a snippet in your code
  • Shortcuts for the COBOL Snippets
  • To create a custom COBOL snippet
Parent topic: Tips and Tricks with the IDE


To insert a snippet in your code

  1. Right-click in the Editor and select Insert Snippet.
  2. Press TAB to navigate through the replacement fields and fill in values as required.
Parent topic: Code Snippets


Shortcuts for the COBOL Snippets

Use the following shortcuts to insert the code snippets. Type the shortcut in the editor and then press the tab key to insert the snippet.

Shortcut | Snippet | Description
accept | Accept From Date or Accept From Time | Enables you to set a variable to the current date or time.
attribute | Attribute | Inserts a class that implements a custom attribute.
class-id | Class-Id | Inserts a class declaration.
create | Create | Creates or constructs an instance of a list or a dictionary.
DateString | .NET Date Format | Enables you to set a localized date format by specifying the desired locale.
declare | Declare as Type | Declares a local variable.
delegate-id | Delegate-Id | Inserts a delegate declaration.
delete | Delete Key | Deletes an element from a list or a dictionary.
enum-id | Enum-Id | Inserts an enum-id declaration.
evaluate | Evaluate True | Inserts an EVALUATE statement declaration.
if | If Then Else | Inserts an IF statement declaration.
implements | Implement Class/interface | Implements Class/Interface method stubs.
inspect | Inspect Replacing simple characters or Inspect Tallying before terminator | Inserts an INSPECT statement declaration for either replace or tally.
interface-id | Interface-Id | Inserts an interface-id declaration.
method-id | Method-Id(instance) | Inserts an instance method declaration.
static-method | Method-Id(static) | Inserts a static method declaration.
perform | Perform Varying, Perform Varying Thru or Perform Varying Dictionary | Inserts a PERFORM statement declaration.
program-id | Program-Id | Inserts a COBOL program declaration.
property | Get/Set Property | Inserts a getter and a setter properties.
read | Read Into Key | Reads an element in a list or reads an element in the dictionary at a given key.
reset | Reset | Delete all the elements from a list or a dictionary.
rewrite | Rewrite From Key | Overwrite an element in a list or a dictionary.
setnew | Set New | Inserts the code to set an instance object to a new class object.
try | Try Catch Finally | Inserts a TRY-CATCH-FINALLY statement declaration.
valuetype-id | ValueType-Id | Inserts a valuetype-id declaration.
write | Write From | Writes an element to a list or a dictionary.
Parent topic: Code Snippets


To create a custom COBOL snippet

  1. Create a code snippet file.

    See the Visual Studio Help for instructions.

  2. Edit the code of the snippet file in the editor to include the desired functionality.

    See the MSDN Code Snippet Schema Reference.

  3. Specify Cobol in the <Code Language=""> tag - <Code Language="Cobol">.
  4. Save the file as type Snippet Files (*.snippet).
  5. To update Intellisense with your snippet, use Visual Studio Code Snippet Manager to add the file you just created to the available COBOL snippets.

    See How to: Manage Code Snippets in the Visual Studio Help.

Parent topic: Code Snippets
Related information
MSDN Code Snippet Schema Reference


Smart Tags in COBOL

Note: This feature works with .NET managed code only.

Smart tags are a feature of the Visual Studio editor that enables you to implement code constructs more easily.

With COBOL you can use the following smart tag:

Smart Tag for Implementing an Interface
Enables you to implement interfaces in managed OO COBOL programs. You need to type the definition of the implementing class or value type, class-id MyClass implements type Interface. The smart tag ( [image]) appears underneath at the beginning of the declaration of any interface that is not fully implemented. When you place the cursor over the tag, the [image] icon appears. Click Implement interface InterfaceName from the drop-down list. This adds the missing interface members to the implementing class or value type.
Note: The smart tag does not support generic interfaces and does not add event members from an interface.
Smart Tag for Adding a Using Directive
You can use a smart tag to add in the appropriate using directive when you specify a type without fully qualifying the namespace. For example, to use System.IO.File::ReadAllText, type File::ReadAllText. An error message is generated in the output window, and then the smart tag icon appears in the program editor under File::ReadAllText showing System.IO on the list of namespaces.
Note: To use this feature, you must have background parsing turned on (default).
Parent topic: Tips and Tricks with the IDE


Overriding the Members of an Inherited Class

Note: The following applies to .NET managed code only.

When you implement a non-abstract class that inherits another class, you must override the abstract methods of the base class. Abstract methods do not contain any implementation and require that you provide an override method in the implementation of the inherited class.

Optionally, you may also override any of the virtual methods or properties of the base class. Virtual methods do contain an implementation, but the creator of the base class recognizes that it is an implementation that a derived class might need to override.

Your COBOL development system provides an easy way to override members. The Override COBOL Members dialog available in the editor:

  • Displays the base classes from which a class inherits.
  • Enables you to select the methods to override.
  • Adds the construct of the overriding methods to the class.

Override the members of an inherited class using the dialog as follows:

  1. In the editor, right-click inside the class-id whose members you want to override.
  2. Choose Override Class Members.
  3. In the dialog, select the members to override.
  4. Click OK.

    This adds the construct of the override methods at the end of the derived class.

Restriction:
  • The dialog supports .NET managed code only.
  • The dialog does not support event members and members from generic classes and these are not displayed in the hierarchy tree. Generic base classes appear in the dialog as empty.
Parent topic: Tips and Tricks with the IDE


Differences between Visual COBOL and Earlier Products

COBOL applications developed and built using previous Micro Focus IDEs, such as Net Express or Server Express, can now be developed and built with Visual COBOL. However there are some differences in behavior and in terminology, which are described here.
  • Overview of the Differences
  • Tips: Visual Studio IDE Equivalents to IDE Features in Net Express
    Many IDE features have different names and locations in Visual COBOL.
Parent topic: Visual Studio and COBOL
Related information
Managed COBOL Restrictions
COBOL Syntax Restrictions in Managed COBOL
Native COBOL Compared with Managed COBOL


Overview of the Differences

This COBOL system is integrated with Microsoft Visual Studio. The techniques you use to develop and debug native COBOL applications are much the same as the techniques you use with Visual Studio to develop nonCOBOL applications.

The development environment is Visual Studio, which provides all the functionality to manage projects and debug applications. It includes:

  • Templates for native COBOL projects such as mainframe applications, Windows applications and console applications, and also the ability to add your own COBOL project type
  • COBOL language colorization when editing and debugging
  • Information provided when hovering over COBOL variables
  • COBOL sensitive debugging including watch windows and breakpoints

COBOL applications previously built in the Micro Focus IDEs can be built with Visual Studio. The main differences between the IDEs are as follows:

Solutions, projects and source file folders
A solution is a container holding one or more projects that work together to create an application. The solution and its projects are reflected in the file system as folders, with solution folder containing the project folders, and the project folders containing the main COBOL source files. The folder tree shown in Solution Explorer mirrors the folder tree on disk.

If your solution has files that are shared across multiple projects, such as copybooks, you can create a folder for the shared files in the solution. COBOL copybooks can be held in folders outside the solution or project folders. You specify the location of the copybooks in the project properties.

Copybook extensions and source file extensions
The default extensions for source files are cbl, cob, and cpy. You can define other copybook extensions, using the COPYEXT Compiler directive. In addition, alternative file extensions need to be identified to the text editor, so that the files can be found when searching. To specify these, go to Tools > Options > Text Editor > COBOL > Miscellaneous > Copy file extensions.
Source code character values
We recommend that you replace any non-text characters representing hexadecimal values with a hexadecimal character string definition.

In Net Express and Mainframe Express, COBOL source files are written using the ANSI character set and can contain characters using the full range of hexadecimal values from 00 to FF. When a source file is written to disk characters with values below hex 20 are NULL protected, that is, a character pair is written to disk, NULL(hex 00) followed by the original character.

Executables created in Visual Studio
In Visual Studio, each project creates a single executable, either an exe or a dll, rather than int or gnt. To choose the type of executable, its location and other build settings, specify these in the project's properties.
Build configurations
Previously, you specified how to build a project in Build Settings and Project Settings. In Visual Studio, you specify this in a build configurations, such as the default Debug or Release configuration, or in a configuration that you create.
Running or debugging an application
Where a solution has multiple projects, you need to ensure that the application's executable can locate the dependent project executables (.dll) and their symbol (.idy) files. To do this, you have several options:
  • In the exe project, add references to the projects that create the dlls. Specify where the symbol files are located using Debug > Options and Settings.
  • Specify that your projects put their output executables in the same folder as the solution executable (such as a bin folder). Copy the symbol files to this folder when building the dll, by setting up a post build event in the project's properties. See Project > Properties > COBOL > Advanced > Build Events.
Navigating the source
In Net Express or Mainframe Express, when you have built a COBOL application, context information is often used for program navigation. Visual Studio does not provide the same capability but you can achieve the same result by using one or more of the following options:
  • Edit > Find and Replace > Find in Files. The results of the find are displayed in the Find Results tab. You can then double-click an item within the find results and the source file is then loaded into a text editor view at the identified location.
  • In the program editor, position the cursor on an object, right-click, and select Go To Definition or press F12. This shows the definition of the object in a popup window.
  • In the program editor, position the cursor on an object, right-click, and select Find All References or press Shift+F12. This lists all instances of the object in the Find Symbol Results window.
Build results in the Output view and the Error List
When you build an application, you can view the build results in the Output view and the Error List. You can double-click a build message to identify a source. You can also double-click an item in the Error List to load the source file into a text editor at the relevant location. Turn on these panes, using View > Output and View > Error List.
Parent topic: Differences between Visual COBOL and Earlier Products
Related information
Solutions and Projects in Visual Studio
COPYEXT
Text Editor Miscellaneous Options
General Debugging Options
Build Configuration
Managed COBOL Restrictions
COBOL Syntax Restrictions in Managed COBOL


Tips: Visual Studio IDE Equivalents to IDE Features in Net Express

Many IDE features have different names and locations in Visual COBOL.

The following table shows Net Express IDE features and their corresponding equivalents and locations in Visual Studio.

Functionality | In Net Express | In Visual COBOL for Visual Studio
Project Control
Project filename | *.APP | *.cblproj
Add file to project | Right-click the project in Solution Explorer. Choose Add > New Item to create a new file from the supported types in the project directory. To add an existing file, choose Add > Existing Item and browse to the location of the file to select it. This adds a link in the project to the file but does not copy it in the project directory. To add existing COBOL files, choose Add Existing COBOL Items.
Copybook path | Choose Project > projectProperties and select the Copybook paths tab.
Build settings for the project:
  • COBOL
  • Preprocessor
  • Additional Directive
Click Project > project Properties, go to the COBOL tab and choose a configuration in the Configuration field. To create a new build configuration or to edit one, click Build > Configuration Manager.
Execution environment settings:
  • General
  • COBOL
The execution environment is COBOL Server.
Debug settings:
  • DateWarp
  • Stored Procedures
Editing
Suggest Word/Content Assist | CTRL+G | CTRL+Space
Locate | F12 (or context menu Locate) | F12
COBOL Find | CTRL+Shift+F12 (or context menu COBOL Find) | Shift+F12
Compress | Tool bar compress Tool Bar Compress (or context menu Compress)
Bookmark | CTRL+F2 | CTRL+B, T
Compiling
Single file Compile CTRL+F7 (or click check mark Check Mark) In Solution Explorer, right-click the file you want to compile and click Compile.
Note: This applies to native code only.
Build | F7 (or click build Build)
Build All | ALT+B A | Click Build > Build <project>.
Debugging
Start Debugging | Alt+D A | Choose Debug > Start Debugging or press F5.
Stop Debugging | Shift+F5 | Choose Debug > Stop Debugging.
Restart Debugging | Ctrl+Shift+F5
Run | F5 | F5
Step | F11 (or click step Step) | F11
Step All | Ctrl+F5
Run Thru
Run Return
Run to Cursor | Shift+F10 (or context menu) | Ctrl+F10
Skip to Cursor | CTRL+Shift+F10 | context menu
Skip Statement
Skip Return
Examine ' data item' | Shift+F9 | Shift+F9
Breakpoint set | F9 | Double-click in the left margin of editor next to the a line of code, or right-click the line and choose Breakpoint > Insert Breakpoint, or press Shift+F9.
Conditional Breakpoint | Breakpoint > Condition
Break on Data Change | Via list view | You can break on data change in native COBOL projects, by right-clicking and choosing Add COBOL Watchpoint.
Attach to Process | Click Debug > Attach to Process, or Ctrl+Alt+P
Just-In-Time Debugging Click Tools > Options > Debugging > Just-In-Time Debugging, and check Micro Focus Native Debugger.
Note: This applies to native code only.
Parent topic: Differences between Visual COBOL and Earlier Products


Solutions and Projects in Visual Studio

Solutions are a Visual Studio concept. A solution is a container holding one or more projects that work together to create an application. Splitting your solution into a number of projects has several advantages:

  • Multiple users can work on a solution, as different users can work on different projects.
  • Breaking a solution down into a number of smaller projects makes them easier to handle and quicker to build.
  • The projects in a solution can be in different programming languages, so splitting your application into a number of projects enables you to take advantage of mixed language programming.
  • Solutions can contain projects, where some are compiled as managed code and some as native COBOL. You can use the various interoperability techniques to combine native COBOL with managed COBOL.

A solution has the extension .sln, and is a human readable text file, which you could edit, though we recommend that you use the Visual Studio IDE to do so.

A COBOL project has the extension .cblproj, and again is human readable. It is in msbuild format, which is explained in the Visual Studio Help. Different types of project have different extensions, so for example a C# project has the extension .csproj.

Templates for different types of COBOL projects are supplied. Each template creates the appropriate file structure to hold the project and defines the appropriate build settings. For example, the following COBOL project templates, among others, are supplied:

  • Windows Forms Application (managed code) - creates an empty Windows form and skeleton COBOL code behind the form. It adds the necessary .NET Framework classes, such as System.Windows.Forms to the project references. It creates default project properties.
  • Console Application (native COBOL) - adds the items needed to create a console application. Console applications are typically designed without a graphical user interface and are compiled into a stand-alone executable file. A console application is run from the command line with input and output information being exchanged between the command prompt and the running application.
  • Class Library (managed code) - creates reusable classes and components that can be shared with other projects. Typically, this is built into a .dll file.
  • Templates for Windows Presentation Foundation (WPF) and Windows Communication Foundation (WCF) (managed code).

See the Visual Studio Help for more information on solutions and projects.

  • Exploring Your COBOL Projects and Solutions
    You can use different windows on the IDE to explore and manage your solutions and projects.
  • Project and File Properties and Options
    You can set different project and file properties to control the way you build your COBOL projects.
  • Importing Net Express Projects into Visual COBOL for Visual Studio
    The Net Express Project Import Wizard enables you to convert existing Net Express projects into Visual Studio solutions so you can use them with Visual COBOL.
  • Adding Existing COBOL Items to a Project
  • Creating COBOL Projects from Existing Code
  • Creating COBOL Projects from Selected Files
Parent topic: Developing COBOL Applications


Exploring Your COBOL Projects and Solutions

You can use different windows on the IDE to explore and manage your solutions and projects.

You can use the following windows in the IDE to explore your solutions and projects:

Solution Explorer

Solution Explorer is the default window of Visual Studio for exploring and managing your solutions and projects. To open the window select View > Solution Explorer.

Solution Explorer displays the projects that form your solution, the files and folders in a project as they appear on the physical hard drive, and any assemblies, COM objects or files the project references. The context menus within Solution Explorer provide a variety of command that help you manage your projects.

Project Details Window

To open the window, select your project or solution in Solution Explorer and click Projects > Project Details Window.

The Project Details window shows a list of the files in a project or files in a solution along with various file details. In the window you can sort the files by a specific detail, double-click a file and open it in the editor, access the file properties from the context menu or reset the file directives.

The window includes the following columns:

Name
File name.
Type
Shows the file type such as CBL or CPY.
Error Count
Displays the number of compiler errors reported for a file.
Full Path
Displays the absolute file path on your hard drive.
Dialect
Shows the dialect of the COBOL files.
Directives
Informs the user if there are any directives set on the file that override the directives set for the project. Right-click a file in the window and select Properties to access the file properties. Alternatively, choose Reset Directives if you wish to apply the directives set in the global properties.
From the context menu for the file you can access the file properties or reset the directives on the file.

Parent topic: Solutions and Projects in Visual Studio
Related concepts
Moving Existing Native COBOL Applications into Visual COBOL IDE
Creating COBOL Projects from Existing Code
Adding Existing COBOL Items to a Project
Building COBOL Applications
Debugging Native COBOL Programs
To set COBOL project properties
To specify file properties
To reset the directives on COBOL files


Project and File Properties and Options

You can set different project and file properties to control the way you build your COBOL projects.
  • Overview of COBOL Project Properties
    You can specify default properties that apply to the COBOL projects in all or selected build configurations, and to individual files in the projects. You can also configure the directives scan feature which automatically determines and sets Compiler directives on the COBOL source files in the IDE.
  • Options for Setting Directives when Scanning Files
    The IDE is configured to automatically perform a directives scan and set Compiler directives on any COBOL files you add to your projects. You can also start a directives scan manually using the Reset source directives context menu command in Solution Explorer. Each file is examined to determine the directives required and the directives are set on the file accordingly. However, if the directive is already set on the project, it is not set on the file.
  • Global Options
    The options you set in the IDE, in Tools > Options, apply to all COBOL projects.
  • Project Properties
    The COBOL project properties comprise some properties that apply to the project generally, regardless of the type of build, and some properties that apply to specific build configurations of the project, such as a debug build or release build.
  • To set COBOL project properties
    The properties set on project level apply to all files in the project.
  • To specify file properties
    Files inherit the properties set on project level. You can, however, specify individual file properties and they override the ones set on project level.
  • To choose options for setting directives when scanning files
    You can configure the directives scan feature in the IDE and specify what Compiler directives it can set.
  • To reset the directives on COBOL files
    This triggers a directives scann of the COBOL files in your project and sets Compiler directives on them as specified in Tools > Options > Projects > COBOL Project Settings.
  • To add references to a managed project
    You can add assemblies, COM objects or other projects as references to your managed COBOL projects.
Parent topic: Solutions and Projects in Visual Studio


Overview of COBOL Project Properties

You can specify default properties that apply to the COBOL projects in all or selected build configurations, and to individual files in the projects. You can also configure the directives scan feature which automatically determines and sets Compiler directives on the COBOL source files in the IDE.

After you have created a solution with one or more projects to hold your source code, you can set various project and file properties to control the way your applications build and execute.

For example, you can first set the project properties that apply to all files in the project in all or selected build configurations. Then you can modify the properties of the individual files in the projects if that’s necessary. If you change the file properties, they take precedence over the directives on project level.

In some cases, for certain project types and for multiple files, it might be useful to perform a directives scan – that is to trigger an automatic scan of all COBOL files in the project or solution to determine and set certain Compiler directives. By default, the IDE performs a directives scan of all COBOL files you add to your projects.

Project Properties

You can set project-level properties that can be specific to native and managed COBOL applications. You can set general properties that apply to all types of build as well as properties that apply to specific build configurations of the project, such as a debug or a release build.

Among the properties you can select are SQL and different debug options.

You can set different properties for the individual files included in your project. In this case the file properties override the ones set on project level.

Performing a Directives Scan and Setting Compiler Directives on Files

Restriction: It is possible to scan and determine the directives only for COBOL files that are part of native COBOL projects. It is not possible to set Compiler directives on individual COBOL files for managed COBOL projects.
Performing a directives scan automatically
By default, the IDE is configured to automatically scan any new COBOL source files you add to the project. The scan assesses the code, determines what Compiler directives are required, and then automatically sets those directives on the files.

The IDE identifies and sets the COBOL dialect of the files or default SQL directives for the files that include EXEC SQL statements as specified in Tools > Options > Projects > COBOL Project Settings.

Triggering a directives scan manually
You can also trigger a directives scan of the COBOL files in your projects from Solution Explorer – right-click your project and select Reset source directives.

The directives identified through a directives scan are only set on individual COBOL files and override the directives set on project level. However, if the directive is already set on the project, it is not set on the file.

The options for a directives scan are project independent.

Viewing the results of a directives scan
Each time the IDE performs a directives scan, it displays the results in the Output window.

In cases when the scan sets or unsets a directive value, a description of the action, and the directive value set is shown. For example:

Scanning file C:\Users\Public\Documents\MyProject\ConfigReader.cbl
Setting SQL off
Setting Dialect MF
Scanning file C:\Users\Public\Documents\MyProject\Minesweeper.cbl
Setting SQL off
Setting Dialect MF
Scan complete.

After a directives scan completes and sets directives on the files, you can further modify the file properties.

File Properties

By default, the files that are included in your project inherit properties from the project level. You can modify the properties of individual files manually or trigger a directives scan to determine and set Compiler directives automatically. The file properties take precedence over the ones set on project level.

Depending on the file type, you can specify properties such as the COBOL dialect and SQL options or any additional directives.

Note: The controls displayed on the properties page are determined by the type of project you are working on. As a result, some of the controls described in this section might be missing from your properties page or be unavailable for selection.
Parent topic: Project and File Properties and Options
Related information
Options for Setting Directives when Scanning Files
Project Properties
To specify file properties
To choose options for setting directives when scanning files
To reset the directives on COBOL files


Options for Setting Directives when Scanning Files

The IDE is configured to automatically perform a directives scan and set Compiler directives on any COBOL files you add to your projects. You can also start a directives scan manually using the Reset source directives context menu command in Solution Explorer. Each file is examined to determine the directives required and the directives are set on the file accordingly. However, if the directive is already set on the project, it is not set on the file.

For more on what a directives scan is see Overview of COBOL Project Properties.

Restriction: It is possible to scan and determine the directives only for COBOL files that are part of native COBOL projects. It is not possible to set Compiler directives on individual COBOL files for managed COBOL projects.

You can configure the options that are set when performing a directives scan in Tools > Options > Projects > COBOL Project Settings. The following directives are available:

  • DIALECT directive

    When a file is examined to determine the dialect, a list of possible dialects is produced. The possible dialects are then compared with:

    • The project dialect. If one of the possible dialects matches the project dialect, the DIALECT directive is not set on the file.
    • A list of dialects in priority order. The most likely dialect is chosen and the directive set on the file.
  • SQL directives

    Files that contain EXEC SQL statements require specific SQL directives.

    Note: You must choose the SQL directives that you want to set if they occur in the file. To do this you click the browse button and select the directives you want.

    If you do not select any directives, but only check the box, no directives are set.

    If any of the required directives are not set on the project, they are set on the file. If a required directive is already set on the project, it is not set on the file.

    You can also choose to unset SQL directives for this file. The directives are then not applied at compile time, regardless of any SQL directives set on the project.

Parent topic: Project and File Properties and Options
Related information
Overview of COBOL Project Properties
Project Properties
To specify file properties
To choose options for setting directives when scanning files
To reset the directives on COBOL files


Global Options

The options you set in the IDE, in Tools > Options, apply to all COBOL projects.
  • Text Editor General Options
    You set general options for the COBOL text editor in Tools > Options > Text Editor > COBOL > General, and on the General page.
  • Text Editor Tabs Options
    You specify options for the indents and for the Tab key in the COBOL text editor in the Tools > Options > Text Editor > COBOL, and on the Tabs page.
  • Text Editor Miscellaneous Options
    You can configure additional features of the COBOL editor such as the COBOL margins, the formatting or some of the tooltips in Tools > Options > Text Editor > COBOL, and on the Miscellaneous page.
  • General Debugging Options
    You can specify options that control the behavior when debugging Micro Focus COBOL in Tools > Options > Debugging .
Parent topic: Project and File Properties and Options


Text Editor General Options

You set general options for the COBOL text editor in Tools > Options > Text Editor > COBOL > General, and on the General page.
Statement completion
Auto list members
Enables IntelliSense to automatically display a list of the available members of an object when writing code.
Hide advanced members
Hides the members that are marked internally as advanced.
Parameter information
Shows information about the parameters available for functions and procedures.
Settings
Enable virtual space
Enables writing in the editor after the end of a line of code.
Word wrap
Enables word wrap for lines of the code that are longer than the visible range.
Apply Cut or Copy command to blank lines when there is no selection
Enables you to copy or cut the blank lines in the code.
Display
Line numbers
Displays the line numbers in the editor.
Enable single-click URL navigation
Enables opening the URLs in the text with a single click of the mouse.
Navigation bar
Displays the navigation bar at the top of the COBOL editor which enables you to use the lists for objects and procedures.
Parent topic: Global Options


Text Editor Tabs Options

You specify options for the indents and for the Tab key in the COBOL text editor in the Tools > Options > Text Editor > COBOL, and on the Tabs page.
Indenting
None
Disables the automatic indenting of new lines of code.
Block
Indents a new line at the same tab position as the previous line.
Smart
Indents new lines of code according to the rules of the COBOL language.
Tab
Tab and indent size
Defines the number of spaces inserted when you press Tab or Enter. When programming in COBOL, the compiler expects the meaningful code to start from column eight. This is why it is convenient to have the tab character replaced by four spaces to reduce the risk of introducing compilation errors in the code.
Insert spaces
Replaces the tab character with the number of spaces specified in the Tab and indent size field.
Keep tabs
Inserts a tab character when you press Tab.
Parent topic: Global Options


Text Editor Miscellaneous Options

You can configure additional features of the COBOL editor such as the COBOL margins, the formatting or some of the tooltips in Tools > Options > Text Editor > COBOL, and on the Miscellaneous page.
COBOL Margins
COBOL margins color
Defines the color of the COBOL margins.
Show margins
Displays the COBOL margins in the editor.
Formatting
Case Format for Identifiers
Specifies the case format of the identifiers in the built assembly.
Case Format for Reserved Words
Specifies the case format of the COBOL reserved words in the built assembly.
Misc
Background syntax check timeout
Specifies the response time (in seconds) after which the background parse is aborted.
Copy file extensions
Specifies the file extensions that are recognized as copybook files. Separate the extensions by a comma.
Customize Editor for COBOL
Enables features that facilitate COBOL development, for example pressing Tab in the editor to position the cursor on the eighth column.
Debug tooltip style for subscripted OCCURS items
Specifies what information should be displayed by the debug tooltip.
Expandable tooltip
Choose this if you wish the tooltip to display the elements of arrays.
Value of expression
Choose this if you wish the tooltip to display the value of the current expression.
Note: You can switch between the two styles of the tooltip in the editor. To do this, press and hold Ctrl and hover over the data item to display the alternative tooltip.
Enable automatic outlining
Enables the outlining of the code.
Enable background syntax checking
Enables automatic syntax checking of the code as you type.
Enable quoted syntax intellisense
Enables intellisense support for code that uses the old quoted syntax of the .NET COBOL language.
Synchronize Project Details Window
Enables synchronziation between the Project Details window and Solution Explorer.
Parent topic: Global Options


General Debugging Options

You can specify options that control the behavior when debugging Micro Focus COBOL in Tools > Options > Debugging .
COBOL Debugging Settings > Step over inline PERFORM statements steps into them
By default, Step Over (F10) skips inline PERFORM statements.
Check this option to enable stepping into inline PERFORM statements when you use Step Over. Works with native code only.
Just-in-time > Micro Focus COBOL
Check this to enable just-in-time debugging for when the application fails.
Symbols
Add a new folder by clicking New Folder, and in the Symbol file locations list, enter the absolute path to the .idy files. This makes the symbol files (.idy) available for debugging.
  • COBOL Debugging Settings
    You can set additional options for debugging Micro Focus COBOL in the Visual Studio IDE, in Tools > Options > Debugging > COBOL Debugging Settings.
Parent topic: Global Options


Project Properties

The COBOL project properties comprise some properties that apply to the project generally, regardless of the type of build, and some properties that apply to specific build configurations of the project, such as a debug build or release build.

You access the properties of a projects from Project > <project> properties.

Note: There are a number of controls that are not available for selection. These will be enabled in future releases.
  • Application Properties for .NET Managed COBOL
    The Application property page for managed COBOL projects lets you specify properties such as the name of the target assembly file to build and output type, targeted version of the .NET framework or Startup object .
  • Application Properties for Native COBOL
    The Application property page for native COBOL projects lets you specify properties such as the name of the file to build and entry point for the application.
  • COBOL Link Page
    You use the COBOL Link page in your project properties to link your native project to the run-time system and specify link parameters.
  • COBOL Properties
    The properties you specify on the COBOL page in your project properties apply to the selected configuration.
  • Copybook Paths
    The Copybook Paths page in your project properties enables you to specify the paths to the directories in which this development system searches for copybook files.
  • Debug Properties
    The properties you specify on the Debug page of the project properties apply to the selected configuration.
  • Namespaces
    The Namespaces page in the project properties lets you add or update namespaces for your managed COBOL project, or specify paths to referenced assemblies.
  • SQL Properties
    The SQL page in your project properties enables you to select an ESQL preprocessor and add SQL directives to your project.
Parent topic: Project and File Properties and Options
Related information
Overview of COBOL Project Properties
Options for Setting Directives when Scanning Files
To set COBOL project properties
To specify file properties
To choose options for setting directives when scanning files
To reset the directives on COBOL files


Application Properties for .NET Managed COBOL

The Application property page for managed COBOL projects lets you specify properties such as the name of the target assembly file to build and output type, targeted version of the .NET framework or Startup object .
Assembly name
The name of the target file to be built and the name of the output assembly. By default, this is the same as the project name. Equivalent to the ILASSEMBLY Compiler directive.
Default namespace
A design time only property that allows new classes to be automatically added to the default namespace.
Target framework
Versions of Visual Studio prior to Visual Studio 2008 targeted a specific .NET framework (.NET Framework version 2.0 was included with Visual Studio 2005, .NET Framework 3.0 was included with Windows Vista). Visual Studio 2008 and Visual Studio 2010 can target the .NET framework version that you specify. When you change the target framework, the IDE requires that you close the project and reload it.

When you migrate a project or solution that was created with an earlier version of Visual Studio, the target .NET framework version stays the same. For example, when you migrate a Visual Studio 2005 project to 2008, the .NET Framework version stays set to 2.0.

Output type
Defines the type of project to be built. This is one of console, library or windows. Console defines a console application (always an .exe), library defines a library project such as a collection of shareable classes (always a .dll), and windows defines a windows application. This is initialized depending on the type of new project the user creates. This is equivalent to ILGEN for a console application, ILGEN (SUB) for a library, and ILGEN(SUB) ILSUBSYSTEM(2) for a windows application.
Startup object
Defines the method entry of the application, for .exe-based projects. If no entry name is specified for a Console or Windows application (.exe type), the first static method in the first program (in OO code) or the first procedure division (in procedural code) becomes the main entry point. The name needs to be the full method name as defined in the Program-ID (in order to include the namespace). Equivalent to the ILMAIN Compiler directive.

Assembly Information

Assembly Identity Attributes
Culture
The name of the culture this assembly supports. Equivalent to the ILCULTURE Compiler directive.
Version
The version of this assembly. Equivalent to the ILVERSION Compiler directive.
Assembly Information Attributes
Custom attributes in the assembly manifest for Company, Copyright, Product and Trademark. Equivalent to the ILCOMPANY, ILCOPYRIGHT, ILPRODUCT and ILTRADEMARK Compiler directives.
Assembly Manifest Attributes
Custom attributes in the assembly manifest for Description and Title. Equivalent to the ILDESCRIPTION and ILTITLE Compiler directives.
Assembly Strong Name Attributes
Delay Sign
Indicates whether you want to reserve space in the executable file for the strong name signature, but defer the actual signing until a later stage. Equivalent to the ILDELAYSIGN Compiler directive.
Key File
The name of a file that contains a key or key pair for strong naming the assembly. Equivalent to the ILKEYFILE Compiler directive.
Key Name
The name of container of a key or key pair that has been installed in the Crypto Service Provider (CSP). Equivalent to the ILKEYNAME Compiler directive.

Resources

The Resources section enables you to specify how the application resources will be managed. You can choose between "Icon and Manifest" or specifying a location for a resource file. The manifest can be used for User Account Control (UAC) configuration in Windows Vista or Windows Server 2008.

When you embed a custom manifest, an app.manifest file is added to the project. This file is placed in the Properties folder of the project.

Parent topic: Project Properties
Related information
Introduction to Visual Studio and COBOL


Application Properties for Native COBOL

The Application property page for native COBOL projects lets you specify properties such as the name of the file to build and entry point for the application.
Output name
The name of the target file to be built. By default, this is the same as the project name.
Note: This setting is disabled for native Link Library projects building to Multiple Libraries as each COBOL program in the project compiles to a .dll file with the same filename.
Output type
Defines the type of project to be built. This is one of console, library or windows. Console defines a console application (always an .exe), library defines a library project such as a collection of shareable classes (always a .dll), and windows defines a windows application. This is initialized depending on the type of new project the user creates.
Output To
Select Single Library to build your project to a single .dll file or Multiple Libraries to build separate .dll files for each COBOL source file in your project. This setting applies to native Link Library projects only.
Entry point
Defines the method entry of the application, for .exe-based projects. If no entry name is specified for a Console or Windows application (.exe type), the first static method in the first program (in OO code) or the first procedure division (in procedural code) becomes the main entry point. The name needs to be the full method name as defined in the Program-ID (in order to include the namespace).

This setting is disabled for native Link Library projects as .dlls do not have a main entry point:

  • If you have a Link Library project that builds to a single .dll file, the entry point is always the first COBOL program passed to the linker when the .dll is created, or the program which you may have specified in your own definition (.def) file. If you do not use a .def file, the IDE links programs in the order in which they appear in the project file which is alphabetical order by default.
  • If you have a Link Library project that builds to multiple .dll files (each COBOL program gets built to a separate .dll), the first entry point in each output .dll file is the name of each individual COBOL program in the project.
Parent topic: Project Properties


COBOL Link Page

You use the COBOL Link page in your project properties to link your native project to the run-time system and specify link parameters.
Note: The following settings apply to native projects only.
Output name
Specify a name for the output application file which can be different for the different configurations.
Note: This setting is disabled for native Link Library projects building to Multiple Libraries as each COBOL program in the project compiles to a .dll file with the same filename.
Entry point
Specify a name for the output application file which can be different for the different configurations.
Note: This setting is disabled for native Link Library projects as .dlls do not have a main entry point.

Run-time Model

Shared
Click this to link the application to the shared run-time system. The run-time system is not linked into your executable files, but is loaded dynamically when your application is run.

Click this if you are building a modular application, or a DLL that will be called by a COBOL program.

Dynamic
Check this to bind the application to run-time system dynamically at run time. The application binds to any appropriate run-time system on the end-user's system when it is run. The COBOL run-time system files are automatically located on the end-user's system by looking them up in the Windows Registry.
If you don't select this, your application requires the run-time system supplied with this version of your COBOL development system to be available on the end-user's system. You need to install the run-time system files in the same directory as your application's executable file.
Bind to current RTS only
Select this to dynamically bind the application to a run-time system of the same version (or later) as your COBOL development system.

If you don't select this, the application binds to any suitable run-time system on the end-user's system.

Application type

Console based
Check this if your application is console based.
Graphical
Check this if your application uses a graphical user interface.
Link with objs
Type the names of any .obj files you want to link with this system executable file. Alternatively, you can add them to the Project tree view under the .exe file.
Link with libs
Type the names of any library (.lib) files you want to link with this system executable file. Alternatively, you can add them to the Project tree view under the .exe file.
Include system programs
Select this if you want any run-time system support modules needed by your application to be automatically linked with it. Run-time support modules provide support for the following:
  • User-defined classes in SPECIAL NAMES paragraphs
  • EXTERNAL files and data
  • Enhanced ACCEPT and DISPLAY syntax
  • Intrinsic functions
  • PC_PRINT library routines

If you don't select this, you need to link any support modules needed by adding them to your project.

If your application needs run-time support other than that listed above, it is loaded dynamically at run time.

Keep temporary files
Select this if you don't want temporary files created when linking to be deleted. Temporary files include import libraries, definition (.def) files, and .lnk files.
Generate map file
Select this to create a .map file when your application is rebuilt. The linker map file contains information such as a timestamp, a preferred loading address, a list of public entry points used in the linked object files, and a fixup (load offset) table.
Display verbose output
Select this if you want all notes and messages from the Linker to be displayed in the Output window. Messages that use the LNK prefix are from the Linker, and are explained in more detail in the Microsoft Win32 Software Development Kit.
Additional directives
Type any additional parameters you want to pass to the Cbllink utility. For a list of possible directives, see the command-line reference in the Reference Bookshelf in help, or look up Cbllink utility in the help index.
Parent topic: Project Properties
Related information
Overview of Linking Native COBOL Applications and Run-time Systems


COBOL Properties

The properties you specify on the COBOL page in your project properties apply to the selected configuration.

General

Platform target
The target platform, such as x86, x64 or Any CPU. Any CPU is available for managed code projects only. Valid values are given in the drop-down list.

For .NET managed projects, this is equivalent to the ILTARGET Compiler directive.

Tip: Avoid building your managed projects for Any CPU if they include ActiveX references. Instead, set the particular target platform to either x86 or x64 to match the targeting of the ActiveX control.
COBOL dialect
Specify the COBOL dialect used by your code. This sets the DIALECT Compiler directive for the project accordingly.
Source format
The default source format for source files. This is one of Fixed, Variable, or Free. Equivalent to the SOURCEFORMAT Compiler directive, but can be overridden (and often is) by using a $set statement in the source code.
Output path
The directory that contains the build output files. The output path may differ for native and managed projects.

For .NET managed code this is equivalent to the ILOUTPUT Compiler directive.

Compile for debugging
With this option set, the Compiler creates files containing extra information about your application that is used for debugging.
Generate verifiable code
This setting applies to managed code only. Check this if you want to generate verifiable code. By default, the build produces non-verifiable code as this ensures a better performance of the Compiler.
Note: SQL database projects have this option enabled by default as verifiable code is a prerequisite for the environment.
Generate 64-bit pointers
This setting is available for managed projects only. Compiles the project with 64-bit pointer support enabled. Equivalent to the P64 Compiler directive.

Advanced COBOL Settings

Generate directives file
Generates a file containing the directives that are used to compile the project. The file is named project name.dir and is placed in the project directory.
Register for COM interop
This setting is available for .NET managed code only. Value of true or false, to determine whether or not to register the build output as a COM component, which allows non-.NET code to use the project as if it was a COM object.
XML documentation file
This setting is available for .NET managed code only. Generates documentation in XML format that includes the comments you have made in the source code about the used methods and classes. Equivalent to the ILDOC Compiler directive.
Additional copybook paths
The paths to search for copybook files that apply only to the selected build configuration of the current project. This enables you, for example, to have different copybook paths for debug and release builds. Use semicolon as a delimiter when entering multiple copybook paths.

This option sets the COBCPY environment variable, which is appended with the COBCPY setting in the Registry.

You can specify general copybook paths that apply to the project regardless of the active build configuration on the Copybook Paths page of your project properties. The configuration-specific copybook paths take precedence over the project copybook paths.

Build Events
The commands to be executed before or after the build and when to execute them. See the Visual Studio Help for details.

Errors and Warnings

The Errors and Warnings fields enable you to choose what warnings and errors will be displayed when you build the specified configuration.

Warning level
Specifies the severity of errors or the warning messages that are displayed in the output console.
Stop after
Specifies the maximum number of errors or the warning messages that will be displayed during the build.
Treat warnings as errors
Stops the build when a warning is received.

Additional Directives

This field enables you to specify additional COBOL Compiler directives to pass to the Compiler.

Build Settings

Displays the build directives that are passed to the Compiler.

Note: The controls displayed on the properties page are determined by the type of project you are working on. As a result, some of the controls described here might be missing from your properties page or be unavailable for selection.
Parent topic: Project Properties


Copybook Paths

The Copybook Paths page in your project properties enables you to specify the paths to the directories in which this development system searches for copybook files.

This sets the COBCPY environment variable, which is appended with the COBCPY setting in the Registry.

Parent topic: Project Properties
Related information
Order in which Copybooks Are Searched For


Debug Properties

The properties you specify on the Debug page of the project properties apply to the selected configuration.

Start Action

Start project
Specifies that the project is to be debugged by launching its output.
Note: This setting does not apply to managed class library projects, or to native projects that compile to multiple library files. For these project types, you must specify a different start action.
Start external program
The path to a file to be debugged. This is typically used when your application is a library.
Start browser with URL
Starts debugging by opening a web page.

The following setting is specific for native COBOL projects:

Wait for debuggable attachment
The debugger waits for the program to start in a separate process before attempting to attach to it. Check this if you need to manually launch your process. You can set the following options:
  • Wait for any program - waits for and then attaches to the next COBOL program that calls CBL_DEBUGBREAK, or is launched with the COBSW environment variable set to +A.
  • Wait for directory - waits for and then attaches to the next COBOL program that is launched with its working directory set to either the folder specified on the Debug page in the project properties under Start Options, or a subfolder of it. If no working directory is specified then the project output path is used.
  • Wait for ID - waits for and then attaches to the next COBOL program which calls CBL_DEBUG_START with the identifier you specify in the ID field as an argument. You set the identifier in the source code - see CBL_DEBUG_START.

Start Options

Command line arguments
Program arguments to be passed.
Working directory
The directory from which the program is launched.
Note: If Start Action is set to Wait for debuggable attachment, then the path you specify in this field is used with the Wait for directory option.
Use remote machine
Check this to enable remote debugging. Specify the remote machine by entering its name over the network or its IP address in the adjacent field.
Port
Specify the port number that is used by the cobdebugremote or cobdebugremote64 process.

Debug Options

The following properties apply to native COBOL projects only:

Bind breakpoints only when debug and compilation source file paths match
Check this to ensure that when debugging only the right version of a source file is being used. This helps avoid conflicts between copybook files with the same filenames that are stored in different folders of your project or solution.
Uncheck this if you have moved the source files of the project since the last time the project was built.
This option is enabled by default.
Suspend at 'stop run'
Causes the program being debugged to pause when a 'stop run' statement is reached.
Note: When the program has been paused at stop run, you can stop debugging only by choosing Debug > Stop Debugging.

The following properties apply to managed COBOL projects only:

Enable SQL Server debugging
Enables the Microsoft SQL debugger.
Enable mixed mode debugging
Check this to enable debugging of C/C++ code alongside managed code.
Redirect standard output
Value of true or false, to determine whether or not standard output (such as System.Console.WriteLine) should be redirected to the debugger's output window. For Console projects, this is initially set to False, and for Windows projects it is initially set to true.
Note: This feature does not work for 64-bit applications and on 64-bit machines it is supported only by a x86 platform type.
Note: The controls displayed on the properties page are determined by the type of project you are working on. As a result, some of the controls described here might be missing from your properties page or be unavailable for selection.
Parent topic: Project Properties
Related concepts
Wait for Debuggable Attachment and Native COBOL
Related reference
CBL_DEBUG_START
Setting Run-time Switches
A1 run-time switch
Related information
Overview - Debugging Native COBOL Programs


Namespaces

The Namespaces page in the project properties lets you add or update namespaces for your managed COBOL project, or specify paths to referenced assemblies.
Note: The following settings apply to managed projects only.
Add namespace
Enables you to add namespaces to the project. This is equivalent to the ILUSING compiler directive.
Update
Enables you to specify a different name for an imported namespace.
Reference Paths
Specify the paths to the locations of the assemblies containing classes that are used by the project.

Parent topic: Project Properties
Related information
Tutorial: Developing .NET Managed COBOL


SQL Properties

The SQL page in your project properties enables you to select an ESQL preprocessor and add SQL directives to your project.
ESQL Preprocessor
Select the preprocessor you want to handle your embedded SQL code.
Directives
Displays the directives that are set for your project.
Directive Details
Directive
Shows the selected directive.
Value
Enables you to change the value available for the selected directive.
Disabled
Check this check box to prefix the directive with NO (e.g. ACCESS becomes NOACCESS).
Note: This check box is only enabled when the NO- form of the directive is valid.
Description
Explains the function of the selected directive.
SQL Directives
Displays the directives that are set for your project for the selected ESQL preprocessor.
Parent topic: Project Properties


To set COBOL project properties

The properties set on project level apply to all files in the project.
  1. In Solution Explorer, click the project whose properties you want to set.
  2. Click Project > project_name properties.
  3. Click a tab in the left hand side of the editor to open a particular properties page.
  4. Set the properties as required.
  5. Click File > Save All to save your changes.
Parent topic: Project and File Properties and Options
Related information
To specify file properties
To choose options for setting directives when scanning files
To reset the directives on COBOL files
Project Properties


To specify file properties

Files inherit the properties set on project level. You can, however, specify individual file properties and they override the ones set on project level.
  1. In Solution Explorer, right-click one or more files whose properties you want to set.
  2. Click Properties.
  3. For files used in the COBOL projects such as .cbl set the options and directives you require.
  4. Click OK or press Enter as required.
Parent topic: Project and File Properties and Options
Related information
To set COBOL project properties
To choose options for setting directives when scanning files
To reset the directives on COBOL files
Project Properties
Overview of COBOL Project Properties
Options for Setting Directives when Scanning Files


To choose options for setting directives when scanning files

You can configure the directives scan feature in the IDE and specify what Compiler directives it can set.
  1. Click Tools > Options.
  2. Expand Projects.
  3. Click COBOL Project Settings.
  4. To determine the COBOL dialect of the files and set the DIALECT directive, check Set the DIALECT directive on files.

    The dialect directive is set only if it differs from the directive set for the project.

  5. Check Set SQL directives on files containing EXEC SQL, if required.

    Click [image] and choose the SQL directives to set if they occur in the file.

    Note: You must select the directives you require, as well as check the box or no directives are set on the files.
  6. Check Unset SQL directives on files that do not contain EXEC SQL, if required.

    When SQL directives are unset on a file, they override any SQL setting on the project.

Tip:
  • The status bar identifies the file currently being scanned for directives
  • The output window shows the directives being set on each file
  • To interrupt and stop setting directives, click Project > Cancel file scanning
Parent topic: Project and File Properties and Options
Related information
To set COBOL project properties
To specify file properties
To reset the directives on COBOL files
Overview of COBOL Project Properties
Options for Setting Directives when Scanning Files
Project Properties


To reset the directives on COBOL files

This triggers a directives scann of the COBOL files in your project and sets Compiler directives on them as specified in Tools > Options > Projects > COBOL Project Settings.
  1. If necessary, check and ensure the options for setting directives are the ones you require. Click Tools > Options > Projects and Solutions > COBOL Project Settings.
  2. In Solution Explorer, right-click your project or the file whose directives you want to reset.
  3. Click Reset source directives.
    Each file is handled in turn, as follows:
    • The existing directives are removed
    • The file is scanned to determine the directives currently required
    • Directives are set on the files as specified in COBOL Project Settings.

      If the directive is already set on project level, it is not reset on file level.

  4. Check the Output window to see the results of the directives scanning.

    It shows which files were scanned and what directives have been set or unset on them.

Parent topic: Project and File Properties and Options
Related information
To set COBOL project properties
To specify file properties
To choose options for setting directives when scanning files
Overview of COBOL Project Properties
Options for Setting Directives when Scanning Files
Project Properties


To add references to a managed project

You can add assemblies, COM objects or other projects as references to your managed COBOL projects.

To add assemblies, COM objects or other projects as references to your managed COBOL project:

  1. Select your project in Solution Explorer.
  2. Click Project > Add Reference.
  3. Select a reference to add to your project and click OK.

You can also point to the location of assemblies that contain classes used by your project as follows:

  1. Select your project in Solution Explorer.
  2. Click Project > <project> properties.
  3. Click the Namespaces tab.
  4. Click References Paths.
  5. Add the paths to the location of the referenced assemblies and click OK.
Parent topic: Project and File Properties and Options


Importing Net Express Projects into Visual COBOL for Visual Studio

The Net Express Project Import Wizard enables you to convert existing Net Express projects into Visual Studio solutions so you can use them with Visual COBOL.

The wizard analyzes the Net Express project file and its configuration settings, creates one or more Visual Studio native projects based on this information, imports the existing source code into them and sets the appropriate directives. When the process is complete, it can optionally display a detailed conversion report.

Note: If you have any questions or comments about the Net Express Project Import Wizard or upgrading to Visual COBOL in general, please use the Micro Focus Community pages (http://community.microfocus.com/Home) to get in touch with us and other Visual COBOL users.

The structure of a Net Express project is similar to that of aVisual COBOL solution, where the solution represents a whole application. A solution can contain multiple projects, each one producing a single output file - either an exe or a .dll. The final application then contains a mixture of .exe and .dll files.

Project types
Visual COBOL uses the information from the Net Express project file to determine the type of Visual Studio project it will convert it to. Depending on the output files they produced, Net Express projects convert to different Visual Studio project types as shown below:
Files created by the Net Express project | Visual Studio project type after the conversion
A single output file | A single Visual Studio project
A mixture of executable files | Multiple Visual Studio projects in the same solution each of which produces one executable - .exe or .dll
.int or .gnt files only | The import wizard prompts you for an output name and you can include or exclude some of the files from the project
A combination of .int and .dll or .gnt and .dll files | A library project
A combination of .int and .exe or .gnt and .exe files | An .exe project
.lbr files | A library project. The data files contained inside the .lbr are added to the .dll file with the "copy to output" option set
Copybook paths
Copybook paths are determined by how the Visual Studio project is structured and by what dependency each file has. If a file depends on another file in a different folder, that folder is added to the copybook paths.
Directives
The Visual Studio project and file directives are taken from the Net Express project.

For more on upgrading Net Express applications to Visual COBOL, see Upgrading to Visual COBOL.

  • How to import Net Express projects into the Visual Studio IDE
  • Restrictions and Limitations to Converting Net Express Projects
    The Net Express Project Import Wizard enables you to convert existing Net Express projects into Visual Studio solutions so you can use them with Visual COBOL.
Parent topic: Solutions and Projects in Visual Studio
Related concepts
Moving Existing Native COBOL Applications into Visual COBOL IDE


How to import Net Express projects into the Visual Studio IDE

You can use the Net Express Project Import Wizard as follows:

  1. Ensure that your Net Express project and all relevant files are available and in the same location.
  2. In Visual Studio IDE, click File > New > Solution From Net Express Project
  3. Select the Net Express project you want to convert and click Continue.

    The wizard analyzes the Net Express project and displays the information about the build configurations, copybook paths, the components to which the project compiles and the directives that are set on the source files. These details will be used in the Visual Studio project.

  4. On the Summary tab check Generate Conversion Report if you wish to create and review the details of the conversion.
  5. Click Finish to start the conversion.
  6. If items from the Net Express project previously compiled to .int or .gnt code, the wizard opens a screen prompting you to specify details for another project in your solution that will hold those particular files. Specify your preferences and click Continue.

    The wizard creates a Visual Studio solution with one or more projects for the COBOL code and creates a conversion report file.

  7. Review the report to double check that the project has converted as you expected.
  8. Review the files in Solution Explorer. You should see:
    • One solution representing your Net Express project
    • One or more native COBOL projects within the solution, where each project builds one output file
    • Any files that were in the original project, such as COBOL source files and copybooks
  9. Review the project properties, by right-clicking the project in Solution Explorer and clicking Properties. Notice the following properties:
    • Application - these properties show the type of application that is built, such as a console application or a library
    • Copybook Paths - the paths for copybooks that aren't in known locations, which are the solution folder tree, links from the solution, and the cpylib folder in the Visual COBOL installation
    • COBOL - the Directives and Build Settings specify the settings that were in the original Net Express project
    • Debug - these properties define how the application starts, such as any command line arguments
  10. You can also check the individual file properties, by right-clicking a COBOL source file in Solution Explorer and clicking Properties.
Parent topic: Importing Net Express Projects into Visual COBOL for Visual Studio


Restrictions and Limitations to Converting Net Express Projects

The Net Express Project Import Wizard enables you to convert existing Net Express projects into Visual Studio solutions so you can use them with Visual COBOL.

  • Visual COBOL does not include Mainframe Subsystem Support (MSS) and it is not possible to convert Net Express projects that include MSS functionality with it. To convert such projects you need to use Micro Focus Enterprise Developer.
  • If you import a Net Express project that uses functionality other than MSS that is not supported in Visual COBOL, the wizard will still produce a Visual Studio solution. In such a case you might need to perform additional steps (such as editing source files, installing AddPacks, or reworking parts of the application) before you can successfully compile and run it.
  • .int, .gnt and .lbr files that were built using Net Express or Server Express are not supported under the Visual COBOL run-time system and cannot be produced from the IDE. However, these file formats are supported if you recompile the files using the Visual COBOL Compiler at the command line.
Parent topic: Importing Net Express Projects into Visual COBOL for Visual Studio


Adding Existing COBOL Items to a Project

To add existing COBOL files or copybooks to a Visual Studio COBOL project:

  1. In Solution Explorer, right-click your project.
  2. Click Add Existing COBOL Items.

    This opens the Add Existing Files To Current Project dialog box.

  3. Select the folders that contain the files to add to the project as follows:
    1. Click Add.
    2. Browse to the folder that contains the source files and select it.
    3. Click Select Folder.
    4. Ensure Add subfolders is checked if you want to add files from all subfolders.
    5. Repeat to add other folders as needed.
  4. Ensure File types to add to the project lists the file extensions that you want to add to your project.
  5. Check Add copybooks to Solution Explorer to display the copybook files as part of the project in Solution Explorer.
  6. Click Finish.
Parent topic: Solutions and Projects in Visual Studio
Related concepts
Moving Existing Native COBOL Applications into Visual COBOL IDE
Creating COBOL Projects from Existing Code
Building COBOL Applications
Debugging Native COBOL Programs
Exploring Your COBOL Projects and Solutions
To set COBOL project properties
To specify file properties
To reset the directives on COBOL files


Creating COBOL Projects from Existing Code

Visual COBOL enables you to import existing COBOL applications into Visual Studio and use its rich development environment to edit and maintain them. You can easily import a legacy COBOL application such as one that ran on the mainframe or that was created with earlier Micro Focus development environments, then update and modernize it in Visual COBOL, compile as managed code and run it on the .NET Framework. You can import the files into a new project or add them to a project that already exists.

The Create Projects from Existing Code wizard helps you choose and configure a Visual Studio project type to use, and imports your existing files. It scans the files as it imports them to determine whether they are COBOL programs or copybooks, and sets directives for each imported file according to the determined file type, taking into account any relevant IDE options.

The following steps show how you create a Visual Studio project from existing COBOL code using the wizard:

  • Configuring the Visual Studio Project
  • Importing the Existing COBOL Files
  • Summary Report of the Import
Parent topic: Solutions and Projects in Visual Studio
Related concepts
Moving Existing Native COBOL Applications into Visual COBOL IDE
Adding Existing COBOL Items to a Project
Building COBOL Applications
Debugging Native COBOL Programs
Exploring Your COBOL Projects and Solutions
To set COBOL project properties
To specify file properties
To reset the directives on COBOL files


Configuring the Visual Studio Project

The process of creating and configuring a Visual Studio COBOL project with the wizard is as follows:

  1. Locate the source files.
  2. Click Tools > Options > Projects > COBOL Project Settings.
  3. Ensure the directives on the Options page are set as appropriate.

    The directives set on this page are set on imported files. For example, you can choose to set the dialect directive or various SQL directives. After the files are imported in the project, the IDE performs an additional directives scanning of them and sets the directives as necessary.

  4. Click File > New > Project from Existing Code to invoke the wizard.
  5. On the Welcome page, ensure Micro Focus COBOL is selected as the project type to create.
  6. Click Next.
  7. On the Specify Project Location, Project Type and Source Files page, specify a directory, a name and an output type for the Visual Studio project.

    You do not need to specify the cblproj extension in the name as the wizard adds it automatically.

  8. Specify the folders that contain the source files to import into your project:
    1. Click Add.
    2. Browse to the folder that contains the source files and select it.
    3. Click Select Folder.
    4. Check Add subfolders if you want to add files from all subfolders.
    5. Repeat and add other folders as needed.
  9. Ensure File types to add to the project lists all file extensions that you want to add to your project.
  10. Check Add copybooks to Solution Explorer if you want to show the copybook files as part of the project in Solution Explorer.
  11. Click Next.
  12. On the Specify New COBOL Project Properties page, specify whether to create a native or a managed project.
  13. For native projects, select the target platforms.
  14. Click Finish.
Parent topic: Creating COBOL Projects from Existing Code
Related concepts
Importing the Existing COBOL Files
Summary Report of the Import


Importing the Existing COBOL Files

During the file import process Visual Studio will be unresponsive to any other events because the file import process is asynchronous.

During file import, the wizard performs the following steps:

  1. Creates a Visual Studio project in the specified directory.
  2. Scans the files in the source folders to determine which ones are COBOL programs and which are copybooks.
  3. Imports the files of the selected file types into your project:
    • If the source files are in the same folder, the wizard adds them to the project and re-creates the subfolder structure.
    • If the source files are stored in other folders, the wizard only links them to your project.
  4. Adds the paths to the source folders that contain copybook files to the COBCPY environment variable as paths relative to the project.

    To see what paths are set for the project, click Project > ProjectName Properties and check the Copybook Paths tab.

  5. Adds the copybooks to the project in Solution Explorer (if you specified this in the wizard).
  6. Sets the Compile build action on files which it identified as COBOL programs.

    Copybook files do not compile so no build action is set on them.

  7. Performs a directives scan of the imported files and sets additional directives as specified in Tools > Options > Projects > COBOL Project Settings.
  8. Displays a summary report about the files it imported, the directives and copybooks paths that it set in the Output window.
Parent topic: Creating COBOL Projects from Existing Code
Related concepts
Configuring the Visual Studio Project
Summary Report of the Import


Summary Report of the Import

Check the Output window for summary report of the actions the wizard performed. From the drop-down list next to Show output from choose:

  • Import Files Results - shows a list of the files that were imported and the copybooks paths that were added to the COBCPY environment variable.
  • General - shows results from the file scan and the directives that were set as specified in Tools > Options > Projects > COBOL Project Settings.
Parent topic: Creating COBOL Projects from Existing Code
Related concepts
Configuring the Visual Studio Project
Importing the Existing COBOL Files


Creating COBOL Projects from Selected Files

You can use selected files in a COBOL project to create new projects in the same solution. Splitting the code and moving parts of it into a different project can be useful when you need to move code to a dynamic library project.

Visual COBOL provides the COBOL Projects From Selection dialog to help you with this task:

To use the dialog, you need to select a number of files in your project in Solution Explorer and select Create Project from the context menu. The dialog lets you specify the project type and whether you want to copy or move the selected the files into the new project. It creates a new project in the same solution with the same properties and references and with the default build configuration for the selected project type.

  • To create a COBOL project from selection
    Use the Create Project from Selection dialog to subdivide your COBOL solutions into projects.
Parent topic: Solutions and Projects in Visual Studio


To create a COBOL project from selection

Use the Create Project from Selection dialog to subdivide your COBOL solutions into projects.
  1. In Solution Explorer, select the COBOL files and copybooks to use in the new project.
  2. Right-click the selection and choose Create Project. This starts the Create Project from Selection dialog:

  3. Specify details for the new project as follows:
    Project Name, Output Type
    Specify a name and type for the new project to create in the directory of the original solution.
    Managed project
    Uncheck this if you want to create a native project.
    More Details
    Click this to verify what files will be used in the new project.
    Exclude selection from original project
    Ensure this is checked if you want to move the selected files from the original project to the new one. If you uncheck this, the selected files are copied to the new project.
  4. Click OK.
This creates a new project in your solution with the same properties and references and with the default build configuration for the selected project type. If Exclude selection from original project was checked, the files you selected are now moved to the new project.
Parent topic: Creating COBOL Projects from Selected Files


Building COBOL Applications

To build an application, you need to compile its programs and link them to a run-time system. You use a build configuration to define how to do this.

  • Build Configuration
  • To build a COBOL project
  • Compiling COBOL Applications
  • Linking Native COBOL Code
  • How to...
Parent topic: Developing COBOL Applications
Related concepts
Moving Existing Native COBOL Applications into Visual COBOL IDE
Creating COBOL Projects from Existing Code
Adding Existing COBOL Items to a Project
Debugging Native COBOL Programs
Exploring Your COBOL Projects and Solutions
To set COBOL project properties
To specify file properties
To reset the directives on COBOL files


Build Configuration

Before you build a project you need to configure how to build in a build configuration.

The following build configurations are available: Debug build and Release build. You can also create your own custom build configuration.

You use the Configuration Manager to choose the build configuration to use for your project / solution, create new build configurations or edit the existing ones.

The combination of configuration type and platform settings define the build configuration of your project / solution. For example you can create a Debug build configuration for x86 platforms, and a Debug build configuration for x64 platforms. Use Project Properties to view and change the platform type for which you want to build your application.

See the Visual Studio Help for more information on build configuration and build configurations and build platforms.

Parent topic: Building COBOL Applications
Related information
Project Properties


To build a COBOL project

Note: The following information is specific to native COBOL applications.
  1. Specify the build configuration.

    Use the Configuration Manager to choose the build configuration to use for your project or solution.

  2. Set the project's properties and specify items such as:
    • On the Application tab, specify the type of executable to build, such as a class library or an application
    • For native Link Library projects, specify whether to produce a single library file or multiple library files for each COBOL program in your solution
    • On the COBOL tab, specify how to build the project, such as Compiler directives and link settings
    • On the COBOL Link tab, specify any link settings
    • On the Copybook Paths tab, specify the copybook locations
    • On the Debug tab, choose the build configuration, such as Debug or Release.
  3. Choose a run-time system.
  4. Define the resources used by your application.
  5. Specify settings for your application such as environment variables and COBOL switches.
  6. Build the project, by clicking Build > Build project name.
Parent topic: Building COBOL Applications
Related tasks
To add a configuration file
Related information
To embed resources in a native COBOL application
To set project properties
To set project-wide build properties and compiler directives
To link a native COBOL project to the run-time system
Project Properties


Compiling COBOL Applications

Before you can run a program, you have to compile the source code.

  • Overview - Compiling COBOL Code
  • Setting Compiler Directives for COBOL
  • Compiled File Types for Native COBOL
  • Temporary Files Used when Compiling Native COBOL
  • Techniques for Compiling Quickly
Parent topic: Building COBOL Applications
Related information
Command Line Reference
Setting Directives Outside the IDE
The cobol Command
cbllink


Overview - Compiling COBOL Code

Before you can run a program, you have to compile the source code.

By default, the Compiler compiles your program without any intervention. You can configure the project to be built in a specific way, such as specifying types of target files to build, the target platform and so on.

You can configure the compilation using the following techniques:

  • Compiler directives. You can control the way programs are compiled by using Compiler directives.

    You use directives to control the way the Compiler behaves. Normally, you need only a few directives. Most of the time, you use the default values. Note that setting some directives affects the default setting of other directives. For example, setting one directive might automatically unset another directive, and some directive settings are mutually exclusive.

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

The Compiler records errors with severity levels ranging from information messages to fatal errors which stop the Compiler working.

When you compile as native code, 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.

Compiling from the command line

Using the command line, you can compile without linking using the cobol command, or compile and link your program in one step using the cbllink utility.

You can either specify all the information required on the command line, or use the Compiler prompts.

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 within the IDE, either on the whole project or on an individual file. You set:

  • Project-wide directives in the build configuration for the project.
  • File-specific directives in the individual file's properties. The file-specific properties override the project-wide ones.

Separate compiler directives with a space. You can supply parameters either within brackets or speech marks: for example charset"ascii" dialect(MF), and if you need more than one parameter for a particular directive, separate the parameters with a comma: for example outdd(sysout 121 r e) or ACTUAL-PARAMS"MyInterface ClassA ClassB".

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.

Important: If you are using COBSQL or DB2 ECM, you might need to set some additional directives.

Setting Compiler Directives from the Command Line

When you compile from the command line using the cobol command, you include any directives as part of the command. This applies to command line fields in the IDE and any compilation started from a prompt.

Setting Compiler Directives in a Response to a Prompt

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.

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"

Setting Compiler Directives in a Directives File

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.

CAUTION:
This file affects all compilation done on the system and using it or editing it can result in unexpected effects.
  • To set project-wide build properties and compiler directives
Parent topic: Compiling COBOL Applications
Related tasks
To set project-wide build properties and compiler directives
To compile a single file
Related information
Compiling from the Command Line
Compiler Directives
Setting Directives Outside the IDE
To set project-wide build properties and compiler directives


To set project-wide build properties and compiler directives

  1. Click Project > MyProject Properties.
  2. Click the COBOL tab.
  3. In Additional directives, type the directives you want to use. Separate the directives with a space.
  4. Click File > Save.

The compiler directives are saved with the project, so that they are used on all files in the project the next time you rebuild.

These directives are overridden by any specified for individual source filesand for the build type.

Parent topic: Setting Compiler Directives for COBOL
Related information
Compiling from the Command Line
Compiler Directives
Setting Directives Outside the IDE


Compiled File Types for Native COBOL

Restriction: The following applies to native COBOL only.

Before your program can be run or debugged, it must be in a form that can be executed. The Compiler can produce the following types of files:

Callable shared objects
Callable shared objects are dynamically loaded at run time when required, that is, when referenced as a main entry point (for example, by cobrun) or by the COBOL CALL syntax. When all the entry points in a callable shared object have been canceled then the callable shared object is unloaded, releasing any memory used.

This behavior 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 callable shared object can contain more than one COBOL program and can also contain other language programs, such as C and C++. Callable shared objects can also be linked with third party object files or shared libraries. This behavior is similar to system executables and shared libraries.

A callable shared object file has a filename extension of .dll.

Executable code
You produce executable code by compiling and linking in one step.

An executable file has a filename extension of .exe.

Object code
You can compile to object code from the source code file. 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.

Object code files must be linked to create .exe or .dll files.

Parent topic: Compiling COBOL Applications


Temporary Files Used when Compiling Native COBOL

Note: The following information applies to native code only.

The Compiler creates a number of temporary work files. The size of them depends on the content of your program and the directives used, in particular the number of data and procedure names. The Compiler puts the files in the directory indicated by the TMP environment variable. If this environment variable does not exist, the files are created in the current directory.

The Compiler normally deletes these temporary files before it terminates. However if the Compiler terminates abnormally, for example due to machine failure, it might leave these files on disk. You can delete them, unless the Compiler is running in another session.

Before compiling, you must ensure there is enough free space for these temporary files in the appropriate directory.

Parent topic: Compiling COBOL Applications


Techniques for Compiling Quickly

Note: The following information applies to native code only.

A large application can consists of many programs; compiling all of these might take some time. To speed up the compilation process, use the following Compiler directives:

  • NOALTER. If your code does not have any ALTER statements, you can disable the ALTER default directive and produce slightly more efficient code and produce it more quickly.
  • NOCOPYLIST. If you are using the LIST directive to create a listing file, you can disable the COPYLIST default directive and prevent the Compiler from expanding the copybooks and include files in the listing. Note that compilation is quicker still if you do not create a listing.
  • NOLIST. This is the default. Compiling is quicker if you accept this default and do not produce a listing file.
  • NOQUAL. If your code does not use qualified data names, you can disable the QUAL default directive to compile more quickly. An example qualified data name is:
    elementary-item-a  of  group-item-1
Parent topic: Compiling COBOL Applications
Related reference
COPYLIST
ALTER
LIST
QUAL


Linking Native COBOL Code

There are several ways to link to the run-time system. The way you link depends on the type of application.

To link native code, the following information is applicable:

  • 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
Parent topic: Building COBOL Applications


Overview of Linking Native COBOL Applications and Run-time Systems

Note: The following information applies to native code only.

When you link a program compiled as native code, 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
Related information
Run-time System Configuration
To link a native COBOL project to the run-time system
cbllink


Shared Run-time System for Running Native COBOL Applications

Note: The following information applies to native code only.

The shared run-time system for running native COBOL code 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.

Parent topic: Linking Native COBOL Code


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 in the Link page of the Build Settings, or by using the Cbllink utility.

Parent topic: Linking Native COBOL Code
Related information
Link Settings
To link a native COBOL project to the run-time system
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 that are built as native COBOL code, 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\Visual COBOL\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


Loading a Dynamic Link Library Built as Native COBOL Code

Note: The following information applies to native code only.

.dll files (which are built as native COBOL code) 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


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 in native code 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


How to...

  • To embed resources in a native COBOL application
  • To add a configuration file
  • To add a resource script file to your native COBOL project
  • To edit a resource-definition script file for a native COBOL project
  • To set an entry point for a native COBOL project
  • To link a native COBOL project to the run-time system
Parent topic: Building COBOL Applications


To embed resources in a native COBOL application

Note: The following information applies to native COBOL applications only.
  1. Create individual files for your cursors, icons, bitmaps, dialog boxes, and fonts.
  2. Create the resource-definition script file (.rc file) that describes the resources used by your application outside of Visual Studio.
  3. Add the resource-definition script file (.rc file) to your project.
  4. Build your project.

    During the build the resource script file compiles to a resource file (.res) which then is linked by the cbllink utility into the output application file (.dll or .exe).

Note that this release does not support the Visual Studio resource editor and you can edit the resource-definition files in the IDE only in code view. It is recommended to create and edit your resource-definition script files outside of Visual Studio.

Parent topic: How to...
Related information
To add a resource script file to your native COBOL project


To add a configuration file

  1. In Solution Explorer, right-click your project.
  2. Click Add > New Item .
  3. Select the relevant configuration file for your application.
  4. Specify a filename in the Name field.
  5. Click OK.
Parent topic: How to...
Related information
To embed resources in a native COBOL application
To set project properties
To set project-wide build properties and compiler directives
To link a native COBOL project to the run-time system
Project Properties


To add a resource script file to your native COBOL project

Note: The following information applies to native COBOL applications only.
  1. In Solution Explorer, right-click your project.
  2. Click Add > Existing Item.
  3. Set Object of type filter to Resources files (.rc).
  4. Browse to the location of the resource script file and select it.
  5. Click Add.
Parent topic: How to...
Related information
To embed resources in a native COBOL application


To edit a resource-definition script file for a native COBOL project

Note: The following information applies to native COBOL applications only.

This release does not support the Visual Studio resource editor and the resource-definition script (.rc) files that you use in your COBOL projects can be opened only in code view.

It is recommended to use other applications to edit resource-definition script files.

Parent topic: How to...


To set an entry point for a native COBOL project

Note: The following information applies to native COBOL applications only.
  1. Right-click a project in the Solution Explorer and click Properties.
  2. Click the Application tab on the left-hand side of the Properties window.
  3. Specify an entry point for your project in the Entry point field.
Parent topic: How to...
Related information
Application Properties for Native Projects


To link a native COBOL project to the run-time system

Note: The following information applies to native COBOL applications only.
  1. Right-click a project or a solution in the Solution Explorer and click Properties.
  2. Click the COBOL Link tab on the left-hand side of the Properties window.
  3. In the section check shared or dynamic, as appropriate.
Parent topic: How to...


Debugging Native COBOL Programs

Note: The following information applies to native code only.
  • Overview - Debugging Native COBOL Programs
    Your COBOL development system provides a debugging environment, which is sensitive to COBOL and includes all the usual features such as stepping, watch windows and breakpoints.
  • Debugging Features in the IDE
  • Just-In-Time Debugging and Native COBOL
  • Debugging Using a Core Dump
    You can arrange for an error in your application to automatically produce a core dump.
  • Remote Debugging of Native COBOL Applications
  • To configure the symbol path for native COBOL applications
  • To set a COBOL watchpoint in native COBOL code
  • To set a program breakpoint in native COBOL code
  • To attach to a native running process and debug
  • To attach to a 64-bit running native process and debug
Parent topic: Developing COBOL Applications
Related concepts
Moving Existing Native COBOL Applications into Visual COBOL IDE
Creating COBOL Projects from Existing Code
Adding Existing COBOL Items to a Project
Building COBOL Applications
Exploring Your COBOL Projects and Solutions
To set COBOL project properties
To specify file properties
To reset the directives on COBOL files


Overview - Debugging Native COBOL Programs

Your COBOL development system provides a debugging environment, which is sensitive to COBOL and includes all the usual features such as stepping, watch windows and breakpoints.
Note: The following information applies to native code only.

When you debug an application, the source code of each program is displayed in a separate window. Each line of the source is highlighted in turn as each statement is executed, showing the effect of each statement. You can execute the program at full speed and can interrupt execution to examine and change data items.

You control the way debugging works by setting options on the Debug page of the project's properties and in the option pages which you can access from Debugging > Options and Settings > Debugging.

Parent topic: Debugging Native COBOL Programs
Related information
Debugging COBOL


Debugging Features in the IDE

  • Debugging Native COBOL Link Libraries
    You can directly debug Link Library projects that produce a single .dll file, whereas for Link Library projects which produce multiple .dll files you must specify one of the output .dll files (or an executable which loads it) in the "Start external program" option on the Debug tab in your project properties.
  • Wait for Debuggable Attachment and Native COBOL
    When you use Wait for debuggable attachment the debugger waits for the program to start in a separate process before attempting to attach to it.
  • Using COBOL Watchpoints and Break on Data Change in Native COBOL
    Native code applications can cause memory overflows by occasionally writing in memory when they should not. You might not be able to locate the line of code that is responsible for the overflow and the only way to find the problem is to watch the area of memory.
  • Using the Memory Window in Native COBOL
    The Memory Windows enables you to view and monitor the contents of the memory.
  • Debug Tooltips
    While debugging you can hover a data item to view its value in a debug tooltip.
Parent topic: Debugging Native COBOL Programs


Debugging Native COBOL Link Libraries

You can directly debug Link Library projects that produce a single .dll file, whereas for Link Library projects which produce multiple .dll files you must specify one of the output .dll files (or an executable which loads it) in the "Start external program" option on the Debug tab in your project properties.

You can directly debug Link Library projects that produce a single .dll file. The entry point for this type of projects is always the first COBOL program passed to the linker when the .dll is created, or the program which you may have specified in your own .def file. If you do not use a .def file, the IDE links programs in the order in which they appear in the project file which is alphabetical order by default.

Restriction: You cannot directly debug native Link Library projects which produce multiple .dll files (each COBOL program in the project compiles to a separate .dll file). Instead, you must specify one of the output .dll files (or an executable which loads it) in the "Start external program" option on the Debug tab in your project properties.
Parent topic: Debugging Features in the IDE
Related reference
Application Properties for Native Projects


Wait for Debuggable Attachment and Native COBOL

When you use Wait for debuggable attachment the debugger waits for the program to start in a separate process before attempting to attach to it.
Note:
  • Works with native COBOL only.

To enable the option:

  1. Click Project > MyProject Properties and click the Debug tab.
  2. Check Wait for debuggable attachment and choose an appropriate option from the corresponding list.
Parent topic: Debugging Features in the IDE
Related reference
Debug Properties


Using COBOL Watchpoints and Break on Data Change in Native COBOL

Native code applications can cause memory overflows by occasionally writing in memory when they should not. You might not be able to locate the line of code that is responsible for the overflow and the only way to find the problem is to watch the area of memory.
Restriction: Works with native code only.

Your COBOL development system provides COBOL watchpoints to help you track memory corruption. COBOL watchpoints are a type of breakpoints that you set on individual data items and not on lines of code. They enable you to watch an area of memory associated with the particular data item. When the memory changes, debugging stops on the line that immediately follows the line on which the data has changed.

You can set watchpoints ( [image]) on data items in any section of the code directly from the editor.

The COBOL watchpoints are associated with the Watchpoints (Native COBOL) window (show by clicking Debug > Windows > COBOL Watchpoints).

  • Shows a list of the watchpoints that have been set in the code.
  • Enables you to add new watchpoints, disable or delete the existing ones - [image], [image], [image], [image].
  • Highlights the watchpoint that has been hit.
  • Displays the values of the data items in decimal or hexadecimal format and their types.
Parent topic: Debugging Features in the IDE


Using the Memory Window in Native COBOL

The Memory Windows enables you to view and monitor the contents of the memory.

Restriction: Works with native COBOL only.

To display the window, click Debug > Windows > Memory > Memory n in debug mode.

Use the Memory window to:

  • Search the memory by typing any of the following in the Address field:
    • A data item
    • The address of a data-item - address of varname
    • A pointer reference - for example, varnamepointer
    • A memory address such as H"nnnnnnnn"
    • An expression
  • Monitor the contents of the memory - any values that change during the execution of the program are displayed in red.
  • View the contents of the memory in hexadecimal or decimal view:
    1. Right-click in the window and select the format you prefer to show the values.
  • Change the values of the memory:
    1. Right-click a value in the window and select Edit Value.
Parent topic: Debugging Features in the IDE


Debug Tooltips

While debugging you can hover a data item to view its value in a debug tooltip.

To query an item from a program which is not the current program being debugged, you need to point that program as the current context in the call stack list as described below. Otherwise, the context is the current program being debugged and the tooltips show the wrong values. This is the default Visual Studio behavior.

Viewing the debug tooltips for a program which is not the one being debugged

To point which program is the current context:

  1. Start debugging your project and step into the code.
  2. Click Debug > Call Stack to display the call stack.

    The program being debugged is indicated by a yellow arrow. This program is also the current context.

  3. Continue stepping the code till the call stack list is populated with the other programs in your application.
  4. Double-click the program you wish to query in the call stack list.

    This adds a green arrow in front of the program in the list to indicate it is the current context.

  5. In the editor, open the program or the copybook which contains a reference to the item you want to query.
  6. Hover a data item.

    The debug tooltip should display the correct value.

Debug Tooltips for Subscripted OCCURS Items

You can configure the style of the debug tooltips to either show all items in an array or the value of an expression. You can do this from Tools > Options > Text Editor > COBOL > Miscellaneous and set your preference in the Debug tooltip style for OCCURS items field.

You can change the tooltip style in the editor with the following default key sequence - ALT+T, T.

Parent topic: Debugging Features in the IDE


Just-In-Time Debugging and Native COBOL

  • Overview - Just-In-Time Debugging and Native COBOL
    Just-In-Time debugging allows a debugger to be connected to a running application when an error occurs.
  • To enable just-in-time debugging for when the application fails for Native COBOL
  • Troubleshooting - Just-In-Time Debugging and Native COBOL
    Provides tips on resolving issues you can encounter while debugging using Just-In-Time.
Parent topic: Debugging Native COBOL Programs


Overview - Just-In-Time Debugging and Native COBOL

Just-In-Time debugging allows a debugger to be connected to a running application when an error occurs.
Note: The following information applies to native code only.

This is how you use the Micro Focus Native Debugger for Just-In-Time debugging when a runtime error occurs:

  1. Just-In-Time debugging must be enabled. See To enable just-in-time debugging for when the application fails .
  2. When a runtime error occurs, the Visual Studio Just-In-Time Debugger dialog is displayed with a list of the possible debuggers to use.
  3. Select a Visual Studio debugger.

    This can either be a new instance of Visual Studio or one that is already running.

  4. Check Manually choose the debugging engines.
  5. Click Yes to start debugging.
  6. In the Attach to Process dialog, ensure only Micro Focus Native Debugger is selected under Choose the types of code to debug.
  7. Click OK.

    The debugger attaches to the application that caused the error.

Note:
  • To debug the application, the debugger must find the symbols file (the .idy file). Depending on what application you debug the path to the symbols file may need to be manually defined.
  • If you have the source files and the .idy files, the source code is displayed at the line where the error occurred. If you do not have the required files, the name of the source file or the program where the error occurred is displayed.
  • For 64-bit applications, your COBOL development system must be running and waiting for a debuggable attachment.
Parent topic: Just-In-Time Debugging and Native COBOL
Related information
To enable just-in-time debugging for when the application fails for Native COBOL
Troubleshooting - Just-In-Time Debugging and Native COBOL


To enable just-in-time debugging for when the application fails for Native COBOL

Note: The following information applies to native code only.
  1. Click Tools > Options > Debugging > Just-In-Time.
  2. Check Micro Focus Native Debugger.
Note:
  • For 32-bit applications, when your application fails, the COBOL debugger is invoked if it is not already running.
  • For 64-bit applications, your COBOL development system must be running and waiting for a debuggable attachment.
  • If you have the source files and the .idy files, the source code is displayed at the line where the error occurred. If you do not have the required files, you are given the name of the source file or program where the error occurred.
Parent topic: Just-In-Time Debugging and Native COBOL
Related information
Overview - Just-In-Time Debugging and Native COBOL
Troubleshooting - Just-In-Time Debugging and Native COBOL


Troubleshooting - Just-In-Time Debugging and Native COBOL

Provides tips on resolving issues you can encounter while debugging using Just-In-Time.
Note: The following information applies to native code only.
"The program does not show in the debugger"
Problem:

You experience one of the following problems when you are debugging your program:

  • You step into a program, but the program runs without debugging.
  • You receive the following alert: "No Source Available. No symbols are loaded for any call stack frame."

    Cause: The reason for this may be that the symbols file (the .idy file) is not found.

    To confirm that this is the issue:

    1. In the Output window, select Show output from: Debug.

      This shows the program name, and if the .idy file was loaded.

    2. Click Debug > Windows > Modules.

      This opens the Modules window that shows all the programs that have been loaded and the relevant symbol status for them.

    3. If the status is "Cannot find or load the IDY file", right-click on the program in the Modules window and choose Symbol Load Information.

      This displays the directory paths that were used to search for the .idy file.

Parent topic: Just-In-Time Debugging and Native COBOL
Related information
To enable just-in-time debugging for when the application fails for Native COBOL
Overview - Just-In-Time Debugging and Native COBOL


Debugging Using a Core Dump

You can arrange for an error in your application to automatically produce a core dump.
Note: The following applies to native code only.
  • Debugging Using a Core Dump
    You can arrange for the state of an application to be saved to disk in a core dump file when the application crashes. You can then use the dump file to help debug problems, as it indicates where in the source code the error occurred, along with the values of variables, expressions, and the contents of memory as they were at the moment the error occurred.
  • core_on_error
    Specifies in what circumstances a core file is produced.
  • core_filename
    Specifies the name of the file that is generated when the core_on_error tunable is set to 3.
Parent topic: Debugging Native COBOL Programs


Debugging Using a Core Dump

You can arrange for the state of an application to be saved to disk in a core dump file when the application crashes. You can then use the dump file to help debug problems, as it indicates where in the source code the error occurred, along with the values of variables, expressions, and the contents of memory as they were at the moment the error occurred.
Note:
  • On Windows, the core dump files created by this product are Microsoft minidump files. If you have a mixed language application you can use the minidump file to debug the other languages involved.
  • The following information applies to native COBOL code only.

You can produce a core dump even when you don't have the COBOL development system installed. This is valuable when you are debugging a released application on site, and you have only the COBOL Server environment installed.

You must have the source files and the .idy files to get the most detail from the core dump. If you do not have the required files, the IDE indicates that no source is available.

You can produce a core dump file in one of the following ways:

  1. Copy the file cblcored.exe from the bin subfolder in the product installation directory to the same directory as your application's main executable file.
  2. At the command line, go to the directory containing cblcored.exe and type:
    cblcored
  3. From the Core Dump list, select one of the following:
    • Enabled with prompt if you want a message box displayed when a core dump is about to be created.
    • Enabled with no prompt if you do not want a message box displayed when a core dump is about to be created.
    • Disabled if you do not require a core dump.

    If you have selected one of the enabled options, the next time you run the application and an error occurs, the state of the application at the time of the error is saved in the file cblcore. This file is saved in the same folder as the application.

Alternatively, you can configure the system so that it produces a core dump for run-time errors. To do this:

  1. Create a run-time tunable configuration file and add to it the core_on_error tunable.

    The default name of the core dump file to be produced is cblcore. To specify a different file name, add the core_filename tunable to the run-time tunable configuration file.

  2. Run the application. When the application crashes, a core dump is produced.

To debug a core dump file:

  1. In the IDE, click Project > MyProject Properties and navigate to the Debug tab.
  2. Click Start external program and specify the name of the Micro Focus core dump file.
  3. When you start debugging you can query the state of the program at the point at which the error occurred.
Note:
  • You cannot enable both Just-In-Time Debugging and Core Dump concurrently.
  • To debug a 64-bit core dump you must first create a 64-bit project configuration or select x64 as the Platform target on the COBOL tab in the Project Properties.
  • cblcored.exe is one of the COBOL Server files, which is provided for on-site debugging. You are authorised to redistribute this file to your customers providing you have the appropriate license.
  • 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.
Parent topic: Debugging Using a Core Dump
Related reference
core_on_error
core_filename
Run-time Configuration Tunables - Overview
Format of a Configuration File for Native COBOL


core_on_error

Specifies in what circumstances a core file is produced.
Restriction: This tunable is supported for native COBOL only.

Syntax:

>>-----set core_on_error=---.-0-.-----------><
                            +-1-+
                            +-2-+
                            +-3-+
                            +-129-+
                            +-130-+
                            +-131-+

Parameters:

0 | The run-time system never produces a core file on any exception or run-time system error. This is the default behavior of the run-time system.
1 | The run-time system produces a core file when any exception is received that would normally produce a core file on the host system; for example, a run-time system error COBRT114, and so on.
2 | The run-time system produces a core file when any run-time system error occurs. After writing out the core file the process terminates immediately.
3 | The run-time system produces a snap shot core file when any run-time system error occurs. After writing out the core file the process continues as normal; for example, to display an RTS error message.
129 | Same as core_on_error=1, except no message box is displayed after the core file is created.
130 | Same as core_on_error=2, except no message box is displayed after the core file is created.
131 | Same as core_on_error=3, except no message box is displayed after the core file is created.

Properties:

Default: | 0
IDE equivalent: | None

Comments:

You can debug core files to determine the cause of the problem if you have the appropriate dictionary (.idy) files. When a core file is produced, using core_on_error=1 or core_on_error=2, the run-time system itself cannot clean up COBOL file buffers or free system resources. This could lead to data file corruption that might not have occurred if no core file was produced.

Parent topic: Debugging Using a Core Dump
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
debug_on_error
signal_regime


core_filename

Specifies the name of the file that is generated when the core_on_error tunable is set to 3.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set core_filename=---"filename"-----------><

Parameters:

filename The 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 folows:
%%
Single %
%d
The date of when the program encountered the error, in the format yyyymmdd
%f
The basename of the program that encountered the error
%p
The process ID of the program that has encountered the error
%t
The time of when the program encountered the error, in the format hhmmss

Properties:

Default: | cblcore in the current working directory.
Setting: | None

Example:

The command

set core_filename="core.%p@%t_%d"

will produce a filename such as core.12345@165920_20080115.

Parent topic: Debugging Using a Core Dump
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


Remote Debugging of Native COBOL Applications

Note: The following applies to native code only.
  • Overview - Debugging Native COBOL Applications Remotely
    You can use Visual COBOL to debug programs that are running on a different computer from the one on which you are using to develop COBOL.
  • To set up remote debugging for native COBOL applications
    The local and remote systems must be networked using TCP/IP and the cobdebugremote or cobdebugremote64 process must be started.
  • To debug a native COBOL program running remotely
  • cobdebugremote
    The cobdebugremote 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.
  • Troubleshooting - Communications Issues when Debugging Native COBOL
Parent topic: Debugging Native COBOL Programs


Overview - Debugging Native COBOL Applications Remotely

You can use Visual COBOL to debug programs that are running on a different computer from the one on which you are using to develop COBOL.

Note: The following applies to native code only.

On Windows:

You can debug 32 or 64-bit programs that are running on a different computer from the one on which you are using to develop COBOL.

Either the COBOL development system or COBOL Server needs to be installed on the remote computer.

To debug remotely, the two systems must be networked using TCP/IP and must be set up appropriately.

On UNIX:

You can debug applications that run on a remote UNIX machine in a similar way. A Micro Focus COBOL development system for UNIX or COBOL Server needs to be installed on the remote machine.

You cannot deploy the application from a Windows machine. You need to compile the application on the UNIX system using a COBOL development system for UNIX. Once the application is deployed, you can debug it in a similar way to debugging applications that are running on a remote Windows machine.

Parent topic: Remote Debugging of Native COBOL Applications


To set up remote debugging for native COBOL applications

The local and remote systems must be networked using TCP/IP and the cobdebugremote or cobdebugremote64 process must be started.

Note: The following applies to native code only.
  1. Before you start your COBOL development system, ensure that the local and remote systems are networked using TCP/IP.
  2. On the remote machine, start a COBOL command environment, and start a cobdebugremote process by typing:
    cobdebugremote port=nnnnn

    where nnnn is the port number. It is recommended that you use a port number greater than 1024 as numbers below are for system use.

    Note:
    • The cobdebugremote process exits after the debug session has completed. If you want it to start listening for another connection, start the process with the following option:
      cobdebugremote port=nnnnn repeat
    • If you need to debug a 64-bit application, start cobdebugremote64 in the same way.
  3. On the remote machine, configure the Firewall so it allows the Micro Focus Debugger Proxy V2.

    Or, open a TCP port for communications in the Firewall. The port number you add should be the one you specified on the cobdebugremote or cobdebugremote64 command line.

  4. On the local machine, configure the Firewall so it allows the Micro Focus Debugger Proxy V2.

    Or, open a TCP port for communications in the Firewall. The port number you add should be the one you specified on the cobdebugremote or cobdebugremote64 command line.

Parent topic: Remote Debugging of Native COBOL Applications
Related reference
cobdebugremote


To debug a native COBOL program running remotely

Note: The following applies to native code in a Windows environment only.
  1. Set up remote debugging.
  2. Build your project for debugging.
  3. Ensure the same .idy file is deployed on the remote machine.
  4. Add the paths to the .idy files on the remote machine to the IDE as follows:
    • Click Debug > Options and Settings > Debugging > Symbols.
    • Use the Symbol file (.pdb) locations pane to add the path to the symbols (.idy) file relative to the remote machine.
  5. Specify the application file to debug as follows:
    • Click Project > Properties.
    • Go to the Debug tab.
    • Check Start external program.
    • In the adjacent field, enter the path to the .exe file to debug relative to the remote machine. For example, path/filename.exe, where path is the location of the .exe file on the remote machine.
  6. Specify the remote machine as follows:
    • Click Project > Properties.
    • Go to the Debug tab.
    • Check Use remote machine.
    • Fill in the IP address or name of the remote machine.
    • In the Port field, specify the port number which is used by the cobdebugremote or cobdebugremote64 process.
  7. Click Debug> Start Debugging .
  8. When you stop debugging, the cobdebugremote or cobdebugremote64 process exits if it was started without the repeat option. Before you can debug again, you need to restart the process.
Parent topic: Remote Debugging of Native COBOL Applications


cobdebugremote

The cobdebugremote process runs on a remote machine and enables you to debug 32-bit applications on that machine using remote connections.
Note: The following applies to native code only.

Syntax:

To start the cobdebugremote process, enter the following at a COBOL command prompt:

Options:

Windows:

cobdebugremote 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.
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 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
Parent topic: Remote Debugging of Native COBOL Applications
Parent topic: Debugging from the Command Line
Related information
To set up remote debugging for native COBOL applications


cobdebugremote64

The cobdebugremote64 process runs on a remote machine and enables you to debug 64-bit applications on that machine using remote connections.

Note: 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.
Parent topic: Remote Debugging of Native COBOL Applications
Parent topic: Debugging from the Command Line


Troubleshooting - Communications Issues when Debugging Native COBOL

Note: The following applies to native code only.
CCITC32-0025E Transport initialization failure CCI_Initclient could not find CCITCP2

The CCITCP2 process could not be found. This process normally runs as a windows service so it may have been stopped or uninstalled.

Use the Services tool to check that either 'Micro Focus CCITCP2 daemon' or 'Micro Focus Directory Server' is installed and started. If neither is installed use the Repair option of the Micro Focus Visual COBOL installation.

CCITC32-0006E An invalid server or machine name was presented to CCITCP

The remote machine name specified in the debug configuration could not be found or is invalid.

Check you have entered the name correctly.

Parent topic: Remote Debugging of Native COBOL Applications


To configure the symbol path for native COBOL applications

Note: The following applies to native code only.
Note: If you are debugging from within a project, you do not need to set this option; the symbol path is set to the project output path by default.

To configure the directory paths that are used to search for the application .idy files when you attach to a native running process or use Just-in-Time debugging:

  1. Click Tools > Options > Debugging > Symbols.
  2. Use the Symbol file (.pdb) locations pane to add or remove paths to search for the symbols files (.idy files), as required.
Restriction: The Micro Focus Native COBOL debugger does not support the Symbol Cache and Load all symbols options.
Parent topic: Debugging Native COBOL Programs


To set a COBOL watchpoint in native COBOL code

Restriction: Works with native code only.

You can add COBOL watchpoints ( [image]) in the source code in one of the following ways:

  1. Add a watchpoint from the editor:
    1. Right-click a data item and select Add COBOL Watchpoint.

      This opens the Watchpoints (Native COBOL) window and adds the data item to it.

  2. Add a watchpoint from the Watchpoints (Native COBOL) window:
    1. To display the window, click Debug > Windows > COBOL Watchpoints.
    2. Click New.
    3. Type a data item in the field and press Enter.

      Click [image], [image], [image] to enable, disable or delete watchpoints as necessary.

Parent topic: Debugging Native COBOL Programs


To set a program breakpoint in native COBOL code

Restriction: Program breakpoints are supported in native COBOL only, and are not supported with nested programs.

You add program breakpoints to the source code in the following way:

  1. To display the Program Breakpoints (Native COBOL) window, click Debug > Windows > Program Breakpoints (Native COBOL).
  2. On the Program Breakpoints (Native COBOL) window, click New.
  3. Type the name of the source file, without the extension, and press Enter. For multi-program source files, to set a break for a sub-program, use its program-id.

    The program breakpoint is set.

Tip: To delete a program breakpoint, on the Program Breakpoints (Native COBOL) window, select the required breakpoint and click [image], or to delete all current program breakpoints, click [image].
Parent topic: Debugging Native COBOL Programs


To attach to a native running process and debug

Note: The following applies to native code only.
  1. Add the path containing the .idy file to the symbol path. To do this:
    • Click Tools > Options > Debugging > Symbols.
    • Add a new folder by clicking the New Folder button.
    • In the Symbol file locations list, enter the absolute path to the .idy files.
  2. Attach the Micro Focus Native Debugger to the process. To do this:
    • Click Debug > Attach to Process.
    • In the Attach To: field, click Select.
    • Check Debug these code types.
    • Select Micro Focus Native Debugger.
    • Click OK.
    • Select the process to debug from the list.
    • Click Attach.

      The debugger is attached to the process, but will not break execution until a breakpoint is hit, an error occurs or you press the break button.

Parent topic: Debugging Native COBOL Programs


To attach to a 64-bit running native process and debug

Note: This information applies to native code and 64-bit machines only.
  1. Add the path containing the .idy file to the symbol path. To do this:
    • Click Tools > Options > Debugging > Symbols.
    • Add a new folder by clicking the New Folder button.
    • In the Symbol file locations list, enter the absolute path to the .idy files.
  2. Click Debug > Attach to Process.
  3. On the Attach to Process dialog, select Micro Focus transport from the drop-down list next to Transport.
  4. Type a qualifier in the Qualifier field or choose one from the drop-down list.

    The qualifier is either localhost or the name of your machine.

    Note: Optionally, you can start a cobdebugremote64 process on your local machine and connect to it as follows:
    1. Start a 64-bit COBOL command environment.
    2. Type the following at the command prompt:
      cobdebugremote64 port=nnnnn

      where nnnnn is the port number. It is recommended that you use a port number greater than 1024 as numbers below are for system use.

    3. To connect the debugger to the process that listens on this port, type the following qualifier in the Attach to Process dialog:

      localhost:nnnnn

    The Available Processes pane lists all 64-bit processes that are running on your machine.

  5. In the Available Processes pane, click the process you want to debug.
  6. Click Attach.

    The dialog disappears and the title bar of Visual Studio displays Running.

  7. Click Debug > Break.

    Visual Studio starts debugging the process.

Parent topic: Debugging Native COBOL Programs


Running Native COBOL Applications

Note: The following information applies to native code only.
  • Overview of Configuring Run-time Behavior for native COBOL applications
  • To set run-time environment variables and switches for native COBOL applications
Parent topic: Developing COBOL Applications


Overview of Configuring Run-time Behavior for native COBOL applications

Note: This information applies to native code only.

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:

  • Configuration file. You can create a configuration file for the project in the IDE. You can configure items such as memory allocation, the search order for called programs, how to handle ANSI displays and so on.
  • Run-time tunables. Certain run-time behavior can be configured only by using run-time tunables. These are stored in a configuration file that is read when the run-time system starts up.
  • COBOL switches. You can also configure the COBOL switches that are used when your application starts up. Their state can be read by your application while it is running, and thereby change your initial setting.
  • cobopt.cfg files. The settings in this file are equivalent to the run-time configuration settings in the IDE. You can import configurations from these cobopt.cfg files.
Parent topic: Running Native COBOL Applications


To set run-time environment variables and switches for native COBOL applications

Note: This information applies to native code only.
  1. In Solution Explorer, open the application configuration file for your project. By default, it has the file extension .config.

    If the file does not exist, create one.

  2. On the Environment tab, enter a variable name and its value in the Name and Value fields, and click Set.
  3. On the COBOL Switches tab, check the switches you require.
  4. Click OK.
Parent topic: Running Native COBOL Applications
Related information
Setting Run-time Switches
Run-time Switches


Test Coverage for Native COBOL

Note: The following applies to native COBOL only.
  • Overview - Test Coverage and Native COBOL
  • Test Coverage Configuration File for Native COBOL
  • Format of a Test Coverage Report for Native COBOL
  • Reporting on Tagged Lines for Native COBOL
  • Test Coverage Tag File for Native COBOL
  • Troubleshooting Test Coverage
  • Test Coverage Error Messages
  • How To...
Parent topic: Developing COBOL Applications


Overview - Test Coverage and Native COBOL

Restriction: Test coverage supports 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.

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

  • Report Files Created for Native COBOL
  • Recompiling Programs
  • Restrictions when Using Test Coverage in Native COBOL
Parent topic: Test Coverage for Native COBOL
Related reference
TESTCOVER


Report Files Created for Native COBOL

Note: This applies to native COBOL 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 and Native COBOL


Recompiling Programs

Note: This applies to native COBOL 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 and Native COBOL


Restrictions when Using Test Coverage in Native COBOL

Note: This applies to native COBOL only.
The following restrictions apply to test coverage:
  • 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 TESTCOVER directive and run it under test coverage, the test coverage results obtained will be unpredictable.
  • When the TESTCOVER directive is used with preprocessors, only the basic blocks of the original code are taken into account.

We recommend 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 TESTCOVER into your production system if needed.

Parent topic: Overview - Test Coverage and Native COBOL
Related reference
TESTCOVER
REENTRANT


Test Coverage Configuration File for Native COBOL

Note: This applies to native COBOL only.

An example test coverage configuration file is supplied in %ProgramFiles%\Micro Focus\Visual COBOL \etc\ default.tcf. 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\TESTCOVR.LOG , where projectdir is the folder in which your project is located. Optional.

The filename specified for the LOGNAME keyword can include the token <pid>. See the description of the RESULT keyword for more information on this token.

We recommend that a configuration file should contain at least the following:

[TESTCOVER]
ECHOLOG NO
RESULT filename.tcz ACCUMULATE
Note:
  • Only one RESULT, ECHOLOG and LOGNAME keyword are allowed. You can have more than one instance of each of the keywords if they are non-active; that is, preceded by the semicolon (;) comment character.

Examples of the RESULT keyword

RESULT .\results\tcresult.tcz ACCUMULATE

Test coverage accumulates all results in the tcresult.tcz, located in the folder results relative to the current folder.

RESULT c:\myres\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: Test Coverage for Native COBOL


Format of a Test Coverage Report for Native COBOL

Note: This applies to native COBOL only.

When you use TCReport 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: Test Coverage for Native COBOL


Reporting on Tagged Lines for Native COBOL

Note: This applies to native COBOL 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 utility.

Parent topic: Test Coverage for Native COBOL


Test Coverage Tag File for Native COBOL

Note: This applies to native COBOL only.

The test coverage tag file is used by TCReport to identify tags in your source code, enabling TCReport 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: Test Coverage for Native COBOL


Troubleshooting Test Coverage

Note: This applies to native COBOL only.
If you have any problems with test coverage, check the following issues and follow the suggestions.
TCReport 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 TCReport 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 for Native COBOL
Related reference
TESTCOVER
Related information
Environment Variables


Test Coverage Error Messages

Note: This applies to native COBOL only.
TC001S No input results file specified
TCREPORT or TCSCAN executed but no results file is named in the parameters.
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.
TC005S Unable to open program source file
TCREPORT was processing a results file and was unable to open the associated source.
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.
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.
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.
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.
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.
TC012I NOHTML and NOTEXT specified - nothing to do
If neither NOHTML nor NOTEXT is specified in TCREPORT, no reports are produced.
TC014S Invalid option entered
One or more of the command line options entered in TCREPORT or TCSCAN was invalid. Re-enter the command.
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.
TC021S Timestamp mismatch
TESTCOVER timestamp check has detected a program has been canceled, and a different one of the same name reloaded.
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.
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.
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.
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.
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.
TC043S Unable to open Trace file
Internal error.
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.

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 for Native COBOL


How To...

  • To create test coverage reports for native COBOL
  • To use test coverage from the command line for native COBOL
  • To use test coverage for native COBOL in a production system
  • To report on tagged lines for native COBOL
Parent topic: Test Coverage for Native COBOL


To create test coverage reports for native COBOL

Note: This applies to native COBOL only.
  1. Locate the .tcz file in the location specified in your .tcf file.
  2. From a command prompt, enter:
    tcreport filename [NO]options

    where:

    • filename is one or more .tcz files, separated by a comma, or @filelist.txt, which is a text file containing a list of all .tcz files to be reported on
    • 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:

#tcscan filename

where filename is the name of your .tcz file.

Parent topic: How To...


To use test coverage from the command line for native COBOL

Note: This applies to native COBOL only.
  1. Create a test coverage configuration file.
  2. Build your application with the TESTCOVER compiler directive set.
  3. Set the TESTCOVER environment variable.

    The value of the variable should be the path of the test coverage configuration file.

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


To use test coverage for native COBOL in a production system

Note:
  • This applies to native COBOL only.
  • We recommend 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.

To use test coverage in a production system, you need:

  • To ship the file testcover.dll which enables your users to run a program that has been compiled with the TESTCOVER directive. This file is in the %ProgramFiles%\Micro Focus\Visual COBOL\bin directory by default.
  • To supply the .idy and the .cbl or .cpy files for the production code. This enables your user to produce .tcz results files.
  • The TCReport executable file, tcreport.exe. You need this file in order to produce reports, as it is used to match the source lines in the code with the results.
  • To ship the appropriate test coverage configuration (.tcf) file.
  • To ensure your user sets up the TESTCOVER environment variable.
Parent topic: How To...


To report on tagged lines for native COBOL

Note: This applies to native COBOL only.

To be able to produce a report with information specific to tagged lines, you must first enter tags in your source code. You can produce the report using TCReport.

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

    For example:

    tcreport myreport.tcz taglines(tagfile.txt)
Parent topic: How To...


Deploying COBOL Applications

  • Deploying Native COBOL Applications
  • COBOL Server
  • Deploying COBOL Applications to the .NET Environment
    This chapter explains how to deploy COBOL applications to the .NET environment.
Parent topic: Developing COBOL Applications


Deploying Native COBOL Applications

Note: The information in this section applies to native COBOL only.
  • Overview of Deploying Native COBOL Applications
  • Shipping Selected Files from COBOL Server
  • Writing Your Own Setup Program
  • To set up an application with a shared COBOL Server
  • To set up an application with its own COBOL Server
Parent topic: Deploying COBOL Applications
Parent topic: Deployment
Related information
Deploying a CGI Application with Embedded HTML


Overview of Deploying Native COBOL Applications

Note: The following applies to native COBOL only.

Native applications developed using a COBOL development system require a COBOL run-time server to provide the necessary run-time system and support.

COBOL Server is your COBOL run-time server. It is supplied as part of Visual COBOL, which is your COBOL development system. COBOL Server is also supplied separately.

End users need to install COBOL run-time licenses before they can run applications that use the COBOL run-time system.

You need to:

  • Ship COBOL Server with your application.
  • Ensure that the application you have developed has the proper COBOL Server licenses. Your end users need to install the licenses before they can run the application. This is done by using the Micro Focus Licensing Administration Tool. The license Authorization Code, required to license the application, is either supplied when you ship the COBOL run-time server with the application or by end-user request from Micro Focus.
Parent topic: Deploying Native COBOL Applications
Related information
Deployment Licensing


Shipping Selected Files from COBOL Server

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

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

The COBOL Server files you need to ship with your application depend on how you linked the application, the type of executable it is, and the support functionality it uses.

You can package the files you need in whatever you choose, such as by creating .dll files from the supplied .obj files.

When you ship a modular application , you need to ship the following files:

  • The main program of your application
  • Any dynamically linked programs that are part of your application, including objects that have been linked into dynamic link libraries
  • The Microsoft Visual C++ run-time system
  • Licensing files
  • The National Locale Support message files for the locales that you support:
    • lang\default\*
    • lang\en_GB\*
    • lang\en_us\*
    • lang\jp_sj\*

In addition, you need to ship the following files depending on your application requirements:

  • The file adisctrl, if your application uses the enhanced ACCEPT/DISPLAY syntax, and you have configured it to use a non-default configuration
  • OO COBOL Files to Ship
  • Run-time System Files to Ship
Parent topic: Deploying Native COBOL Applications
Related information
COBOL 2010 Runtime Installation Options


OO COBOL Files to Ship

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

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

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

If your application requires: Multi-threading files needed:

OO programming support

  • class.dll
  • classm.dll
  • mfom.dll
  • oopsm.cfg
  • oopsm.dll

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

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


Run-time System Files to Ship

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

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

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

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

If your application uses: Files needed:
Command-line Sort
  • mfsort.exe
FaultFinder facility
  • cbldbg.dll
  • cblffndm.exe (multi-threaded)
Fileshare
  • fs.dll (server)
  • fs.exe (server trigger)
  • fsservice.exe (to run as an NT service)
  • fsclose.exe (server closedown support)
  • fsmgr.dll (manager API support)

Micro Focus run trigger program:

  • multithreaded trigger
  • multithreaded trigger (Windows)

  • run.cfg
  • run.exe
  • runm.exe
  • runmw.exe
  • runw.exe
  • shell.dll
  • utils.dll
ODBC
  • drivers obtained separately, and
  • odbcrw32.dll
Rebuild facility (command-line file recovery tool)
  • rebuild.exe
  • the language files in the relevant lang subfolders. These files need to be available, and the COBDIR environment variable needs to point to the directory containing them
SQL, ESQL and ODBC
  • csqlsupp.dll (Cobsql)
  • odbcrw32.dll or odbcrw64.dll (OpenESQL)
  • oesqlebc.dll (OpenESQL with EBCDIC data)
  • ODBC drivers obtained separately
  • mfsqlsmf.dll
Parent topic: Shipping Selected Files from COBOL Server


Writing Your Own Setup Program

Note: The following applies to native COBOL only.

You can write your own setup program for applications that run under a COBOL run-time system, such as COBOL Server.

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

The main ways of packaging an application and COBOL Server are:

  • As an application using a shared run-time system - This run-time system is used by multiple COBOL applications on an end user's machine. It is installed in its own directory, separate from any applications. There is only one run-time system installed on the machine.

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

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

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

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

Parent topic: Deploying Native COBOL Applications


To set up an application with a shared COBOL Server

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

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

    path = app-server-dir;%PATH%

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

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


To set up an application with its own COBOL Server

Note: The following applies to native COBOL only.
  1. Install COBOL Server.
  2. Install your application executable files in the same directory as COBOL Server.
  3. Create a shortcut pointing to the application. We recommend a shortcut in preference to adding the application directory to the user's path, so that you avoid interactions with other COBOL applications.
Parent topic: Deploying Native COBOL Applications


COBOL Server

  • To install COBOL Server (or selected files)
  • COBOL Server Installation Options
    Describes the different ways in which you can install COBOL Server.
  • COBOL Server Deployment Toolkit
    Describes the component parts of the COBOL Server Deployment Toolkit.
Parent topic: Deploying COBOL Applications


To install COBOL Server (or selected files)

Note: The following applies to native COBOL only.

To install the full COBOL Server (recommended):

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

    You can also install COBOL Server silently.

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

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


COBOL Server Installation Options

Describes the different ways in which you can install COBOL Server.

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

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

  • Standard Installation
    • Format:
    • COBOLServer20.exe
    • Summary:
    • Full installation including License Manager, Vision, and COBOL Server. During installation you can specify options including the location to which the components are installed.
  • Non-interactive Installation
    • Format:
    • COBOLServer20.exe /qb
    • Summary:
    • Full installation, but the components are installed non-interactively using default options and directories.
  • Silent Installation
    • Format:
    • COBOLServer20.exe /q
    • Summary:
    • Full installation, but the components are installed non-interactively with no user interface, using default options and directories.
  • Modified Silent Installation
    • Format:
    • COBOLServer20.exe /q /componentargs "Micro Focus COBOL Server":"INSTALLDIR=d:\cobolrts"
    • Summary:
    • Full installation, but the installation is controlled by the /componentargs switch and the standard MSI property INSTALLDIR. In the example above, COBOL Server is installed into d:\cobolrts.
Note:
  • You can display the valid values for the /componentargs switch by using the /displayconfig switch:

    COBOLServer20.exe /displayconfig

  • Log files that are created during installation are saved in the folder specified by the TEMP environment variable.
  • You can extract the component .msi files from COBOLServer20.exe by using the by using the /extractcab switch:

    start /wait COBOLServer20.exe /extractcab

    The extracted .msi files are saved in the SupportFiles subfolder.

Parent topic: COBOL Server


COBOL Server Deployment Toolkit

Describes the component parts of the COBOL Server Deployment Toolkit.

  • Introduction to the COBOL Server Deployment Toolkit
  • Merge Modules
    Provides background information on merge modules and describes the Deployment Toolkit's support for them.
  • The Deployment Toolkit Web Installer
    Lists and describes the files that comprise the Deployment Toolkit web installer.
Parent topic: COBOL Server


Introduction to the COBOL Server Deployment Toolkit

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

When you install COBOL Server, the files making up the Deployment Toolkit are saved in the deployment_toolkit folder.

Parent topic: COBOL Server Deployment Toolkit


Merge Modules

Provides background information on merge modules and describes the Deployment Toolkit's support for them.

Merge modules provide you with a standard method by which you can deliver shared Windows Installer components and setup logic to your applications. See MSDN for information on merge modules.

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

Parent topic: COBOL Server Deployment Toolkit


The Deployment Toolkit Web Installer

Lists and describes the files that comprise the Deployment Toolkit web installer.

The Deployment Toolkit includes a web installer client to enable you to deploy using a client/server installation. The deployment_toolkit folder contains the following files for the web installer client:

deployment_toolkit_client.exe | Client application that loads deployment_toolkit_client.xml, that is deployment_toolkit_client.exe /configfile deployment_toolkit_client.xml.
deployment_toolkit_client.xml | Specifies the location of deployment_toolkit_server.xml on an internal or external web server.
deployment_toolkit_server.xml | Specifies each component to be installed as part of the product. The example XML lists Microsoft .NET Framework 4.0, Microsoft Visual Studio Shell edition as prerequisites and two dummy entries for Productx86 and Productx64. See dotNetInstaller: setup bootstrapper for Windows for information on the XML format.
Parent topic: COBOL Server Deployment Toolkit


Deploying COBOL Applications to the .NET Environment

This chapter explains how to deploy COBOL applications to the .NET environment.

  • Overview of Deploying COBOL Applications to the .NET Environment
  • Deploying to the .NET Environment with or without a Setup Project
  • Deploying Web and ASP.NET Applications
Parent topic: Deploying COBOL Applications


Overview of Deploying COBOL Applications to the .NET Environment

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

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

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

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

Parent topic: Deploying COBOL Applications to the .NET Environment


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

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

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

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

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

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

Parent topic: Deploying COBOL Applications to the .NET Environment


Deploying Web and ASP.NET Applications

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

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

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

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

For more information, see the MSDN:

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


Programming

  • COBOL Programming
  • Compatibility
  • Data Access
  • Managed COBOL Programming
  • Problem Determination and Diagnostic Tools
  • Hints and Tips
Parent topic: Micro Focus Visual COBOL for Visual Studio 2010


COBOL Programming

  • Embedded HTML
    Embedded HTML (EHTML) enables you to output HTML directly from a COBOL CGI program.
  • Internationalization Support
  • Mixed Language Programming with Native COBOL
    This section covers parameters, return codes and call conventions for mixed language development with native COBOL.
  • Creating 64-bit Native COBOL Programs
    You can create a 64-bit native COBOL program from scratch, or convert an existing 32-bit native program.
  • Calling COBOL Programs
Parent topic: Programming


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 Wait for debuggable attachment or Launch URL debug options in the project properties.
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 Visual Studio project must be created as a Native COBOL project using the Console Application output type or template.
    • In the project properties, set the Runtime Library in your COBOL Link Settings to Dynamic.
  • Server Specifications

    If using Apache 2.2, 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/ "C:/Apache2.2/cgi-bin/"
</IfModule>
    • Enable ExecCGI for the directory that contains your cgi executable. For example:
      <Directory "C:/Apache2.2/cgi-bin">
    AllowOverride None
    Options ExecCGI
    Order allow,deny
    Allow from all
</Directory>
    • Micro Focus Licensing Specifications
      If you are using a version of the COBOL runtime earlier than the one supplied with Visual COBOL 2.0, 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
Related information
Creating COBOL Projects from Existing Code


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
Related information
Deploying Native COBOL Applications


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 Wait for debuggable attachment or Launch URL debug options in the project properties.

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 from the Debugging > Symbols page in your Visual Studio Options. For example: c:\apache2.2\cgi-bin.

You can debug native CGI projects using the Launch URL start option.

  1. Start your Web server.
    • Currently, IIS is not supported
    • On Apache, you must run the Apache process as your own user (not as a service)
    • If you run Apache as a service, you need to use a call to CBL_DEBUGBREAK
  2. Ensure the CGI binaries are in a folder on the Web server and execution of CGIs in that folder is enabled.
  3. In the IDE, click Project > myproject properties and select the Debug tab.
  4. Click Start browser with URL and specify the application URL.
  5. Click Debug > Start debugging.

    The debugger waits for your CGI application to run, and then attaches to it.

    Note: Either the project output folder or the Working directory in the project's Debug properties must be set to the CGI folder of the Web server.
Parent topic: Embedded HTML
Related reference
CBL_DEBUGBREAK


Internationalization Support

  • National Locale Support
  • Unicode Support
Parent topic: COBOL Programming


National Locale Support

Restriction: National Locale Support is not available for .NET managed 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 not available for .NET managed 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 not available for .NET managed 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 not available for .NET managed code.

You define a locale using the LANG environment variable. LANG is set using the operating system command SET:

set LANG=language

Parameters

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
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 not available for .NET managed 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 not available for .NET managed 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 not available for .NET managed 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 not available for .NET managed 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 not available for .NET managed 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 not available for .NET managed 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 not available for .NET managed 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 not available for .NET managed 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 not available for .NET managed 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 not available for .NET managed 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 not available for .NET managed 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


Mixing Programs With and Without NLS

Restriction: National Locale Support is not available for .NET managed 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 not available for .NET managed code.

Message files use so that the COBOL always displays them using the appropriate codeset for the environment an application is running in. You write each message file as an ASCII file with the file extension .err, and then compile it into a language file (which has the file extension .lng). To make messages available in more than one language, you write one message file per language, and compile them into separate .lng files.

You can open, read and close message files with the NLS library routines.

  • Format of a Message File
  • Example Error 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


Format of a Message File

Restriction: National Locale Support is not available for .NET managed 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.

Parent topic: Message Files
Related information
Example Error Message File


Example Error Message File

Restriction: National Locale Support is not available for .NET managed 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: 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. For example:

01 mystring	pic n(20) usage national
Parent topic: Unicode Support
Related information
Overview - Unicode Support
Overview - National Literals
UTF-16 Byte Ordering
National Hexadecimal Literals


Mixed Language Programming with Native COBOL

This section covers parameters, return codes and call conventions for mixed language development with native COBOL.

Restriction: The following applies to native COBOL only.

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

Restriction: The following applies to native COBOL only.

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 with Native COBOL
Related information
Storage Representation of Parameters
Number of Parameters in a USING Phrase
Number of Files for Sorting or Merging
Call Conventions for Interfacing with Mixed Languages
Mixed Language Programming with Native COBOL
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.

Restriction: The following applies to native COBOL only.

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 with Native COBOL
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 or Merging
Call Conventions for Interfacing with Mixed Languages
Mixed Language Programming with Native COBOL


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.

Restriction: The following applies to native COBOL only.

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 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.
COMP-5 | Defined as Intel reversed byte storage format, in which data is stored with the least significant byte first; that is, the least 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 | The entire format is a double-word reversed byte offset. 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 with Native COBOL
Related information
Ordering Parameters to Pass to Non-COBOL Programs
Number of Parameters in a USING Phrase
Number of Files for Sorting or Merging
Call Conventions for Interfacing with Mixed Languages
Mixed Language Programming with Native COBOL
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


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.
Restriction: The following applies to native COBOL only.

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" by default.
  • Use the SYNCHRONIZED clause in conjunction with the IBM COMP Compiler directive.
Parent topic: Mixed Language Programming with Native COBOL
Related information
Building a Mixed Language Application
Removing Parameters from the Stack
Handling Return Codes in Mixed Language Applications
Mixed Language Programming with Native COBOL
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.

The registers used to pass the return code from COBOL and Microsoft C are:

32-bit Intel Return Code Size | Register
One byte | AL
Two bytes | AX
Four bytes | EAX
X64 Return Code Size | Register
One, two, and four bytes | as for X86
Eight bytes | RAX
IA64 Return Code Size | Register
Any size | R8
Parent topic: Mixed Language Programming with Native COBOL
Related information
Building a Mixed Language Application
Removing Parameters from the Stack
Aligning Parameters on Word and Double Word Boundaries
Mixed Language Programming with Native COBOL
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.

These call conventions are relevant to .NET managed code when using Platform Invoke only to call unmanaged code.

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
Bit 1
0 | Parameters removed from stack by calling program
1 | Parameters removed from stack by called program
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.
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
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.
Bit 10
0 | Normal calling behavior
1 | The first parameter is always the RETURNING item for the CALL when you use DIALECT"RM"
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.

Parent topic: Mixed Language Programming with Native COBOL
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 or Merging
Mixed Language Programming with Native COBOL
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.
Restriction: The following applies to native COBOL only.

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 with Native COBOL
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 with Native COBOL
Ordering Parameters to Pass to Non-COBOL Programs
Storage Representation of Parameters
Call Conventions for Interfacing with Mixed Languages


Interfacing with Assembler Subprograms

Restriction: The following applies to native COBOL only.

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 with Native COBOL
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: The following applies to native COBOL 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 with Native COBOL
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

Restriction: The following applies to native COBOL only.

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 the base\include folder of the installation of your COBOL development system.

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 in the include folder.

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

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

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 with Native COBOL
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.

Restriction: The following applies to native COBOL only.

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, \include\cbltypes.h , 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 cpylib\cbltypes.cpy in your COBOL development system installation.

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 with Native COBOL
Related reference
cobget
cobput
Related information
Interfacing with C Programs
Signal Handling Overview


Error Messages when Calling Non-COBOL Programs

Restriction: The following applies to native COBOL only.

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 with Native COBOL
Related information
Mixed Language Programming with Native COBOL


Signal Handling

You can use signal handling in your application, especially if you are mixing COBOL and C in your application.

Restriction: The following applies to native COBOL only.
  • 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 with Native COBOL


Signal Handling Overview

Restriction: The following applies to native COBOL only.

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

Restriction: The following applies to native COBOL only.

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

Restriction: The following applies to native COBOL only.

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

Restriction: The following applies to native COBOL only.

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

Restriction: The following applies to native COBOL only.

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

Restriction: The following applies to native COBOL only.

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

Restriction: The following applies to native COBOL only.
  • 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 with Native COBOL


Example of Calling C functions from COBOL

Restriction: The following applies to native COBOL only.

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

Restriction: The following applies to native COBOL only.

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 "cob32api"
     $if NOILGEN defined
         call "cob32api"
     $end
     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

Restriction: The following applies to native COBOL only.

The following example illustrates posting a signal handler for the SIGABRT signal:

#include <stdio.h>
#include <signal.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


Creating 64-bit Native COBOL Programs

You can create a 64-bit native COBOL program from scratch, or convert an existing 32-bit native program.
Restriction: The following 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.

  • Overview of Creating 64-bit Native COBOL Programs
  • Creating 64-bit Programs from 32-bit Native COBOL Programs
  • Compiling Native COBOL Programs for 64-Bit
  • Pointers and Compiling Native COBOL Programs for 64-Bit
  • Single Sourcing and Compiling Native COBOL Programs for 64-Bit
  • Library Routine Prototypes and Compiling Native COBOL Programs for 64-Bit
  • File and FCD Handling and 64-bit Native COBOL Programs
  • Single Sourcing and Dual FCD Support in 64-Bit Native COBOL Programs
Parent topic: COBOL Programming


Overview of Creating 64-bit Native COBOL Programs

Restriction: The following information applies to native COBOL only.

This COBOL system includes both 32-bit and a 64-bit versions of both the development and run time systems. This enables you to create new 64-bit native COBOL programs, or to convert existing 32-bit native programs.

64-bit COBOL programs are restricted to 32-bit sizes, but have 64-bit pointers. Therefore, COBOL elements such as Data Division sizes, offsets, Procedure Divisions, and so on, are restricted to 32-bits; however, these elements are addressed with 64-bit pointers.

The COBOL system works in 32-bit mode, but is configured in a 64-bit environment to enable it to work with 64-bit programs.

Restriction: You cannot port executable code between 32-bit and 64-bit development systems.
Parent topic: Creating 64-bit Native COBOL Programs
Related information
Creating 64-bit Programs from 32-bit Native COBOL Programs
Compiling Native COBOL Programs for 64-Bit
Pointers and Compiling Native COBOL Programs for 64-Bit
Single Sourcing and Compiling Native COBOL Programs for 64-Bit
Library Routine Prototypes and Compiling Native COBOL Programs for 64-Bit
File and FCD Handling and 64-bit Native COBOL Programs
Single Sourcing and Dual FCD Support in 64-Bit Native COBOL Programs


Creating 64-bit Programs from 32-bit Native COBOL Programs

Restriction: The following information applies to native COBOL only.

In general, you can take a 32-bit program, recompile it with the P64 Compiler directive set, and it should run without problem as a 64-bit application. There are, however, certain circumstances in which the conversion of your program won't be as simple as this:

If your program uses pointers
You need to ensure that pointers are not redefined or modified by reference. There should also be no assumptions in your record definitions about the sizes of pointers.
If your program uses a File Control Description (FCD) block that has been directly coded
The program will have to be modified to use the 64-bit FCD3 format if the 32-bit program was using the older FCD2 format. 64-bit programs need an FCD control block that has a different format to that used by older 32-bit applications.
Parent topic: Creating 64-bit Native COBOL Programs
Related information
Overview of Creating 64-bit Native COBOL Programs
Compiling Native COBOL Programs for 64-Bit
Pointers and Compiling Native COBOL Programs for 64-Bit
Single Sourcing and Compiling Native COBOL Programs for 64-Bit
Library Routine Prototypes and Compiling Native COBOL Programs for 64-Bit
File and FCD Handling and 64-bit Native COBOL Programs
Single Sourcing and Dual FCD Support in 64-Bit Native COBOL Programs


Compiling Native COBOL Programs for 64-Bit

Restriction: The following information applies to native COBOL only.

The Compiler directive P64 enables you to create a program that can be run on COBOL Server in 64-bit mode. If you do not use the P64 directive when you compile your program, the program can only be run on COBOL Server in 32-bit mode. Therefore, if you have developed an application on a 32-bit development system, you must recompile it with the P64 directive set, if you want to migrate it using COBOL Server in 64-bit mode.

The P64 directive is set by default if you check the 64-bit check box in the Build Settings dialog box.

Parent topic: Creating 64-bit Native COBOL Programs
Related information
Overview of Creating 64-bit Native COBOL Programs
Creating 64-bit Programs from 32-bit Native COBOL Programs
Pointers and Compiling Native COBOL Programs for 64-Bit
Single Sourcing and Compiling Native COBOL Programs for 64-Bit
Library Routine Prototypes and Compiling Native COBOL Programs for 64-Bit
File and FCD Handling and 64-bit Native COBOL Programs
Single Sourcing and Dual FCD Support in 64-Bit Native COBOL Programs


Pointers and Compiling Native COBOL Programs for 64-Bit

Restriction: The following information applies to native COBOL only.

If you compile a program using the P64 Compiler directive (referred to in the rest of this chapter as "64-bit programs") the data-type POINTER is a different size to that in programs compiled without the P64 directive (referred to in the rest of this section as "32-bit programs").

Parent topic: Creating 64-bit Native COBOL Programs
Related information
Overview of Creating 64-bit Native COBOL Programs
Creating 64-bit Programs from 32-bit Native COBOL Programs
Compiling Native COBOL Programs for 64-Bit
Single Sourcing and Compiling Native COBOL Programs for 64-Bit
Library Routine Prototypes and Compiling Native COBOL Programs for 64-Bit
File and FCD Handling and 64-bit Native COBOL Programs
Single Sourcing and Dual FCD Support in 64-Bit Native COBOL Programs


Single Sourcing and Compiling Native COBOL Programs for 64-Bit

Restriction: The following information applies to native COBOL only.

To aid migration and application development, the $IF statement has been extended to enable you to find out which Compiler directives have been set when your program is compiled. In particular, you can use $IF...SET to determine whether the P64 Compiler directive has been set. For details on the $IF ... SET statement, see your Language Reference.

Parent topic: Creating 64-bit Native COBOL Programs
Related information
Overview of Creating 64-bit Native COBOL Programs
Creating 64-bit Programs from 32-bit Native COBOL Programs
Compiling Native COBOL Programs for 64-Bit
Pointers and Compiling Native COBOL Programs for 64-Bit
Library Routine Prototypes and Compiling Native COBOL Programs for 64-Bit
File and FCD Handling and 64-bit Native COBOL Programs
Single Sourcing and Dual FCD Support in 64-Bit Native COBOL Programs
COBOL Language Reference


Library Routine Prototypes and Compiling Native COBOL Programs for 64-Bit

Restriction: The following information applies to native COBOL only.

Prototypes are provided for the COBOL library routines in this COBOL system. These help ensure that the library routines can run correctly in a 64-bit environment. Prototyping is an accepted way to ensure that the parameters provided to a library routine are correctly typed. See Using the Library Routine Type Definitions and Call Prototypes for information on how prototyping has been implemented for the library routines.

Parent topic: Creating 64-bit Native COBOL Programs
Related information
Overview of Creating 64-bit Native COBOL Programs
Creating 64-bit Programs from 32-bit Native COBOL Programs
Compiling Native COBOL Programs for 64-Bit
Pointers and Compiling Native COBOL Programs for 64-Bit
Single Sourcing and Compiling Native COBOL Programs for 64-Bit
File and FCD Handling and 64-bit Native COBOL Programs
Single Sourcing and Dual FCD Support in 64-Bit Native COBOL Programs
Using the Library Routine Type Definitions and Call Prototypes


File and FCD Handling and 64-bit Native COBOL Programs

Restriction: The following information applies to native COBOL only.

The File Control Description (FCD) is a data area which contains information about the file in use.

There are two different formats of the FCD that you can directly code in your application, FCD2 and FCD3 (FCD 1 is obsolete and should never be used in your applications).

FCD2 is not supported on 64-bit COBOL systems. This has the following effects on application conversion:

  • Applications that use FCD structures, either through explicit declaration and creation, or by using the syntax CALL program USING filename, have to be converted to handle FCD3 when compiled and run as a 64-bit application.
  • Applications that use the FCDREG directive need to be aware that various data-items including pointers and record sizes within the FCD have different sizes, and that reference modification of these fields results in different values on a 32-bit environment and a 64-bit one.
  • The copybook xfhfcd.cpy defines an FCD3 unless you specify the NOFCD3 directive. 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.
Parent topic: Creating 64-bit Native COBOL Programs
Related information
Overview of Creating 64-bit Native COBOL Programs
Creating 64-bit Programs from 32-bit Native COBOL Programs
Compiling Native COBOL Programs for 64-Bit
Pointers and Compiling Native COBOL Programs for 64-Bit
Single Sourcing and Compiling Native COBOL Programs for 64-Bit
Library Routine Prototypes and Compiling Native COBOL Programs for 64-Bit
Single Sourcing and Dual FCD Support in 64-Bit Native COBOL Programs


Single Sourcing and Dual FCD Support in 64-Bit Native COBOL Programs

Restriction: The following information applies to native COBOL only.

All system components supplied with the 32-bit development system support FCD 2 and FCD 3. System components supplied with the 64-bit development system only support FCD 3; no system components can support FCD 2, due to the incompatibilities in pointer size. 32-bit and 64-bit system components are single sourced, meaning that the components work with FCD 3 on 64-bit systems if compiled with P64, or work with both FCD 2 and FCD 3 on 32-bit systems if compiled with NOP64. We recommend that you take this single-sourcing approach when developing your own applications.

Because the development system supports FCDs in both formats, your applications can use one of the following:

  • FCD 3 only. In this case, applications can be built on either a 32-bit or 64-bit development system, and shipped with either the 32-bit or 64-bit COBOL Server.
  • FCD 2 only. In this case, applications can be built only on the 32-bit development system, and shipped only with the 32-bit COBOL Server.

If you can solely use either FCD 3 or FCD 2 in your application, you need make no other provisions to handle the extended FCD structure.

However, some programs in your application might provide interfaces to other components in your application, and these interfaces might include FCD structures. In this case you might need to provide gradual transition to full FCD 3 support; at run time, therefore, your program will need to accept both FCD 2 and FCD 3 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
         *> Dealing with FCD2..
$if P64 set
        display "Error: cannot accept FCD2 on 64 bit platform"
        exit program
$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 FCD 3 structure and, if necessary, establish mappings, to and from FCD 2 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"
        exit program
     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
     exit program.
Parent topic: Creating 64-bit Native COBOL Programs
Related information
Overview of Creating 64-bit Native COBOL Programs
Creating 64-bit Programs from 32-bit Native COBOL Programs
Compiling Native COBOL Programs for 64-Bit
Pointers and Compiling Native COBOL Programs for 64-Bit
Single Sourcing and Compiling Native COBOL Programs for 64-Bit
Library Routine Prototypes and Compiling Native COBOL Programs for 64-Bit
File and FCD Handling and 64-bit Native COBOL Programs


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 programs from .NET COBOL projects
  • 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 managed 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 programs from .NET COBOL projects

Note: The following applies to .NET COBOL only.

If a program in your managed project is calling a program in another managed project you need to add a project or a file reference in the calling project to the project containing the program to be called. To do this:

  1. In Solution Explorer, select the calling project.
  2. Click Project > Project Properties.
  3. Click the References tab.
  4. Click Add.
  5. Choose Projects or Browse to add a project or a file reference.

Once this is done, you can use the classes and methods from the referenced project in the calling project.

For information on calling native code from a managed program see Interoperating with Unmanaged COBOL.

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.

The called program can be dynamically linked, where a dynamically linked module is a .dll 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.

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
L1 run-time switch


Search Conventions Used for Calling Programs

Restriction: This information is not applicable to .NET 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 first in the current directory, then the directory containing the calling program, and then the directories set in the COBDIR environment variable.

The search sequence described here applies to executable files (programs). It does not apply to other file types, for example data files and COBOL source files. Also, you don't need to be concerned in this discussion if you have only one executable version of your program on disk.

The run-time system first looks in the current directory for the called program. If the called program is named explicitly, (its name and its extension are specified), the specific executable file is searched for. If the called program is named implicitly, (only its base name and not its extension is specified) the run-time system looks for executable files in the order:

  1. filename.dll
  2. filename

If the called program is not found in the current directory, the run-time system repeats the search in the calling program's directory, and then in each directory specified by COBDIR. If it reaches the last directory without finding an executable file, the run-time system issues a "program not found" error message.

This is the default behavior of the run-time system; you can change the search order using the Configure Application Environment dialog.

In the case of a library file, 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 is 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 information
Library Routine Prototypes and Compiling Native COBOL Programs for 64-Bit
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


Compatibility

  • Compatibility with ACUCOBOL-GT
  • Compatibility with DG Interactive COBOL
  • Compatibility with RM/COBOL
  • Modernizing Dialog System Applications
  • Java and COBOL
  • OO COBOL Class Library Reference
  • User Interface Programming
Parent topic: Programming


Compatibility with ACUCOBOL-GT

Describes supported ACUCOBOL-GT features and how to enable them.

  • Working with ACUCOBOL-GT Applications
    An introduction to working with ACUCOBOL-GT applications.
  • Enabling ACUCOBOL-GT Compatibility
    How to compile ACUCOBOL-GT applications.
  • ACUCOBOL-GT Library Routines
    Supported ACUCOBOL-GT library routines.
  • ACUCOBOL-GT Syntax Extensions
    Supported ACUCOBOL-GT syntax elements and behaviors.
Parent topic: Compatibility


Working with ACUCOBOL-GT Applications

An introduction to working with ACUCOBOL-GT applications.

ACUCOBOL-GT programs are built, compiled, and debugged by the normal Micro Focus methods described in this COBOL system's documentation. Enabling compatibility with ACUCOBOL-GT's language extensions, data files, and other behaviors does, however, require setting certain compiler directives. The phrase compiler directive is synonymous with the phrase compiler option.

You can compile ACUCOBOL-GT applications to the same runnable formats supported by this COBOL system by using the standard Visual COBOL tools and command lines. With the ACUOPT directive you can even specify traditional ACUCOBOL-GT-style compiler options with the Micro Focus Compiler.

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.

This COBOL system does not support ACUCOBOL-GT configuration files and variables. Visual COBOL uses different configuration files and variables. Using the information in this manual, you should review your existing ACUCOBOL-GT configuration to determine which settings are relevant for use with Visual COBOL (some may no longer be needed) and which settings have Visual COBOL equivalents.

The remaining topics in the section describes the ACUCOBOL-GT compatibility features and how they are enabled within Visual COBOL.

Parent topic: Compatibility with ACUCOBOL-GT


Enabling ACUCOBOL-GT Compatibility

How to compile ACUCOBOL-GT applications.

There are several Compiler directives that enable support for ACUCOBOL-GT syntax, data files, and other behaviors. This section describes these directives and the ACUCOBOL-GT features they enable.

  • ACU Compiler Directive
    How to enable ACUCOBOL-GT compatibility features
  • Compiling and Compiler Option Support
    Compiling and supported options.
  • Vision Indexed File System
    Support for ACUCOBOL-GT's native indexed file system.
Parent topic: Compatibility with ACUCOBOL-GT


ACU Compiler Directive

How to enable ACUCOBOL-GT compatibility features

ACUCOBOL-GT compatibility is controlled by the ACU Compiler directive. You need to set this directive in your source code directly, through the COBOL project options interface in your IDE or from the command line.

The Language Reference section details the specific language elements that are enabled by the ACU directive.

Parent topic: Enabling ACUCOBOL-GT Compatibility
Related reference
ACU
Related information
Setting Directives Outside the IDE
ACUCOBOL-GT Syntax Extensions


Compiling and Compiler Option Support

Compiling and supported options.

  • 32 and 64-Bit Code Generation
    How to generate 32- or 64-bit code.
  • Setting Compiler Options
    Using the ACUOPT directive or ccbl to set ACUCOBOL-GT compiler options.
  • Supported and Unsupported Options
    Supported ACUCOBOL-GT compiler options.
Parent topic: Enabling ACUCOBOL-GT Compatibility


32 and 64-Bit Code Generation

How to generate 32- or 64-bit code.

When compiling with the ACU directive, the Compiler generates intermediate code that is bit independent. By using ccbl, you can specify 32 or 64-bit intermediate code.

When compiling for generated code you must specify 32 or 64-bit. Visual COBOL is bit-specific and does not support cross-bit generation.

To produce bit-specific code, use ccbl from either a 32-bit or 64-bit command prompt.

Parent topic: Compiling and Compiler Option Support


Setting Compiler Options

Using the ACUOPT directive or ccbl to set ACUCOBOL-GT compiler options.

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 and NOACUOPT is not allowed.

Parent topic: Compiling and Compiler Option Support
Related reference
ACUOPT


Supported and Unsupported Options

Supported ACUCOBOL-GT compiler options.

This section lists the supported ACUCOBOL-GT compiler options. There is no support for options not mentioned. For descriptions of ACUCOBOL-GT compiler options see chapter 2 of the ACUCOBOL-GT User's Guide.

General Support Notes

Visual COBOL supports the following ACUCOBOL-GT compiler functionality:

  • Grouping of options
  • CBLFLAGS environment variable
  • Replacement of @ by the base name of the source file.

Standard Options

Option | Support Notes
-e |
-o | This option produces intermediate code with the suffix .int. It does not produce code with the .acu suffix.
-v |
-w |
-x |

Compatibility Options

Option | Support Notes
-Ca |
-Ci |
-Cr |
-Cv |

Truncation Options

Option | Support Notes
-Dz |
-noTRUNC |
-truncANSI |

Source Options

Option | Support Notes
-Sa, -Sd, -Sp, -St, -S1..-S9 |

Listing Options

Option | Support Notes
-La, -Lc, -Lf, -Li, -Ll, -Lo, -Ls, -Lw | The output these list options provide differs in Visual COBOL.

Video Options

Option | Support Notes
-Vc |
-Vd | This option is always on.

Data Item/Storage Options

Option | Support Notes
-D1, -D2, -D5, -D6, -D7 |
-Da, -Db, -Df, -Dm, -Dq, -Ds, -Dv |
-DCa, -DCb, -DCi, -DCm, -DCn, -DCr, -DCv |
-Dd31 |
-Dl1/2/4/8 |
-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.

Reserved Word Options

Option | Support Notes
-Rc, -Rn, -Rw |

Warning and Error Options

Option | Support Notes
-a | This flag is now obsolete and should not be used.
-Qm |

Internal Table Options

Option | Support Notes
-Td, -Te |

Debugging Options

Option | Support Notes
-G | The Compiler supports all -G options, but they map onto standard Visual COBOL animation directives.

Miscellaneous Options

Option | Support Notes
-Za ,-Zc ,-Zd ,-Zg ,-Zi ,-Zl,-Zn,-Zs, -Zy |
-Zr0 ,-Zr1 |

Native Object Code Options

Option | Support Notes
-n | The Compiler supports the other native options if the bit arrangement and host machine match the selected target machine. There is no support for cross generation of native code.
Parent topic: Compiling and Compiler Option Support


Vision Indexed File System

Support for ACUCOBOL-GT's native indexed file system.

Note: This functionality is supported for native COBOL only.

This COBOL development system supports ACUCOBOL-GT's native indexed file system known as Vision. This enables you to use your existing data files.

Alternatively, you can use the data migration tool, ACU2MFDataMigration.exe, to convert Vision data files to Micro Focus format. The tool is available from the folder in which the product samples are installed.

  • Configuring Access to Vision Data Files
    Configuring your environment to access Vision data files.
  • Searching for Vision Data Files
    Determining how Vision data files are located at runtime.
  • Vision Related Utilities
    The Vision-related utilities that are supported in this COBOL system.
Parent topic: Enabling ACUCOBOL-GT Compatibility


Configuring Access to Vision Data Files

Configuring your environment to access Vision data files.

To enable access to your Vision data files:

  • Compile your programs with the following Compiler directive:
    CALLFH(ACUFH)

    Set this directive directly in your source code or from the COBOL project option's interface.

  • Set environment variable A_CONFIG to the path of an ACUCOBOL-GT configuration file:
    set A_CONFIG=acu.cfg
Parent topic: Vision Indexed File System
Related reference
Searching for Vision Data Files
Related information
Setting Directives Outside the IDE


Searching for Vision Data Files

Determining how Vision data files are located at runtime.

If you are accessing Vision data files, use the following environment variables to enhance the way that they are searched for at runtime:

  • APPLY_FILE_PATH
    Enables the values of the FILE_PREFIX variable to be applied to the path when searching for Vision data files.
  • FILE_CASE
    Enables you to adjust the case of data file names.
  • FILE_PREFIX
    Defines a set of directories that the runtime searches to locate Vision data files.
  • FILE_SUFFIX
    Appends an extension to Vision data files that do not already specify one.
Parent topic: Vision Indexed File System
Related reference
Configuring Access to Vision Data Files


APPLY_FILE_PATH

Enables the values of the FILE_PREFIX variable to be applied to the path when searching for Vision data files.

Parameters:

1/0, On/Off, True/False, Yes/No
When set to 1 (or On, True or Yes), the values of FILE_PREFIX are applied to data files whose path names begin with a forward slash ("/").

The default value is 0 (Off, False or No).

Example:

If your application specifies:

/accounting/data/ind.dat

and your FILE_PREFIX variable is set to:

FILE_PREFIX  /master_data

and APPLY_FILE_PATH is set to 1 (On, True or Yes), the runtime will look for your file in:

/master_data/accounting/data/ind.dat
Parent topic: Searching for Vision Data Files
Related reference
FILE_SUFFIX
FILE_PREFIX
FILE_CASE


FILE_CASE

Enables you to adjust the case of data file names.

Parameters:

None or 0
Data file names are not changed
LOWER or 1
Data file names are changed to lower case, including directory (path) elements
UPPER or 2
Data file names are changed to upper case, including directory (path) elements
LOWER_BASE or 3
Data file names are changed to lower case, excluding directory (path) elements
UPPER_BASE or 4
Data file names are changed to upper case, excluding directory (path) elements

The default is 0.

Examples:

FILE_CASE=2				*> e.g. cust_acc\fy11.dat becomes CUST_ACC\FY11.DAT
FILE_CASE=LOWER_BASE	  *> e.g. CUST_ACC\FY11.dat becomes CUST_ACC\fy11.dat

Comments:

Translation occurs before the FILE_PREFIX and FILE_SUFFIX environment options are applied. You should make sure that those variables specify the correct case.

Parent topic: Searching for Vision Data Files
Related reference
APPLY_FILE_PATH
FILE_SUFFIX
FILE_PREFIX


FILE_PREFIX

Defines a set of directories that the runtime searches to locate Vision data files.

Parameters:

Directories

One or more relative or absolute paths. Entries are separated by one or more spaces, or a semicolon.

The default value is "." (current working directory).

Comments:

You can specify a directory path that contains embedded spaces if you surround the path with quotation marks. For example:

FILE_PREFIX  C:\"Sales Data"
Parent topic: Searching for Vision Data Files
Related reference
APPLY_FILE_PATH
FILE_SUFFIX
FILE_CASE


FILE_SUFFIX

Appends an extension to Vision data files that do not already specify one.

Parameters:

Suffix
The extension that is appended to a data file that does not already have one specified.
The default value is empty.

Example:

FILE_SUFFIX dat		*> Attempt to open "EMPFILE" and "EMPFILE.dat" is searched for.
Parent topic: Searching for Vision Data Files
Related reference
APPLY_FILE_PATH
FILE_PREFIX
FILE_CASE


Vision Related Utilities

The Vision-related utilities that are supported in this COBOL system.

This COBOL development system supports the following Vision-related utilities:

  • vutil.
  • vio.
  • logutil.

For full information on Vision and its related utilities, see chapters 3 and 6 of the ACUCOBOL-GT User's Guide. Topics in this section describe how to enable support for Vision and its general usage.

Parent topic: Vision Indexed File System


ACUCOBOL-GT Library Routines

Supported ACUCOBOL-GT library routines.

The following ACUCOBOL-GT library routines are now available in this COBOL system when you set the ACU Compiler directive.

Note: These library routines are available for native COBOL only.
  • 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$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$RERR
    Returns extended file status information.
  • 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.
  • 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.
Restriction: This routine is supported in native COBOL only.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are displayed 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.
Restriction: This routine is supported in native COBOL only.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are displayed 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.
Restriction: This routine is supported in native COBOL only.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are displayed 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

  • "@[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$MAKEDIR

Creates a new directory.
Restriction: This routine is supported in native COBOL only.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are displayed 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.
Restriction: This routine is supported in native COBOL only.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are displayed 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.
Restriction: This routine is supported in native COBOL only.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are displayed 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$RERR

Returns extended file status information.
Restriction: This routine is supported in native COBOL only.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are displayed in the Compatibility Issues section at the end of the topic.

Usage

CALL "C$RERR"
    USING EXTEND-STAT, TEXT-MESSAGE, STATUS-TYPE

Parameters

EXTEND-STAT (returned) | PIC X(5) or larger; PIC X(7) or larger under VMS
TEXT-MESSAGE (returned) | PIC X(n)
STATUS-TYPE (input) | Numeric parameter

Comments

C$RERR must be passed a USING argument that should be PICTURE X(5) or larger. This argument is filled in with either the extended file status caused by the last file I/O, or the extended transaction status caused by the last transaction operation. The value of STATUS-TYPE determines which status will be filled in.

A text message is available for some 9D errors, which are host system errors. When a text message is available, it's moved into the data item TEXT-MESSAGE, and returned as the second parameter. You can use TEXT-MESSAGE to display text to the user, so the user can decide what action to take. This parameter is ignored for transaction status.

The third parameter, STATUS-TYPE, controls whether file status or transaction status information is returned by the routine. If STATUS-TYPE is set to 1 or the parameter is omitted, file status is returned. If STATUS-TYPE is set to 2, transaction status is returned.

The first two characters of the extended file status are identical to the normal FILE STATUS value returned by ACUCOBOL-GT for a file operation. The last two characters further clarify the reason for the particular FILE STATUS value. The values used here 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.

The first two characters of the extended transaction status are identical to the contents of the TRANSACTION-STATUS register. The last two characters further clarify the reason for the particular transaction status value. The values used here are listed in the transaction status table found in Appendix E of the ACUCOBOL-GT product documentation .

In a few cases, there may also be a tertiary status code. If there is one, a comma will be placed immediately after the secondary status code, and the tertiary code will then appear left-justified.

Compatibility Issues

  • The EXTEND-STAT parameter is only returned for INTERFACE errors (when the file status is 9/83).
  • The STATUS-TYPE parameter is not supported in this COBOL system, and therefore only the extended file status, and not the extended transaction status caused by the last transaction operation, is returned.
Parent topic: ACUCOBOL-GT Library Routines


M$ALLOC (Dynamic Memory Routine)

Allocates a new area of dynamic memory.
Restriction: This routine is supported in native COBOL only.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are displayed 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.
Restriction: This routine is supported in native COBOL only.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are displayed 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.
Restriction: This routine is supported in native COBOL only.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are displayed 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.
Restriction: This routine is supported in native COBOL only.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are displayed 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.
Restriction: This routine is supported in native COBOL only.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are displayed 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.
Restriction: This routine is supported in native COBOL only.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are displayed 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


WIN$VERSION

Returns version information for Windows and Windows NT host platforms.
Restriction: This routine is supported in native COBOL only.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are displayed 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 98 | 4 | 10 |
Windows ME | 4 | 90 |
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 NT | 4 | 0 |
Windows 2000 | 5 | 0 | Not applicable
Windows Vista | 6 | 0 | OSVERSIONINFOEX.wProductType == VER_NT_WORKSTATION
Windows 7 | 6 | 1 | 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 runtime.
  • 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 following fields are not supported in this COBOL system:

  • WIN-BUILDNUMBER
  • WIN-CSDVERSION
  • WIN-SERVICEPACK-MAJOR
  • WIN-SERVICEPACK-MINOR
  • WIN-SUITEMASK
  • WIN-PRODUCTTTYPE
Parent topic: ACUCOBOL-GT Library Routines


ACUCOBOL-GT Syntax Extensions

Supported ACUCOBOL-GT syntax elements and behaviors.

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 ACUCUBOL-GT language reference. It specifically provides descriptions of Acu's language extensions to ANSI 85 COBOL that are enabled when programs are compiled in Acu compatibility mode. 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.
  • 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: Compatibility with ACUCOBOL-GT
Related concepts
ACU Compiler Directive
Language Concepts
Related reference
ACU


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.
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. Numeric literals may contain up to 31 digits. Note that is not required to compile with the -Dd31 option, as 31 digits is the default.

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. Refer to ACUCOBOL-GT User’s Guide, section Compatibility Options for details on the -Cv Compiler option.

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

ACUCOBOL-GT supports two different source formats:

  • ANSI format
  • Terminal format

ANSI format has the following characteristics:

  • Columns 1 - 6 are used for sequence numbers. This area is ignored by the compiler.
  • Column 7 is the indicator area.
  • Columns 8 - 11 are area A.
  • Columns 12 - 72 are area B.
  • Columns 73 - 80 are the identification area. This area is ignored by the Compiler (but see Source Code Control below).
  • Lines are 80 characters long. Lines shorter than 80 characters are padded with spaces, and longer lines are truncated.

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. This indicator must be preceded by a backslash (\) in column 1 (placing the D in column 2).
  • 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 identification area starts when a | or *> is encountered, provided it is not part of a literal. The Identification Area extends to the end of the line. This can be used to introduce in-line comments.
  • 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).

Both formats expand tab characters to every eight spaces. Both formats also translate lower-case characters to upper-case except in literals. Finally, both formats translate the underscore character to a hyphen when it is found in identifiers.

Normally, the Compiler determines the source format automatically by examining the first character of the first non-blank line. If this character is blank or a digit, the file is assumed to be an ANSI file; otherwise it is assumed to be in terminal format. This is done independently for the main source file and all COPY libraries. This allows mixing of formats among a source file and its COPY libraries. If desired, the format to use for the entire input source can be set to either mode via the -Sa or -St compile flags.

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


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 Section 2.2.10, "Data Storage Options" of the ACUCOBOL-GT User's Guide for details on these options.

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


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

Parent topic: Procedure Division Statements
Related information
The INSPECT Statement


SET ENVIRONMENT

ACUCOBOL-GT format 6 SET extension.

FORMAT 6

SET { env-name TO env-value } ...
    {ENVIRONMENT  }
Note: The CONFIGURATION option that is supported in ACUCOBOL-GT is not supported in Visual COBOL.

Syntax Rules

  1. env-name is a nonnumeric literal or data item.
  2. env-value is a USAGE DISPLAY numeric or nonnumeric literal or data item. If numeric, it must be an integer.

General Rules

  1. A format 6 SET statement is used to set environment variables. ACUCOBOL-GT maintains a set of configuration variables that can affect various aspects of the runtime system. These variables can be initially set in the ACUCOBOL-GT runtime configuration file described in Appendix H of the ACUCOBOL-GT Appendices Manual. The Format 6 SET statement can be used to modify these values at runtime.
    Note: ACUCOBOL-GT allows you to set runtime configuration variables and to change their values. This COBOL system does not support this functionality.
Parent topic: Procedure Division Statements


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

Introduction to compatibility with DG Interactive COBOL.

Visual COBOL provides compatibility with the DG Interactive COBOL programming language.

This enables you to migrate programs from this environment.

You can:
  • Convert applications written in DG Interactive COBOL to the Micro Focus COBOL language, and enhance them using the advanced language and development features offered by Visual COBOL.
  • Retain the use of the selected COBOL on some machine environments while moving to Visual COBOL on others. You might want to maintain a common set of source programs which are suitable for all environments.
Note: Any error messages and numbers that are returned when you compile your program in Visual COBOL or when you execute the resulting code are different in the two environments. This should present no problems, but is something of which you should be aware.
Parent topic: Compatibility with DG Interactive COBOL


Compatibility Directives

This COBOL system provides compatibility with Data General Interactive COBOL rev 1.30 and 1.30 through the use of a Compiler directive.

  • DG
    Changes the behavior of certain features to be compatible with Data General Interactive COBOL rev 1.30.
Parent topic: Compatibility with DG Interactive COBOL
Related concepts
DG Interactive COBOL Source Programs
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 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.

Parent topic: Compatibility Directives
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 concepts
Compatibility Directives
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
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


DG International Character Set

The environment dependent feature of DG Interactive COBOL which allows you to use an extra 69 characters in addition to the 96 characters in the ASCII set, is not supported by this COBOL system.

Parent topic: Compatibility with DG Interactive COBOL Source


DG File Status and other Exception Values

DG Interactive COBOL file status and other exception values are not supported by this COBOL system, as they are environment dependent. If you wish to maintain a common source for programs used by both systems, you should maintain COPY-files of the file status values returned by each system.

Parent topic: Compatibility with DG Interactive COBOL Source


Calls

DG Interactive COBOL system calls are environment dependent, and are not supported by this COBOL system. Under this COBOL system you cannot pass a switch in a CALL statement; you should use Linkage Section items to communicate between programs.

Parent topic: Compatibility with DG Interactive COBOL Source


Linkage Section Access

DG Interactive COBOL allows a main program to access its Linkage Section but this facility is not supported by this COBOL system. We recommend that if a program is to be accessed as a main program, you transfer the Linkage Section entries into Working-Storage.

Parent topic: Compatibility with DG Interactive COBOL Source


Arithmetic of Group Level Items

DG Interactive COBOL allows arithmetic of group level items, but this is not supported by this COBOL system. We recommend that you redefine such fields into numeric items to overcome this problem.

Parent topic: Compatibility with DG Interactive COBOL Source


Run-time Switches

DG Interactive COBOL run-time switches A to Z, inclusive, are mapped onto switches 1 to 26, respectively, in this COBOL system.

Parent topic: Compatibility with DG Interactive COBOL Source


Program Identification and Data-names

The DG Interactive COBOL system allows the Program-ID and a data item in that program to have the same name. However, this COBOL system does not allow the use of the same name for the Program-ID and a data item in a program, requiring instead that each should be unique. We recommend that you either change the program-name in the Program-ID and in any programs that call this program, or change the name of the data item.

Parent topic: Compatibility with DG Interactive COBOL Source


Reformatting a DG COBOL Source File

Source programs written in DG Interactive COBOL CRT format cannot be accepted by this COBOL system unless you first amend the format, using a formatter or editor. This must alter the margins in these programs, and split any lines in them containing more than 72 characters, into lines of 72 characters or fewer.

  • Reformatting Rules
Parent topic: Compatibility with DG Interactive COBOL


Reformatting Rules

You should amend your source program according to the following rules:

  1. If the character in column 1 is an indicator (*/-), append six spaces to the beginning of a line.
  2. If the character in column 1 is any non-space character not mentioned in rule 1, append seven space characters to the beginning of the line.
  3. If area A (columns 1 to 4 inclusive) contains all spaces, append seven additional space characters to the beginning of the line. However, if the entire line contains spaces, it outputs a single 72 character line containing spaces.
  4. If a line is too long to fit onto a single 72 character line, break it onto subsequent lines, up to a maximum of three. Where possible, these breaks occur at a space character to preserve the program's readability.
  5. If a line is expanded beyond 132 characters, truncate the line to 132 characters. This prevents any pseudo-comment areas from being included in the program source.
Parent topic: Reformatting a DG COBOL Source File


Compatibility with RM/COBOL

Visual COBOL provides compatibility with the RM/COBOL programming language:

This enables you to migrate programs from this environment. You can:
  • Convert applications written in RM/COBOL to the Micro Focus COBOL language, and enhance them using the advanced language and development features offered by Visual COBOL.
  • Retain the use of the selected COBOL on some machine environments while moving to Visual COBOL on others. You might want to maintain a common set of source programs which are suitable for all environments.
Note: Any error messages and numbers that are returned when you compile your program in Visual COBOL or when you execute the resulting code are different in the two environments. This should present no problems, but is something of which you should be aware.
  • Converting RM/COBOL Applications
    This COBOL system supports certain extensions that enable you to submit source programs written in the RM/COBOL language.
  • Converting RM/COBOL Data Types
    Information on how to convert COMPUTATIONAL, COMPUTATIONAL-3, COMPUTATIONAL-6 and DISPLAY data from RM/COBOL format to the formats used by this system.
  • RM/COBOL Conversion Issues
    Information on issues you might encounter when running RM/COBOL source programs in this COBOL system.
  • Compatibility Directives
    This COBOL system provides compatibility with RM/COBOL V2.0 through the use of the following Compiler directives.
  • RM/COBOL Library Routines
    A list of RM/COBOL standard library routines supported in this COBOL system.
  • RM/COBOL File Handler
    This COBOL system enables you to utilize RMFM, the RM/COBOL file handler.
  • Compatibility with XML Extensions
Parent topic: Compatibility


Converting RM/COBOL Applications

This COBOL system supports certain extensions that enable you to submit source programs written in the RM/COBOL language.

To convert an RM/COBOL application and make it suitable for input to this COBOL system, perform the following steps.
  1. Submit your RM/COBOL source programs to this COBOL system.
  2. Compile the programs with the RM directive set.
  • RM/COBOL Source Programs
  • The RM Directive
  • RM/COBOL File Status Codes
  • Perform Statements
  • Table Bound Checking
Parent topic: Compatibility with RM/COBOL
Related reference
RM


RM/COBOL Source Programs

To submit RM/COBOL source programs to this COBOL system which contain syntax not supported in the standard COBOL language, you must set the RM Compiler directive. See the topic RM for full details of of this Compiler directive.

When you set the RM directive the additional syntax required is enabled. See the section Ryan McFarland COBOL V2.0 Syntax Support in your Language Reference for details of syntax support for Ryan McFarland COBOL V2.0.

You will need to alter your source programs only if they contain RM/COBOL features which are not supported by this COBOL system. You might also want to change your source programs if they contain features which behave differently under both COBOL systems, in order to force this system to emulate the behavior of the RM/COBOL system.

You must change any tab characters to spaces before submitting any source programs to this COBOL system.

Parent topic: Converting RM/COBOL Applications
Related reference
Ryan McFarland COBOL V2.0 Syntax Support


The RM Directive

By default, the standard COBOL language supported by this system, as documented in the Language Reference, already supports much of the RM/COBOL syntax and behavior. You can, however, enable some additional RM/COBOL syntax, using the RM Compiler directive. Setting the RM directive 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. The additional syntax enabled by the RM directive is documented in the section Ryan McFarland COBOL V2.0 Syntax Support in your Language Reference.

If you normally set the ANSI switch when you submit your RM/COBOL source programs to the RM/COBOL system, you must specify the ANSI parameter with the RM directive when you submit these programs to this COBOL system.

Setting the RM directive automatically sets additional Compiler directives, namely NOTRUNC, OLDINDEX, NOOPTIONAL-FILE, RETRYLOCK, ALIGN"2" and SEQUENTIAL"LINE". See the topic Compiler directives for full details of these Compiler directives.

The system will also behave as if you had specified the following syntax:

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. When you set the RM directive with the ANSI parameter, the same Compiler directives are set as for the RM directive, except that the SEQUENTIAL directive is set as SEQUENTIAL"RECORD". Also, the system behaves as if you had specified the syntax:

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.

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 to NOSPZERO, TRUNC"ANSI", NOOLDINDEX, OPTIONAL-FILE, NORETRYLOCK, ALIGN"8" and SEQUENTIAL"RECORD". Additionally, the system behaves as if you had specified the syntax:

sign trailing included

for signed numeric data items, and:

lock mode is exclusive

for each file in the program which has no explicit locking syntax declared. 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
Ryan McFarland COBOL V2.0 Syntax Support
RM


RM/COBOL File Status Codes

RM/COBOL file status codes are either ANSI'74 file status codes or can be mapped onto extended file status codes, as shown below.

Status Key 1 | Status Key 2 | Extended File Status Code | Description
9 | 0 | 9/143 | REWRITE/DELETE not after successful READ
 |  | 9/147 | Wrong open or access mode for READ/ START.
 |  | 9/148 | Wrong open or access mode for WRITE.
 |  | 9/149 | Wrong open or access mode for REWRITE/ DELETE.
 | 1 | 9/142 | File not open - cannot be closed.
 | 2 | 9/141 | File already open - cannot be opened.
 | 3 | 9/138 | File is closed with lock - cannot open.
 |  | 9/210 | File is closed with lock.
 | 4 | 9/013 | File not found.
 |  | 9/035 | Incorrect access permission.
 |  | 9/037 | File access denied.
 |  | 9/139 | Record length or key inconsistent.
9 | 4 | 9/188 | Filename too large.
 | 6 | 9/146 | No current record defined for sequential read.
 | 8 | 9/071 | Bad indexed file format.
 | 9 | 9/065 | File locked.
 |  | 9/068 | Record is locked.
Parent topic: Converting RM/COBOL Applications


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: Converting RM/COBOL Applications
Related reference
The PERFORM Statement


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: Converting RM/COBOL Applications
Parent topic: Producing Executable Code
Related reference
BOUND
BOUNDOPT


Converting RM/COBOL Data Types

Information on how to convert COMPUTATIONAL, COMPUTATIONAL-3, COMPUTATIONAL-6 and DISPLAY data from RM/COBOL format to the formats used by this system.

  • Types of Data
  • COMP/COMPUTATIONAL Data
  • COMP-3/COMPUTATIONAL-3 Data
  • COMP-6/COMPUTATIONAL-6 Data
  • DISPLAY Data
Parent topic: Compatibility with RM/COBOL


Types of Data

This COBOL system always allocates the same number of bytes to a data item as in the original program, but might redefine its contents when it is converted. Therefore, you must be aware that if these items are redefined, and the program logic expects to find a certain binary value in the redefinition, you might not receive the behavior you are expecting at run time. At run time, this COBOL system might treat the ON SIZE ERROR clause differently from the RM/COBOL system. See the chapter RM/COBOL Conversion Issues for further details.

The following sections define how this COBOL system treats COMPUTATIONAL, COMPUTATIONAL-1 and COMPUTATIONAL-6 types of data.

  • COMPUTATIONAL (COMP) Data Types
  • COMPUTATIONAL-1 (COMP-1) Data Types
  • PICTURE Character-strings
  • COMPUTATIONAL-6 (COMP-6) Data Types
Parent topic: Converting RM/COBOL Data Types
Related concepts
RM/COBOL Conversion Issues


COMPUTATIONAL (COMP) Data Types

This COBOL system treats any COMP data items in your RM/COBOL source program as the standard Micro Focus COBOL DISPLAY format. The difference in the internal representation of such data in the two systems is that this COBOL system always sets the most significant four bits of each byte to the value 3, while the RM/COBOL system always sets such bits to the value 0.

For example, under the RM/COBOL system:

PIC 999 COMP VALUE 123

is held in three bytes as hexadecimal value 01 02 03

while under this COBOL system:

PIC 999 VALUE 123

is held in three bytes as hexadecimal value 31 32 33.

Parent topic: Types of Data
Related concepts
COMPUTATIONAL-1 (COMP-1) Data Types
COMPUTATIONAL-1 Data Items with a PICTURE other than S9(4)
COMP/COMPUTATIONAL Data


COMPUTATIONAL-1 (COMP-1) Data Types

For each data item declared as USAGE COMP-1 in your RM/COBOL source program, regardless of its picture-string, this COBOL system allocates a 2-byte signed binary data item. This data item is capable of holding a hexadecimal value in the range -32768 to +32767. That is, this COBOL system treats each RM/COBOL USAGE COMP-1 data item as though it had a standard Micro Focus COBOL picture-string of S9(4) COMP. See your Language Reference for details on the standard Micro Focus COBOL language.

Parent topic: Types of Data
Related concepts
COMPUTATIONAL-1 Data Items with a PICTURE other than S9(4)
COMPUTATIONAL (COMP) Data Types
COMP/COMPUTATIONAL Data
Field Wrap-Around


PICTURE Character-strings

The maximum length of a PICTURE character-string in a record description is 20 characters. However, you can overcome this limitation by splitting any PICTURE character-string which exceeds this limit into two, and defining a FILLER item with a PICTURE character-string which corresponds to the size of the second half of the original string.

Parent topic: Types of Data
Related reference
The PICTURE Clause


COMPUTATIONAL-6 (COMP-6) Data Types

This COBOL system treats any COMP-6 data items in your RM/COBOL source program as the standard Micro Focus COBOL COMP format. If, as a result of this, less data space is allocated to each item than would be under the RM/COBOL system, this COBOL system pads the space with a byte containing a zero, as shown in the following table:

RM COMP-6 PICTURE clause | Bytes allocated when converting to Micro Focus COBOL COMP PICTURE clause | Number of bytes containing leading zeros required to precede COMP PICTURE clause
9(1) | 1 | NONE
9(2) | 1 | NONE
9(3) | 2 | NONE
9(4) | 2 | NONE
9(5) | 3 | NONE
9(6) | 3 | NONE
9(7) | 4 | NONE
9(8) | 4 | NONE
9(9) | 5 | NONE
9(10) | 5 | NONE
9(11) | 5 | 1
9(12) | 5 | 1
9(13) | 6 | 1
9(14) | 6 | 1
9(15) | 7 | 1
9(16) | 7 | 1
9(17) | 8 | 1
9(18) | 8 | 1

The padding byte precedes the converted field, and is therefore included in any redefinition of group fields which contain the converted field. However, the padding byte would not be included if you redefined only the converted field. If you wish to ensure that the padding byte is included in the redefinition of the converted field, you must add a field at a higher level immediately before the converted field, and redefine this new field instead.

Parent topic: Types of Data
Related concepts
Redefinition of COMP or COMP6 Data Items
COMP-6/COMPUTATIONAL-6 Data


COMP/COMPUTATIONAL Data

The RM/COBOL system represents COMP (or COMPUTATIONAL) data in packed decimal format with one character per byte stored in each least significant four bits. The most significant half-byte always contains zero. If the picture string specifies a signed representation, an additional byte is added to the least significant end of the string: a negative value is represented by the hexadecimal value x"D", and a positive value is represented by the hexadecimal value x"B".

Consider the following examples:

Value | Picture Clause | RM Representation (Hexadecimal)
1234 | PIC 9(5) COMP | 00 01 02 03 04
1234 | PIC S9(5) COMP | 00 01 02 03 04 0B
-1234 | PIC S9(5) COMP | 00 01 02 03 04 0D

You should converts COMP data fields into DISPLAY format, with sign trailing separate. This is compatible with this COBOL system's treatment of RM/COBOL COMP fields in the source program when the RM directive is set. If the data item is signed, the sign byte has the most significant half-byte set to hexadecimal value 2.

After conversion, the examples above are represented as follows:

Value | Picture Clause | This COBOL's Representation (Hexadecimal)
1234 | PIC 9(5) DISPLAY | 30 31 32 33 34
1234 | PIC S9(5) DISPLAY | 30 31 32 33 34 2B
-1234 | PIC S9(5) DISPLAY | 30 31 32 33 34 2D
Parent topic: Converting RM/COBOL Data Types
Related concepts
COMPUTATIONAL-1 (COMP-1) Data Types
COMPUTATIONAL-1 Data Items with a PICTURE other than S9(4)
COMPUTATIONAL (COMP) Data Types


COMP-3/COMPUTATIONAL-3 Data

The RM/COBOL system represents COMP-3 data in packed decimal format with the least significant half-byte holding the sign.

This sign half-byte contains the following values:

Field | RM Sign half-byte value (Hexadecimal)
Unsigned | F
Signed, Positive | B or F
Signed, Negative | D

Consider the following examples:

Value | Picture Clause | RM Representation (Hexadecimal)
1234 | PIC 9(5) COMP-3 | 00 23 4F
1234 | PIC S9(5) COMP-3 | 00 23 4F
-1234 | PIC S9(5) COMP-3 | 00 23 4D

The only requirement for conversion is that the sign half-byte has to be changed for signed positive fields to hexadecimal value C. The examples above are represented as follows:

Value | Picture Clause | This COBOL's Representation (Hexadecimal)
1234 | PIC 9(5) COMP-3 | 00 23 4F
1234 | PIC S9(5) COMP-3 | 00 23 4C
-1234 | PIC S9(5) COMP-3 | 00 23 4D
Parent topic: Converting RM/COBOL Data Types
Related concepts
COMPUTATIONAL-3 or PACKED-DECIMAL Format


COMP-6/COMPUTATIONAL-6 Data

The RM/COBOL system holds COMP-6 data in a similar format to COMP-3 data, except there is no sign half-byte. If a sign is indicated in the picture clause it is ignored and has no effect. The value held is always positive.

Consider the following examples:

Value | Picture Clause | RM Representation (Hexadecimal)
1234 | PIC 9(5) COMP-6 | 00 12 34
123456 | PIC S9(6) COMP-6 | 12 34 56

In order to maintain the size and capacity of the data items, this COBOL system treats COMP-6 data items as this COBOL's COMP format fields, and pads the field with binary zeros where necessary. The examples above are represented as follows:

Value | Picture Clause | This COBOL's Representation (Hexadecimal)
1234 | PIC 9(5) COMP-6 | 00 04 D2
123456 | PIC S9(6) COMP-6 | 01 E2 40

The 9(5) COMP field is extended by one byte containing binary zero in order to maintain the size of the original item. See the section COMPUTATIONAL-6 (COMP-6) Data Types in the chapter Compatibility with RM/COBOL for details.

Parent topic: Converting RM/COBOL Data Types
Related concepts
COMPUTATIONAL-6 (COMP-6) Data Types
Redefinition of COMP or COMP6 Data Items


DISPLAY Data

You should be aware of the following differences between the representation of numeric DISPLAY format data items, with sign INCLUDED, under the RM/COBOL system and this COBOL system:

  • This COBOL system does not encode a sign on the data if the data is positive, whereas the RM/COBOL system increments the value of the most significant half-byte by one to denote a positive value.
  • This COBOL system increments the value of the most significant half-byte by four to denote a negative value. The RM/COBOL system increments the value of the byte by twenty-five (that is, hexadecimal 19).

When the RM directive is set, a DISPLAY format data item with no sign clause associated is treated by this system as though you had specified the SIGN TRAILING IS SEPARATE clause. However, when the RM"ANSI" directive is set, the same data item is treated as though you had specified the SIGN TRAILING IS INCLUDED clause. This is the default state for such data items in this COBOL system.

Consider the following examples:

Value | Picture Clause | RM Representation (Hexadecimal)
 |  | Leading | Trailing
123 | PIC 9(3) DISPLAY | 31 32 33 | 31 32 33
123 | PIC S9(3) DISPLAY | 41 32 33 | 31 32 43
-123 | PIC S9(3) DISPLAY | 4A 32 33 | 31 32 4C

These examples are represented as follows:

Value | Picture Clause | This COBOL's Representation (Hexadecimal)
 |  | Leading | Trailing
123 | PIC 9(3) DISPLAY | 31 32 33 | 31 32 33
123 | PIC S9(3) DISPLAY | 31 32 33 | 31 32 33
-123 | PIC S9(3) DISPLAY | 71 32 33 | 31 32 73
Parent topic: Converting RM/COBOL Data Types
Related reference
RM


RM/COBOL Conversion Issues

Information on issues you might encounter when running RM/COBOL source programs in this COBOL system.

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: Compatibility with RM/COBOL
Related concepts
Types of Data


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.

  • ACCEPT FROM CENTURY-DATE and FROM CENTURY-DAY
    In Visual COBOL, to use the FROM CENTURY-DATE and FROM CENTURY-DAY phrases with the ACCEPT statement, set the RM Compiler directive.
  • COPY REPLACING within REPLACE or vice versa
    In Visual COBOL, you cannot specify text replacement when text replacement is already active.
  • Duplicate Paragraph-names
    Visual COBOL and RM/COBOL differ in the way that they reference paragraph-names when two or more duplicate paragraph names exist differs.
  • Empty Groups
    In Visual COBOL, if you have any empty groups specified in your source code, you must set the RM Compiler directive.
  • Figurative Constants and the USING Phrase
    In Visual COBOL, to use figurative constants in the USING phrase of a CALL statement or as values of level 78 constants, set the RM Compiler directive.
  • File Not Found Errors
    Visual COBOL and RM/COBOL differ in the environment variables that they use to locate program and data files.
  • Indexed File Error on Open
    Visual COBOL and RM/COBOL differ in how they handle record length fields and some data fields when you open an RM/COBOL indexed file.
  • Linkage Section in Main Program
    Visual COBOL and RM/COBOL differ in their ability to reference the Linkage Section items in the main program.
  • Library Routines
    To use the RM/COBOL standard library routines that are available in Visual COBOL, you must set the DIALECT(RM) Compiler directive.
  • Nested OCCURS DEPENDING Clauses
    In Visual COBOL, if you are using nested OCCURS DEPENDING clauses, you must set the ODOSLIDE Compiler directive.
  • Numbering of Segments
    Visual COBOL and RM/COBOL differ in the number of segments that they permit you to specify.
  • Program Identification and Data Names
    In Visual COBOL, ensure that the Program-ID name does not share the same name as any data items in the program.
  • REMARKS Paragraph
    In Visual COBOL, if your program uses the REMARKS paragraph in the Identification Division, you must set the RM Compiler directive.
  • Reserved Words
    In Visual COBOL, setting certain Compiler directives (such as RM and ANS85) activates certain reserved words that you cannot use as names for your data items.
  • SAME AS Clause Not Available When Defining Data Structures
    Visual COBOL and RM/COBOL differ in the way that they allow you to reuse existing data structures.
  • Source Code in Columns 73 to 80
    Visual COBOL ignores any of the code in your source programs which lies within columns 73-80 inclusive.
  • Table Bound Checking
  • Undeclared Data Items in Clauses
    In Visual COBOL, if the data item used in a clause (for example, the File Status clause) is not declared, you receive an error.
  • User-names Longer than 127 Bytes are Truncated
    In RM/COBOL, you can specify user-names (data-names, procedure-names, program-names, etc) up to 240 characters long. In this COBOL system, user-names longer than 127 bytes in length are truncated and a warning message is produced.
Parent topic: RM/COBOL Conversion Issues


ACCEPT FROM CENTURY-DATE and FROM CENTURY-DAY

In Visual COBOL, to use the FROM CENTURY-DATE and FROM CENTURY-DAY phrases with the ACCEPT statement, set the RM Compiler directive.

Alternatively, use the following equivalent phrases with the ACCEPT statement:

  • FROM DATE YYYYMMDD, which is the equivalent of FROM CENTURY-DATE.
  • FROM DAY YYYYDDD, which is the equivalent of FROM CENTURY-DAY.
procedure division.
ACCEPT data-name-1 FROM DATE YYYYMMDD.
ACCEPT data-name-2 FROM DAY YYYYDDD.
Parent topic: Producing Executable Code
Related reference
The ACCEPT Statement


COPY REPLACING within REPLACE or vice versa

In Visual COBOL, you cannot specify text replacement when text replacement is already active.

If you attempt to use COPY REPLACING in a file copied with a COPY REPLACING statement, an error code COBCH0062 Cannot have COPY REPLACING within REPLACE or vice versa is displayed on compilation.

Parent topic: Producing Executable Code
Related reference
COBCH0062 Cannot have COPY REPLACING within REPLACE or vice versa
The COPY Statement


Duplicate Paragraph-names

Visual COBOL and RM/COBOL differ in the way that they reference paragraph-names when two or more duplicate paragraph names exist differs.

In Visual COBOL, if you have duplicate paragraph-names, in different sections, and then call a paragraph-name from outside its section, an error is produced unless you have explicitly referenced the paragraph-name and its section. In RM/COBOL, by just calling the paragraph-name, it assumes you are calling the next declaration of the paragraph-name found.

To ensure that references to duplicate paragraph-names are correctly resolved, you must qualify a reference to a duplicate paragraph-name by adding the section-name in which it is declared.

Example

If your source code contains the following:

      ....
      perform para-2.
      ....
 sect-1 section.
      para-1.
      ....
      para-2.
      ....
 sect-2 section.
      para-2.
      ....

RM/COBOL will resolve the reference to para-2 in the PERFORM statement by using the declaration of para-2 in the sect-1 SECTION. In Visual COBOL, however, you must qualify the reference to the duplicate paragraph-name in your source code by using the PERFORM para-2 OF sect-1 statement.

Parent topic: Producing Executable Code
Related reference
The PERFORM Statement


Empty Groups

In Visual COBOL, if you have any empty groups specified in your source code, you must set the RM Compiler directive.
Parent topic: Producing Executable Code
Related reference
RM


Figurative Constants and the USING Phrase

In Visual COBOL, to use figurative constants in the USING phrase of a CALL statement or as values of level 78 constants, set the 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
RM


File Not Found Errors

Visual COBOL and RM/COBOL differ in the environment variables that they use to locate program and data files.

If your source code produces a file not found error, ensure the correct paths are set in the correct environment variables. In Visual COBOL, set COBPATH to locate program files and COBDATA to locate data files. The RUNPATH environment variable used in RM/COBOL, is not used in Visual COBOL.

Parent topic: Producing Executable Code
Related reference
Environment Variables


Indexed File Error on Open

Visual COBOL and RM/COBOL differ in how they handle record length fields and some data fields when you open an RM/COBOL indexed file.

In Visual COBOL, when you try to open an RM/COBOL indexed file, you may receive either a run-time error COBRT161 Illegal intermediate code or a file status code 39 A conflict has been detected between the fixed file attributes and the attributes specified for that file in the program.

You must ensure that you read in the same size records that were created in RM/COBOL.

In Visual Studio, hover over the level 01 item of the file description to display the length of the record.

If the length of the file description does not match that which was processed in RM/COBOL, check the following:

  • In RM/COBOL, you can set the RECORD CONTAINS nn CHARACTERS clause to be a different length than the actual length specified in the record description. If this clause is greater than the actual description, you must pad the record description with filler bytes to match the RECORD CONTAINS clause.
  • If you have signed numeric display data in your file, Visual COBOL will treat the sign as a separate byte if you are using the RM directive without "ANSI" specified. If these fields are stored as sign internal, you must use RM"ANSI" or do not use the RM directive at all.
Parent topic: Producing Executable Code
Related reference
COBRT161 Illegal intermediate code (Fatal)
RM/COBOL File Status Codes


Linkage Section in Main Program

Visual COBOL and RM/COBOL differ in their ability to reference the Linkage Section items in the main program.

In RM/COBOL, if the main program has a Linkage Section, it is initialized by the parameter passed on the command line. In Visual COBOL, it is illegal to reference Linkage Section items in the main program.

Use the following root program to pass the command line and its length to your main program:

 identification division.
 program-id.     root.
 environment division.
 configuration section.
 source-computer. cobol2.
 working-storage section.
 01  main-linkage.
     03  cmd-length                  pic 9(4) binary value 0.
     03  cmd-line                    pic x(100).
 procedure division.
 accept cmd-line from command-line.
 if cmd-line not = spaces
     inspect cmd-line tallying cmd-length for
     characters before initial space
 end-if
 call "main" using main-linkage.
 exit program.
Parent topic: Producing Executable Code
Related reference
Linkage Section


Library Routines

To use the RM/COBOL standard library routines that are available in Visual COBOL, you must set the DIALECT(RM) Compiler directive.
Note: These routines are supported for native COBOL only.
  • C$Century
  • C$ConvertAnsiToOem
  • C$ConvertOemToAnsi
  • C$DARG (only partially supported)
  • C$Delay
  • C$GetEnv
  • C$GetNativeCharset
  • C$LogicalAnd
  • C$LogicalComplement
  • C$LogicalOr
  • C$LogicalShiftLeft
  • C$LogicalShiftRight
  • C$LogicalXor
  • C$NARG
  • C$SetEnv
  • C$RERR
  • DELETE
  • RENAME

For more information on each library routine, see RM/COBOL Library Routines in the product Help.

Parent topic: Producing Executable Code
Related reference
RM/COBOL Library Routines


Nested OCCURS DEPENDING Clauses

In Visual COBOL, if you are using nested OCCURS DEPENDING clauses, you must set the ODOSLIDE Compiler directive.
Parent topic: Producing Executable Code
Related reference
The OCCURS Clause
ODOSLIDE


Numbering of Segments

Visual COBOL and RM/COBOL differ in the number of segments that they permit you to specify.

In Visual COBOL, you can only specify segment numbers in the range 0 to 99 inclusive, which conforms to segment number limit specified in the ANS X3.23-1985 COBOL standard. In RM/COBOL, you can specify segment numbers greater than 99.

If your source code has segment numbers greater than 99, recode the program. Make sure that any new segment numbers you allocate do not clash with an already existing segment number. Segment numbers between 0 and 49 inclusive are used by Visual COBOL to indicate fixed portions of your object program, while segment numbers 50 to 99 inclusive indicate independent segments.

For details on the use of segmentation and segment numbers in your source programs, see COBOL Language Reference in the product Help.

Parent topic: Producing Executable Code


Program Identification and Data Names

In Visual COBOL, ensure that the Program-ID name does not share the same name as any data items in the program.

In Visual COBOL, you cannot use the same name for the Program-ID and a data item in the program; each name should be unique. RM/COBOL permits the name of the Program-ID paragraph and a data item to share the same name.

Parent topic: Producing Executable Code
Related reference
The Program-ID Paragraph
Segmentation


REMARKS Paragraph

In Visual COBOL, if your program uses the REMARKS paragraph in the Identification Division, you must set the RM Compiler directive.

Alternatively, mark the paragraph as comment lines.

Parent topic: Producing Executable Code
Related reference
RM


Reserved Words

In Visual COBOL, setting certain Compiler directives (such as RM and ANS85) activates certain reserved words that you cannot use as names for your data items.

If you attempt to use a reserved word, you receive a COBCH0666 ("Reserved word used as data name or unknown data description qualifier") COBOL syntax error.

To continue to use the reserved word as a data name, you can:

  • Use the REMOVE Compiler directive, to unreserve that particular keyword.
  • Set the MFLEVEL Compiler directive to an appropriate level, to unreserve all keywords above that level.

    See Compiler Directives in the product Help.

Example

Your RM/COBOL source program may contain the following lines of code:

     ....
     03 sort   pic 99.
     ....
     move 1 to sort

If you submit this to Visual COBOL, you will receive an error because the SORT verb is reserved. However, if you specify the REMOVE"SORT" Compiler directive when you submit this source program, you will not receive the error.

Parent topic: Producing Executable Code
Related reference
COBCH0666 Reserved word used as data-name or unknown data description qualifier
REMOVE


SAME AS Clause Not Available When Defining Data Structures

Visual COBOL and RM/COBOL differ in the way that they allow you to reuse existing data structures.

In Visual COBOL, use the TYPEDEF clause to define your base data structure, and then use the USAGE clause to create data structures of the same type.

data division.
working-storage section.
01 atype is typedef.
   03 var1 pic x(10) value "brown".
   03 var2 pic x(10) value "blue".
   03 var3 pic x(10) value SPACE.
01 a1 usage atype.
procedure division.
display var2 of a1.

The result of the display statement is blue.

The SAME AS clause used in RM/COBOL is not supported in Visual COBOL.

Parent topic: Producing Executable Code
Related reference
The TYPEDEF Clause
The USAGE Clause


Source Code in Columns 73 to 80

Visual COBOL ignores any of the code in your source programs which lies within columns 73-80 inclusive.

Code in these columns could be the result of expanding TAB characters in your source program, instead of standard TAB stops. If your source program contains TAB stops, convert them to spaces.

Parent topic: Producing Executable Code


Undeclared Data Items in Clauses

In Visual COBOL, if the data item used in a clause (for example, the File Status clause) is not declared, you receive an error.

In Visual COBOL, you receive a COBCH0250 STATUS field data-name missing or illegal error if a data item used in the File Status clause is not declared in the Working-Storage section. In RM/COBOL, you do not have to declare the data item in Working Storage.

Parent topic: Producing Executable Code
Related reference
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


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.

  • ACCEPT Fields at the Edge of the Screen
    Visual COBOL and RM/COBOL differ in their alignment of numeric data items from an ACCEPT statement that would result in the data going beyond the right-hand edge of the screen.
  • COMPUTATIONAL-1 Data Items with a PICTURE other than S9(4)
    In Visual COBOL, a COMPUTATIONAL-1 data item is assumed to have a picture-string of S9(4). In some cases in RM/COBOL, this is not the case.
  • Display of Input Data in Concealed ACCEPT Fields
    Visual COBOL and RM/COBOL differ in the way that they treat data entered as part of an ACCEPT statement when the OFF and ECHO clauses are specified.
  • Embedded Control Sequences in DISPLAY Statements
    In Visual COBOL, you cannot embedded control sequences within data items that you want to be displayed.
  • End of File Notification
    After an unsuccessful READ on a sequential file, due to reaching the end of the file, Visual COBOL will indicate that there is still no next logical record if you attempt to read the file without closing and opening it again.
  • Environment Variables Used to Resolve File Names
    In Visual COBOL, you are unable to use environment variables to resolve a file name at run time if you are using RMFM, the RM/COBOL file handler.
  • Field Wrap-Around
    Visual COBOL and RM/COBOL differ when performing arithmetic operations on binary data items (that is, RM/COBOL COMPUTATIONAL-1 format items) which result in the value exceeding the capacity of the target data item and there is no ON SIZE ERROR clause specified.
  • File and Record Locking
    Certain versions of RM/COBOL contain some software errors in the way in which locks for files and records are handled. These errors do not occur in Visual COBOL.
  • Initialization of Working Storage
    Visual COBOL and RM/COBOL differ in the way that they initialize data items without values in Working Storage.
  • Numeric Fields Containing Illegal Characters When Using a DEPENDING ON Phrase of an OCCURS Clause
    In Visual COBOL, if you fail to initialize a numeric data item that is used in a DEPENDING ON phrase of an OCCURS clause appropriately, a COBRT163 Illegal character in numeric field error is displayed at run time.
  • ON SIZE ERROR Phrase
    Visual COBOL and RM/COBOL differ in their treatment of the ON SIZE ERROR condition.
  • Open EXTEND of Nonexistent File
    Visual COBOL when you have the RM Compiler directive set and RM/COBOL differ in the result of attempting to open a non-existent file for EXTEND.
  • Printer Output is Written to Disk
    By default, Visual COBOL writes all output intended for a printer to disk.
  • Redefinition of COMP or COMP6 Data Items
    Visual COBOL fully supports the size and capacity of RM/COBOL type COMPUTATIONAL and COMPUTATIONAL-6 data items when the RM Compiler directive is set. However, the internal representation of these data items in Visual COBOL and in RM/COBOL is not the same.
  • Screen Column Number Specification
    Visual COBOL and RM/COBOL differ in the number of screen columns you are able to specify.
  • Trailing Blanks in Line Sequential Files
    Visual COBOL and RM/COBOL differ in the way that they deal with trailing blanks from line sequential records before writing the record.
  • Undefined Results of MOVE and Arithmetic Operations
    Visual COBOL and RM/COBOL differ in the results of MOVE statements, arithmetic operations, and comparisons that involve numeric and alphanumeric data items.
  • Using the Correct Calling Convention
    The library routines provided for RM/COBOL compatibility use a different calling convention to the Visual COBOL library routines. Therefore, programs that contain both types of library routine must explicitly specify the appropriate calling convention for one type or the other.
Parent topic: RM/COBOL Conversion Issues


ACCEPT Fields at the Edge of the Screen

Visual COBOL and RM/COBOL differ in their alignment of numeric data items from an ACCEPT statement that would result in the data going beyond the right-hand edge of the screen.

If your program contains an ACCEPT statement for a numeric data item at a position on the screen where the definition of the numeric data item would cause the ACCEPT field to go beyond the right-hand edge of the screen, both COBOL systems will truncate the input value. In RM/COBOL, the input value will be aligned into the ACCEPT field as an alphanumeric field, whereas in Visual COBOL, the input value is aligned as a numeric field.

Change the definition of the relevant PICTURE clause from numeric to alphanumeric. Alternatively, change the PICTURE clause so that the field does not go beyond the edge of the screen.

Example

If your program contains the following statement:

ACCEPT data-item AT COLUMN NUMBER 75.

where data-item is a numeric data item defined as PIC 9(10), a value of 123456 entered into the ACCEPT field will be held under Visual COBOL as "0000123456". However, in RM/COBOL, the value in the ACCEPT field would be held as "1234560000". To allow Visual COBOL to emulate the RM/COBOL behavior, alter the definition of the data item in your program to PIC X(10) or PIC 9(6).

Parent topic: Running the Code
Related reference
The ACCEPT Statement


COMPUTATIONAL-1 Data Items with a PICTURE other than S9(4)

In Visual COBOL, a COMPUTATIONAL-1 data item is assumed to have a picture-string of S9(4). In some cases in RM/COBOL, this is not the case.

In Visual COBOL, a COMPUTATIONAL-1 data item is assumed to have a picture-string of S9(4). In RM/COBOL, when a COMP-1 item is used as the source of a MOVE statement to an alphanumeric item, the picture clause is preserved.

To produce the result you require, you must alter the definition of the target of the MOVE statement.

Example

The following source code causes TEST-RECORD to hold"99 " in RM/COBOL, but"0099" in Visual COBOL.

 01 test-record                pic x(4).
 01 comp-1-item                pic 99 comp-1.
 procedure division.
    ...

     move 99 to comp-1-item.
     move comp-1-item to test-record.

To overcome this problem, alter the definition of TEST-RECORD as shown below:

 01 test-record.
     03 test-numeric-field     pic 99.
     03 filler      pic xx.
 01 comp-1-item                pic 99 comp-1.
 procedure division.
     ...
    move 99 to comp-1-item.
    move comp-1-item to test-numeric-field.

This avoids moving the COMPUTATIONAL-1 data item directly to an alphanumeric field.

Parent topic: Running the Code
Related concepts
COMPUTATIONAL-1 (COMP-1) Data Types
COMPUTATIONAL (COMP) Data Types
COMP/COMPUTATIONAL Data
Related reference
COMPUTATIONAL-1, COMPUTATIONAL-2,FLOAT-SHORT and FLOAT-LONG Formats


Display of Input Data in Concealed ACCEPT Fields

Visual COBOL and RM/COBOL differ in the way that they treat data entered as part of an ACCEPT statement when the OFF and ECHO clauses are specified.

If you have specified OFF and ECHO clauses for the same ACCEPT statement in your program, RM/COBOL will conceal any data entered during input for that statement but on completion of input will display the data. Visual COBOL will not display the data for this ACCEPT statement once input has been completed.

If you want to display the data input for an ACCEPT statement with the OFF and ECHO clauses specified, you must add a DISPLAY statement after the ACCEPT statement.

Parent topic: Running the Code
Related reference
The ACCEPT Statement


Embedded Control Sequences in DISPLAY Statements

In Visual COBOL, you cannot embedded control sequences within data items that you want to be displayed.

Such characters are ignored at run time as they are hardware dependent.

Remove the control sequences from your source program and replace with the equivalent Micro Focus COBOL syntax; for example, use the syntax WITH UNDERLINE to replace <left-arrow>]4m.

Parent topic: Running the Code
Related reference
COBOL Language Reference


End of File Notification

After an unsuccessful READ on a sequential file, due to reaching the end of the file, Visual COBOL will indicate that there is still no next logical record if you attempt to read the file without closing and opening it again.

The first time you unsuccessfully try to READ a sequential file in either COBOL system because you have reached the end of the file, status key 1 in the FILE STATUS is set to 1 and status key 2 is set to 0. This indicates that there is no next logical record. If you try to READ the same file again, without it either having been previously closed and reopened, or it having been successfully started, Visual COBOL continues to indicate that there is no next logical record. However, if you try to READ the same file again under RM/COBOL, status key 1 is set to 9 and status key 2 is set to 6.

A solution to the different file statuses returned for the circumstances given above will depend on the way in which your source program is coded. We suggest that you include tests for the values 1 and 0 in status key 1 and 2 of the file status, respectively, at the same time as you test for the values 9 and 6 in these status keys.

Parent topic: Running the Code
Related reference
The READ Statement


Environment Variables Used to Resolve File Names

In Visual COBOL, you are unable to use environment variables to resolve a file name at run time if you are using RMFM, the RM/COBOL file handler.

To configure the RM/COBOL file handler, you must use the CALLFH(ACUFH) Compiler directive. When this is set, the value of an environment variable will not resolve any file names you have set.

Parent topic: Running the Code
Related reference
CALLFH


Field Wrap-Around

Visual COBOL and RM/COBOL differ when performing arithmetic operations on binary data items (that is, RM/COBOL COMPUTATIONAL-1 format items) which result in the value exceeding the capacity of the target data item and there is no ON SIZE ERROR clause specified.

If, when using binary data items (that is, RM/COBOL COMPUTATIONAL-1 format items) an arithmetic operation gives a value which exceeds the capacity of the data item, and there is no ON SIZE ERROR clause, Visual COBOL wraps-around the value of the item. However, in RM/COBOL, the data item is set to the limit of its capacity.

You should specify an ON SIZE ERROR clause to highlight such problems.

Example

In RM/COBOL, the following lines of code result in the value +32767 being stored in the data item, CALC-ITEM. However, Visual COBOL sets CALC-ITEM to -32768:

01 calc-item         pic s9(4)  comp-1.

 procedure division.
      ....
     move 32767 to calc-item.
     add 1 to calc-item.
Parent topic: Running the Code
Related concepts
COMPUTATIONAL-1 (COMP-1) Data Types


File and Record Locking

Certain versions of RM/COBOL contain some software errors in the way in which locks for files and records are handled. These errors do not occur in Visual COBOL.

The errors fixed when upgrading to Visual COBOL are:

  • Indexed files do not detect or acquire locks if they are opened for output. This is regardless of whether you specify the WITH LOCK phrase
  • Relative and sequential files cannot be locked exclusively
  • Files which are opened for input can detect record locks, although the RM/COBOL documentation states that they cannot. When the RM directive is set in Visual COBOL, record locks can still be detected by files opened for input
  • The first record in a sequential file opened for input-output is locked whenever any other record in that file is locked
Parent topic: Running the Code
Related reference
The OPEN Statement


Initialization of Working Storage

Visual COBOL and RM/COBOL differ in the way that they initialize data items without values in Working Storage.

Visual COBOL initializes all working storage items without VALUE clauses to SPACES .The RM/COBOL system initializes all working storage items to SPACES, unless you have placed numeric data items between data items with VALUE clauses.

If this feature causes you any problems, because your program relies on the initial value given to the system, add a VALUE clause with the appropriate value to your source program and resubmit it.

Example

The RM/COBOL system initializes the following group item to SPACES:

01 group-item.
     03 item-1     pic x.
     03 item-2     pic 99.
     03 item-3     pic x.

However, if item-1 and item-3 have value clauses associated with them, the RM/COBOL system initializes the second byte of item-2 to hexadecimal value 0 when item-2 is defined as USAGE COMP (signed or unsigned) or USAGE DISPLAY (unsigned only).

Parent topic: Running the Code
Related reference
The VALUE Clause


Numeric Fields Containing Illegal Characters When Using a DEPENDING ON Phrase of an OCCURS Clause

In Visual COBOL, if you fail to initialize a numeric data item that is used in a DEPENDING ON phrase of an OCCURS clause appropriately, a COBRT163 Illegal character in numeric field error is displayed at run time.

In Visual COBOL, if you fail to initialize a numeric data item that is used in a DEPENDING ON phrase of an OCCURS clause appropriately, a COBRT163 Illegal character in numeric field error is displayed at run time, because the data item is initialized to SPACES if no value is specified. In RM/COBOL, the data item is initialized to ZERO, and therefore, the error does not occur.

Parent topic: Running the Code
Related reference
COBRT163 Illegal character in numeric field (Fatal)
The OCCURS Clause


ON SIZE ERROR Phrase

Visual COBOL and RM/COBOL differ in their treatment of the ON SIZE ERROR condition.

In Visual COBOL, the ON SIZE ERROR condition exists when the value resulting from an arithmetic operation exceeds the capacity of the specified picture-string. In RM/COBOL, the ON SIZE ERROR condition exists when the value resulting from an arithmetic operation exceeds the capacity for the associated data item.

Ensure that the capacity of any data items in your source programs is specified by a picture-string; for example, COMPUTATIONAL-1 data items.

Parent topic: Running the Code
Related reference
The ON SIZE ERROR Phrase and NOT ON SIZE ERROR Phrase


Open EXTEND of Nonexistent File

Visual COBOL when you have the RM Compiler directive set and RM/COBOL differ in the result of attempting to open a non-existent file for EXTEND.

In Visual COBOL, because setting the RM Compiler directive sets the NOOPTIONAL-FILE Compiler directive, if you try to open a non-existent file for I-O or EXTEND the run-time system will give an error message. For I-O, RM/COBOL does the same. However, for EXTEND, RM/COBOL creates the file and opens it as if you had specified OUTPUT.

The following options are available:

  • Add the keyword OPTIONAL to the SELECT statement. This makes Visual COBOL create the file and open it for OUTPUT
  • Create the empty file before running your program
  • Specify the OPTIONAL-FILE Compiler directive. This makes Visual COBOL create the file and open it for OUTPUT. However, the behavior with files opened for I-O will now differ from RM/COBOL
Parent topic: Running the Code
Related reference
OPTIONAL-FILE


Printer Output is Written to Disk

By default, Visual COBOL writes all output intended for a printer to disk.
To send output to a physical printer, you must map the filename using the dd_LPT1 environment variable or, if your system supports the lp printer spooler, you should use:
dd_LPT1=">lp";export dd_LPT1
Parent topic: Running the Code
Related concepts
Filename Mapping


Redefinition of COMP or COMP6 Data Items

Visual COBOL fully supports the size and capacity of RM/COBOL type COMPUTATIONAL and COMPUTATIONAL-6 data items when the RM Compiler directive is set. However, the internal representation of these data items in Visual COBOL and in RM/COBOL is not the same.

Visual COBOL fully supports the size and capacity of RM/COBOL type COMPUTATIONAL and COMPUTATIONAL-6 data items when the RM Compiler directive is set. However, the internal representation of these data items in Visual COBOL and in RM/COBOL is not the same. See the chapter Compatibility with RM/COBOL in the product Help.

If this causes you problems, redefine these data items to take advantage of their internal format. MOVE the data items concerned to other data items which are not defined as COMPUTATIONAL or COMPUTATIONAL-6. Moving these data items converts the data automatically, overcoming any problems you might have.

Example

The following source code is coded to take advantage of the internal representation of COMPUTATIONAL-6 data items in RM/COBOL, and to analyze a date field:

 01 birthdate-1          pic 9(6) comp-6.
 01 birthdate-2 redefines birthdate-1.
     03 month-2         pic 99 comp-6.
     03 day-2           pic 99 comp-6.
     03 year-2          pic 99 comp-6.
     ....

 procedure division.
 start-up section.
 para-1.
     ....

     move 082462 to birthdate-1.
     ....

     if year-2 = 62
         display "records not available for 1962."

Amend your source program to use the DISPLAY format instead of redefining COMPUTATIONAL-6 data items, before submitting it to Visual COBOL:

 01 birthdate-1          pic 9(6) comp-6.
 01 birthdate-2 redefines birthdate-1.
     03 month-2         pic 99 comp-6.
     03 day-2           pic 99 comp-6.
     03 year-2          pic 99 comp-6.

 01 birthdate-1a         pic 9(6).
 01 birthdate-2a redefines birthdate-1a.
     03 month-2a        pic 99.
     03 day-2a          pic 99.
     03 year-2a         pic 99.
     ....

 procedure division.
 start-up section.
 para-1.
     ....

     move 082462 to birthdate-1.
     move birthdate-1 to birthdate-1a.
     ....

     if year-2a = 62
         display "records not available for 1962."
Parent topic: Running the Code
Related concepts
COMPUTATIONAL-6 (COMP-6) Data Types
COMP-6/COMPUTATIONAL-6 Data


Screen Column Number Specification

Visual COBOL and RM/COBOL differ in the number of screen columns you are able to specify.

Visual COBOL permits you to specify screen column numbers up to and including 999, but RM/COBOL permits you to specify column numbers greater than 999. If you try to run an RM/COBOL source program containing a column number greater than 999 in Visual COBOL, the column number is truncated so that only the last three digits are used. If truncation of the column number occurs for an item to be displayed on the screen, the position of that item on the screen in Visual COBOL will differ from its position in RM/COBOL.

Parent topic: Running the Code
Related reference
COBOL Language Reference


Trailing Blanks in Line Sequential Files

Visual COBOL and RM/COBOL differ in the way that they deal with trailing blanks from line sequential records before writing the record.

Visual COBOL always removes trailing blanks from line sequential records before writing the record. RM/COBOL removes trailing blanks from such records only if the FD entry contains 01 level records of different sizes. This will not cause you any problems when you run your converted RM/COBOL programs in Visual COBOL. However, you may receive errors at run time if any REWRITE operations on line sequential files change the length of the records.

Change the file organization to sequential, or move an alternative padding character (for example, LOW-VALUES) to the end of the record before it is written. This ensures that full-length records are written.

You also need to ensure that the T run-time switch is not set, as this might also change the size of the record. See Run-time Switches in the product Help.

Parent topic: Running the Code
Related reference
T run-time switch


Undefined Results of MOVE and Arithmetic Operations

Visual COBOL and RM/COBOL differ in the results of MOVE statements, arithmetic operations, and comparisons that involve numeric and alphanumeric data items.

You can overcome most of these incompatibilities by redefining the data items involved, or by recoding the comparisons. If you submit a program in Visual COBOL containing an alphanumeric to numeric data item MOVE statement, a warning message will be displayed indicating this.

Example

If you submit a source program containing the following data items and procedural statements, the specified test will fail at run time:

 01 numeric-field        pic 9(5).
 procedure division.
     move "abc" to numeric-field.
     if numeric-field = "00abc"
         ....

When the RM Compiler directive is set, Visual COBOL partially emulates the behavior of RM/COBOL for alphanumeric to numeric MOVEs by treating the numeric item as an alphanumeric item which is right justified. However, the above example will still fail because RM/COBOL treats the literal ABC as numeric, and places 00ABC in the numeric item. To make the statement run successfully in Visual COBOL, amend the test in the source program to:

     if numeric-field = " abc"

and resubmit the source program.

Parent topic: Running the Code
Related reference
The MOVE Statement
Arithmetic Operators


Using the Correct Calling Convention

The library routines provided for RM/COBOL compatibility use a different calling convention to the Visual COBOL library routines. Therefore, programs that contain both types of library routine must explicitly specify the appropriate calling convention for one type or the other.

To run the RM/COBOL library routines provided in Visual COBOL, you set the DIALECT(RM) Compiler directive, which sets the required calling convention. To run the Visual COBOL library routines, you use the standard COBOL calling convention.

If you have RM/COBOL compatible library routines and Visual COBOL library routines in the same program, do one of the following:

  • Set the DIALECT(RM) Compiler directive to enable the RM/COBOL library routines, then explicitly use the standard COBOL calling convention for the Visual COBOL library routines.
  • Explicitly use the 1024 calling convention for calls to the RM/COBOL compatible library routines if DIALECT(RM) is not set.
Parent topic: Running the Code


Compatibility Directives

This COBOL system provides compatibility with RM/COBOL V2.0 through the use of the following Compiler directives.

  • DIALECT
    Enables check-time and run-time behavior consistent with the specified dialect.
  • RM
    Specifies that words reserved in Ryan-McFarland COBOL V2.0 are to be regarded as reserved words, and changes the behavior of certain features to be compatible with that COBOL system.
Parent topic: Compatibility with RM/COBOL


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" DIALECT"ANS85"
This sets ALIGN to ALIGN"8", since this is the value set by the DIALECT"ANS85".
ALIGN"2" DIALECT"MF"
This also sets ALIGN to ALIGN"8", since the MF dialect sets the directives to their default values. For ALIGN, the defualt is ALIGN"8".
  • ANS85 DIALECT setting
  • BS2000 DIALECT setting
  • BS2000-OFFLOAD DIALECT setting
  • COB370, COB371 and COB372 DIALECT settings
  • 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: Compatibility Directives
Parent topic: Language Features - Dialect
Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Control - Directives Control
Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
AMODE
Language Features - Dialect


RM

Specifies that words reserved in Ryan-McFarland COBOL V2.0 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
See Comments.

Properties:

Default: | NORM (Dialect)
Phase: | Syntax check
$SET: | Initial

Dependencies:

RM sets COMP-6"1", SEQUENTIAL"LINE", NOTRUNC, OLDINDEX, NOOPTIONAL-FILE, RETRYLOCK and ALIGN"2" immediately.

RM"ANSI" sets COMP-6"1", SEQUENTIAL"RECORD", NOTRUNC, OLDINDEX, NOOPTIONAL-FILE, RETRYLOCK and ALIGN"2" immediately.

RM"NOBEEP" stops the beep from sounding when the RM"ANSI" directive is set and you use the ACCEPT statement.

NORM sets COMP-6"2", SEQUENTIAL"RECORD", TRUNC"ANSI", NOOLDINDEX, OPTIONAL-FILE, NORETRYLOCK and ALIGN"8" immediately.

Comments:

With the ANSI parameter these features behave as they do when a program is compiled in that COBOL system with the ANSI switch set.

Use the DIALECT"RM" Compiler directive for a fuller emulation of RM/COBOL behavior and to enable the RM/COBOL standard library routines compatible with Visual COBOL.

Parent topic: Compatibility Directives
Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List
Related concepts
REMARKS Paragraph
DISPLAY Data
Empty Groups
Figurative Constants and the USING Phrase
The RM Directive
Related information
DIALECT
COBOL Language Reference
Language Features - Dialect
Key to Compiler Directives


RM/COBOL Library Routines

A list of RM/COBOL standard library routines supported in this COBOL system.

The following RM/COBOL routines are available in this COBOL system.
Note: You must set the DIALECT"RM" Compiler directive to use these routines.
  • 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$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$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.
Parent topic: Compatibility with RM/COBOL
Related concepts
Library Routines


C$Century

Updates your COBOL programs to handle the year 2000 issue.
Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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 reference
DIALECT


C$ConvertAnsiToOem

Converts a buffer containing ANSI characters to a buffer containing the corresponding OEM characters.
Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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 reference
DIALECT


C$ConvertOemToAnsi

Converts a buffer containing OEM characters to a buffer containing the corresponding ANSI characters.
Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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 reference
DIALECT


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.

To use this routine, set the DIALECT"RM" Compiler directive.

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-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
DIALECT
The CALL Statement


C$Delay

Relinquishes the CPU for a length of time specified in seconds.
Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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 reference
DIALECT


C$GetEnv

Returns the value of an environment variable.
Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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 reference
DIALECT


C$GetNativeCharset

Retrieves information about the native character set in effect for the current run unit.
Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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 reference
DIALECT


C$LogicalAnd

Performs a bitwise logical AND operation on two or more non-numeric or numeric operands.
Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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 reference
DIALECT


C$LogicalComplement

Performs a bitwise logical One's Complement operation on a non-numeric or numeric operand.
Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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 reference
DIALECT


C$LogicalOr

Performs a bitwise logical OR operation on two or more non-numeric or numeric operands.
Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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 reference
DIALECT


C$LogicalXor

Performs a bitwise logical exclusive OR operation on two or more non-numeric or numeric operands.
Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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 reference
DIALECT


C$LogicalShiftLeft

Performs a logical shift left operation on a non-numeric or numeric operand.
Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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 reference
DIALECT


C$LogicalShiftRight

Performs a logical shift right operation on a non-numeric or numeric operand.
Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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 reference
DIALECT


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.

Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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
DIALECT
The CALL Statement


C$SetEnv

Sets or clears the value of an environment variable.
Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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 reference
DIALECT


C$RERR

Returns the expanded I/O completion status, based on an error code received at run-time.
Restriction: This routine is supported in native COBOL only.

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:

To use this routine, set acu_library=true in your COBCONFIG config file, and then set the environment variable CONVERTSTATUS=rmstat.

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.
Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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 reference
DIALECT


RENAME

Renames a file.
Restriction: This routine is supported in native COBOL only.

To use this routine, set the DIALECT"RM" Compiler directive.

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 reference
DIALECT


RM/COBOL File Handler

This COBOL system enables you to utilize RMFM, the RM/COBOL file handler.
  • Configuring the RM/COBOL File Handler
    To use an RM/COBOL data file in your source code, you can utilize an add-on in Vision (ACUCOBOL-GT's native indexed sequential file system) to use the RM/COBOL file handler. Alternatively, you can use a data migration tool to convert the data file to Micro Focus format.
  • Enabling CTF with the RM/COBOL File Handler
    Enable the Micro Focus Consolidated Tracing Facility (CTF) to trace activity with the RM/COBOL File Handler.
Parent topic: Compatibility with RM/COBOL


Configuring the RM/COBOL File Handler

To use an RM/COBOL data file in your source code, you can utilize an add-on in Vision (ACUCOBOL-GT's native indexed sequential file system) to use the RM/COBOL file handler. Alternatively, you can use a data migration tool to convert the data file to Micro Focus format.

The data migration tool, RMMFDataMigration.exe, which you can use to convert a data file to Micro Focus format, is available from the folder in which the product samples are installed.

To configure Visual COBOL to use an RM/COBOL data file without converting it:

  • Set the CALLFH(ACUFH) Compiler directive.
  • Set environment variable A_CONFIG to the path of an ACUCOBOL-GT configuration file:
    set A_CONFIG=acurmfm.cfg		*> acurmfm.cfg is your ACUCOBOL-GT configuration file.
  • In acurmfm.cfg, set the file handler:
    DEFAULT_FILESYSTEM RMFM
To retrieve RMFM file status codes or call C$RERR in your COBOL programs:
  • Set the following environment variables:
    set CONVERTSTATUS=rmstat
set COBCONFIG=cobconfig.cfg  *> cobconfig.cfg is your MF COBOL run-time configuration file.
  • In cobconfig.cfg, set the following:
    set ACU_LIBRARY=TRUE

Comments:

The following list contains a number of additional configurations that you can add to your ACUCOBOL-GT configuration file, that are supported in this COBOL system:

  • RMFM_DEFINE_DEVICE

  • RMFM_EXTERNAL_ACCESS_METHOD

  • RMFM_EXTERNAL_ACCESS_METHOD_RMPLUSDB_CREATE_FILES

  • RMFM_EXTERNAL_ACCESS_METHOD_RMPLUSDB_OPTIONS

  • RMFM_EXTERNAL_ACCESS_METHOD_RMINFOX_CREATE_FILES

  • RMFM_EXTERNAL_ACCESS_METHOD_RMINFOX_OPTIONS

  • RMFM_EXTERNAL_ACCESS_METHOD_USRRMTACC_CREATE_FILES

  • RMFM_EXTERNAL_ACCESS_METHOD_USRRMTACC_OPTIONS

  • RMFM_EXTERNAL_ACCESS_METHOD_RMBTRV_CREATE_FILES

  • RMFM_EXTERNAL_ACCESS_METHOD_RMBTRV_OPTIONS

  • RMFM_EXTERNAL_ACCESS_METHOD_RMBTRV32_CREATE_FILES

  • RMFM_EXTERNAL_ACCESS_METHOD_RMBTRV32_OPTIONS

  • RMFM_EXTERNAL_ACCESS_METHOD_RMTCP32_CREATE_FILES

  • RMFM_EXTERNAL_ACCESS_METHOD_RMTCP32_OPTIONS

  • RMFM_PRINT_ATTR_AUTO_LINE_FEED

  • RMFM_PRINT_ATTR_COLUMNS

  • RMFM_PRINT_ATTR_FORM_FEED_AVAILABLE

  • RMFM_PRINT_ATTR_LINAGE_INITIAL_FORM_POSITION

  • RMFM_PRINT_ATTR_LINAGE_PAGES_PER_PHYSICAL_PAGE

  • RMFM_PRINT_ATTR_LINES

  • RMFM_PRINT_ATTR_TOP_OF_FORM_AT_CLOSE

  • RMFM_PRINT_ATTR_WRAP_COLUMN

  • RMFM_PRINT_ATTR_WRAP_MODE

  • RMFM_RUN_FILES_ATTR_ALLOW_EXTENDED_CHARS_IN_FILENAME

  • RMFM_RUN_FILES_ATTR_BLOCK_SIZE

  • RMFM_RUN_FILES_ATTR_BUFFER_POOL_SIZE

  • RMFM_RUN_FILES_ATTR_DEFAULT_USE_PROCEDURE

  • RMFM_RUN_FILES_ATTR_DISABLE_LOCAL_ACCESS_METHOD

  • RMFM_RUN_FILES_ATTR_ENABLE_OLD_DOS_FILENAME_HANDLING

  • RMFM_RUN_FILES_ATTR_EXPANDED_PATH_SEARCH

  • RMFM_RUN_FILES_ATTR_FATAL_RECORD_LOCK_TIMEOUT

  • RMFM_RUN_FILES_ATTR_FILE_LOCK_LIMIT

  • RMFM_RUN_FILES_ATTR_FILE_PROCESS_COUNT

  • RMFM_RUN_FILES_ATTR_FORCE_USER_MODE

  • RMFM_RUN_FILES_ATTR_KEEP_FLOPPY_OPEN

  • RMFM_RUN_FILES_ATTR_LARGE_FILE_LOCK_LIMIT

  • RMFM_RUN_FILES_ATTR_RESOLVE_LEADING_NAME

  • RMFM_RUN_FILES_ATTR_RESOLVE_SUBSEQUENT_NAMES

  • RMFM_RUN_FILES_ATTR_SKIP_INITIAL_CWD_SEARCH

  • RMFM_RUN_FILES_ATTR_USE_PROCEDURE_RECORD_LOCK_TIMEOUT

  • RMFM_RUN_INDEX_FILES_ALLOCATION_INCREMENT

  • RMFM_RUN_INDEX_FILES_BLOCK_SIZE

  • RMFM_RUN_INDEX_FILES_DATA_COMPRESSION

  • RMFM_RUN_INDEX_FILES_DEFAULT_FILE_VERSION_NUMBER

  • RMFM_RUN_INDEX_FILES_ENABLE_ATOMIC_IO

  • RMFM_RUN_INDEX_FILES_FORCE_CLOSED

  • RMFM_RUN_INDEX_FILES_FORCE_DATA

  • RMFM_RUN_INDEX_FILES_FORCE_DISK

  • RMFM_RUN_INDEX_FILES_FORCE_INDEX

  • RMFM_RUN_INDEX_FILES_KEY_COMPRESSION

  • RMFM_RUN_INDEX_FILES_MINIMUM_BLOCK_SIZE

  • RMF_RUN_INDEX_FILES_PREVENT_WRITE_STARVATION

  • RMFM_RUN_INDEX_FILES_ROUND_TO_NICE_BLOCK_SIZE

  • RMFM_RUN_INDEX_FILES_USE_LARGE_FILE_LOCK_LIMIT

  • RMFM_RUN_REL_FILES_BLOCK_SIZE

  • RMFM_RUN_REL_FILES_USE_LARGE_FILE_LOCK_LIMIT

  • RMFM_RUN_SEQ_FILES_BLOCK_SIZE

  • RMFM_RUN_SEQ_FILES_DEFAULT_TYPE

  • RMFM_RUN_SEQ_FILES_DEVICE_SLEWING_RESERVE

  • RMFM_RUN_SEQ_FILES_TAB_STOPS

  • RMFM_RUN_SEQ_FILES_USE_LARGE_FILE_LOCK_LIMIT

Refer to the RM/COBOL User's Guide for full details of these configurations.

Parent topic: RM/COBOL File Handler
Related reference
CALLFH


Enabling CTF with the RM/COBOL File Handler

Enable the Micro Focus Consolidated Tracing Facility (CTF) to trace activity with the RM/COBOL File Handler.

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

  • In acurmfm.cfg, set the following:

    *> acurmfm.cfg is your ACUCOBOL-GT configuration file.
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 File Handler.

For more information on CTF, see Introduction to the Consolidated Tracing Facility.

Parent topic: RM/COBOL File Handler
Related concepts
Introduction to the Consolidated Tracing Facility


Compatibility with XML Extensions

Note: This functionality is supported in native COBOL only.

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 RM/COBOL product documentation set, in 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.
  • 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			*> The size of the data item pointed to by MY-DOCUMENT-POINTER.
    "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


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

When attempting to import or export an ambiguous model data-name, this COBOL system now displays a warning.

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

XML Extensions uses a different calling convention to the one used by the standard library routines implemented for RM/COBOL compatibility.

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:

If you set the DIALECT"RM" Compiler directive, the correct calling convention will be enabled for all entry points and CALL statements, for use of the standard library routines. If this is set, you must explicitly use the standard COBOL calling convention for your XML Extensions calls.

If you do not set the DIALECT"RM" Compiler directive, the correct calling convention will be enabled for all entry points and CALL statements, for use of XML Extensions. If this is not set, you must explicitly use the 1024 calling convention for the standard library routine calls.

Parent topic: Compatibility with XML Extensions


Modernizing Dialog System Applications

  • Overview of Modernizing Dialog System Applications
    The Dialog System AddPack enables you to modernize Dialog System applications within Visual COBOL for Visual Studio 2010 and to run them under COBOL Server.
  • Dialog System AddPack Information and Restrictions
    The Dialog System AddPack comprises the Dialog System run-time components, with a subset of the development components.
  • Migrating a Dialog System Application to Visual COBOL
    To migrate an application, you start by using the Import wizard to convert a Net Express project into aVisual COBOL solution. When you have migrated a Dialog System application into Visual COBOL, you can update and maintain it from Visual COBOL.
  • Modernizing a Dialog System Application
    When you are ready to modernize the application, you can do so gradually, using the interoperability techniques to keep the old and new code (the native and managed code) working together.
  • Samples of Modernizing Dialog System Applications
    Several samples are supplied that demonstrate different techniques for modernizing Dialog System applications.
Parent topic: Compatibility
Parent topic: User Interface Programming


Overview of Modernizing Dialog System Applications

The Dialog System AddPack enables you to modernize Dialog System applications within Visual COBOL for Visual Studio 2010 and to run them under COBOL Server.

The Dialog System AddPack enables you to modernize Dialog System applications within Visual COBOL for Visual Studio 2010. You upgrade an application to Visual COBOL and from there, you can run the application without change, or modernize it over time. The application runs under the COBOL Server and the Dialog System run-time system.

The first stage is to import the application into Visual COBOL, and there is an import wizard to help. You can then build and run the application from Visual COBOL.

From then on, you can edit and maintain the application from within Visual COBOL. The screensets are referenced in the Visual COBOL project, and you can double-click a screenset to start Dialog System and edit the screenset. In this way, you can continue maintaining your application with Visual COBOL until you are ready to modernize it.

The next stage is to modernize the application gradually, as much or as little as you want, keeping other code unchanged. There is a range of techniques for modernization. For example, you can replace one Dialog System screen with a Windows Form or you can wrap a .NET user control as an ActiveX and use that in Dialog System.

The AddPack provides a number of samples to demonstrate the various modernization techniques, and there is supporting documentation in this Help explaining the significant elements of the code. Some samples use the same code as in Net Express, and have the key difference that they use the Visual COBOL version of the COBOL and Dialog System run-time systems.

Finally, to fully modernize, you use Microsoft tooling, the .NET Framework and Microsoft interoperability techniques.

Note: The Dialog System AddPack is not part of Visual COBOL or COBOL Server. It is separately installable and available from Micro Focus SupportLine
Parent topic: Modernizing Dialog System Applications


Dialog System AddPack Information and Restrictions

The Dialog System AddPack comprises the Dialog System run-time components, with a subset of the development components.

The Dialog System AddPack comprises the Dialog System run-time components, with a subset of the development components. The AddPack comprises:

  • Dialog System run-time system and run-time components.
  • Panels V2.
  • GUI class library and OLE class library. These libraries are needed if you migrate an existing Dialog System application that was extended using those libraries.

    Projects for building the GUI and OLE class libraries from source are also supplied. Additionally, a project file for the Base class library is supplied in Visual COBOL 2.0.

  • Visual Studio plug-in to associate screensets in Visual Studio with Dialog System. When you double-click a screenset in Solution Explorer in Visual COBOL, Dialog System starts.
  • Sample applications demonstrating a range of modernization techniques.
  • Supporting documentation in this Help explaining the significant elements of the sample code.

Prerequisites and Requirements

The Dialog System AddPack requires the following software:

  • Either Enterprise Developer or Visual COBOL 2.0 for Visual Studio 2010. This provides full support for developing and running applications.

    Alternatively, since the AddPack contains the Dialog System run-time components, you can run Dialog System applications (not develop them) if you have Enterprise Server or COBOL Server installed.

  • Net Express (which includes Dialog System) for editing the Dialog System screensets

Restrictions and Limitations

The following restrictions apply to the Dialog System AddPack:

  • Several Dialog System extensions are not supported, such as DSGRAPH, DSDDE, DSPLAYER and DSONLINE.
  • Screenset script animation is not supported.
  • To make changes to a screenset, you continue to use the Dialog System painter.
  • Only x86 projects are supported, because there is no 64-bit support for Dialog System.
  • Unlike in Net Express, debuggable versions of the class libraries are not installed automatically (and there is no debugger switch to enable use of the debug versions as there is in Net Express). Instead, you need to build the libraries yourself. See Debuggable OO Class Libraries in the topic Migrating a Dialog System Application to Visual COBOL.
  • Migrating an existing Dialog System application to the .NET Framework might require significant changes to the application because some objects, such as ActiveX controls and the GUI class library, are not portable to .NET.
Parent topic: Modernizing Dialog System Applications
Related information
Migrating a Dialog System Application to Visual COBOL


Migrating a Dialog System Application to Visual COBOL

To migrate an application, you start by using the Import wizard to convert a Net Express project into aVisual COBOL solution. When you have migrated a Dialog System application into Visual COBOL, you can update and maintain it from Visual COBOL.

You can use the Net Express Project Import wizard to convert a Net Express project into aVisual COBOL solution, or alternatively you can create a solution manually.

There is one Dialog System specific item that is added to the project and that is the screenset, the .gs file. The wizard sets the following properties on the screenset file and you need to do the same if you create the project manually:

  • Copy to Output Directory is set to Copy if newer. This ensures that the screenset is added to the output directory whenever the screenset is changed.
  • Build Action is set to Content. This ensures that the screenset is not compiled and consequently doesn't create spurious warnings or errors.

When the Dialog System application is in Visual COBOL, you can continue to maintain and run it with Visual COBOL, as shown here:

In Visual COBOL, you can:

  • Open the screenset, by double-clicking the .gs file in Solution Explorer. This starts Dialog System with the screenset open, ready for you to edit.
  • Edit a .cbl file by double-click it in Solution Explorer.
  • Build and debug the application. Although debugging COBOL is supported, the screenset animator is not supported.
  • Run the application.

Debuggable OO Class Libraries

If your application uses the native OO COBOL class libraries, and you want to step into those libraries when debugging, you need to build debuggable versions of them. This is different from Net Express, where the libraries were supplied and you could select them from the IDE. To build and use debuggable versions of the libraries:
  1. Open the project for the required class library. The projects are located in the cpylib folder of your installation, which is by default %ProgramFiles%\Micro Focus\Visual COBOL. The class library projects are:
    • GUI class library - guicl\apiguim.cblproj
    • OLE class library - olecl\olecl.cblproj
    • Base class library - basecl\baseclm.cblproj
  2. Ensure the Debug configuration is selected and then build the project. The resulting output is stored in the debug subfolder of the project folder.
  3. In your application, set the COBPATH environment variable to point to the folder containing the debuggable version of the library. To do this, add the variable to the application.config file, as follows:
    1. Open your application in Visual COBOL.
    2. Right-click your main project and click Add > New Item > Application Configuration File.
    3. Double-click Application.config in Solution Explorer.
    4. In the Name field, specify COBPATH.
    5. In the Value field, specify the full path of the folder. For example, %ProgramFiles%\Micro Focus\Visual COBOL\cpylib\guicl\debug.
    6. Click Set.
Note: The Help for the class libraries is available in the file nxrclr.chm, which is installed in the Help folder of your installation. The default location is %ProgramFiles%\Micro Focus\Visual COBOL\Help.
Parent topic: Modernizing Dialog System Applications


Modernizing a Dialog System Application

When you are ready to modernize the application, you can do so gradually, using the interoperability techniques to keep the old and new code (the native and managed code) working together.

Modernize Dialog System applications by migrating them to Visual COBOL When you are ready to modernize the application, you can choose from a range of techniques. You have the flexibility to modernize as much or as little as you want in your own time. For example, you can replace one Dialog System dialog with a Windows Form or you can wrap a .NET WPF control as an ActiveX control and use that on a Dialog System dialog.

There are distinct advantages to modernizing gradually and using the interoperability techniques to keep the old and new code working together. Microsoft's recommendation is:

"The COM interoperability features of the .NET Framework are very powerful and, in nearly all cases, allow you to continue to use your existing code without migrating it to managed code. As you develop new parts of your application or reuse components of your application from newer managed code applications, in most cases you can simply call your existing components through the COM interoperability functionality provided by .NET."

There are a range of modernization techniques and a multitude of ways to adopt them. The technique to use depends on the application. You first need to understand the application, what it does, how it's structured, how it performs, and its limitations and benefits. You can then identify an area where you can improve things.

Some modernization techniques that you can use are:

  • A Windows Forms form replacing a Dialog System dialog, where the form can contain .NET controls. See the Customer + .NET WinForm sample CustomerWinForm.sln.
  • A Windows Forms control wrapped as an ActiveX control and used on a Dialog System dialog. See the Customer + .NET GridView User Control sample custgrid.sln.
  • A WPF user control hosted by a Windows Forms user control, which is then exposed as ActiveX ready for use by Dialog System. See the Customer + .NET WPF GridView User Control sample CustGridWPF.sln
  • A .NET managed code application interacting with Dialog System as native COBOL .dll or as . See the Managed Customer sample ManagedCustomer.sln.

Your Visual COBOL solution is likely to have some native code projects and some managed code projects. The native code projects will contain the original code, largely unchanged, and also the managed code projects will contain the new modernized elements.

Note: It is not possible to debug both native and managed COBOL in the same session. You can debug them separately by setting the project you want to debug as the StartUp project. To do this, right-click your project, and click Set as StartUp project.
Parent topic: Modernizing Dialog System Applications


Samples of Modernizing Dialog System Applications

Several samples are supplied that demonstrate different techniques for modernizing Dialog System applications.

You can access the samples from Start > All Programs > Micro Focus Visual COBOL > Samples. Then click Dialog System to list the available samples.

Some samples, Calc, Customer and SplitWindow, use the same code as they did in Net Express. They run the same as before, except the key difference is that they use the Visual COBOL version of the COBOL and Dialog System run-time systems.

  • Sample: Windows Forms Replacing Dialog System Dialogs
    The Customer + .NET WinForm sample CustomerWinForm.sln takes the original Customer sample from Dialog System and replaces the Orders dialog with a more modern .NET Windows Forms version.
  • Sample: Windows Forms Control as ActiveX for a Dialog System Application
    The Customer + .NET GridView User Control sample custgrid.sln shows a Windows Forms usercontrol wrapped as an ActiveX control and used by Dialog System.
  • Sample: WPF User Control in a Dialog System Application
    The Customer + .NET WPF GridView User Control sample CustGridWPF.sln shows a WPF user control hosted by a Windows Forms user control, which is then exposed as ActiveX ready for use by the Dialog System application.
  • Sample: Managed Dialog System Application
    The Managed Customer sample ManagedCustomer.sln is broadly the original Customer sample that was supplied with Dialog System. The key difference with this sample is that it is compiled to managed code and run under .NET.
  • Sample: Managed Application and Windows Forms
    The Managed Customer + .NET WinForm sample ManagedCustomerWinForm.sln puts together the Managed Customer sample and the .NET Order Forms dialog that is used in the Customer + WinForm sample. These two together form a sample where all the COBOL is compiled to .NET and the Dialog System user interface remains in native code.
Parent topic: Modernizing Dialog System Applications


Sample: Windows Forms Replacing Dialog System Dialogs

The Customer + .NET WinForm sample CustomerWinForm.sln takes the original Customer sample from Dialog System and replaces the Orders dialog with a more modern .NET Windows Forms version.

The Customer + .NET WinForm sample CustomerWinForm.sln takes the original Customer sample from Dialog System and replaces the Orders dialog with a more modern Windows Forms Orders form. The main Customer application remains largely unchanged, so that the application becomes a native code main program calling managed code as a COM object to handle the Windows Forms Orders form.

The following diagram shows the native code on the left, with Dialog System handling the screenset. The managed code is on the right, with the new Windows Forms form. The image also shows the native code interfacing with a COM Callable Wrapper (CCW) containing the managed code, and shows the data block being passed and returned.

The numbers in the above diagram highlight some key points in the process and are explained below:

  1. The native COBOL application calls Dialog System in the traditional way.
  2. Instead of calling the now redundant dialog, the dialog returns control to the application, using RETC.
  3. The native COBOL invokes the managed code interface, IFormsFactory, using standard native OO COBOL syntax.

    A copy of the data block is created for the managed classes to use.

    An entry point is created in the native code, ready for calling back from the managed code.

  4. The managed code library, OrderFormsLibrary is registered for COM Interop. This ensures that a COM Callable Wrapper (CCW) is created, which provides an interface for the native code to use.
  5. The managed code class, FormsFactory, instantiates and displays the form, as a modal dialog, handling the events as needed.
  6. The managed code calls back to the entry point previously created in the native COBOL, passing back a pointer to the updated data block.

Customer Project in Native COBOL

The solution has two projects: one native and one managed. The native project, Customer, contains the original sources with some changes to handle the Orders dialog differently and to interact with the managed code project.

The native project, Customer, contains:

  • Properties - these define how the project is built. For example, it is built as a Windows application called Customer, stored in .\bin\x86\Debug.
  • Customer.cbl - original source code, plus some additional code to interact with the managed COBOL project, which handles the new Windows Forms Orders form.
  • Customer.cpb - original unchanged copybook generated from the Dialog System data block.
  • Customer.gs - original screenset, which now handles the Orders button by returning control to the customer.cbl, rather than displaying the Orders dialog
  • Cust.ism - the original unchanged data file.

To debug the native project, make sure the Customer project is set as the startup project. To do this, right-click the project and click Set as StartUp Project.

OrderFormsLibrary Project in Managed COBOL

The managed project, OrderFormsLibrary, contains the new Windows Forms Orders form. It also contains the supporting code to pass the customer data block between managed and native code. It is registered and exposed as a COM object.

The managed project, OrderFormsLibrary, contains:

  • Properties - these define how the project is built. Notice that the project is registered as a COM object, thereby exposing it as a COM object and enabling the native project to access it. See Project > Properties > COBOL > Advanced.
  • References - all the required .NET classes.
  • Calendar.cbl - implements a calendar editor column for use in the data grid.
  • Link to Customer.cpb - the same copybook is used and understood by the native and managed COBOL projects. The copybook itself remains in the native project and a link to it is now added in the managed project.
  • FormsFactory.cbl - implements the CreateOrderForm() method and creates a delegate for the callback function, which is used to get hold of the customer data block.
  • IFormsFactory.cbl - defines the CreateOrderForm() method, which provides the entry point into managed code from native code.
  • OrderForm.cbl [Design] - this is the order form, drawn with the designer.
  • OrderForm.cbl [Code] - this contains the code to handle the form and you can edit this and add your own code.

To debug the managed project, make sure the OrderFormsLibrary project is set as the startup project.

Customer.cbl in Native COBOL

Customer.cbl, contains the original code for the business logic and for interaction with the Dialog System screenset. Customer.cbl also contains some additional code to interact with the managed COBOL project and to display the Windows Forms Order form. Customer.cbl contains additional code to do the following:

  1. Set the following Compiler directives, using $SET:

      $SET ans85 mfoo ooctrl(+P) case
    • ANS85 remains set as before
    • MFOO enables support for the Micro Focus native OO syntax
    • OOCTRL(+P) enables the run-time system to map COBOL data types to COM data types
    • CASE prevents external symbols (such as Program-ID and names of called programs) being converted to upper case

  2. Map the COM class, OrderFormsLibrary.FormsFactory, to an OO COBOL class name, OrderFormFact , in the CLASS-CONTROL paragraph, where the class is in the COM domain, $OLE$, of the Micro Focus native OO class library:

      class-control.
  OrderFormFact is class"$OLE$OrderFormsLibrary.FormsFactory".

  3. Evaluate the flag to determine if the Orders button has been pressed and respond accordingly:

      WHEN customer-orders-flg-true
  PERFORM Show-Orders-Form

  4. Create an instance of the COM object, the new .NET order forms library, which implements a Windows Forms version of the Orders dialog that originally existed in customer.gs:

      invoke OrderFormFact "New" Returning formsLibrary

  5. Set a procedure pointer that the managed code can use to call the native code:

      set  pptr  to  entry  "Customer_Callback"

  6. Get a pointer to the data block, to be used in the callback:

      Customer-Callback SECTION.
      entry "Customer_Callback" stdcall.
      exit program returning address of CUSTOMER-DATA-BLOCK.

  7. Invoke and display the new Orders form:

      invoke formsLibrary "CreateOrderForm" using
      by value pptr-val

Customer.GS, the Dialog System Screenset

The screenset, customer.gs no longer displays the original Orders dialog, but instead it passes control back to the native COBOL program. The instructions for the Orders button in the Main-Window dialog have changed as follows:

  SET-FLAG ORDERS-FLG(1)
  RETC
  * REFRESH-OBJECT DIALOG-BOX
  * SET-FOCUS DIALOG-BOX

The instructions now set the ORDERS-FLG to indicate that the Orders button has been pressed, so that the native COBOL program can evaluate the flag and respond appropriately. Control is returned to the native COBOL program. The redundant lines are commented out, so that the old Orders dialog is no longer displayed.

IFormsFactory.cbl in Managed COBOL

IFormsFactory.cbl defines an interface to create a Windows Forms Order form. IFormsFactory.cbl has code to do the following:

  1. Declare the interface using the InteropServices classes from the .NET Framework. In addition, establish the COM object support for late binding, by specifying ComInterfaceType:: InterfaceIsDual. Alternatively, you could specify ComInterfaceType::InterfaceIsIDispatch (but not ComInterfaceType::InterfaceIsIUnknown):

      interface-id OrderFormsLibrary.IFormsFactory
      attribute System.Runtime.InteropServices.InterfaceType
        (type
        System.Runtime.InteropServices.ComInterfaceType::InterfaceIsDual)

    Note, the 'Register For COM Interop' property exposes everything as a dual interface, by default.

  2. Define the CreateOrderForm() method. This is the definition of the entry point into managed code from native code:

      method-id CreateOrderForm.
  procedure division using by value callback as binary-long.
  end method.

FormsFactory.cbl in Managed COBOL

FormsFactory.cbl creates an instance of the Orders form, when the native program asks for it. FormsFactory.cbl has code to do the following:

  1. Declare the class, which implements the IFormsFactory interface:

      class-id OrderFormsLibrary.FormsFactory implements
      type OrderFormsLibrary.IFormsFactory.

  2. Expose the class to COM, by making it visible:

      attribute ComVisible(true)

  3. Specify our interface IFormsFactory as the default interface to expose to COM:

      attribute ComDefaultInterface
      (type of OrderFormsLibrary.IFormsFactory)
  4. Set the ComVisible attribute off by default at the assembly level. This means the types we expose must be explicitly marked as ComVisible(true), which gives us a more well-defined type library for clients to use:
      assembly-attributes.
  attribute ComVisible(false).

  5. Get a delegate for the callback function and use it to get hold of the customer data block. The GetDelegateForFunctionPointer() converts an unmanaged function pointer to a delegate:

      set  pptr to new System.IntPtr(callback)
  set  custCallback to type
      System.Runtime.InteropServices.Marshal::GetDelegateForFunctionPointer
      (pptr, type of CustomerCallback)
      as type  CustomerCallback

  6. Declare the delegate for the callback function:

      delegate-id CustomerCallback.
  procedure division returning pCustomerDataBlock as type IntPtr.
  end delegate.

  7. Create the Orders form and show it as a modal dialog box:

      set form to new OrderFormsLibrary.OrderForm(custCallback)
  invoke form::ShowDialog()

OrderForm.cbl [Design] in Managed COBOL

The order form is drawn with the form designer. See the Windows Forms tutorials.

OrderForm.cbl [Code] in Managed COBOL

OrderForm.cbl [Code] is a partial class, also called OrderFormsLibrary.OrderForm and this contains the code to handle the Windows Forms Orders form.

OrderForm.cbl [Code] has the following methods:

New()

Call back to native code to retrieve customer data block. We store the pointer in _pCustomerDataBlock.:

  set  _pCustomerDataBlock  to  callback::Invoke()
OrderForm_Load()

Unpack the data block to a copy in local storage, which can then be accessed in the same way as in native code. The Marshal::Copy() method copies the pointer _pCustomerDataBlock into pData:

  invoke type Marshal::Copy
  (_pCustomerDataBlock, pData, 0, length  of  CUSTOMER-DATA-BLOCK)
  set CUSTOMER-DATA-BLOCK to pData
PopulateOrder()

Initialize the Orders form using the orders information in the CUSTOMER-DATA-BLOCK, with a PERFORM block and statements such as:

  perform varying row thru OrdersGridView::Rows
  move CUSTOMER-ORD-NO(array-ind) to
      row::Cells::get_Item("OrderNo")::Value
  move CUSTOMER-ORD-DATE(array-ind) to dt1
  ...
OrderForm_FormClosing()

Handle the form closing event and move the locally held Dialog System data block back to the caller. The Marshal::Copy() method copies the pointer pData into _pCustomerDataBlock:

  set pData to CUSTOMER-DATA-BLOCK
  invoke type Marshal::Copy
  (pData, 0, _pCustomerDataBlock, LENGTH OF CUSTOMER-DATA-BLOCK)
OK_Click()

Handle the OK button click event.

Delete_Click()

Handle the Delete button click event.

OrderForm.Designer.cbl in Managed COBOL

This is the code behind the Windows Forms that defines the form and is generated from the design. See the Windows Forms tutorials.

Parent topic: Samples of Modernizing Dialog System Applications


Sample: Windows Forms Control as ActiveX for a Dialog System Application

The Customer + .NET GridView User Control sample custgrid.sln shows a Windows Forms usercontrol wrapped as an ActiveX control and used by Dialog System.

The Customer + .NET GridView User Control sample shows a Windows Forms user control wrapped as an ActiveX control. Since Dialog System can host ActiveX controls, the new Windows Forms user control is built to be exposed as an ActiveX control. The sample shows how a user control can be hosted, how it can have methods invoked and how it can fire events, which can be consumed in the Dialog System application.

The sample is based on the original CustGrid sample from Dialog System. It has two projects: one is the original CustGrid sample and the second contains the code for a simple Windows Forms DataGridView user control written in COBOL. The DataGridView control is similar to the one used in the Customer samples (Customer +.NET WPF User Control and Customer + WinForm). Here, in this sample, the DataGridView is a .NET user control instead of a WPF user control or a control contained in Windows Forms.

The following diagram shows the native code on the left, with Dialog System handling the screenset. The managed code is on the right, with the Windows Forms user control wrapped as an ActiveX. The image also shows the native code interfacing with a COM Callable Wrapper (CCW) containing the managed code.

Note:

In this sample, the control is not a complete implementation of a grid control and the application is not a complete implementation. The sample is designed to illustrate the principles only.

CustGrid Project

The CustGrid project contains the original CustGrid project from Dialog System and contains:

  • CustGrid.gs is the screenset, which now contains the DataGridView control instead of the original ActiveX grid control. In the same way as before, Dialog System communicates with the native code gridctrl.cbl, using callouts and callbacks.
  • GridCtrl.cbl handles the events generated by the DataGridView control. It invokes the COM code in the same way that it invoked the ActiveX code before. For example, the Delete-A-Row Section handles the delete-row event and invokes the COM code, as follows:
      INVOKE  RowSet  "GetSelect"  USING  theRow  RETURNING  Numeric-Value
  INVOKE  RowSet  "Remove"  USING  Numeric-Value

    Where RowSet is defined in the COM interface for the Windows Forms user control. See the ControlInterface.cbl section, later in this topic.

GridViewUserControl Project

The GridViewUserControl project is registered for COM interop. In addition, the COMRegister() method puts the appropriate entries into the registry so that ActiveX containers see this as a control. This is covered in more detail later.

The managed COBOL grid user control is exposed to COM by declaring a class interface, an events interface, and the class itself, as follows:

  • Class interface, MicroFocus.VisualCOBOL.ISampleGridView in ControlInterface.cbl
  • Class SampleGridView in GridViewControl.cbl
  • Events interface, IGridViewEvents in GridViewEvents.cbl

The project contains other classes to complete the implementation:

  • UserDataGridViewRow class, which contains the methods to handle the row
  • RowSet class, which contains the methods to handle a row of the grid
  • CalendarColumn class, which implements a calendar editor column for use in the data grid

ControlInterface.cbl

ControlInterface.cbl defines the interface that exposes the methods and properties of the control to COM:

  interface-id  MicroFocus.VisualCOBOL.ISampleGridView
      attribute  Guid("5A0AED5B-7D47-48C9-9F95-DEE8BC2D4807").
  method-id  get  property  RowSet.
  ...

GridViewControl.cbl [code]

GridViewControl.cbl contains the class that defines the behavior of the DataGridView control. Its main task is to replicate the behavior of the old ActiveX control in the new DataGridView control.

GridViewControl.cbl includes the following code that is of interest:

Class-id SampleGridView

Define the SampleGridView class, which inherits from the Windows Forms UserControl class and implements the ISampleGridView interface declared in ControlInterface.cbl. It also implements the ISerializable interface, which enables the class to control its serialization behavior:

  Class-id SampleGridView
  inherits type System.Windows.Forms.UserControl
  implements type System.Runtime.Serialization.ISerializable
  type MicroFocus.VisualCOBOL.ISampleGridView
attribute Serializable()

Enable the class to be serialized. This attribute is required even though the class also implements the ISerializable interface to control the serialization process:

  attribute Serializable()
attribute ComVisible(true)

Make the managed class visible to COM. In other words, exposes the class to COM:

 attribute ComVisible(true)
attribute ProgId

Specify the ProgID for the COM object. This is a human-readable version of the class identifier (CLSID) used to identify COM/ActiveX objects:

  attribute ProgId
      ("MicroFocus.VisualCOBOL.SampleGridView")
attribute ClassInterface

Generate a class interface that supports early and late binding:

  attribute ClassInterface
      (type ClassInterfaceType::AutoDual)
attribute ComDefaultInterface

Specify the interface ISampleGridView as the default interface to expose to COM:

  attribute ComDefaultInterface
      (type of MicroFocus.VisualCOBOL.ISampleGridView)
attribute ComSourceInterfaces

Identify the IGridViewEvents as the interface to be exposed as COM event sources for the library WindowsFormsControlLibrary1.dll (which is built by the GridViewUserControl project):

  attribute ComSourceInterfaces
      (type of GridViewUserControl.IGridViewEvents)
attribute Guid

Specify an explicit GUID. This is useful during the debugging phase, as it avoids a new GUID being generated each time you build and register:

  attribute Guid("B33E4887-6BC0-4382-883B-EB0015F55D9B")
COMRegister()

Adds an entry to the Registry for the specified object. It sets the appropriate entries to register the object as an ActiveX, so that ActiveX containers see this as a control. This enables Dialog System to list the ActiveX as one of the controls available for import.

The project property Register for COM Interop registers the object as COM, but does not register it as ActiveX.

COMUnregister()

Removes the entry for the specified object from the Registry.

New()

Create an instance of the SampleGridView.

GetObjectData()

This is used as part of serialization of the control. However, this sample does not have anything to persist so this method is unused.

Event Handling methods
  • FireOnChanged() - handles the OnChanged event
  • FireRowSelected() - handles the OnRowSelected event
  • FireRowDeleted() - handles the OnRowDeleted event
  • OnRowEnter() - invokes the FireRowSelected() method
Get property RowSet

Implements the interface ISampleGridView. Creates an instance of the row.

Get property OrderGrid

This enables the Windows Forms user control to access the DataGridView user control.

  01 OrdersGridView
         type System.Windows.Forms.DataGridView.
  method-id. get property OrderGrid.
  procedure division
          returning thegrid as type DataGridView.
    set thegrid to self::OrdersGridView
    goback.
  end method.
OrdersGridView_CellEndEdit()

Handles the cell editing event and invokes FireOnChanged().

  method-id OrdersGridView_CellEndEdit
      final private.
  procedure division using by value
      sender as object
      e as type System.Windows.Forms.DataGridViewCellEventArgs.
      invoke self::FireOnChanged
         (e::RowIndex, e::ColumnIndex)
Delegates

Defines the delegates for our events.

  01 OnRowSelected type RowSelectedEventHandler event public.
  01 OnRowDeleted type RowDeletedEventHandler event public.
  01 OnChanged type RowChangedEventHandler event public.
     ...
  delegate-id RowSelectedEventHandler.
  delegate-id RowDeletedEventHandler.
  delegate-id RowChangedEventHandler.

GridViewEvents.cbl

GridViewEvents.cbl defines an interface for the events and assigns each event a COM dispatch identifier (DispId), as follows:

  method-id OnRowSelected attribute DispId(29).
  procedure division using by value
      row as binary-long,
      coln as binary-long.
      ...
  method-id OnRowDeleted attribute DispId(18).
  method-id OnChanged attribute DispId(6).

The events correspond to the delegates defined in the SampleGridView class in GridViewControl.cbl.

Note, this interface is not implemented in our solution.

Parent topic: Samples of Modernizing Dialog System Applications


Sample: WPF User Control in a Dialog System Application

The Customer + .NET WPF GridView User Control sample CustGridWPF.sln shows a WPF user control hosted by a Windows Forms user control, which is then exposed as ActiveX ready for use by the Dialog System application.

The Customer + .NET WPF GridView User Control sample CustGridWPF.sln shows a WPF user control used by a Dialog System application. The sample shows how a WPF user control can be hosted, how it can have methods invoked and how it can fire events, which can be consumed in the Dialog System application, as illustrated in the following diagram:

There are two key points about WPF shown in this sample:

  • The WPF user control is hosted by a Windows Forms user control, which is then exposed as ActiveX ready for use by Dialog System. This means that the sample has two user controls: one WPF and one Windows Forms. These are both needed because you cannot expose WPF as ActiveX directly.
  • The WPF user control uses data binding, that is, it associates the data with the user interface. This is similar to Dialog System associating master fields to controls such as entry fields and list boxes. The sample shows this with the CustomerOrder class and the ObservableCollection of customer orders.

The sample is based on the original CustGrid sample from Dialog System. It has two projects: one is the original CustGrid sample and the second contains the code for a simple WPF DataGrid control written in COBOL. The DataGrid control is similar to the control used in the Customer samples (Customer +.NET User Control and Customer + .NET WinForm). Here, in this sample, the DataGrid is a WPF user control.

Note:

In this sample, the control is not a complete implementation of a grid control and the application is not a complete implementation. The sample is designed to illustrate the principles only.

WPFCustGrid Project

The WPFCustGrid project contains the original CustGrid project from Dialog System.

CustGrid.gs is the screenset, which now contains the DataGrid control instead of the original ActiveX grid control. In the same way as before, Dialog System communicates with the native code gridctrl.cbl, using callouts and callbacks.

GridCtrl.cbl handles the events generated by the DataGrid control. It invokes the COM code in the same way as it invoked the ActiveX code before. For example, the Delete-A-Row Section handles the delete-row event and invokes the COM code, as follows:

  INVOKE RowSet "GetSelect" USING theRow RETURNING Numeric-Value
  INVOKE RowSet "Remove" USING Numeric-Value

Where RowSet is defined in the COM interface for the WPF user control in ControlInterface.cbl, which is described later.

WPFGridViewUserControl Project

The WPFGridViewUserControl project contains two user controls: one WPF and one Windows Forms. Both controls are needed because the WPF user control is hosted as a Windows Forms user control (which is then wrapped as an ActiveX control). The content is actually a WPF control, but it is handled as a Windows Forms user control, just as in the sample Customer + .NET User Control.

To see the two controls, double-click:

  • WPFUserControl.xaml - The properties show that the control is a WPF control, of type DataGrid. The XAML shows the definition of the DataGrid. The Document Outline shows the control as a DataGrid. Document Outline is available from View > Other Windows.
  • GridViewControl.cbl [Design] - The properties show that the control is of type Windows.Forms.ElementHost. The Document Outline shows the control as GridHost of type ElementHost. The Toolbox lists this type of control under WPF Interoperability, as ElementHost.

The project contains the following to complete the implementation:

  • CustomerOrder class, which maps to a CustomerOrder group item in the data block, in CustomerOrder.cbl
  • Class interface, MicroFocus.VisualCOBOL.IWPFSampleGridView in ControlInterface.cbl
  • Class WPFSampleGridView in GridViewControl.cbl
  • Events interface, IWPFGridViewEvents in GridViewEvents.cbl
  • RowSet class, which contains the methods to handle a row of the grid, in RowSet.cbl.

The project is registered for COM interop. In addition the COMRegister() method puts the appropriate entries into the registry so that ActiveX containers see this as a control. This method is covered in more detail later.

ControlInterface.cbl

ControlInterface.cbl defines the interface that exposes the methods and properties of the control to COM:

  interface-id  MicroFocus.VisualCOBOL.IWPFSampleGridView
      attribute  Guid("77BECD4D-5504-442D-9DDA-A78C30ADF6A9")
      attribute  InterfaceType(type  ComInterfaceType::InterfaceIsDual)
      attribute  ComVisible(true).
  method-id  get  property  RowSet.
  ...

GridViewControl.cbl [code]

GridViewControl.cbl contains the class that defines the behavior of the DataGrid control. Its main task is to replicate the behavior of the old ActiveX control in the new DataGrid control.

GridViewControl.cbl includes the following code of interest:

WPFSampleGridView

Defines the WPFSampleGridView class, which inherits from the Windows Forms UserControl class and implements the IWPFSampleGridView interface declared in ControlInterface.cbl. It also implements the ISerializable interface, which enables the class to control its serialization behavior.

  Class-id WPFSampleGridView
      inherits type System.Windows.Forms.UserControl
      implements
        type System.Runtime.Serialization.ISerializable
        type MicroFocus.VisualCOBOL.IWPFSampleGridView
attribute Serializable()

Enable the class to be serialized. This attribute is required even if though the class also implements the ISerializable interface to control the serialization process.

  attribute Serializable()
attribute ComVisible(true)

Make the managed class visible to COM. Exposes the class to COM:

  attribute ComVisible(true)
attribute ProgId

Specify the ProgID for the COM object. This is a human-readable version of the class identifier (CLSID) used to identify COM/ActiveX objects:

  attribute ProgId("WPFSampleGridView")
attribute ClassInterface

Generate a class interface that supports early and late binding:

  attribute ClassInterface(type ClassInterfaceType::None)
attribute ComDefaultInterface

Specify the interface ISampleGridView as the default interface to expose to COM:

  attribute ComDefaultInterface
  (type of MicroFocus.VisualCOBOL.IWPFSampleGridView)
attribute ComSourceInterfaces

Identify the IGridViewEvents as the interface to be exposed as COM event sources for the library WindowsFormsControlLibrary1.dll (which is built by the GridViewUserControl project):

  attribute ComSourceInterfaces (type of
        MicroFocus.VisualCOBOL.IWPFGridViewEvents)
attribute Guid

Specify an explicit GUID. This is useful during the debugging phase, as it avoids a new GUID being generated each time you build and register:

  attribute Guid("E0A41600-4531-4E55-9B24-6D2F1CF8B106")
ObservableCollection of CustomerOrder Objects

Create an observable collection of CustomerOrder objects, which enables the backing data to be updated when the user interface changes (such as when the user edits the data):

 *> Create an observable collection of CustomerOrder
 *> objects so that the data grid receives notifications
 *> such as add, delete in order to refresh the list
  01 _customerOrders
      type ObservableCollection[type CustomerOrder]
      value new ObservableCollection[type CustomerOrder]
      public
      property as "CustomerOrders".
SampleGridView class

The SampleGridView class provides the following methods and delegate definitions:

COMRegister()

This method adds an entry to the Registry for the specified object. It sets the appropriate entries to register the object as an ActiveX, so that ActiveX containers see this as a control. This enables Dialog System to list the ActiveX as one of the controls available for import.

The project property Register for COM Interop registers the object as COM, but does not register it as ActiveX.

COMUnregister()

The reverse of the COMRegister() method.

New()

These methods create an instance of the WPFSampleGridView. The default New() method initializes the instance and adds the specified data by invoking the appropriate methods: OnSelectionChanged(), OnCellEditEnding() and OnSourceUpdated().

OnSourceUpdated()

Handles the OnSourceUpdated event, determines the row updated and invokes the FireOnChanged() method.

OnCellEditEnding()

Handles the OnCellEditEnding event and invokes the FireOnChanged() method.

OnSelectionChanged()

Handles the OnSelectionChanged event, determines the row and invokes the FireRowSelected() method.

GetObjectData()

This is used as part of serialization of the control. However, this sample does not have anything to persist so this method is unused.

Event Handling methods
  • FireOnChanged() - handles the OnChanged event
  • FireRowSelected() - handles the OnRowSelected event
  • FireRowDeleted() - handles the OnRowDeleted event
  • OnRowEnter() - invokes the FireRowSelected() method
Get property RowSet

Implements the interface IWPFSampleGridView. Creates an instance of the row.

Get property OrderGrid

This enables the Windows Forms user control to access the WPF DataGrid user control.

  method-id. get property OrderGrid.
  procedure division returning thegrid as
        type System.Windows.Controls.DataGrid.
    set thegrid to self::wpfUserControl1::OrdersGrid
WPFSampleGridView_Load()

Handles the cell editing event.

  method-id OrdersGridView_CellEndEdit final private.
  procedure division using by value
      sender as object
      e as type System.EventArgs.
Delegate definitions

Defines the delegates for our events:

  01 OnRowSelected type RowSelectedEventHandler event public.
  01 OnRowDeleted type RowDeletedEventHandler event public.
  01 OnChanged type CellEditEndingHandler event public.
     ...
  delegate-id RowSelectedEventHandler.
  delegate-id RowDeletedEventHandler.
  delegate-id CellEditEndingHandler.

GridViewEvents.cbl

IWPFGridViewEvents.cbl defines an interface for the events. The interface has the ComInterfaceType.InterfaceIsIDispatch attribute, which restricts callers to late binding.

  interface-id MicroFocus.VisualCOBOL.IWPFGridViewEvents
      attribute Guid("3DC45DA1-A580-4280-A2DB-7B6A266032AE")
      attribute InterfaceType
         (type ComInterfaceType::InterfaceIsIDispatch)
      attribute ComVisible(true).

The interface defines a method for each event, and assigns each event a COM dispatch identifier (DispId), as follows:

  method-id OnRowSelected attribute DispId(29).
  ...
  method-id OnRowDeleted attribute DispId(18).
  ...
  method-id OnChanged attribute DispId(6).

The events correspond to the delegates defined in the WPFSampleGridView class in GridViewControl.cbl.

Note, this interface is not implemented in our solution.

CustomerOrder.cbl

CustomerOrder.cbl defines the CustomerOrder class, which contains methods to create and initialize an instance of a customer order, and to return an array of customer orders.

The CustomerOrder class demonstrates a key concept in WPF, data binding. It demonstrates how the data can be associated with the user interface.

The CustomerOrder class maps to a Customer Order group item in the data block, so part of the sample gets data from the data block and creates a list of Customer Orders. This object is then associated with the WPF DataGrid, which renders the control to match the data in the list. The object is defined in GridViewControl.cbl, as the type ObservableCollection.

Parent topic: Samples of Modernizing Dialog System Applications


Sample: Managed Dialog System Application

The Managed Customer sample ManagedCustomer.sln is broadly the original Customer sample that was supplied with Dialog System. The key difference with this sample is that it is compiled to managed code and run under .NET.

The Managed Customer sample ManagedCustomer.sln is broadly the original Customer sample that was supplied with Dialog System. The key difference with this sample is that it is compiled to managed code and run under .NET. The existing Dialog System run-time calls remain but are automatically converted to Platform Invoke calls into the native code. In other words, the user interface and screensets are all still running as native code. The following diagram illustrates this.

This sample is using the Platform Invoke technique, which enables managed code to call unmanaged functions implemented in dynamic link libraries (.dlls). Platform invoke is similar to an API call.

The sample has just one project, a managed code project, comprising:

  • Properties - Notice that the project is compiled to managed code. See Project > ManagedCustomer Properties > Application tab, which shows the application is managed because it targets the .NET Framework (4, in our case).
  • References - Notice that one of the references is to the Dialog System run-time system, dsgrun.dll, which is compiled as native COBOL. This enables the managed COBOL to call into dsgrun, using CALL statements. These CALL statements generate a Platform Invoke call if the CALL matches an entry in the native .dll.
  • Customer.cbl - original source code, plus some additional code to call the native Dialog System run-time system correctly.
  • Customer.cpb - original copybook generated from the Dialog System data block. This is unchanged.
  • Customer.gs - original screenset, which is unchanged.
  • Cust.ism - the original data file, which is unchanged.

Customer.cbl

Customer.cbl contains the original code for the business logic and for interaction with the Dialog System screenset.

The only change to Customer.cbl is to ensure that the managed code calls the native Dialog System run-time system correctly. The code must supply all the parameters that Dialog System might need (or at least signify that we are not passing all the parameters). The original Customer sample uses only two parameters, so the code here needs to add a third parameter as 'omitted'.

  Call-Dialog-System SECTION.
      CALL dialog-system USING ds-control-block,
                               customer-data-block
                               omitted
Parent topic: Samples of Modernizing Dialog System Applications


Sample: Managed Application and Windows Forms

The Managed Customer + .NET WinForm sample ManagedCustomerWinForm.sln puts together the Managed Customer sample and the .NET Order Forms dialog that is used in the Customer + WinForm sample. These two together form a sample where all the COBOL is compiled to .NET and the Dialog System user interface remains in native code.

The Managed Customer + .NET WinForm sample ManagedCustomerWinForm.sln puts together the Managed Customer sample and the .NET Order Forms dialog that is used in the Customer + WinForm sample. These two together form a sample where all the COBOL is compiled to .NET and the Dialog System user interface remains in native code. The following diagram illustrates this.

The advantage of moving all the code to .NET means that the native/managed interoperation through COM is no longer relevant, which simplifies the sample greatly. Compare this sample with the Customer + Win Form sample.

To create this sample:

  • The ManagedCustomer project has a reference to the Dialog System run-time system, dsgrun, which you can see if you expand the References folder in Solution Explorer.
  • The call to Dialog System uses the correct case of the main entry point and supplies all parameters that Dialog System might need (or at least signifies that we are not passing all the parameters). The original Customer sample uses only two parameters, so the code here adds a third parameter as 'omitted'.
      Call-Dialog-System SECTION.
      CALL dialog-system USING ds-control-block,
                               customer-data-block
                               omitted
  • The new Order Form dialog written in .NET COBOL is invoked from the main customer using .NET COBOL syntax because this is now compiled to managed code, as follows:
     invoke type OrderFormsLibrary.FormsFactory::CreateOrderForm
     (by reference CUSTOMER-DATA-BLOCK)

    This differs from the Customer + Win Form sample which uses native/managed interop through COM to pass the data between the main customer program and the new Order form.

    From the managed side, the Order form no longer has to use .NET marshalling to get the data and can remove the COM interfaces previously used to communicate with native code.

  • The project no longer needs to set the project property Register For COM Interop.
Parent topic: Samples of Modernizing Dialog System Applications


Java and COBOL

You can use COBOL and Java together, by coding the calls using the supplied support libraries.

Restriction: This applies to native code only.
  • Using Java and COBOL Together
    This chapter introduces the different ways that Java and COBOL applications can call each other.
  • 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.
Parent topic: Compatibility


Using Java and COBOL Together

This chapter introduces the different ways that Java and COBOL applications can call each other.
Restriction: This applies to native code only.
  • Overview
  • Setting Up the Environment for Java and COBOL
  • 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: Java and COBOL


Overview

Restriction: This applies to native code only.

You can use COBOL and Java together, by coding the calls using the supplied support libraries. Java itself provides access to other technologies, such as Remote Method Invocation (RMI) and Java Naming and Directory Interface (JNDI) which enable you to distribute objects across different machines.

You can use COBOL and Java together by:

  • Calling procedural COBOL from Java, using 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). This is ideal for use with Java 2 Standard Edition (J2SE).
  • Calling Java from OO COBOL, using the Java object domain for OO COBOL. This is ideal for use with Java 2 Standard Edition (J2SE).
  • Calling OO COBOL from Java, creating a Java wrapper class that provides a function for each method in the OO COBOL class. This is ideal for use with Java 2 Standard Edition (J2SE).

You use COBOL Server for running the other types of applications that use both COBOL and Java programs.

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. Where a COBOL data type cannot be translated directly (for example, edited fields), it is under some circumstances translated to a string.

Parent topic: Using Java and COBOL Together


Setting Up the Environment for Java and COBOL

Restriction: This applies to native code only.

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 also need a Java development environment. You can use either the Java Software Development Kit (SDK) available from Oracle, or any Java IDE which is based on either the Oracle or Microsoft Java run-time environments. Alternatively you can have a Java Virtual Machine (JVM), which provides both a development environment and a run-time environment.

Your COBOL development system currently supports several Java run-time systems.

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

    If you are using the Java run-time system from Oracle, 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.

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

Parent topic: Using Java and COBOL Together


Compiling COBOL Programs that Call Java

Restriction: This applies to native code only.

Any COBOL program which is going to call Java must be compiled with the following directive:

ooctrl(+p-f)

This does two things:

  • Adds type information to invoke statements, which the COBOL run-time system needs to convert data correctly between the COBOL and Java domains
  • Prevents the compiler from folding method names it invokes to lower-case - Java method names are case-sensitive
Parent topic: Using Java and COBOL Together


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: Using Java and COBOL Together


Linking to the Multi-threaded Run-time System

Restriction: This applies to native code only.

All COBOL programs for use with Java must be linked to the multi-threaded run-time system.

Parent topic: Using Java and COBOL Together


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: Java and COBOL


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

    REENTRANT(2) causes the COBOL run-time system to allocate separate user data and FD file areas to each different thread. This prevents any conflicts or data corruption within the program. But REENTRANT(2) can't guarantee thread safety if it calls other non-threaded programs, or accesses other shared resources - in these sorts of cases, SERIAL is a safer option. The REENTRANT(2) directive can provide better performance than SERIAL as one thread is not kept waiting for the next thread to finish.

  • Use thread-local storage in your COBOL programs instead of working storage.

    Thread-local storage is allocated per thread, so there is no possibility of one thread corrupting the data used by another thread. This is fairly efficient, but might not be always be an option with legacy code.

  • Multi-thread your COBOL program using COBOL multi-threading syntax or run-time system calls.

    This can be very efficient as you control which data is thread-local and which data is shared between threads. You could use this option with legacy COBOL code if you are ready to write COBOL driver programs to sit between the Java run-time environment and your legacy programs. Your driver program would be responsible for controlling access to the legacy programs, and would have to use semaphores or some similar mechanism to prevent two threads from accessing the same code at the same time.

    You need to be very careful when canceling a COBOL program in a threaded environment where the program is shared between threads. This applies whether you are using CANCEL or the com.microfocus.cobol.RuntimeSystem.cobcancel() method calls. If possible avoid canceling altogether.

Alternatively, consider using the CobolBean interface, which associates a COBOL programs working storage with a instance of a CobolBean class.

Parent topic: Calling Procedural COBOL from Java


Loading a COBOL Program or Library

Restriction: This applies to native code only.

If your COBOL programs are linked into a library file, or if you want to expose entry-points inside a COBOL program, you need to load the library file or programs before making any calls. You can do this using the runtime.cobload() method in runtime.class. For example, to load the programs inside mycbl:

{
  if (RuntimeSystem.cobload("mycbl") != 0)
     System.out.println("Could not load library\n") ;
  else
     System.out.println("Library loaded successfully\n") ;
}
Parent topic: Calling Procedural COBOL from Java


Using the cobcall() Methods

Restriction: This applies to native code only.

Once you have loaded the libraries or programs required by your Java application (see the previous section for details) you can make calls to COBOL using the cobcall_ methods. The cobcall_ methods are all static methods of RuntimeSystem.class, so you do not have to instantiate RuntimeSystem.class before starting. Each cobcall_ method takes two or three parameters (the third parameter is optional):

Style 1:

  • A string naming the COBOL program
  • A Java object array containing any parameters you want passed to the COBOL program, in the order they appear in the USING clause of the COBOL program's Procedure Division header. By default, parameters are passed by reference.
  • A Java integer array defining the USAGE clause for each parameter. You can select BY REFERENCE, BY VALUE or BY CONTENT, defined by static values of com.microfocus.cobol.RuntimeSystem

Style 2:

  • A string naming the COBOL program
  • A list of parameters encapsulated in a ParameterList()

Parameters are converted between Java and COBOL data types as described in the chapter Java Data Types. As explained in the section Coding Your Java Program there are different cobcall_ methods, each named according to the Java equivalent of the data type returned by the COBOL program or entry being called. For example, a COBOL program that returns a signed integer (such as a pic s9(9) comp-5) is returning the Java data type int. So you would call the COBOL program using the cobcall_int method. By default all parameters are passed by reference.

The copybook javatypes.cpy also provides a set of COBOL type definitions for Java data types. We advise you to use the data types defined in this file to declare COBOL data items that are going to be used for passing parameters between Java and COBOL. Using these data types helps keep your code portable between different COBOL platforms.

See the Java Run-time Class Library Reference, which is in help\mfcobol.docs.zip in your COBOL development system installation.

Parent topic: Calling Procedural COBOL from Java


Examples of Calling COBOL from Java

Restriction: This applies to native code only.

This section shows you two short examples of calling a COBOL program from Java. The first example shows the following features:

  • Passing data to a COBOL program by reference (the default)
  • Returning an integer by using cobcall_int()

This is a simple COBOL subroutine, named legacy.cbl:

working-storage section.
copy "javatypes.cpy".
01 wsResult       jint.

linkage section.
01 wsOperand1     jint. *> type defined in javatypes.cpy
01 wsOperand2     jint.
01 wsOperation    pic x.

procedure division using wsOperand1 wsOperand2 wsOperation.
    evaluate wsOperation
    when "a"
        add wsOperand1 to wsOperand2 giving wsResult
    when "s"
        subtract wsOperand1 from wsOperand2 giving wsResult
    end-evaluate
    exit program returning wsResult.

This is a Java program which calls the subroutine:

import com.microfocus.cobol.* ;
class SimpleCall
{
   public static void main(String argv[]) throws Exception
   {
       int i = RuntimeSystem.cobcall_int("legacy",
                        new ParameterList()
                                   .add((int)4
                          .add((int)7
                                   .add((byte)'a'));
       System.out.println(i) ;
   }
}

The second example shows you how to pass data to a COBOL program with the equivalent of different usage clauses. The cobcall() method used does not return a value, but it takes an object as the first parameter, and returns the same object type from the COBOL program. SimpleCall2 passes the first parameter by reference, the second by value, and the third by content.

import com.microfocus.cobol.* ;

class SimpleCall2
{
   public static void main(String argv[]) throws Exception
   {
      RuntimeSystem.cobcall(null, "usages",
                    new ParameterList()
                    .add((int)1, RuntimeSystem.BY_REFERENCE)
                    .add((int)2, RuntimeSystem.BY_VALUE)
                    .add((int)3, RuntimeSystem.BY_CONTENT));
   }
}
Parent topic: Calling Procedural COBOL from Java


Changing Data Members in a Java Object

Restriction: This applies to native code only.

The example in this section is similar to the example in the previous section, except that the result from the COBOL program is also used to change the value of one of the data members in the Java object.

thread-local-storage section.
copy "javatypes.cpy".

linkage section.
01 wsOperand1               jint.
01 wsOperand2               jint.
01 wsOperation              pic x.
01 wsResult                 jint.

procedure division using wsOperand1 wsOperand2 wsOperation
                         wsResult.
    evaluate wsOperation
    when "a"
        add wsOperand1 to wsOperand2
    when "s"
        subtract wsOperand1 from wsOperand2
    end-evaluate
    exit program returning wsResult

The Java class SimpleCall2 assumes that legacy2.cbl is built into a library file called legacy2.ext. However, if this subroutine were built into a different library file, you would need to use the RuntimeSystem.cobload() method to load the library file before making calls to the legacy program.

import com.microfocus.cobol.* ;
class SimpleCall2
{
   Integer simpleInteger1;
   Integer simpleInteger2;
   Integer simpleResult;
   public SimpleCall2(int a, int b)
   {
      simpleInteger1 = new Integer(a);
      simpleInteger2 = new Integer(b);
      simpleResult   = new Integer(0);
   }
   public String toString()
   {
      return new String(
            "simple1Integer1 = "+simpleInteger1+"\n" +
            "simple1Integer2 = "+simpleInteger2+"\n" +
            "simpleResult    = "+simpleResult);
   }
   public static void main(String argv[]) throws Exception
   {
      SimpleCall2 firstDemo = new SimpleCall2(4,7);
      Object theParams[] = { firstDemo.simpleInteger1,
                             firstDemo.simpleInteger2,
                             new Byte((byte) 'a'),
                             firstDemo.simpleResult }
      System.out.println("Before call\n"+firstDemo) ;
      int i = RuntimeSystem.cobcall_int("legacy2",theParams);
      System.out.println("After call\n"+firstDemo) ;
   }
}
Parent topic: Calling Procedural COBOL from Java


Using CobolBean for Instance Data

Restriction: This applies to native code only.

The com.microfocus.cobol.CobolBean class enables you to associate an instance of CobolBean to an instance of a COBOL program's storage section without having to recode the COBOL application to either be thread-safe or take the parameters from the Java application.

For example, the following COBOL program shares the same data when it is called using cobcall() by more than one Java class.

$set intlevel"4" 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: Java and COBOL


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

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: Java and COBOL


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.

The functions in the Java wrapper class put all the parameters for the method into a Java array, and then call one of the member functions of Java class com.microfocus.cobol.RuntimeSystem to invoke the method in the OO COBOL class and return the result. This is shown in the figure below:

Calling OO COBOL from Java

Parent topic: Calling OO COBOL from Java
Related information
Java Web Site


Writing a Java Class in OO COBOL

Restriction: This applies to native code only.

To write a class in OO COBOL which can be called from Java, you need to do the following:

  1. Set the following directive in your program:
    $set ooctrl(+p-f)
  2. Ensure that the OO COBOL class inherits from javabase.
  3. Create a Java wrapper class for the OO COBOL class. The wrapper class must have the same class name as the filename of the OO COBOL class.
  4. For each method that you create in your OO COBOL class, create a corresponding method in the Java wrapper class.
  5. Package the class inside a .dll file when deploying it on Windows platforms.
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 .
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


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 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 in your COBOL development system installation.

Parent topic: Calling OO COBOL from Java


Using BY REFERENCE Parameters

Restriction: This applies to native code only.

When parameters to a method are declared as BY REFERENCE, the default behavior is for any updates to those parameters to be reflected in the corresponding Java objects in the calling Java class on return from the OO COBOL method.

If you do not want the Java objects to be updated, you can set the following static variable:

static boolean mfcobol.runtimeProperties.updateByRefParams;

The default value for this variable is true. Set it to false if you do not want the Java objects to be updated.

Note: In an earlier version of this COBOL development system, the default behavior was for updates to BY REFERENCE parameters not to be reflected in the calling Java. If you have existing Java code that makes use of that behavior, you need to modify it to set mfcobol.runtimeProperties.updateByRefParams to false.

Your COBOL development system includes a demonstration program that illustrates the different ways of handling BY REFERENCE parameters.

Parent topic: Calling OO COBOL from Java


Working with Java Programs

Restriction: This applies to native code only.

When you develop mixed COBOL and Java programs, you need to be aware of the following:

  • The default Java build directives that your COBOL development system uses are -d %TARGETDIR -classpath "%CLASSPATH";%TARGETDIR %FILENAME. The "%CLASSPATH";%TARGETDIR section of the command appends the currently-specified target directory to the end of the current setting for the CLASSPATH environment variable, retaining any spaces specified in the current setting of CLASSPATH.
  • If you specify multiple classes in a .java program, only the resultant .class file with the same basename as the .java program is added to the project automatically. You must add any other .class files manually.
  • 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). 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: Java and COBOL


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) comp | 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-1BKDIDIJADTS003.html#FOOTNOTE1 | comp-1 BKDIDIJADTS003.html#FOOTNOTE1 | Floating-point number
double | comp-2 BKDIDIJADTS003.html#FOOTNOTE1 | comp-2 BKDIDIJADTS003.html#FOOTNOTE1 | Double-precision floating-point number
String | mf-jstring pointer | 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.
StringBufferBKDIDIJADTS003.html#FOOTNOTE4 | mf-jstring BKDIDIJADTS003.html#FOOTNOTE2 pointer BKDIDIJADTS003.html#FOOTNOTE3 | 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.

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
1 The parameter can be passed only by reference. 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.


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 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 Programs that use this typedef must be compiled with the directive INTLEVEL 4
jbiginteger | pic s9(38) comp-3 Programs that use this typedef must be compiled with the directive INTLEVEL 4
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 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


User Interface Programming

  • Modernizing Dialog System Applications
  • Windows Forms
  • Web Application Projects
  • Web Forms
Parent topic: Compatibility


Windows Forms

  • To deploy a Windows application to the .NET environment
Parent topic: User Interface Programming


To deploy a Windows application to the .NET environment

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

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

    See the Visual Studio Help for details.

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

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


Web Application Projects

  • To deploy a Web Application to the .NET environment
Parent topic: User Interface Programming


To deploy a Web Application to the .NET environment

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

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


Web Forms

  • To deploy a COBOL Web site to the .NET environment
Parent topic: User Interface Programming


To deploy a COBOL Web site to the .NET environment

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

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

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

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

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

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


Data Access

  • Database Access
  • File Handling
Parent topic: Programming


Database Access

We provide several programming options and features to accommodate database access in your COBOL applications.

  • Database Access Features
    This topic provides a brief overview of the main database access features.
  • Database Access Preprocessors
    Provides introductory information about each of the supported Database Access preprocessors.
  • Developing SQL Applications
    Information to assist you in developing SQL applications from scratch or maintaining SQL applications developed elsewhere.
  • Compiling SQL Applications
    Explains the process of compiling (building) and debugging SQL applications.
  • OpenESQL
    Explains the functionality available with the OpenESQL preprocessor and provides information for developing and deploying OpenESQL SQL applications.
  • DB2
    Explains the functionality associated with the DB2 External Compiler Module (ECM) preprocessor, and provides information for developing and deploying DB2 ECM SQL applications.
  • COBSQL
    Explains the functionality associated with the COBSQL preprocessor, and provides information for developing and deploying SQL applications for Oracle, Sybase, and Informix.
  • How to...
    How to use the database access utilities and editors available to help you develop and deploy your SQL applications.
  • Reference
    Reference information for embedded statements, compiler directives, and other coding standards associated with database access.
Parent topic: Data Access
Related concepts
Database Access Support with Native COBOL
Database Access Support with .NET Managed COBOL


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 Managed .NET Runtime - communicates with managed COBOL SQL applications that use any type of database
  • DB2 ECM Runtime - communicates with native COBOL SQL applications that use DB2 databases.
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 CLR2 and CLR 4 ADO.NET data providers
  • DB2 ECM for use with DB2 databases
  • COBSQL for use with COBOL preprocessors supplied by relational database vendors
    Note: You can also use a preprocessor supplied by your database vendor without COBSQL.
Stored Procedures
We support COBOL stored procedures for both DB2 LUW and SQL Server 2008.
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. For managed code under .NET, ignore all references to COBSQL, and DB2 that appear in the remaining topics in this Database Access documentation. They do not apply to managed code.
Parent topic: Database Access


Database Access Preprocessors

A database access preprocessor is essentially a conversion tool called by the COBOL compiler that processes embedded SQL, and can convert embedded SQL into code that is understood by your target database. Visual COBOL provides three database access preprocessors from which to choose, all designed to work closely with the Micro Focus COBOL Compiler.

OpenESQL Preprocessor

The OpenESQL preprocessor is the most flexible of the three available in Visual COBOL. Use it for basic SQL applications, applications designed to use multiple relational database systems, and for applications you might want to update to use a different relational database system in the future. In addition to processing embedded SQL statements, the OpenESQL preprocessor converts COBOL data types to their equivalent SQL data types.

OpenESQL provides these levels of database access:
  • ODBC for native applications
  • ADO.NET for managed .NET applications

DB2 External Compiler Module (ECM) Preprocessor

The DB2 ECM preprocessor converts embedded SQL statements into the appropriate calls to DB2 database services. Use this preprocessor for applications that access a DB2 relational database.

COBSQL Preprocessor

COBSQL is an integrated preprocessor designed to work with COBOL precompilers supplied by the Oracle, Sybase, and Informix relational database vendors. Use COBSQL if you are already using one of these precompilers with an earlier version of a Micro Focus COBOL product and want to migrate your application(s) to Visual COBOL. For any other type of embedded SQL application development, we recommend that you use OpenESQL.

This preprocessor replaces embedded SQL statements with the appropriate calls to database services, and adds code to bind COBOL host variables to the SQL variable names known to the database system.

When using the COBSQL precompiler with Visual COBOL, you can debug programs from the original source code rather than from the code produced by the precompiler.

Note: The COBSQL preprocessor is supported only for standard procedural COBOL programs. You cannot use COBSQL with Object Oriented COBOL syntax (OO programs) or with nested programs.
Parent topic: Database Access
Related concepts
OpenESQL
COBSQL
DB2


Developing SQL Applications

The following topics describe the programming features available for SQL applications in general. Specific information on programming for a particular preprocessor is contained in the topics covering the use of that preprocessor.

  • Embedded SQL
    Instructions on how to embed SQL statements into your programs.
  • Host Variables
    The purpose of host variables, how to declare them, and how to use them in your SQL applications.
  • Cursors
    The purpose of cursors, how to declare them, and how to use them in SQL applications.
  • Data Structures
    The purpose and use of the SQLCA and SQLDA data structures available for SQL applications.
  • Dynamic SQL
    An explanation of how dynamic SQL works, and a description of its purpose, advantages, and use.
Parent topic: Database Access


Embedded SQL

Each of the database access preprocessors works by taking the SQL statements that you have embedded in your COBOL program and converting them to the appropriate function calls to the database.

Keywords

In your COBOL program, each embedded SQL statement must be preceded by the introductory keywords:

EXEC SQL

and followed by the keyword:

END-EXEC

For example:

     EXEC SQL
         SELECT au_lname INTO :lastname FROM authors
          WHERE au_id = '124-59-3864'
     END-EXEC

The embedded SQL statement can be broken over as many lines as necessary following the normal COBOL rules for continuation, but between the EXEC SQL and END-EXEC keywords you can only code an embedded SQL statement; you cannot include any ordinary COBOL code.

The case of embedded SQL keywords in your programs is ignored. You can use all upper-case, all lower-case, or a combination of the two. For example, the following are all equivalent:

EXEC SQL CONNECT
exec sql connect
Exec Sql Connect

Cursor names, statement names, and connection names

The case of cursor names, statement names and connection names must match that used when the variable is declared. For example, if you declare a cursor as C1, you must always refer to it as C1 (and not as c1).

The settings for the particular database determine whether such things as connection names, table and column names, are case-sensitive.

SQL identifiers

Hyphens are not permitted in SQL identifiers such as table and column names.

SQL identifiers are typically restricted regarding which characters they support. Typically, unquoted identifiers can only contain A-Z, 0-9 and underscore. Some databases might also allow lower-case characters, and/or @ and # symbols. If your SQL identifiers contain any other characters, such as a grave accent, spaces, or DBCS characters, they must be delimited. Refer to your database vendor documentation for more information, including the character to use as the delimiter.

SQL statements

Most vendors provide SQL Reference documentation with their database software that includes full information about embedded SQL statements. Regardless of the database software, you should, for example, be able to perform the following typical operations using the statements shown:

Operation | SQL Statement(s)
Add data to a table | INSERT
Change data in a table | UPDATE
Retrieve a row of data from a table | SELECT
Create a named cursor | DECLARE CURSOR
Retrieve multiple rows of data using a cursor | OPEN, FETCH, CLOSE

A full syntax description is given for each of the supported embedded SQL statements, together with an example of its use, in the topics under Embedded SQL Statements.

Parent topic: Developing SQL Applications
Related reference
Embedded SQL Statements


Host Variables

Host variables are data items defined within a COBOL program. They are used to pass values to and receive values from a database. Host variables can be defined in the File Section, Working-Storage Section, Local-Storage Section or Linkage Section of your COBOL program and can be coded using any level number between 1 and 48.

A host variable can be input or output:
  • Input host variables - to specify data to be transferred from the COBOL program to the database
  • Output host variables - to hold data to be returned to the COBOL program from the database

To use host variables, you must declare them in your program and then reference them in your SQL statements.

A host variable can be defined as any of the following types:
  • Simple Host Variable - to store and retrieve a single string of data
  • Host Array - to store and retrieve multiple rows of data
  • Indicator Variable - a companion variable that store null value and data truncation information
  • Indicator Array - a companion array used to store null value and data truncation information for multiple rows

See the topics listed under Related concepts below for more information on features related to host variables.

Note: The OpenESQL Managed .NET Runtime supports .NET host variables in managed code. See the topic .NET 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
.NET 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.

The SQLCA 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

For COBSQL, SQLSTATE is a separate data item. For the currently supported versions of Oracle and Sybase, the SQLCA should be used in preference to the SQLSTATE variable. The SQLSTATE variable will eventually supersede the SQLCA as the preferred method of passing data between the database and the client application, but this is not yet the case.

  • Using the SQLCA
  • The SQLCODE Variable
  • The SQLSTATE Variable
  • The Warning 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 the %ProgramFiles%\Micro Focus\Visual COBOL\cpylib directory. 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
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
SQLSTATE Values


The Warning 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 occured, otherwise the value will be 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
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 the file sqlda.cpy, which by default is located in the %ProgramFiles%\Micro Focus\Visual COBOL\cpylib directory. You can include it in your COBOL program by adding the following statement to your data division:

EXEC SQL
   INCLUDE SQLDA
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.

If the value of the SQLTYPE field is an odd number, the address of the indicator variable must also be supplied in SQLIND.

Parent topic: Using the SQLDA


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
Parent topic: Using the SQLDA


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 a Preprocessor
    Instructions that explain the various methods of specifying a preprocessor to use when compiling an SQL application.
  • Compiling Multiple Program Modules
    Provides information on how to best compile SQL applications that specify multiple program modules.
  • Creating Debug Files
    Explains the process of creating debug files to assist Micro Focus SupportLine representatives in resolving issues related to the compiling of an SQL application.
Parent topic: Database Access
Related concepts
OpenESQL
COBSQL
DB2


Specifying a Preprocessor

We provide several alternative methods for specifying a database access preprocessor for your programs and applications.

Project Properties

You can specify a preprocessor as part of your project properties.
OpenESQL
  1. On the SQL tab for your Project Properties, specify OpenESQL as the ESQL Preprocessor.
  2. To specify the type of database access you want, add the DBMAN directive and set its value to ODBC or ADO.
DB2
  1. On the SQL tab for your Project Properties, specify DB2 as the ESQL Preprocessor.
  2. To specify a value for the DB directive, type the name of your DB2 database into the Value field.
    Note: If you leave the value for DB blank, the compiler uses the database specified as the value of the DB2DBDFT environment variable.
COBSQL
On the COBOL tab for your Project Properties, type PREPROCESS(cobsql) into the Additional Directives field.

Command Line

If you compile your applications from the command line, specify your preprocessor as a command-line directive and set options as appropriate. Here we present the minimum with regard to options. For complete information on these compiler directives and their options, see the appropriate Reference topic listed at the end of this topic.

OpenESQL
Use the SQL compiler directive, followed by the DBMAN option to specify the type of database access:

SQL(DBMAN=dbaType)

Where dbaType is ODBC or ADO.

DB2
Use the DB2 compiler directive, followed by the DB option to specify the type of database access:

DB2(DB=dbName)

Where dbName is the name of your DB2 database.

Note: If you do not specify the DB option, the compiler uses the database specified as the value of the DB2DBDFT environment variable.
COBSQL
Use the PREPROCESS compiler directive:
PREPROCESS(cobsql)

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.

OpenESQL
Use the SQL compiler directive, followed by the DBMAN option to specify the type of database access:
$SET SQL(DBMAN=dbaType)

Where dbaType is ODBC or ADO.

DB2
Use the DB2 compiler directive, followed by the DB option to specify the type of database access:
$SET DB2(DB=dbName)

Where dbName is the name of your DB2 database.

Note: If you do not specify the DB option, the compiler uses the database specified as the value of the DB2DBDFT environment variable.
COBSQL
Use the PREPROCESS compiler directive:
$SET PREPROCESS(cobsql)
Parent topic: Compiling SQL Applications


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). If subsequent program modules (in the same process) do not process a CONNECT statement, they share the same database connection with the module that included the CONNECT statement.

OpenESQL
In a program that includes multiple, separately compiled modules, you should compile only one module with the INIT option of the SQL Compiler directive. All other modules in the program should share that first automatic connection or make explicit connections using the CONNECT statement.
OpenESQL - DB2
  • Statement names are local to a particular program module (compilation unit). This means that a statement cannot be prepared in one module and executed in another.
  • Within an application, cursor names should be unique.
COBSQL
With COBSQL, if the INIT directive is specified more than once, second and subsequent uses are ignored.
Parent topic: Compiling SQL Applications
Related reference
CONNECT
INIT


Creating Debug Files

If an error occurs when compiling a program that requires technical support, your support representative might ask you to provide additional debug files to help in determining the cause of the problem. You obtain these debug files by specifying extra Compiler directives. You might want to specifiy some of these directives to help in your own debugging efforts. The directives are:

OpenESQL
Directive | File created | Information within file
CHKECM(CTRACE) | ecmtrace.txt | Pseudo COBOL code that shows the code generated to replace the EXEC SQL statements. This file is equivalent to output from the OpenESQL ODBC precompiler.
CHKECM(TRACE) | ecmtrace.txt | Detailed information as to what information is passed between the ODBC ECM and the Compiler. If an error occurs that generates invalid syntax, this file will be needed to help isolate where the problem occurred.
SQL(CTRACE) | sqltrace.txt | Detailed list of information passed to OpenESQL Precompiler Services, and the results. This file is very useful if an error might involve a bug in the OpenESQL run time as well as the OpenESQL ECM.
ECMLIST | program-name.lst | The standard COBOL list file, with pseudo COBOL code that shows the code generated to replace the EXEC SQL statements. You must also compile the program with the CHKECM(CTRACE) and LIST directives.
DB2 ECM
Directive | File created | Information in the file
CHKECM(CTRACE) | ecmtrace.txt | This file contains pseudo COBOL code that shows the code generated to replace the EXEC SQL statements. This code is equivalent to output from the IBM DB2 COBOL precompiler.
CHKECM(TRACE) | ecmtrace.txt | This file contains detailed information as to what information is passed between the DB2 ECM and the Compiler. If an error occurs that generates invalid syntax, this file will be needed to help isolate where the problem occurred.
DB2(CTRACE) | sqltrace.txt | This file contains a detailed list of information passed to IBM Precompiler Services, and the results. This file is very useful if an error might involve a bug in the DB2 system software as well as the DB2 ECM.
ECMLIST | program-name.lst | This file is the standard COBOL list file, with pseudo COBOL code that shows the code generated to replace the EXEC SQL statements. You must also compile the program with the CHKECM(CTRACE) and LIST directives.
COBSQL
This feature is not supported for COBSQL programs.
Parent topic: Compiling SQL Applications


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 ADO for .NET managed code.
  • 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 Configuration Utility
    The purpose and use of the OpenESQL Configuration utility to specify the default behavior for the SQL(BEHAVIOR) compiler directive option.
  • Database Connections
    A discussion of the implicit and explicit database connection types, and how and under what circumstances to use each of them.
  • Setting OpenESQL Background Syntax Checking Options
    Explains how to set options that determine the level at which the OpenESQL preprocessor checks syntax in the background.
  • 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.
  • ADO.NET
    Information specific to developing and maintaining managed SQL applications that access ADO.NET data sources.
  • SQL CLR Integration Support
  • 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 ADO for .NET 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 Native Runtime
  • Enables maximum interoperability between different database systems
  • Provides comprehensive support for pessimistic (locking) concurrency control
  • Does not support disconnected or offline DataSets
ADO
Use OpenESQL with the ADO option to compile your .NET managed applications. This option:
  • Is invoked using the SQL(DBMAN=ADO) compiler directive
  • Uses ADO.NET data providers
  • Connects to one ADO.NET data source
  • Compiles applications to communicate with the OpenESQL Managed Runtime
  • Enables EXEC SQL statements to communicate with the ADO.NET data provider and data source name specified
  • Supports the use of EXEC ADO statements to create and manipulate ADO.NET objects
  • Maximizes scalability of data handling components in distributed systems
  • Is strongly biased in favour of optimistic (non-locking) concurrency control
  • Fully supports disconnected and offline DataSets
  • 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
Parent topic: OpenESQL


Scope - OpenESQL SQL Compiler Directive Options

Important: If you want to run your application under Enterprise Server using the 1PC ODBC XA switch module or the XA switch module for SQL Server, you must recompile the appropriate XA switch module if you use OpenESQL directives that are defined as process-based.
Each SQL compiler directive option is used either at compile time, runtime, 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
    • ADO.NET - .NET session, each session having its own set of global directive settings

For information on the scope of each SQL compiler directive option, see its corresponding Reference topic.

Parent topic: OpenESQL


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 | Maximize performance and talk to an SQL Server data store via a .NET data provider | SQL(DBMAN=ADO, TARGETDB=MSSQLSERVER, BEHAVIOR=MAINFRAME)
COBOL | ANSI compliant, and talk to an SQL Server data store via an ODBC driver | SQL(DBMAN=ODBC, TARGETDB=MSSQLSERVER, BEHAVIOR=ANSI)
COBOL | Maximize performance, not worry about mainframe compatibility, and talk to an Oracle data store via an ODBC driver | SQL(DBMAN=ODBC, TARGETDB=ORACLE, BEHAVIOR=MAINFRAME)
COBOL | Mimic Oracle Pro*COBOL functionality for SQL cursors, and talk to an Oracle data store via .NET data provider | SQL(DBMAN=ADO, TARGETDB=ORACLE, BEHAVIOR=ANSI)
Parent topic: OpenESQL


OpenESQL Configuration Utility

Use the OpenESQL Configuration utility to change the default behavior for the SQL(BEHAVIOR) directive option. OpenESQL uses this default only when SQL(BEHAVIOR) is not explicitly specified in one of the following places:

  • program source code
  • project settings
  • COBOL compiler directives file

When you specify the SQL(BEHAVIOR) directive in any of these places, the value you specify overrides the default set using the OpenESQL Configuration utility.

You can run this utility, using either its user-interface or command-line implementation (esqlconfig command), on each machine where you have installed Visual COBOL, to change the default behavior 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
Related concepts
DBMAN Directive Settings
Programming for OpenESQL
COBOL Program Migration Support
Related reference
esqlconfig command
BEHAVIOR
Related information
To start the OpenESQL Configuration Utility
To set a default for SQL(BEHAVIOR)
COBOL Program Migration Support


Optimize for performance and mainframe compatibility

Sets the SQL(BEHAVIOR) directive to SQL(BEHAVIOR=MAINFRAME), meaning that data access is read only for everything except data access that is explicitly specified as read only or 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).

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
Related reference
BEHAVIOR
Related information
To set a default for SQL(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 or 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).

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
Related reference
BEHAVIOR
Related information
To set a default for SQL(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
Related reference
BEHAVIOR
Related information
To set a default for SQL(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=UNOPTIMIZED).

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
Related reference
BEHAVIOR
Related information
To set a default for SQL(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
Related reference
BEHAVIOR
Related information
To set a default for SQL(BEHAVIOR)


Database Connections

Each OpenESQL preprocessor option - ODBC and ADO - The OpenESQL preprocessor 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.

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.

Important: ADO.NET does not support the use of implicit connections.

Explicit Connections

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.
Parent topic: OpenESQL
Related reference
CONNECT
DB
DISCONNECT
INIT
PASS


Setting OpenESQL Background Syntax Checking Options

Before compiling an OpenESQL application, you can set options that determine the level at which the OpenESQL preprocessor checks syntax in the background. To do this, click Tools > Options; then expand Micro Focus Visual COBOL and click OpenESQL Background Syntax Checking. You can set the following options:

  • Background Compile Setting > No syntax checking

    The precompiler does not connect to the DBMS and does not validate EXEC SQL statements; however, the precompiler does check host variables.

  • Background Compile Setting > Basic syntax checking

    The precompiler checks only ANSI and standard SQL syntax.

  • Background Compile Setting > Complete syntax checking

    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 Visual Studio documentation for information on setting properties.

Parent topic: OpenESQL


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 ADO.NET topic.

  • OpenESQL Assistant
  • Working With OpenESQL Cursors and Result Sets
  • Working With OpenESQL Stored Procedures and Result Sets
  • Unicode Support in OpenESQL
  • Keywords
Parent topic: OpenESQL
Related concepts
ODBC
ADO.NET
OpenESQL Configuration Utility


OpenESQL Assistant

The OpenESQL Assistant is an interactive tool that makes it easy for you to:

  • Prototype SQL SELECT, INSERT, UPDATE, and DELETE statements and test them against your database
  • Generate EXEC ADO statements
  • Insert your SQL queries into your COBOL code
  • Create and insert auxiliary code into your COBOL code
  • Tutorials: OpenESQL Assistant
    Use OpenESQL Assistant to generate SQL queries in a COBOL application.
  • Setting OpenESQL Assistant Options
  • Using OpenESQL Assistant
Parent topic: Programming for OpenESQL
Related concepts
Using OpenESQL with ADO.NET
Managed Code Concepts
Managed COBOL Restrictions
ADO.NET Data Providers and Data Source Names
Unicode Support in OpenESQL


Tutorials: OpenESQL Assistant

In this set of tutorials, you create an application using OpenESQL Assistant to generate an SQL query, embed that query into a program, and generate a copybook for host variables. It also takes you through the process of compiling and running the resulting application.

Tutorial Requirements

To complete the OpenESQL Assistant tutorials, you must have the following software installed:

  • Visual COBOL for Visual Studio 2010
  • Microsoft SQL Server 2008, including the SQL Server Management Studio

Additional requirements that apply to specific tutorials appear in the Requirements section of each.

Order

You must complete this series of tutorials in the following order:

  • Tutorial: Create a SQL Server Database
    Create a SQL Server database using Microsoft SQL Server 2008 Management Studio.
  • Tutorial: Create and Configure a Visual Studio Project
    Create and configure a Visual Studio Managed COBOL solution and project in which to create an application.
  • Tutorial: Set OpenESQL Assistant Configuration Options
    Set configuration options for the OpenESQL Assistant.
  • Tutorial: Catalog a Connection
    Catalog a connection to the database you created in a previous tutorial.
  • Tutorial: Build and Test a Query
    Use the OpenESQL Assistant to build and test an SQL query.
  • 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.
  • 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.
  • Tutorial: Build and Run the Application
    Add the generated copybook to the OESQLAssistantTutorial project, set a break point, and build and run the resulting application.
Parent topic: 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. Start the Microsoft SQL Server 2008 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. Open and execute CreateAndLoadOESQLDemo.sql, located in your %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples\sql\OpenESQL\SampleData directory.

    This SQL script creates a SQL Server database named OESQLDemo, and creates the schemas and tables required to complete the OpenESQL Assistant tutorials.

  4. Close SQL Server 2008 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 %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples\sql\OpenESQL\SampleData directory.
  2. Enter:

    sqlcmd -S . -E -i CreateAndLoadOESQLDemo.sql

This completes the tutorial. Next, please complete Tutorial: Create and Configure a Visual Studio Project.

Parent topic: Tutorials: OpenESQL Assistant


Tutorial: Create and Configure a Visual Studio Project

In this tutorial, you create a Visual Studio Managed 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.
Phase 1: Launch Visual COBOL for Visual Studio 2010
  • Click Start > All Programs > Micro Focus Visual COBOL > Visual COBOL for Visual Studio 2010.
Phase 2: Create a New Managed COBOL Project
In this set of tutorials, you create a Managed COBOL application to take advantage of the features available in the ADO.NET connection editor, and the OpenESQL Managed Runtime.
  1. From the Visual Studio IDE, click File > New > Project.
  2. Under Installed Templates, click COBOL > Managed.
  3. Click Console Application.
  4. In the Name field, type OESQLAssistantTutorial.
  5. In the Location field, specify a directory in which to store the project; then click OK.

    Visual Studio creates a new solution and a project named OESQLAssistantTutorial. The project contains one generic program, Program1.cbl, that we use in a later tutorial. If Visual Studio has automatically opened this file for editing, close it for now.

Phase 3: Set Project Properties
To compile this application such that it connects to the database via ADO.NET, we must set the project properties to include the DBMAN=ADO SQL compiler directive option. We must also set the BEHAVIOR compiler directive to provide optimal cursor behavior, including isolation level and lock concurrency settings.
  1. From the Solution Explorer, double-click Properties under your OESQLAssistantTutorial project.
  2. On the SQL tab, select OpenESQL from the ESQL Preprocessor drop-down list; then click Add.
  3. On the Available Directives list, click DBMAN; then click OK.
  4. From the Value drop-down, select ADO.
  5. Click Add.
  6. On the Available Directives list, click BEHAVIOR; then click OK.
  7. From the Value drop-down, select ANSI.
  8. Save your changes and close the Properties window.

This concludes this tutorial. Please continue with Tutorial: Set OpenESQL Assistant Configuration Options.

Parent topic: Tutorials: OpenESQL Assistant


Tutorial: Set OpenESQL Assistant Configuration Options

You can configure several features within OpenESQL Assistant, but for the purposes of this tutorial, we 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 Object, your compiled application communicates with the OpenESQL Managed Runtime, greatly 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 a Visual Studio Project
Set the Type COBOL Variable Option
  1. From the Visual Studio IDE, click Tools > Options > Micro Focus Visual COBOL > OpenESQL Assistant.
  2. Change the value of Type COBOL Variable from Standard to Object; then click OK.

This completes the tutorial. Next, please complete Tutorial: Catalog a Connection.

Parent topic: Tutorials: OpenESQL Assistant


Tutorial: Catalog a Connection

Before you can connect to the SQL Server database you created earlier, you must catalog it using the ADO.NET Connection Editor.

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 a Visual Studio Project
  • Tutorial: Set OpenESQL Assistant Configuration Options
Phase 1: Start the OpenESQL Assistant
You can start the OpenESQL Assistant from the Start menu or from within Visual Studio. In this tutorial, we opt to start the OpenESQL Assistant from within Visual Studio.
  • From the Visual Studio IDE, click Tools > Micro Focus Visual COBOL > OpenESQL Assistant.
Phase 2: Start the ADO.NET Connection Editor
You can start the ADO.NET Connection Editor from the Start menu, or from within the OpenESQL Assistant. Here, we start it from within the OpenESQL Assistant.
  • From the OpenESQL Assistant, click ADO.NET Connection Editor Button ADO.NET Connection Editor.
Phase 3: Catalog the OESQLDemo Connection
In this phase, we catalog a 32-bit connection to our SQL Server database.
Important: If you are running on a 64-bit machine, you must catalog a 64-bit connection in addition to the 32-bit connection. Both connections have the same data source name. To do this, complete all of the steps in this phase, and then repeat the steps of this phase with the following change:
  • Before performing step 1, on the Connection tab, click 64 bit.
  1. On the Connection tab, click Add.
    Note: The 32-bit connection cataloged here does not require that we change any of the default settings on the Connection tab of the ADO.NET Connection Editor.
  2. In the grid on the Provider tab, click SqlClient Data Provider.
  3. In the Data Source Name field, type OESQLDemo, which is the name of your connection; then click Next, which takes you back to the Connection tab.
  4. With OESQLDemo selected on the Data Source Name list, modify the following fields on the Connection Settings grid, providing the appropriate values:
    Field | Value
    Initial Catalog | OESQLDemo
    Data Source | (local)
    Integrated Security | True
  5. Click Save to save your changes.
  6. Click Test Connection to ensure the connection works properly; then click OK to clear the message.
Phase 4: Close the ADO.NET Connection Editor
  • Click OK to close the ADO.NET Connection Editor.

    The OESQLDemo connection now appears on the list in the OpenESQL Assistant.

Phase 5: Refresh the Database Connection
For Visual Studio to recognize the connection you have cataloged, you must refresh it in the Server Explorer.
  1. From the Visual Studio IDE, open the Server Explorer.
  2. Right-click the connection listed for OESQLDemo, and select Refresh.

This completes the tutorial. Next, please complete Tutorial: Build and Test a Query.

Parent topic: Tutorials: OpenESQL Assistant


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 a Visual Studio Project
  • Tutorial: Set OpenESQL Assistant Configuration Options
  • Tutorial: Catalog a Connection
Phase 1: 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.
  2. Check the box next to EMP.

    The Select Type of Query to Create dialog box enables you to choose the type of query you want to generate. In this case, we want to create a simple SELECT CURSOR statement. OpenESQL Assistant generates a default cursor name that we have the option to override. Here, we'll 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.

Phase 2: Select Columns
We want our SQL query to return the first and last names of our employees along with the pay rate for each employee.
  • Check the following column names:
    • A.FIRSTNME
    • A.LASTNAME
    • A.SALARY

    OpenESQL Assistant updates the Query tab with the appropriate code.

Phase 3: Test the Query
Our SQL query is complete at this point so we can test it.
  • Click Run Query Run Query.

    The OpenESQL Assistant shows the results of the query on the Results tab.

This completes the tutorial. Next, please complete Tutorial: Generate and Embed an SQL Program.

Parent topic: Tutorials: OpenESQL Assistant


Tutorial: Generate and Embed an SQL Program

Now that the SQL query has been generated, we 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 a Visual Studio Project
  • Tutorial: Set OpenESQL Assistant Configuration Options
  • Tutorial: Catalog a Connection
  • Tutorial: Build and Test a Query
Phase 1: Generate a Generic SQL Program
  1. Click the Auxiliary Code tab.
  2. From the drop-down list, click Generic SQL Program.

    OpenESQL Assistant generates a generic SQL program in the right-hand pane of the Auxiliary Code tab.

Phase 2: Open Program1.cbl
In this phase, we open the program that was automatically generated when we created the OESQLAssistantTutorial project, and delete its contents so we can replace them with the code generated by OpenESQL Assistant.
  1. In Solution Explorer, double-click Program1.cbl.

    This opens the source code editor with the cursor placed at the very beginning of the file.

  2. Select and delete all text in the file.
Phase 3: Embed the Generic SQL Program
We're now ready to embed our generic SQL program into the Program1.cbl file.
  1. Place your cursor at the beginning of the Program1.cbl file.
  2. From the OpenESQL Assistant Auxiliary Code tab, click Insert Query Into Current Program Insert Query Into Current Program.

    The generated code appears in Program1.cbl.

  3. Save Program1.cbl.
Phase 4: Embed the SQL Query
Next, we embed our SQL query into the generic program.
  1. In the program editor for Program1.cbl, place the cursor on the line just after the comment:
    *> Put your program logic/SQL statements here
  2. On the OpenESQL Assistant, click the Query tab; then click Insert Query Into Current Program Insert Query Into Current Program.

    OpenESQL Assistant inserts the query into the program.

This completes the tutorial. Next, please complete Tutorial: Provide Additional Code.

Parent topic: Tutorials: OpenESQL Assistant


Tutorial: Provide Additional Code

Our application will not compile and run unless we provide code that declares our table, provides a COBOL record to receive the data, and provides a COBOL record for indicator variables. We can use OpenESQL Assistant to generate a copybook that contains all of this code and an INCLUDE statement to call the copybook. We can also use OpenESQL Assistant to embed the INCLUDE statement into the program.

We want to send the output from the application to the console in a readable format. This requires additional code we 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 a Visual Studio Project
  • Tutorial: Set OpenESQL Assistant Configuration Options
  • Tutorial: Catalog a Connection
  • Tutorial: Build and Test a Query
Phase 1: Generate a Copybook
We 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, right-click the EMP table; then 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 Visual Studio 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 for the 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.
Phase 2: Embed the INCLUDE statement
We need to embed the generated INCLUDE statement into our program.
  1. In the program editor for Program1.cbl, place the cursor on the line just after the EXEC SQL INCLUDE SQLCA statement.
  2. From the OpenESQL Assistant Auxiliary Code tab, click Insert Query Into Current Program Insert Query Into Current Program.

    OpenESQL Assistant inserts the generated INCLUDE statement into the program.

  3. Save Program1.cbl.
Phase 3: Add Code to Format Output
When we run our program, we want to be able to see the results of the query as easily as we see them when we run the query in the OpenESQL Assistant. To achieve this, we 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. With Program1.cbl showing in the source code 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 SQLSTATE < "02000"
  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 Program1.cbl.

This completes the tutorial. Next, please complete Tutorial: Build and Run the Application.

Parent topic: Tutorials: OpenESQL Assistant


Tutorial: Build and Run 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 a Visual Studio 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
Phase 1: Add the Generated Copybook to the Project
While the OpenESQL Assistant generated and saved the copybook necessary to compile the application, it does not automatically add the file to the current project. The copybook must be part of the project to be included in the compiled application.
  1. From the Solution Explorer, right-click the OESQLAssistantTutorial project and select Add > Existing Item.
  2. Select EMP.cpy; then click Add.

    The EMP.cpy copybook is added to the project.

Phase 2: Add a Break Point
The program sends output to the console, and we want the application to pause at the point where we can see the output.
  1. If it isn't already in the program editor, double-click Program1.cbl from the Solution Explorer to call it up into the program editor.
  2. In ther program editor, scroll down to the following line of code:
    EXEC SQL DISCONNECT CURRENT END-EXEC
  3. Press F9 to toggle a break point.
  4. Save Program1.cbl.
Phase 3: Build the Application
  1. From the Solution Explorer, right-click the OESQLAssistantTutorial project and select Build.
Phase 4: Run the Application
  1. Press F5 to start debugging.
  2. If the console is not visible, minimize Visual Studio. You should see the console output.
  3. Press F5 again to complete the debugging process.

This completes the OpenESQL Assistant tutorials.

Parent topic: Tutorials: OpenESQL Assistant


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. To do this, click Tools > Options; then expand Micro Focus Visual COBOL and click OpenESQL Assistant. You can set the following 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.
DCLGEN > 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, or set it to OBJECT to provide better performance for .NET applications.
DCLGEN > 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. You set this option to Other, specify your own structure in the DCLGEN > User Defined Structure Name field.
DCLGEN > 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.
DCLGEN > 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 > Mode
  • ADO.NET - builds the list of data sources using the information maintained by the Connection Editor (32-bit version). Default.
  • ODBC - builds the list of data sources maintained by the ODBC Data Source Administrator (32-bit version).

    Set this option before connecting to a data source. When in ADO.NET mode, you can also set the following:

General > Start OpenESQL Assistant docked
By default, OpenESQL Assistant is not docked to Visual Studio. Set this option to True if you want OpenESQL Assistant to start docked to Visual Studio.
General > 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.
General > Automatically catalog data source
OpenESQL under .NET supports both EXEC SQL and EXEC ADO access to managed data sources. There currently exists no common repository for sharing connection information between ADO.NET data providers. However, we provide a common repository that all COBOL applications can use to save connection information. This also allows OpenESQL to be source code compatible when using EXEC SQL CONNECT statements. If you check this option, OpenESQL Assistant automatically transfers the ODBC connection information into the repository when you CONNECT to a data source.

OpenESQL Assistant also includes an ADO.NET Connection Editor which allows you to manually add connection information.

Once you have cataloged all your data sources in the repository you can uncheck this option.

General > 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.
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.
Logon > User name and Password
If you choose not to specify a user ID or password here, OpenESQL Assistant prompts you for your user ID and password when connecting to a data source. Depending on how you define your connection names, you might have the option of saving your login user name and password via the ADO.NET Connection Editor.
Query > Type Stored Procedure
Select one of the following types:
  • TSQL - Generates TSQL stored procedures when you check Generate query as Stored Procedure when selecting the type of query to generate. Default.
  • SQLCLR - Generates SQL CLR stored procedures when you check Generate query as Stored Procedure when selecting the type of query to generate.
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.
Query > 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.
Query > 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.
Query > 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.
Query > 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.
Query > Generate
Select one of three statement types:
  • EXEC SQL
  • EXEC ADO - disconnected model
  • EXEC ADO - connected model

By default, OpenESQL Assistant generates EXEC SQL statements. However, you can change it to build EXEC ADO statements if you have set Mode to ADO.NET and want to build EXEC ADO queries. You can then also generate EXEC ADO Disconnected or Connected statements as auxiliary code.

Restrict Tables
When using ADO.NET mode:
  • Wildcard characters are not supported.
  • The qualifier, owner, and table name are case sensitive for some data providers and not for others. You might need to experiment when setting these restrictions.

See your Visual Studio documentation for information on setting properties.

Parent topic: OpenESQL Assistant
Related tasks
To configure the OpenESQL Assistant
To create a TSQL stored procedure query
To create a SQL CLR database project
To create a SQL CLR stored procedure query
Related reference
SQL TYPEs


Using OpenESQL Assistant

Use the OpenESQL Assistant to easily design and build SQL queries and embed those queries into your COBOL 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.

  • Starting the OpenESQL Assistant
  • Connecting to a Data Source
  • Building Queries
  • Testing Your SQL Queries
  • Embedding SQL into a Program
  • Auxiliary Code
  • Stored Procedures
Parent topic: OpenESQL Assistant


Starting the OpenESQL Assistant

You can configure the OpenESQL Assistant's dockable window to appear when you start Visual Studio or you can simply invoke it when you need it.

Depending on how OpenESQL is configured, you might be prompted to supply a user name and password.

Parent topic: Using OpenESQL Assistant
Related tasks
To start the OpenESQL Assistant


Connecting to a Data Source

Before you can use OpenESQL Assistant to generate SQL, you must first connect to the data source that contains the data you want to access. All data sources cataloged on your workstation are listed in the tree view of the OpenESQL Assistant. You can only connect to one data source at a time. After you have connected, all of the table names in the data source show on the tree view.

Important: You must connect to a 32-bit data source even if the generated application targets a 64-bit platform.
Note:
  • You can use the ADO.NET Connection Editor to catalog other data sources as ADO.NET data providers.
  • If you receive a connect error, OpenESQL Assistant prompts you for your User ID and Password if you don't want to save the information with connection settings.
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.

  • Selecting a Table and a Query Type
  • 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 tasks
To create a TSQL stored procedure query
To start the OpenESQL Assistant
To connect to a data source
To create an SQL query
To create a SQL CLR stored procedure query
To create a SQL CLR database project
To generate a SQL CLR stored procedure


Selecting a Table and a Query Type

You can select one table at a time or you can select all of the tables in a data source. OpenESQL Assistant prompts you to select the type of query you would like to perform on the table or tables by presenting the Select Type of Query to Create dialog box. This dialog box contains a list of query types you can perform on your selection. Depending on the type of query you select, you can also change the default cursor name, specify that your query be generated as a Stored Procedure, and specify the stored procedure (SP) name.

Selected tables appear in the tree view with a check mark next to the table icon, Checked Table.

Once you have selected a query, the COBOL 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 generated automatically 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.

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.

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.

If the name generated from the column name (including any prefixes and suffixes) is longer than 31 characters or contains illegal characters would be 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 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 your table and query type selected, you can select one or more columns to process in your query.

Selected columns appear in the tree view with a check mark next to the column icon, Checked Column.

Parent topic: Building Queries
Related tasks
To add a column to a query
To add all columns in a table 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
Related tasks
To perform an aggregate function


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)


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 section Auxiliary Code later in this chapter 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 tasks
To display column details


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
Related tasks
To change a SELECT (cursor) query to do an array FETCH


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.
Parent topic: Using OpenESQL Assistant


Embedding SQL into a Program

Once you are happy with the SQL query that you have created, you can insert it into your COBOL program.

Parent topic: Using OpenESQL Assistant
Related tasks
To generate and embed auxiliary code
To embed an SQL query into a COBOL program
To change a SELECT (cursor) query to do an array FETCH


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
  • Generating EXEC ADO Auxiliary Code
Parent topic: Using OpenESQL Assistant
Related tasks
To generate and embed auxiliary code
To embed an SQL query into a COBOL program
To change a SELECT (cursor) query to do an array FETCH


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 Program

    Generates a skeleton SQL program that includes the INCLUDE SQLCA, CONNECT and DISCONNECT SQL statements and a default SQL error routine.

  • CALL Stored Procedure

    Generates the code to call the stored procedure when creating a SQL CLR stored procedure query.

Parent topic: Auxiliary Code
Related tasks
To generate and embed auxiliary code
To embed an SQL query into a COBOL program
To change a SELECT (cursor) query to do an array FETCH
To generate a SQL CLR stored procedure


Embedding Auxiliary Code

You embed auxiliary code in the same manner as you embed your SQL queries.

Parent topic: Auxiliary Code
Related tasks
To generate and embed auxiliary code
To embed an SQL query into a COBOL program
To change a SELECT (cursor) query to do an array FETCH


Generating EXEC ADO Auxiliary Code

If you have enabled OpenESQL Assistant to generate EXEC ADO code by checking the Generate EXEC ADO option when you set options for OpenESQL, you can generate auxiliary code for both the EXEC ADO disconnected and connected models.

OpenESQL Assistant embeds the dataset name you specify in the Dataset name field on the Auxiliary Code tab into all generated statements that cite a dataset.

Note: You can mix EXEC ADO and EXEC SQL statements in the same program providing that you compile your COBOL program with the directive SQL(DBMAN=ADO).
  • Generated EXEC ADO Statements
  • Disconnected Model Statements
  • Connected Model Statements
  • EXEC ADO Wizards
Parent topic: Auxiliary Code


Generated EXEC ADO Statements

OpenESQL Assistant can generate the following types of EXEC ADO auxiliary code. For a description of each, see the section Using Embedded EXEC ADO Statements in the chapter Using OpenESQL with ADO.NET.

Connected or Disconnected Models

  • DECLARE DATASET
  • DECLARE DATATABLE
  • GET CHANGES
  • INITIALIZE DATASET
  • UNBIND DATASET

Disconnected Models

  • ACCEPT CHANGES
  • BIND DATASET
  • BIND DATATABLE
  • CLEAR
  • DECLARE DATATABLE
  • DECLARE UNTYPED DATASET
  • GET DATATABLE
  • INITIALIZE DATASET
  • INITIALIZE DATATABLE
  • LOAD DATASET
  • MERGE DATASET
  • REJECT CHANGES
  • SAVE DATASET
  • SAVE DATATABLE
  • UNBIND DATASET
  • UNBIND DATATABLE
  • USING DATASET
  • Generic SQL Program

    Generates a skeleton SQL program that includes the INCLUDE SQLCA statement and a default SQL error routine.

Connected Models

  • BIND CONNECTION
  • FILL DATASET
  • GET CONNECTION
  • PREPARE TO FILL
  • PREPARE TO UPDATE
  • REBIND CONNECTION
  • UNBIND DATASET
  • UPDATE DATASOURCE
  • UNBIND CONNECTION
  • TO DELETE USE
  • TO FILL USE
  • TO INSERT USE
  • TO REFRESH USE
  • TO UPDATE USE
  • Generic SQL Program

    Generates a skeleton SQL program that includes the INCLUDE SQLCA, CONNECT and DISCONNECT SQL statements and a default SQL error routine.

Parent topic: Generating EXEC ADO Auxiliary Code


Disconnected Model Statements

Disconnected model statements enable you to define, create and manipulate ADO.NET objects in COBOL. They are commonly used to:

  • Define DataTables and their relationships to each other within a DataSet
  • Insert, update and delete DataRows in a DataTable
  • Select DataRows from a DataTable
  • Clear DataTables in a DataSet
  • Commit or rollback pending changes in a DataSet
  • Load an existing XML DataSet file into a COBOL DataSet
  • Save a DataSet to a file in XML format.

The following disconnected model statements are available to you:

  • BIND DATATABLE – allows an ADO.NET DataTable to be shared with OpenESQL
  • BIND DATASET – allows an ADO.NET DataSet to be shared with OpenESQL
  • CLEAR - clears the data in specified DataTables of a DataSet
  • DECLARE DATATABLE – defines a DataTable
  • DECLARE DATASET – defines a DataSet
  • GET DATATABLE – copies a DataTable object into a host variable or creates a DataTable object within a host variable
  • INITIALIZE DATATABLE – creates a DataTable
  • INITIALIZE DATASET – creates a DataSet
  • INSERT – adds DataRows into a DataTable
  • DELETE (SEARCHED) – deletes DataRows from a DataTable
  • UPDATE (SEARCHED) – updates DataRows in a DataTable
  • SELECT INTO – retrieves DataRows from a DataTable
  • CLEAR – clears the DataTables in a DataSet
  • ACCEPT CHANGES – commits pending changes to a DataSet.

    Note that, this statement does not commit changes to a database. To commit changes to a database, you must use the connected model to synchronize the DataSet with the database and then use the EXEC SQL COMMIT statement.

  • REJECT CHANGES – rolls back pending changes made to a DataSet.

    Note that, this statement does not roll back changes made to a database. To roll back changes in a database, you must use the connected model to synchronize the DataSet with the database and then use the EXEC SQL ROLLBACK statement.

  • LOAD DATATABLE – loads a DataTable from an XML file
  • LOAD DATASET – loads a DataSet from an XML file
  • SAVE DATATABLE – saves a DataTable to an XML file
  • SAVE DATASET – saves a DataSet to an XML file
  • MERGE DATATABLE – merges two similar DataTables together
  • MERGE DATASET – merges two similar DataSets together
  • UNBIND DATATABLE – disassociates OpenESQL from a DataTable in another ADO.NET application
  • UNBIND DATASET – disassociates OpenESQL from a DataSet in another ADO.NET application
  • USING – defines a default DataSet for EXEC ADO processing
Parent topic: Generating EXEC ADO Auxiliary Code
Parent topic: Using Embedded EXEC ADO Statements


Connected Model Statements

Connected model statements enable you to interact with a data source. The FILL commands retrieve data from a data source and place it into the DataTables of a DataSet. The UPDATE commands ensure that any Data Manipulation Language (DML) changes (INSERT, UPDATE, and DELETE) are returned to the data source.

The following connected model statements are available to you:

  • PREPARE TO FILL – signals the DataSet to be filled
  • TO FILL USE – specifies the logic to retrieve data from table in data source to DataTable in DataSet
  • FILL – does the actual fill of the DataTables
  • PREPARE TO UPDATE – signals the DataSet whose DML changes are to be placed in a data source
  • TO DELETE USE – specifies the delete logic to be used in a data source
  • TO INSERT USE – specifies the insert logic to be used in a data source
  • TO REFRESH USE – specifies the refresh logic to be used in a data source
  • TO UPDATE USE – specified the update logic to be used in a data source
  • UPDATE – does the actual update to a data source
Parent topic: Generating EXEC ADO Auxiliary Code
Parent topic: Using Embedded EXEC ADO Statements


EXEC ADO Wizards

Certain EXEC ADO statements require a significant amount of user input to build them correctly. When you use the OpenESQL Assistant Auxiliary Code tab to generate one of these statements, you invoke a wizard that walks you through the various options for that statement.

The statements generated by these wizards are very similar to the EXEC ADO DELETE, INSERT, SELECT, and UPDATE statements except that you cannot execute them from the OpenESQL Assistant. Because the Wizards need table and column names to work correctly, you must create a query first.

OpenESQL Assistant provides the following wizards for use in generating auxiliary code:

  • TO DELETE USE Wizard

    Use this wizard to build a WHERE clause that limits what values to delete from a data source when the data source is updated. The wizard provides a page similar to the Search Criteria tab. It is not necessary for you to supply a Target type or Value because these are dependent upon the column selected.

    Embed the generated TO DELETE USE statement into your program after an EXEC ADO PREPARE TO UPDATE statement and before the EXEC ADO UPDATE DATASOURCE statement.

  • TO FILL USE Wizard

    Use this wizard to limit the number of rows and columns that are returned from the data source when the EXEC ADO FILL DATASET statement is executed. The wizard provides pages that enable you to:

    • Specify all columns or specific columns
    • Specify search criteria to use in building a WHERE clause
    Note: If you specify a literal value as part of your WHERE clause, surround it with either single or double quotes depending on which identifier your DBMS uses to enclose literals.

    For the generated statement to work properly you must have DECLARE DATATABLE and DECLARE DATASET statements coded into your program, and you must embed the TO FILL USE statement into your program after a PREPARE TO FILL statement.

    The ConnectedDemo application provided by Micro Focus shows detailed examples of using the TO FILL USE statement in an application. For more information, see the section Demonstration Projects in the chapter Using OpenESQL with ADO.NET.

  • TO INSERT USE Wizard

    Use this wizard limit what values to insert into a data source when the data source is updated. The wizard provides pages that enable you to:

    • Optionally generate a WITH REFRESH clause

      You should opt to generate this clause if you want data to be returned to your application after updating a data source with newly inserted rows.

    • Specify all columns or specific columns
    • Specify search criteria to use in building a WHERE clause
    • Specify the source data and column you want to return

      You can specify these only if you have opted to generate the WITH REFRESH clause. The pre-defined source value “@@IDENTITY” is provided to work with Microsoft SQL Server data providers.

    Embed this statement into your program after an EXEC ADO PREPARE TO UPDATE statement and before the EXEC ADO UPDATE DATASOURCE statement.

  • TO REFRESH USE WizardSpecify the source data and column you want to refresh

    Use this wizard to generate an EXEC ADO TO REFRESH statement to update values in your dataset after updating the data source. Generate this statement in lieu of placing the REFRESH clause in TO INSERT or TO UPDATE EXEC ADO statements. The wizard provides one page that enables you to specify the source data and column you want to return. The pre-defined source value “@@IDENTITY” is provided to work with Microsoft SQL Server data providers.

    Embed this statement into your program after an EXEC ADO PREPARE TO UPDATE statement and before the EXEC ADO UPDATE DATASOURCE statement.

  • TO UPDATE USE Wizard

    Use this wizard to limit what columns and values to update to a data source. The wizard provides pages that enable you to:

    • Optionally generate a WITH REFRESH clause

      You should opt to generate this clause if you want data to be returned to your application after updating a data source with new values.

    • Specify all columns or specific columns
    • Specify search criteria to use in building a WHERE clause

      It is not necessary for you to supply a Target type or Value when building your WHERE clause because these are dependent upon the column selected.

    • Specify the source data and column you want to return

      You can specify these only if you have opted to generate the WITH REFRESH clause. The pre-defined source value “@@IDENTITY” is provided to work with Microsoft SQL Server data providers.

    Embed this statement into your program after an EXEC ADO PREPARE TO UPDATE statement and before the EXEC ADO UPDATE DATASOURCE statement.

Parent topic: Generating EXEC ADO Auxiliary Code


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 TSQL stored procedures and the COBOL code required to invoke those stored procedures.

The steps are similar for generating a SQL CLR stored procedure. For SQL CLR stored procedures, OpenESQL Assistant generates an entire COBOL program, including the .NET variables needed to execute the query.

  • Generating a TSQL Stored Procedure Query
  • Testing a TSQL Stored Procedure Query
  • Embedding a TSQL Stored Procedure into a Program
  • Generating a SQL CLR Stored Procedure Query
  • Testing a SQL CLR Stored Procedure Query in a SQL CLR Project
Parent topic: Using OpenESQL Assistant
Related tasks
To create a TSQL stored procedure query
To create a SQL CLR stored procedure 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 COBOL program


Generating a SQL CLR Stored Procedure Query

Microsoft provides tools to create, edit, and test SQL CLR stored procedures. It is then the task of the programmer to generate the code to invoke SQL CLR 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 SQL CLR stored procedure. OpenESQL Assistant generates both the SQL statements to create a SQL CLR stored procedure and the client code to invoke it.

OpenESQL Assistant generates the entire SQL CLR stored procedure COBOL program in a SQL CLR Project. You can easily add the generated program to a COBOL SQL CLR Database project. If you decide to modify the query later, OpenESQL Assistant gives you the option to replace the program in the project by just re-building the query using the same SQL CLR stored procedure name.

OpenESQL Assistant also generates the code that goes into the client program and invokes the SQL CLR stored procedure. You can select code that calls a SQL CLR stored procedure from the Auxiliary Code tab when building the stored procedure query.

Parent topic: Stored Procedures
Related tasks
To generate a SQL CLR stored procedure
To create a SQL CLR database project
To add or update a SQL CLR Stored Procedure in a SQL CLR Database project
To create a SQL CLR stored procedure query
To generate and embed auxiliary code


Testing a SQL CLR Stored Procedure Query in a SQL CLR Project

Once you have built the SQL CLR stored procedure query, you can test it in the same manner as you test other SQL queries with in OpenESQL Assistant.

Microsoft also provides tools via Server Explorer or SQL Server Management Studio to test a SQL CLR stored procedure once it has been deployed.
Parent topic: Stored Procedures
Related tasks
To add or update a SQL CLR Stored Procedure in a SQL CLR Database project
To generate a SQL CLR stored procedure


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
Working With OpenESQL Stored Procedures and Result Sets
Related reference
DECLARE CURSOR
FETCH
GET NEXT RESULT SET


Working With OpenESQL Stored Procedures and Result Sets

An OpenESQL 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, or the EXECSP embedded SQL statement if you want to ensure backward compatibility with the Micro Focus Embedded SQL Toolkit for Microsoft SQL Server. For complete details on using these statements, see the CALL and EXECSP topics.

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.

Coding a SQL CLR Stored Procedure to Return Result Sets

You return multiple result sets to a calling program by declaring one or more cursors in a stored procedure, and defining each declared cursor to return multiple result sets by including multiple SELECT statements in its definition.

To return multiple result sets for a particular cursor, its DECLARE CURSOR statement in your stored procedure 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

      EXEC SQL
      DECLARE C2 CURSOR
      FOR
          SELECT COMPNAME FROM COMPANY;
      END-EXEC
      EXEC SQL OPEN C2 END-EXEC

In this example, we have two cursors, C1 and C2, with C1 returning two result sets, and C2 returning one result set. Therefore, these cursors return a total of three result sets to the calling application.

When you are done with cursor processing in the stored procedure itself, close each cursor using a CLOSE statement that includes the WITH RETURN clause. For example:
EXEC SQL CLOSE C1 WITH RETURN TO CALLER END-EXEC
EXEC SQL CLOSE C2 WITH RETURN TO CALLER END-EXEC

Once the cursors are closed, the result sets associated with them become available to the calling application.

Note: Any forward only read only cursor that is open when the stored procedure returns is also returned to the calling application.
Parent topic: Programming for OpenESQL
Related concepts
Working With OpenESQL Cursors and Result Sets
Related reference
CALL
EXECSP
DECLARE CURSOR
FETCH
GET NEXT RESULT SET


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.

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


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 Native 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 provided to illustrate programming techniques and runtime behavior for native applications using ODBC, along with a description of each of these applications.
  • ODBC Drivers and Data Source Names
    Install ODBC drivers and create DSNs.
  • Using OpenESQL with ODBC
    Programming and compiling OpenESQL native SQL applications with ODBC.
  • 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

A number of ODBC demonstration applications are supplied in the Samples Browser, available from Start > All Programs > Micro Focus Visual COBOL > Samples. These files are located in the %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples\sql\openesql directory by default.

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 demonstration applications all produce a console log displaying their progress and, possibly, query results. They all terminate on receipt of an error, after displaying an error message.

The following applications are provided:

  • Behavior Demo

    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.

  • Catalog Demo

    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.

  • Connect Demo

    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.

  • Select Demo

    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.

  • Static Demo and Dynamic Demo

    Both applications run the same sequence of tests, but using different SQL syntax options. They both start by prompting for a data source and user name. The test sequence is:

    1. connect
    2. drop test table
    3. create test table
    4. insert a row
    5. commit
    6. update the row
    7. read and verify
    8. rollback
    9. read and verify
    10. drop test table
    11. disconnect
    12. create test table

    Step two may output an error message - this is expected and the programs will continue. The final stage should produce an error message, and again this is not treated as a genuine error (though the absence of an ODBC error is treated as a test failure).

  • Whenever Demo

    Attempts to connect and displays an error message. Displays an SQL Data Sources dialog. Select the DSN name you created and click on OK. A Login dialog is displayed. Enter a login name of "admin", leave the password blank and click on OK. Tests error handling and outputs two error messages.

Parent topic: ODBC


ODBC Drivers and Data Source Names

To use ODBC with OpenESQL, you must install at least one ODBC driver. Most Windows operating systems automatically install several ODBC drivers. You can use one of these or install additional drivers of your choice.

Once your driver is installed, you must then create at least one data source name (DSN) that identifies a database to which you can connect. Do this using the ODBC Data Source Administrator, available from Start > All Programs > Micro Focus Visual COBOL > Data Tools > Data Connections > ODBC Data Source Administrator.

Parent topic: ODBC


Using OpenESQL with ODBC

When using the ODBC option, follow the programming and compiling guidelines provided for OpenESQL in general. In addition, the following topics provide information specific to working with ODBC:

  • Managing Transactions
  • Positioned Update
  • XML Support
Parent topic: ODBC


Managing Transactions

With OpenESQL, you can use the COMMIT and ROLLBACK statements to exploit the transaction control facilities of ODBC. Although ODBC specifies transaction AUTOCOMMIT after each statement as the default mode of operation, OpenESQL turns this off for greater compatibility with other SQL systems. If you require this functionality, specify the AUTOCOMMIT option of the SQL Compiler directive.

Note:

Not all ODBC drivers implement transaction processing and those that do not may make updates to the database permanent immediately. For more information see your database driver documentation.

Parent topic: Using OpenESQL with 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

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

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

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

In many cases, the application server will provide transaction management. This will be 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, you must do the following:

  • If connection management is not provided by the application server (that is, your application uses connect and disconnect statements), you must use the SQL(AUTOCOMMIT) directive. This does not mean that your SQL statements will be committed automatically, rather that your application will not be handling transactions by COMMIT and ROLLBACK statements.
  • Your application must not use OpenESQL COMMIT and ROLLBACK statements. Instead, your application server will 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

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

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


ADO.NET

Use OpenESQL with the ADO option to compile your managed applications. This option:
  • Is invoked using the SQL(DBMAN=ADO) compiler directive
  • Uses ADO.NET data providers
  • Connects to one ADO.NET data source
  • Compiles applications to communicate with the OpenESQL Managed Runtime
  • Enables EXEC SQL statements to communicate with the ADO.NET data provider and data source name specified
  • Supports the use of EXEC ADO statements to create and manipulate ADO.NET objects
  • Maximizes scalability of data handling components in distributed systems
  • Is strongly biased in favour of optimistic (non-locking) concurrency control
  • Fully supports disconnected and offline DataSets
  • 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
  • Demonstration Applications
    A list of available demonstration applications provided to illustrate programming techniques and runtime behavior for managed applications using ADO.NET, along with a description of each of these applications.
  • ADO.NET Data Providers and Data Source Names
    Instructions for obtaining ADO.NET data providers and creating a data source name.
  • ADO.NET Connection Editor
    the ADO.NET Connection Editor enables you to catalog connections used used by the OpenESQL Managed Runtime.
  • Using OpenESQL with ADO.NET
    Programming and compiling OpenESQL managed SQL applications with ADO.NET.
Parent topic: OpenESQL
Related concepts
Programming for OpenESQL
Related reference
DBMAN


Demonstration Applications

A number of ADO.NET demonstration applications are supplied in the Samples Browser, available from Start > All Programs > Micro Focus Visual COBOL > Samples. The default location for these files is %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples\sql\ado.net.

Each sample application comes with a Readme file to explain how to use the application, and a makefile.

Before you can use any of the demonstration applications, you need to set up the data sources used by the demonstrations. You can do this with the ADO.NET Connection Editor.

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

  • Connected Demo

    Connected Demo uses the SQL Server Northwind database. You must set up a connection to the Northwind database to run the Connected Demo project.

    The ConnectedDemo.cbl program fills a DataSet from a data source, modifies the DataSet and then synchronizes the changes in the DataSet with the data source. The modified contents of the DataSet are displayed in the Output Window.

    Connected Demo demonstrates three methods for refreshing server generated primary keys in a DataSet after rows are added; a statement batch, a separate TO REFRESH statement and a stored procedure with output parameters. Connected Demo also shows you how to synchronize changes in the DataSet with the data source using either the main DataSet or a separate DataSet which contains only changed rows. You could use the latter method to minimize network traffic in a distributed application.

  • Cursor Demo

    You must set up a connection to the SQL Server Northwind database to run the Cursor Demo project. This project demonstrates how to intermix OpenESQL with direct calls to ADO.NET.

    The NoFetch.cbl program uses EXEC SQL to open a cursor and then EXEC ADO to fetch the results. The TestCursor.cbl program performs an EXEC SQL FETCH. The CursorDemo.cbl program populates a DataTable.

  • Disconnected Demo

    The DisconnectedDemo.cbl program manipulates offline data in a DataSet. The results of the data manipulation are displayed in the Output Window.

    Disconnected Demo demonstrates how to declare a DataSet from an XSD file generated by another project and how to load a DataSet from an XML file generated by another application.

  • Lob Demo

    This project shows how ADO.NET can be used in mixed language projects to insert and select large objects (LOBs). LobDemo shows OpenESQL working with LOB columns in a SQL Server table.

    LOB columns are columns that can be up to 2GB in size. In this demo, the LOB columns are image columns and the OpenESQL object reference host variable.

    The LobDemo.cbl program includes instructions for changing Lob Demo to use DB2 LUW and BLOB columns.

  • Order Status Demo

    The Order Status Demo project shows how ADO.NET can be used in mixed language projects. Order Status Demo uses COBOL and C#.

    The netorderstatus.cbl program generates an XSD file from a DataSet declaration. The XSD file is then imported into the C# form. This simplifies building the user interface by enabling data binding with a strongly typed DataSet generated from the XSD file.

    Order Status Demo also demonstrates the use of ADO.NET in legacy reuse not directly related to DBMS access. The data source used in this project is an existing COBOL subroutine.

    The techniques used in this demo are applicable to CICS ECI transactions.

Parent topic: ADO.NET
Related concepts
ADO.NET Connection Editor


ADO.NET Data Providers and Data Source Names

OpenESQL supports ADO.NET data providers. To obtain ADO.NET support, you must:

  1. Install ADO.NET data providers.
  2. Set up an ADO.NET Data Source Name (DSN) via the ADO.NET Connection Editor.
Parent topic: ADO.NET
Related concepts
ADO.NET Connection Editor
Using Embedded EXEC ADO Statements
OpenESQL Assistant


ADO.NET Connection Editor

The ADO.NET Connection Editor enables you to edit the repository that stores the connection information used by the OpenESQL managed run-time when a COBOL program connects to an ADO.NET data provider. The repository is a standard .NET Framework repository, machine.config. This enables mixed language applications to share connection strings and is accessible to all users of the machine on which it is installed. In addition, you can store connection settings in one of the following configuration files:
  • UserConnections32_v2.config for 32 bit, framework 2.0, 3.0, or 3.5 connections
  • UserConnections64_v2.config for 64 bit, framework 2.0, 3.0, or 3.5 connections
  • UserConnections32_v4.config for 32 bit, framework 4.0 connections
  • UserConnections64_v4.config for 64 bit, framework 4.0 connections

These files are located in %LOCALAPPDATA%\Micro Focus.

The OpenESQL run time supports any ADO.NET provider that supports the DbProviderFactory API.

Note:
  • We recommend that you automatically catalog ODBC data providers by setting the Automatically catalog data source on CONNECT option for the OpenESQL Assistant rather than cataloging them using the ADO.NET Connection Editor. The ODBC Data Provider supplied by the DbProviderFactory API is a generic provider and provides few options. This does not apply to COBOL Server.
  • When you run the ADO.NET Connection Editor under operating systems that have User Access Control enabled, such as Windows 7, you must run it as an administrator if you are adding, deleting, or updating connection settings to the system repository. However, when accessing User settings, you do not need this elevated authority.
  • Cataloging an ADO.NET Connection
  • Copying Connection Settings
  • Example Connection Settings
Parent topic: ADO.NET
Related concepts
ADO.NET Data Providers and Data Source Names
Demonstration Applications
Related tasks
To start the ADO.NET Connection Editor
To catalog an ADO.NET data provider
To test an ADO.NET connection
To uncatalog an ADO.NET data provider
To export ADO.NET connection settings
To import ADO.NET connection settings


Cataloging an ADO.NET Connection

OpenESQL Assistant automatically catalogs any ODBC connection as an ODBC ADO.NET data provider if you have set your OpenESQL options to enable automatic cataloging. To use other ADO.NET data providers, you must catalog them manually using the ADO.NET Connection Editor. All cataloged data providers are listed on the Editor.

When you catalog a connection, the ADO.NET Connection Editor supplies default connection settings and values for the type of connection you catalog. You should edit the values to reflect the correct settings for your data source. Micro Focus provides templates for certain ADO.NET data providers as examples of what type of connection settings are required and what their values should be. See the section Example Connection Settings for specific examples.

You also have the option of encrypting your connection settings in the repository. You might want to do this if your connection settings include sensitive information such as a user ID and password used to access your application.

When you launch the ADO.NET Connection Editor from the OpenESQL Assistant UI in Visual Studio, it can access both 32-bit and 64-bit repositories even though the OpenESQL Assistant itself can only access 32-bit repositories. On UAC-enabled operating systems, to update the system repository (machine.config) for either 32-bit or 64-bit applications, you must start Visual Studio as an administrator.

Parent topic: ADO.NET Connection Editor
Related tasks
To catalog an ADO.NET data provider
To uncatalog an ADO.NET data provider


Copying Connection Settings

You can copy your connection settings from one machine to another using the ADO Connection Editor's Export and Import functions. You do this by exporting the connection settings on one machine and importing them to another.

You can also import connection settings at a using the MFImportConn command.

Parent topic: ADO.NET Connection Editor
Related reference
MFImportConn command


Example Connection Settings

The following topics provide examples of appropriate connection settings for a SqlClient and a DB2 ADO.NET data provider.

  • SqlClient Data Provider
  • DB2 ADO.NET
Parent topic: ADO.NET Connection Editor


SqlClient Data Provider

For a SqlClient data provider, you must provide the following connection information:

  • Data Source - The name of the SQL Server you want to use. If the server is local, you can usually specify localhost or (local).
  • Initial Catalog - The name of the database you want to access.
  • Integrated Security - Set this to True to use Windows security. It is set to False by default. When set to False, you must either provide values for the User ID and Password connection settings, or provide them in your program as part of the EXEC SQL CONNECT statement.
  • MultipleActiveResultSets - When using a SQL Server 2005 or later, set this to True to allow multiple active result sets.
Parent topic: Example Connection Settings


DB2 ADO.NET

For a DB2 ADO.NET data provider, you must provide the following connection information:

  • Database – The name of the database to access
  • Server – The name of the database server. If the server is remote, you might also need to specify the TCP port number used by DB2, typically 50000. For example, servername:50000.
  • User ID and Password - You can specify these as connection settings or code them into your program using the EXEC SQL CONNECT statement.
Parent topic: Example Connection Settings


Using OpenESQL with ADO.NET

When using the ADO option, follow the programming and compiling guidelines provided for OpenESQL in general. In addition, the following topics provide information specific to working with ADO.NET:

  • Using Embedded EXEC ADO Statements
  • .NET Host Variables in Managed Code
  • Disconnected and Offline DataSets
  • Compiling Native Applications as Managed Code
  • Stored Procedures with ADO.NET
  • XML Support
Parent topic: ADO.NET


Using Embedded EXEC ADO Statements

To enhance ADO.NET support, a new family of EXEC ADO statements has been added to OpenESQL. These statements operate with DataSets rather than databases but their syntax is familiar to anyone with a knowledge of SQL and embedded SQL. Other EXEC ADO statements have been added which allow direct access to the underlying ADO.NET objects used by the OpenESQL Managed Runtime. With these statements it is possible for OpenESQL to share connections and transactions with other software components or for COBOL programmers to use low level properties and methods of objects that have been created by OpenESQL.

You embed EXEC ADO statements into a COBOL program in the same way as EXEC SQL statements. Embedded EXEC ADO statements enable you to:

  • Program ADO.NET calls without writing COBOL calls to the native ADO.NET API
  • Define, create and manipulate DataSets and associated objects in the ADO.NET disconnected model
  • Manipulate the underlying data source in the ADO.NET connected model, retrieving data as well as updating it
  • Declare and manipulate an ADO.NET DataRows cursor in the same way as a SQL cursor
  • Save and load ADO.NET DataSets (schema and data) to and from XML files
  • Share ADO.NET objects between COBOL programs and other .NET applications
  • Share calls and information between EXEC ADO and EXEC SQL statements in the same program
  • Disconnected Model Statements
  • Connected Model Statements
  • ADO.NET Cursor Statements
  • Sharing ADO.NET Objects Statements
Parent topic: Using OpenESQL with ADO.NET
Related concepts
ADO.NET Data Providers and Data Source Names
XML Support


ADO.NET Cursor Statements

ADO.NET cursor statements enable you to define, create and manipulate an ADO.NET DataRows cursor. These statements are similar to SQL cursor statements. However, instead of a selection criteria based on a table in a data source, an ADO.NET DataRows cursor is based on a DataTable in a DataSet.

The following ADO.NET cursor statements are available to you:

  • DECLARE DATAROWS – defines a DataRows cursor
  • OPEN – creates and opens a DataRows cursor
  • FETCH – fetches the DataRows from the DataRows cursor
  • DELETE (POSITIONED) – deletes the current DataRow from the DataRows cursor
  • UPDATE (POSITIONED) – updates the current DataRow in the DataRows cursor
  • CLOSE – closes a DataRows cursor
Parent topic: Using Embedded EXEC ADO Statements


Sharing ADO.NET Objects Statements

Sharing ADO.NET objects statements enable you to share ADO.NET objects (Connections, DataSets and DataReaders) between COBOL programs and other .NET applications. The GET statements retrieve objects OpenESQL has generated for EXEC SQL commands where dbman=ado. The BIND statements allow COBOL to access ADO.NET objects created by other .NET applications and the UNBIND statements disassociate COBOL from those objects.

The following sharing ADO.NET objects statements are available to you:

  • GET CHANGES - creates a DataSet that only contains changed information
  • GET CONNECTION – gets the current OpenESQL connection object
  • GET CURSOR – gets the DataReader or DataSet associated with an EXEC SQL cursor
  • GET RUNTIME – gets the OpenESQL MFADORTS run-time object
  • BIND CONNECTION – allows a named EXEC SQL connection to use an existing connection object
  • BIND – allows a named EXEC ADO DataSet to use an existing DataSet object
  • REBIND CONNECTION – informs a previously bound EXEC SQL connection object that a new transaction object is being used
  • UNBIND – releases an OpenESQL reference to a bound DataSet object
  • UNBIND CONNECTION – releases an OpenESQL reference to a bound connection object
Parent topic: Using Embedded EXEC ADO Statements


.NET Host Variables in Managed Code

For your managed applications, OpenESQL provides the option of using traditional host variable declarations, and an option to use .NET data types as your host variable declarations. Use of .NET data types is made possible by the OpenESQL Managed Runtime, specified by setting the DBMAN directive option to ADO.

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 .NET type. However, by declaring your host variables using the .NET 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 .NET types, thereby greatly enhancing performance.
  • No size restrictions - .NET 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 .NET.
When coding your applications to use .NET host variables, keep in mind:
  • All .NET host variables must be defined at the 01 level or compiler errors result.
  • Syntax for common .NET data types can be defined with the short name. For example, System.String can be defined simply as:
    01 myName string.
  • Syntax for other .NET variables typically include a TYPE clause. For example:
    01 myDate type System.DateTime.
  • If a specific .NET 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 .NET host variables. Currently, no DBMS vendors provide direct support for EXEC SQL syntax in .NET applications.
  • For complete information on declaring .NET host variables for the OpenESQL Managed Runtime, see the reference topics under SQL Data Types.
  • The OpenESQL Assistant provides an easy method of generating .NET 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 .NET 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 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.

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 ADO.NET
Related concepts
Host Variables
Related reference
SQL Data Types


Disconnected and Offline DataSets

ADO.NET fully supports the use of disconnected and offline DataSets.

A DataSet is like a miniature database, complete with tables, columns, keys and constraints, which can be filled from a database. When a DataSet is modified, both current and original values of data are kept in the DataSet. This allows the DataSet to be synchronized with the database from which it was filled after being passed between servers and components in a distributed system. Used in this way, a DataSet can be regarded as a lightweight replication tool. For example, data for a customer order is extracted from a database and processed remotely from the database server. Later, the database is synchronized with the changes made to the DataSet. Processing could take place on either a Web server or a laptop. Because the DataSet has no connection to the database while it is being processed, optimistic concurrency must be used when the database is updated.

DataSet contents can also be loaded from and saved to data sources other than relational databases. For example, XML files or software components, where the mechanism used to store data does not concern the application that processes the contents of the DataSet, can be used. DataSets also have excellent support for data binding to user interface controls in WinForms and WebForms. This means that DataSets are useful for communicating data in mixed language applications.

Parent topic: Using OpenESQL with ADO.NET


Compiling Native Applications as Managed Code

Many existing native applications can be compiled as managed applications simply by changing the compiler directive option from ODBC to ADO. For these applications, performance characteristics and storage requirements might differ.

For example, any cursor used for scrolling fetches or positioned updates has its result set read completely and buffered on the client system in a DataSet when it is opened. ADO.NET provides no native support for positioned updates and so OpenESQL converts them to searched updates using original column values and optimistic concurrency. For this to provide the same degree of integrity as ODBC, an application must use repeatable read transaction isolation and the result set must contain columns that will uniquely identify the row being updated.

It is also possible for a single application to include some programs compiled with each, but each of the programs included in the application must use one or the other, and each must specify a database connection that uses an appropriate DSN. You cannot share database connections and transactions between ODBC and ADO.NET.

Parent topic: Using OpenESQL with ADO.NET


Stored Procedures with ADO.NET

You can call stored procedures with ADO.NET. However, when calling stored procedures, be aware that the following features are not currently supported:
  • Named parameters
  • Oracle stored procedures returning a result set using Microsoft or Oracle managed providers (the ODBC provider can return Oracle result sets without problems)
  • Stored procedures called by dynamic SQL
Parent topic: Using OpenESQL with ADO.NET


XML Support

XML support is implemented in a different way for ADO.NET data providers. See the section Using Embedded EXEC ADO Statements for more information.

Parent topic: Using OpenESQL with ADO.NET
Related concepts
Using Embedded EXEC ADO Statements


SQL CLR Integration Support

The SQL CLR Integration feature of Visual COBOL for Visual Studio 2010 enables you to create stored procedures, user-defined functions and types, aggregates, and triggers in managed code, taking advantage of the Microsoft SQL Server 2008 R2 SQL CLR feature.

The following topics provide you with the information you need to use the SQL CLR Integration feature effectively:

  • Prerequisites for SQL CLR Integration
  • Tutorials: SQL CLR Integration
  • SQL CLR Database Project Template
  • SQL CLR Integration Process
  • SQL CLR Stored Procedures
  • COBOL Wrapper Programs
Parent topic: OpenESQL


Prerequisites for SQL CLR Integration

You must have the following in place before using the SQL CLR Integration feature:

SQL CLR Integration Enabled in SQL Server 2008 R2
You must enable the SQL CLR feature in SQL Server 2008 R2. You can do this either from SQL Server Management Studio or as a batch process using sqlcmd. The required commands are:
sp_configure 'clr enabled', 1

followed by

reconfigure
Create a SQL CLR-enabled Data Source
You must have a SQL CLR-enabled SQL Server data source to which you can connect.
Note: Microsoft SQL Azure does not support SQL CLR. If you attempt to use it instead of SQL Server 2008 R2, the following error message appears:
Msg 40510, Level 16, State 1, Line 1
Statement 'CREATE ASSEMBLY' is not supported in this version of SQL Server.

For third-party software requirements, see the Database Access Support with .NET Managed COBOL topic.

Parent topic: SQL CLR Integration Support
Related concepts
Database Access Support with .NET Managed COBOL
Related tasks
To generate a SQL CLR stored procedure
To create a SQL CLR database project
To create a SQL CLR stored procedure query


Tutorials: SQL CLR Integration

Using the SQL CLR Integration feature in Visual COBOL, you can code stored procedures, user-defined functions, aggregates, triggers, and user-defined types that contain EXEC SQL statements, and compile the code using the OpenESQL preprocessor.

The scenario that represents the most common and best use of the SQL CLR Integration feature in Visual COBOL is that of creating a SQL CLR stored procedure for OpenESQL and calling it from an OpenESQL application. Here, we provide a series of tutorials that lead you through this processes.

Tutorial Requirements

To complete the SQL CLR Integration tutorials, you must have the following software installed:

  • Visual COBOL for Visual Studio 2010
    Note: This tutorial does not work with the Visual Studio Shell - it requires Visual Studio Professional or higher.
  • Microsoft SQL Server 2008 R2, Enterprise or Developer Edition, including the SQL Server Management Studio

Additional requirements that apply to specific tutorials appear in the Requirements section of each.

Order

You must complete this series of tutorials in the following order:

  • Tutorial: Enable SQL CLR Integration
    This tutorial takes you through the process of enabling the SQL CLR Integration feature in Microsoft SQL Server 2008 R2.
  • Tutorial: Create a Sample Database
    In this tutorial, you run an SQL script that creates the sample database required to complete these tutorials and populates the database with the necessary data.
  • Tutorial: Create and Configure a SQL CLR Database Project
    This tutorial takes you through the process of creating a Visual Studio COBOL Database project to use as you complete the remainder of these tutorials.
  • Tutorial: Create an ADO.NET Connection
    In this tutorial, you configure the OpenESQL Assistant, including an ADO.NET database connection, in preparation for building your SQL CLR stored procedure.
  • Tutorial: Code a SQL CLR Stored Procedure using OpenESQL Assistant
    In this tutorial, you use the OpenESQL Assistant to build on the SQL CLR stored procedure that you created in a previous tutorial such that it looks up an employee number and returns the employee number and first and last names of the employee.
  • Tutorial: Build and Run a Stored Procedure
    This tutorial takes you through the process of building, deploying, debugging, and executing the stored procedure you created in the previous tutorials.
  • Tutorial: Call a Deployed Stored Procedure
    This tutorial takes you through the process of calling your deployed stored procedure from a COBOL program.
  • Tutorial: Generate a COBOL Wrapper for a SQL CLR Stored Procedure
    This tutorial takes you through each step in the process of generating a COBOL wrapper for a SQL CLR stored procedure.
Parent topic: SQL CLR Integration Support


Tutorial: Enable SQL CLR Integration

The SQL CLR Integration is not available in SQL Server 2008 by default. To access the database objects necessary for SQL CLR integration in your COBOL applications, you must enable SQL CLR in SQL Server 2008.

Do this using the clr enabled option of the sp_configure stored procedure.

  • Execute the following SQL either from SQL Server Management Studio or as a batch process using sqlcmd:
    sp_configure 'clr enabled', 1
GO
reconfigure
GO
    Note: If SQL Server 2008 R2 is already running, you might be required to stop and then restart the instance.

This concludes this tutorial. Please continue with Tutorial: Create a Sample Database

Parent topic: Tutorials: SQL CLR Integration


Tutorial: Create a Sample Database

Requirement
Before attempting this tutorial, you must complete Tutorial: Enable SQL CLR Integration.
Create the SQLCLR_Test Database
  1. Start SQL Server Management Studio.
  2. Open the CreateAndLoadSQLCLR_Test.sql script, located in your %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples\sql\sqlclr directory.
  3. Execute the script.

    This creates the SQLCLR_Test database and populates its tables with sample data necessary for stored procedure deployment.

  4. Exit SQL Server Management Studio.

This concludes this tutorial. Please continue with Tutorial: Create and Configure a COBOL Database Project.

Parent topic: Tutorials: SQL CLR Integration


Tutorial: Create and Configure a SQL CLR Database Project

Requirements
Before attempting this tutorial, you must complete the following tutorials in the order listed:
  • Tutorial: Enable SQL CLR Integration
  • Tutorial: Create a Sample Database
Phase 1: Launch Visual COBOL for Visual Studio 2010
  • Click Start > All Programs > Micro Focus Visual COBOL > Visual COBOL for Visual Studio 2010.
Note: On UAC-enabled operating systems, you must start Visual COBOL as an administrator.
Phase 2: Create a New COBOL Database Project

The SQL CLR Integration feature in Visual COBOL for Visual Studio 2010 provides a project template named SQL CLR Database, which is configured specifically for SQL CLR. Here, you create a Visual Studio project based on this template.

  1. From the Visual Studio IDE, click File > New > Project.
  2. Under Installed Templates, click COBOL > Database.
  3. From the drop-down list above SQL CLR Database Project, select .NET Framework 3.5.
    Note: SQL Server 2008 R2 cannot run SQL CLR assemblies created using .NET Framework 4.0.
  4. Click SQL CLR Database Project.
  5. In the Name field, type SQLCLRTutorial.
  6. In the Location field, specify a directory in which to store the project; then click OK.

    Visual COBOL launches the Add Database Reference dialog box.

Phase 3: Add a Database Reference
SQL CLR projects require access to a SQL Server database. Here, you add a reference to the SQLCLR_Test database you created in a previous tutorial.
  1. On the Add Database Reference dialog box, provide your SQL Server instance name, select a login authentication method, provide a user name and password if required, and specify the SQLCLR_Test database you created for stored procedure deployment.
  2. Click Test Connection to verify that you have a valid SQL Server connection; then click OK to clear the message.
  3. Click OK to close the Add Database Reference dialog box.
Phase 4: Set Project Properties
  1. From the Solution Explorer, double-click Properties under your SQLCLRTutorial project.
  2. On the SQL tab, select OpenESQL from the ESQL Preprocessor drop-down list; then click Add.
  3. On the Available Directives list, click DBMAN; then click OK.
  4. From the Value drop-down, select ADO.
  5. On the Available Directives list, click BEHAVIOR; then click OK.
  6. From the Value drop-down, select MAINFRAME.
  7. On the COBOL tab, set the Warning level to Include recoverable errors (Level E).
  8. Click Save, and close the Properties window.
Phase 5: Set OpenESQL Assistant Options
  1. From the Visual Studio IDE, click Tools > Options > Micro Focus Visual COBOL > OpenESQL Assistant.
  2. In the Query > Type Stored Procedure field, select SQLCLR; then click OK.

This concludes this tutorial. Please continue with Tutorial: Create an ADO.NET Connection.

Parent topic: Tutorials: SQL CLR Integration


Tutorial: Create an ADO.NET Connection

Requirements
Before attempting this tutorial, you must complete the following tutorials in the order listed:
  • Tutorial: Enable SQL CLR Integration
  • Tutorial: Create a Sample Database
  • Tutorial: Create and Configure a SQL CLR Database Project
Phase 1: Set OpenESQL Assistant Options
  1. From the Visual Studio IDE, click Tools > Options > Micro Focus Visual COBOL > OpenESQL Assistant.
  2. In the Type COBOL Variable field, double-click until the value changes to Object.
  3. Set Qualify table with owner name to True.
  4. Click OK to save the settings; then close the Options window.
Phase 2: Start OpenESQL Assistant
  • From the Visual Studio IDE, click Tools > Micro Focus Visual COBOL > OpenESQL Assistant.
Phase 2: Catalog an ADO.NET Connection
  1. From the tool bar in the OpenESQL Assistant, click the ADO.NET Connection Editor icon [image].
  2. Click Add to create a new database connection.
  3. On the Name list, click SqlClient Data Provider.
  4. In the Data Source Name field, type SQLCLRTutorial; then click Next.
  5. In the Value field for the Data Source key, type the name of your SQL Server instance.
  6. In the Value field for the Initial Catalog key, type SQLCLR_Test, which is the name of the database you created for these tutorials.
  7. Do one of the following to set authentication for your SQL Server instance:
    • If you want to connect using Windows authentication, change the value for the Integrated Security key to True.
    • If you want to connect by providing SQL Server-specific login credentials, type your SQL Server user ID and password into the Value fields for the User ID and Password keys respectively.
  8. Click Save.
  9. To test the connection, click Test Connection; then click OK to clear the message.
  10. Click OK to close the ADO.NET Connection Editor.
Phase 3: Connect to your SQL Server Instance
  1. On the OpenESQL Assistant, uncheck all listed data source names, if any.
  2. From the tool bar, click the Refresh list of data sources icon [image].
  3. Check SQLCLRTutorial to make the connection.

This concludes this tutorial. Please continue with Tutorial: Code a SQL CLR Stored Procedure using OpenESQL Assistant.

Parent topic: Tutorials: SQL CLR Integration


Tutorial: Code a SQL CLR Stored Procedure using OpenESQL Assistant

Requirements
Before attempting this tutorial, you must complete the following tutorials in the order listed:
  • Tutorial: Enable SQL CLR Integration
  • Tutorial: Create a Sample Database
  • Tutorial: Create and Configure a SQL CLR Database Project
  • Tutorial: Create an ADO.NET Connection
Phase 1: Create a SQL CLR Stored Procedure Query
  1. In the OpenESQL Assistant, check the EMP (TEST) table listed under the SQLCLRTutorial connection entry.
  2. On the Select Type of Query to Create dialog box, click SELECT (singleton).
  3. Check Generate Query as a SQLCLR Stored Procedure.
  4. In the SP name field, type SQLCLRTutorial. The OpenESQL Assistant uses this name for both the generated program and the stored procedure.
  5. Click OK.
  6. On the tree view, check the A.EMPNO, A.FIRSTNAME, and A.LASTNAME columns to add them to the query.
  7. Click the Search Criteria tab.
  8. Verify that the following fields are set to the values specified:
    Column | A.EMPNO
    Conditional Operator =
    Target Type | Host Variable
    Target Value | :EMP-EMPNO
  9. Click > (right arrow ) to construct the arguments for the WHERE clause of the SELECT statement we are building.

As you build the query, the OpenESQL Assistant generates all code necessary to complete the stored procedure program, including host variables and SQLCA declarations.

Phase 2: Add the Stored Procedure to the Project
  1. Right-click over the toolbar and select Add SP to SQLCLR project.

    The OpenESQL Assistant adds the program to the project as SQLCLRTutorial.cbl.

  2. Save your project.

This concludes this tutorial. Please continue with Tutorial: Build and Run a Stored Procedure.

Parent topic: Tutorials: SQL CLR Integration


Tutorial: Build and Run a Stored Procedure

Before attempting to debug by stepping into the stored procedure code using the steps below, if you are using a UAC-enabled operating system, you must be running Visual COBOL as an administrator.

Requirements
Before attempting this tutorial, you must complete the following tutorials in the order listed:
  • Tutorial: Enable SQL CLR Integration
  • Tutorial: Create a Sample Database
  • Tutorial: Create and Configure a SQL CLR Database Project
  • Tutorial: Create an ADO.NET Connection
  • Tutorial: Code a SQL CLR Stored Procedure using OpenESQL Assistant
Phase 1: Build and Deploy Your Stored Procedure to SQL Server
  1. In the Solution Explorer, right-click the SQLCLRTutorial project; then select Build. This generates a SQLCLRTutorial.dll from your stored procedure code.
  2. Again in the Solution Explorer, right-click the SQLCLRTutorial project; then select Deploy.

    This action copies your stored procedure code to your SQL Server and creates a stored procedure in the SQL Server database to use the generated DLL code.

Phase 2: Debug Your Stored Procedure
Now that your stored procedure is available for use, you can debug it from Visual Studio 2010.
  1. In Server Explorer, expand your SQL Server instance and Stored Procedures.
  2. Right-click SQLCLRTutorial and select Step Into Stored Procedure.
  3. In the Value field for the @empid name, type 000020.
  4. In the Value fields for the @firstname and @lastname names, select <NULL> from the drop-down list; then click OK.

    Visual Studio connects to your SQL Server instance, calls your stored procedure, and runs the debugger. The Output windows displays information returned from the debugger.

  5. Use the Visual Studio debugger to step through the lines of code in your stored procedure, examining variables and values, etc.
  6. To exit the debugger, click Debug > Stop Debugging.
Phase 3: Execute Your Stored Procedure
You can now execute the stored procedure providing required input values, and see the output that results from the stored procedure call.
  1. From the Server Explorer, right-click the SQLCLRTutorial stored procedure, and select Execute.
  2. If not already set, type 000020 into the Value field for the @empid name, and change the Value fields for the other two names to <NULL>.
  3. Click OK to execute the stored procedure.
  4. View the results in the Output window, which should show the output from Database Output as follows:
    Running [dbo].[SQLCLRTutorial] ( @empid = 000020, @lastname = <NULL>, @firstname = <NULL> ).

No rows affected.
(0 row(s) returned)
@empid = 000020
@lastname = THOMPSON
@firstname = MICHAEL
@RETURN_VALUE = 0
Finished running [dbo].[SQLCLRTutorial].

This concludes this tutorial. Please continue with Tutorial: Call a Deployed Stored Procedure.

Parent topic: Tutorials: SQL CLR Integration


Tutorial: Call a Deployed Stored Procedure

Requirements
Before attempting this tutorial, you must complete the following tutorials in the order listed:
  • Tutorial: Enable SQL CLR Integration
  • Tutorial: Create a Sample Database
  • Tutorial: Create and Configure a SQL CLR Database Project
  • Tutorial: Create an ADO.NET Connection
  • Tutorial: Code a SQL CLR Stored Procedure using OpenESQL Assistant
  • Tutorial: Build and Run a Stored Procedure
Phase 1: Create a Visual Studio Project
You need to create a Visual Studio project in which to code a program that calls your deployed stored procedure.
  1. From the Visual Studio IDE, click File > New > Project.
  2. Under Installed Templates, click COBOL > Managed > Console Application.
  3. From the drop-down field above the list of templates, select .NET Framework 4.
  4. In the Name field, type SQLCLRTutorialCall.
  5. In the Location field, specify a directory in which to store the project; then click OK.
Phase 2: Set Project Properties
  1. From the Solution Explorer, double-click Properties under your SQLCLRTutorialCall project.
  2. On the SQL tab, select OpenESQL from the ESQL Preprocessor drop-down list; then click Add.
  3. On the Available Directives list, click DBMAN; then click OK.
  4. From the Value drop-down, select ADO.
  5. Click Save, and close the Properties window.
Phase 3: Code a COBOL Program
You now code a COBOL program to call your stored procedure.
  1. From the Solution Explorer, double-click Program1.cbl.
  2. Replace all of the code in the program with the following code:
    program-id. Program1 as "SQLCLRtutorialCall.Program1".

    data division.
    working-storage section.
    exec sql include sqlca end-exec.

    01 empid       PIC X(6).  *>string.
    01 lastname    PIC X(50). *>string.
    01 firstname   PIC X(50). *>string.

    01 connectString  string.
    01 spReturnCode binary-long.

    procedure division.
        exec sql connect to "SQLCLRtutorial" end-exec

        if sqlcode <> 0
           display "CONNECT FAILED"
        end-if

        set empid to "000020"
        exec sql
             :spReturnCode = call "SQLCLRtutorial" (:empid INOUT, :lastname OUT, :firstname OUT)
        end-exec

        if sqlcode <> 0
             display "Call FAILED"
        else
             display "User = " firstname " " lastname
        end-if

        exec sql disconnect all end-exec.
        goback.

    end program Program1.
    Note: You could also generate the CALL statement from the Auxiliary Code tab and insert it into the program rather than coding it manually as it is here.
  3. Save the program.
Phase 4: Run the COBOL Program
  1. From the Program1.cbl [Code] window, toggle a breakpoint at the goback. statement.
  2. Press F5 to run the program.
    When the debugger hits the breakpoint, you should see the following in the Output window as a result of calling the stored procedure:
    User = MICHAEL THOMPSON
  3. Click File > Save All (optional).
  4. Exit Visual Studio.

This concludes the series of SQL CLR Integration tutorials.

Parent topic: Tutorials: SQL CLR Integration


Tutorial: Generate a COBOL Wrapper for a SQL CLR Stored Procedure

Requirements
Before attempting this tutorial, you must first complete the following SQL CLR Integration tutorials to ensure you have an established SQL Server database named SQLCLR_Test and a connection to that database:
  • Tutorial: Enable SQL CLR Integration
  • Tutorial: Create a Sample Database
  • Tutorial: Create and Configure a SQL CLR Database Project
Phase 1: Add COBOL Source to the Project
We provide a sample COBOL program, GETHIRE.cbl, that receives an employee number, and returns the employee's first name, last name, and hire date. In this phase, you add this COBOL program and its required copybook, EMP.cpy, to your SQL CLR project.
  1. From the Solution Explorer, right-click the SQLCLRTutorial project, and click Add > Existing Item.
  2. Browse to the %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples\Mainframe\sql\sqlclr directory.
  3. From the Objects of type drop-down list, click COBOL Files (*.cbl, *.cpy, *.cob).
  4. Select the GETHIRE.cbl and EMP.cpy files; then click Add.
Phase 2: Create a Stored Procedure Definition File and Skeleton COBOL File
You need to create a stored procedure definition file (.spd file) that contains the stored procedure from which to generate the COBOL wrapper program.
  1. From the Solution Explorer, right-click the SQLCLRTutorial project, and click Add > New Item.
  2. Under Installed Templates, click COBOL.
  3. In the center pane, click Stored Procedure Definition.
  4. In the Name field, type SQLCLRStoredProc.spd; then click Add.

    This adds an empty SQLCLRStoredProc.spd file to the project and opens it in the center pane of Visual Studio. It also generates a skeleton COBOL file named SQLCLRStoredProc.mssp.cbl and adds it to the project.

Phase 3: Define the Stored Procedure and Generate the COBOL Wrapper
These two steps are done automatically in one phase.
  1. Cut the following Stored Procedure definition from this tutorial and paste it into the empty SQLCLRStoredProc.spd file open in Visual Studio:
    CREATE PROCEDURE HCOSQL.GETHIRE
    ( IN    EMPNO       CHAR   (6)
     ,OUT   FIRST_NAME  VARCHAR     (12)
     ,OUT   LAST_NAME   VARCHAR (16)
     ,OUT   HIRE_DATE   DATE
     ,OUT   OT_SQLCODE  INTEGER
     )
  RESULT SETS 0
  PARAMETER STYLE GENERAL
  ;
  2. Save the SQLCLRStoredProc.spd file. This automatically generates the COBOL wrapper code, saving it to the SQLCLRStoredProc.mssp.cbl file.
  3. In the Solution Explorer, double-click SQLCLRStoredProc.mssp.cbl to see the generated COBOL wrapper code.
  4. Close the SQLCLRStoredProc.spd and SQLCLRStoredProc.mssp.cbl files.
Phase 4: Build and Deploy the COBOL Wrapper Application
  1. From the Solution Explorer, right-click the SQLCLRTutorial project, and click Build.
  2. Again, right-click the SQLCLRTutorial project, but this time select Deploy.
Phase 5: Execute the Stored Procedure
  1. In Visual Studio, open the Server Explorer.
  2. Expand the SQLCLR_Test.dbo data connection.
  3. Expand Stored Procedures.
  4. Right-click GETHIRE, and select Execute.
  5. Provide the following Values for the corresponding Names:
    Name | Value
    @lkEMPNO | 000200
    @lkFIRST_NAME | <NULL>
    @lkLAST_NAME | <NULL>
    @lkHIRE_DATE | <NULL>
    @lkOT_SQLCODE | 0
  6. Click OK. The data appears in the Output window:
    Running [dbo].[GETHIRE] ( @lkEMPNO = 000200, @lkFIRST_NAME = <NULL>, @lkLAST_NAME = <NULL>, @lkHIRE_DATE = <NULL>, @lkOT_SQLCODE = 0 ).

No rows affected.
(0 row(s) returned)
@lkFIRST_NAME = DAVID
@lkLAST_NAME = BROWN
@lkHIRE_DATE = 1966-03-03
@lkOT_SQLCODE = 0
@RETURN_VALUE =
Finished running [dbo].[GETHIRE].

This completes the tutorial.

Parent topic: Tutorials: SQL CLR Integration


SQL CLR Database Project Template

The Visual COBOL SQL CLR Integration feature provides a Visual Studio project template configured to make SQL CLR integration easy. A Visual Studio project created with this template provides the following:
  • Project objects:
    • PreDeployScript.sql - an SQL script file that executes ahead of the standard deployment process when you deploy an object. Initially, this script is empty. You can edit it according to your needs.
    • PostDeployScript.sql - an SQL script file that executes just after the standard deployment process when you deploy an object. Initially, this script is empty. You can edit it according to your needs.
    • Test.sql - an SQL script template file that you can edit and run to execute a SQL CLR stored procedure in preparation for debugging or running the stored procedure.
    • projectName.spd - a blank stored procedure definition file you can populate and then use to generate a COBOL wrapper program.
    • References to the System, System.Data, and System.XML assembly types.
  • User Interface enhancements that enable you to create SQL CLR objects, including the following options available from the Project menu and also from the project's context menu:
    • Add User-Defined Function
    • Add Stored Procedure
    • Add Aggregate
    • Add Trigger
    • Add User-Defined Type
    • Generate a COBOL wrapper program
  • A custom tool, SPDFileCodeGenerator, you can use to generate COBOL wrapper programs from .spd files.
  • The following COBOL program templates, all of which you can add to a SQL CLR Database project. Each template includes all of the mandatory code required for its respective SQL CLR object type:
    • Function1.cbl
    • StoredProcedure1.cbl
    • Aggregate1.cbl
    • Trigger1.cbl
    • Type1.cbl
Parent topic: SQL CLR Integration Support
Related tasks
To create a SQL CLR database project


SQL CLR Integration Process

The process of effectively using the Visual COBOL SQL CLR integration feature to create and access stored procedures, user-defined functions and types, aggregates, and triggers in managed code, is as follows:

  1. Launch Visual COBOL.
    Important: On UAC-enabled operating systems, you must start Visual COBOL as an administrator.
  2. Create a Visual Studio project using the COBOL > Database > SQL CLR Database project template. Specify .NET Framework 3.5 or earlier.
  3. Create or specify a database reference to your SQL CLR-enabled SQL Server 2008 R2 data source.
  4. If you intend to code your SQL CLR objects using EXEC SQL statements, set your project properties to use the OpenESQL ESQL Preprocessor, and add the DBMAN compiler directive set to the value of ADO.
  5. Add any of the following SQL CLR objects in the form of a COBOL program by selecting it either from the Projects menu or the project's context menu:
    • User-Defined Function
    • Stored Procedure
    • Stored Procedure Definition (.spd) File
    • Aggregate
    • Trigger
    • User-Defined Type
  6. Edit the object code to reflect the functionality you require.
    Note: When coding for the OpenESQL preprocessor,
    • Consider using the OpenESQL Assistant to generate EXEC SQL statements.
    • Because SQL CLR manages database updates via the calling program, do not code EXEC SQL COMMIT or EXEC SQL ROLLBACK statements into a stored procedure. Instead, do one of the following:
      • Code EXEC SQL COMMIT and EXEC SQL ROLLBACK statements into the calling program as necessary.
      • Compile the calling program with the SQL(AUTOCOMMIT) directive, ensuring that database updates are automatic after the execution of each EXEC SQL statement.
      • Run the calling program under a managed transaction manager that controls and issues commits and rollbacks, such as CICS.NET.
  7. If you have added a stored procedure definition file, optionally generate a COBOL wrapper program for it.
  8. Build the project to generate a DLL module that can be accessed from a COBOL application.
  9. Deploy the project to copy your code to your SQL Server instance and create an object in the SQL Server database to use the generated DLL module.
  10. Execute the SQL CLR object, providing input values as necessary, so you can see the output it generates.
At this point, your SQL CLR object is available to any COBOL application by calling the object using the following EXEC SQL statement in your COBOL code:
EXEC SQL :spReturnCode = call "objectName" args

We recommend that you complete the OpenESQL tutorials that take you through the process of creating and calling a SQL CLR stored procedure. These are available from the Tutorials: SQL CLR Integration topic.

Parent topic: SQL CLR Integration Support
Related tasks
To generate a COBOL wrapper for a SQL CLR stored procedure


SQL CLR Stored Procedures

You can create SQL CLR stored procedures using the OpenESQL Assistant, which generates an entire SQL CLR program based on a selected table, query type, and columns, and includes any host variables you need to execute the query.

Parent topic: SQL CLR Integration Support
Related tasks
To generate a SQL CLR stored procedure
To create a SQL CLR stored procedure query
To create a SQL CLR database project


COBOL Wrapper Programs

In the past, stored procedures originally written for DB2 mainframe applications could not be accessed as SQL CLR stored procedures running on SQL Server. To use a stored procedure that originated in DB2 required that you manually convert the DB2 code to Microsoft SQL Server standards.

To get around this requirement, we provide the SPD File Code Generator tool. This tool generates a COBOL wrapper program from a stored procedure definition (SPD) file. The generated program contains SQL CLR APIs, calls the original DB2-style COBOL stored procedure routine, and returns the information from the call to SQL Server. The benefits of generating a COBOL wrapper program for your DB2-style stored procedure are:
  • You are not required to manually convert the code.
  • The COBOL wrapper program converts the .NET variables required by SQL CLR stored procedures to standard COBOL host variables.
  • You can pass COBOL group variable names by defining parameters as BINARY or VARBINARY in the SPD file and use the BINARY or VARBINARY SQL Type in the client stored procedure code instead of PIC X COBOL variables.
Parent topic: SQL CLR Integration Support
Related tasks
To generate a COBOL wrapper for a SQL CLR stored procedure


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:

  • BEHAVIOR can be set to any of the following:
    ANSI | Enables OpenESQL to work like the ANSI standard, and enhances the access speed
    MAINFRAME | Enables OpenESQL to work as it does on the mainframe, and enhances the access speed
    UNOPTIMIZED | Provides backward compatibility with earlier Micro Focus products
    primitivedirective | Optional directives that enable the fine-tuning of BEHAVIOR
  • With either the MAINFRAME 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 set a default behavior of ANSI, MAINFRAME, 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 setting overrides the default setting.

  • Capability to override the BEHAVIOR characteristics cited above without changing the program's associated EXEC SQL statement.

For more information, see the BEHAVIOR topic and the demo application behavior listed in the topic Demonstration Applications.

Parent topic: OpenESQL
Related concepts
Demonstration Applications
OpenESQL Configuration Utility
Related reference
BEHAVIOR
Related information
To set a default for SQL(BEHAVIOR)
OpenESQL Configuration Utility


DB2

  • DB2 External Compiler Module
  • DB2 Stored Procedures
Parent topic: Database Access
Related concepts
Database Access Preprocessors
Compiling SQL Applications


DB2 External Compiler Module

This collection of topics describe how you can access a DB2 database from a COBOL program that contains embedded SQL statements.

The DB2 External Compiler Module (ECM) is an integrated preprocessor provided with this system and designed to work closely with the Micro Focus COBOL Compiler. The DB2 ECM converts embedded SQL statements into the appropriate calls to DB2 database services.

  • Demonstration Applications
    A list of available demonstration applications provided to illustrate programming techniques and runtime behavior for native applications using the DB2 ECM, along with a description of each of these applications.
  • Compound SQL
  • User Defined Functions
  • Extensions to Embedded SQL Support
  • UDB-VERSION DB2 Directive Option
  • Compiling
  • Error Codes
  • Linking
  • Binding
Parent topic: DB2


Demonstration Applications

A number of DB2 ECM demonstration applications are supplied in the Samples Browser, available from . These files are located in the %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples\sql\db2ecm directory by default.

Each sample application comes with a Readme file to explain how to use the application, and a makefile.

The following applications are provided:

  • Connect Demo

    Shows the syntax variants for connecting to and disconnecting from a DB2 database using Type 1 CONNECTs that IBM DB2 LUW supports.

  • Dynamic Demo

    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.

  • Lob Demo

    Shows how LOB LOCATOR and VALUES functions to retrieve Lob data from DB2 LUW.

  • Select Demo

    A simple example of using both singleton SELECT and cursor-based FETCH statements with IBM DB2 LUW.

  • Whenever Demo

    Shows how to use EXEC SQL WHENEVER statements for error handling, and the DB2(MSGAREA) Compiler directive to specify a COBOL variable for retrieving error message text larger than the 70 bytes provided in SQLERRMC.

Parent topic: DB2 External Compiler Module


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

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.

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

Parent topic: Extensions to Embedded SQL Support


The DECLARE TABLE Statement

Statements of the form:

exec sql
   DECLARE table-name TABLE
   ...
end-exec

are permitted and are treated as comments.

Parent topic: Extensions to Embedded SQL Support


Qualified Host Variables

Host variables can be qualified using DB2 for MVS compatible syntax.

For example, suppose you have defined some host variables as follows:

01 block-1.
   03 hostvar pic s9(4) comp-5.
01 block-2.
   03 hostvar pic s9(4) comp-5.

You can qualify which instance of hostvar to use with syntax of the form:

exec sql
   fetch s2 into :block-1.hostvar
end-exec
Parent topic: Extensions to Embedded SQL Support


Host Variable Groups and Indicator Arrays

When host variables are declared in a group item, an SQL statement which needs to refer to each of these variables in turn can be abbreviated by referring instead to the group-name. If you need to associate indicator variables with these host variables, define a table of indicator variables with as many instances as there are host variables, and reference this table (the item with the OCCURS clause, not a group item containing it).

For example, suppose you have defined some host variables as follows:

01  host-structure.
   03 sumh           pic s9(9) comp-5.
   03 avgh           pic s9(9) comp-5.
   03 minh           pic s9(9) comp-5.
   03 maxh           pic s9(9) comp-5.
   03 varchar.
      49 varchar-l   pic s9(4) comp.
      49 varchar-d   pic x(1000).
 01  indicator-table.
     03 indic          pic s9(4) comp-5 occurs 4.
 01  redefines indicator-table.
     03 indic1         pic s9(4) comp-5.
     03 indic2         pic s9(4) comp-5.
     03 indic3         pic s9(4) comp-5.
     03 indic4         pic s9(4) comp-5.

In such an example, the procedural statement:

exec sql fetch s3 into
  :host-structure:indic
end-exec

is equivalent to:

exec sql fetch s3 into
  :sumh:indic1, :avgh:indic2, :minh:indic3,
  :maxh:indic4, :varchar
end-exec

The four declared indicator variables are allocated to the first four host variables. If five or more had been declared, all five host variables would have an associated indicator variable.

The table of indicator variables is redefined only to show the equivalent SQL statement (subscripting is not allowed in SQL statements). The redefinition can be omitted and the COBOL program can refer to the indicator variables using subscripting, if desired.

Parent topic: Extensions to Embedded SQL Support


The NOT Operator (¬)

DB2 allows the operators ¬=, ¬> and ¬<. These are mapped to <>, <= and >=. The character representation of the NOT operator varies from system to system, so you can define it using the NOT option of the DB2 Compiler directive.

Parent topic: Extensions to Embedded SQL Support


The Concat Operator (|)

In some countries the symbol used for the concat operator is not the ASCII character (|). The DB2 ECM enables you to specify a different ASCII character for the concat operator via the CONCAT option of the DB2 Compiler directive.

Parent topic: Extensions to Embedded SQL Support


SQL Communications Area

After any SQL statement has executed, important information is returned to the program in an area called the SQL Communications Area (SQLCA). The SQL Communications Area is usually included in your program using the statement:

exec sql include sqlca end-exec

If you do not include this statement, the DB2 ECM automatically allocates an area, but this area is not addressable in your program. However, if you declare either or both of SQLCODE and SQLSTATE, the DB2 ECM generates code to copy the corresponding fields in the SQLCA area to the user-defined fields after each EXEC SQL statement.

Tip: For ANSI compatibility, we recommend you define the entire SQLCA.

After any non-zero condition in SQLCODE, the DB2 ECM updates the contents of the MFSQLMESSAGETEXT data item with a description of the exception condition, provided it has been defined. If it is, it must be declared as a character data item (PIC X(n), where n can be any legal value; if the message does not fit into the data item it is truncated).

None of SQLCA, SQLCODE, SQLSTATE and MFSQLMESSAGETEXT is required to be declared as host variables.

Parent topic: Extensions to Embedded SQL Support


Support for Object Oriented COBOL Syntax

The DB2 ECM has been enhanced to work with Object Oriented COBOL syntax (OO programs). There are, however, a couple of restrictions that you should be aware of:

  • The INIT option of the DB2 Compiler directive is disabled if used within an OO program. Therefore, to obtain the functionality of the DB2(INIT=PROT) Compiler directive, include a non-OO module and compile it with this directive.
  • If you use an EXEC SQL WHENEVER statement within a METHOD, any additional METHODs coded in the same CLASS that have SQL statements in them need to have the section that is referenced in the preceding WHENEVER statement defined. Not doing this results in a compilation error indicating that the section has not been defined. You can get around this restriction by defining another EXEC SQL WHENEVER statement.
Parent topic: Extensions to Embedded SQL Support


Support for Nested COBOL programs

The DB2 ECM allows you to work with nested COBOL programs.

By default, DB2 interface code is generated for every nested COBOL program. To avoid generating DB2 interface code for each nested program, use the DB2 directive IGNORE-NESTED. To use the IGNORE-NESTED directive properly, there is one restriction that you should be aware of:

  • You must specify the PROGRAM-ID statement in the program for which you wish DB2 interface code to be generated. Otherwise, a compile error occurs.
Parent topic: Extensions to Embedded SQL Support


UDB-VERSION DB2 Directive Option

The DB2 ECM can use one of two sets of API calls, depending on the version of DB2 Database for Windows (DB2 LUW) you are using. The set of calls used for DB2 LUW Version 7.1 and later make use of the new facilities that IBM introduced in Version 7. In this version, IBM changed the size of the program identifier string (PID) from 40 bytes to 162 bytes. The PID is stored in each application program when it is compiled. You need to use the new PID structure if you use a COLLECTION-ID greater than 8 characters.

The DB2 ECM automatically tries to use the newer set of calls if you connect to a DB2 LUW server at Version 7.1 or later when you compile your program. However, you might want to use the newer set of calls in other circumstances, for example, if you are not using Version 7.1 client software, or if you are connected to another DB2 server via DB2 Connect. To do this, use the DB2 Compiler directive UDB-VERSION, which allows you to indicate which DB2 LUW version you want to use. Valid values are V6, V7, V8, V9, V95, and V97. If you specify V7 or later, the ECM makes the new calls. For example:

DB2(UDB-VERSION=V7)

If the DB2 ECM fails to find the new API, it displays the following message:

* critical errror - DB2Initialize API not found
* Try using directive DB2(UDB-VERSION=V6)
* to compile program

followed by the message:

** DB00010 DB2 rejected an unspecified option. This error
** prevents SQL processing from continuing - further
** EXEC SQL statements will be ignored
Parent topic: DB2 External Compiler Module
Related reference
UDB-VERSION


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 try to compile any SQL program, please make sure the following have been done:

  • To avoid a compiler error with the DB2 directive, DB2 LUW Data Server Client must be installed.
  • DB2 has been started if checking against a local database or a remote database server via the DB2START or NET START DB2 command
  • If using DB2 LUW as a remote database server, that security services also must have been started
  • You have specified a valid database in the project settings under the SQL tab
Note: This is important since to compile a program, you must first connect to the database. If the connect fails, your program will not compile.

If you have done all of the above steps, and get a DB006 error ("Required DB software: db2agapi could not be found"), check the PATH statement that this COBOL development system generates from aVisual COBOL command prompt. The PATH gets modified by this COBOL development system software, and the directory where DB2 is installed may be beyond 255 bytes. Modify your PATH statement to ensure that the ..\SQLLIB\BIN directory is closer to the beginning of the PATH statement so that required database DLLs required to compile the program can be loaded.

Before you can compile a SQL program, you must have been granted authorization. This is usually done by the DB2 Database Administrator. You must have one of the following:

  • sysadm or dbadm authority
  • BINDADD privilege if a package does not exist, and 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

The user also needs all table privileges required to compile any static SQL statement in the application. Note that 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 company's DB2 Database Administrator.

You use the DB2 Compiler directive to give the DB2 ECM information such as the fact that you are using SQL, and which database you are using.

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:

Normally, programs containing embedded SQL are compiled in the same way as non-SQL programs, except that the DB2 Compiler directive is required. Special action is required only when creating an executable (binary) file when additional modules need to be linked in. Programs containing SQL code can be animated like any other program. You can examine host variables inside SQL statements as they are regular COBOL data items.

  • Setting DB2 Background Syntax Checking Options
    Explains how to set options that determine the level at which the DB2 ECM preprocessor checks syntax in the background.
  • Compiling Programs That Use a Remote DB2 Server
  • DB2 Compiler Directive
Parent topic: DB2 External Compiler Module


Setting DB2 Background Syntax Checking Options

Before compiling a DB2 application, you can set options that determine the level at which the DB2 ECM preprocessor checks syntax in the background. To do this, click Tools > Options; then expand Micro Focus Visual COBOL and click DB2 Background Syntax Checking. You can set the following options:

  • Background Compile Setting > No syntax checking

    The precompiler does not connect to the DBMS and does not validate EXEC SQL statements; however, the precompiler does check host variables.

  • Background Compile Setting > Complete syntax checking

    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 Visual Studio documentation for information on setting properties.

Parent topic: Compiling


Compiling Programs That Use a Remote DB2 Server

To compile a program that uses a remote DB2 server, you must first connect to that remote server. The DB2 ECM first attempts to connect to the database using the default values for the client workstation you logged on with. If the logon fails, the DB2 ECM will invoke the Micro Focus SQL Logon dialog box, from which you can specify a logon ID and password for the database you are trying to compile your program against.

The Micro Focus SQL Dialog Box

There is an option to save your logon ID and password in memory so that you do not need to be prompted the next time you try to compile a program using the same database. This information is lost the next time you reboot your client machine or if you type the following command from aVisual COBOL command prompt: MFDAEMON CLOSE.

  • Automated Compiles
Parent topic: Compiling


Automated Compiles

Having the graphical logon dialog appear might not be acceptable for automating compiles from a background process such as a command file. There is a way to supply the logon information by setting an environment variable and pointing the variable at a text file that contains the logon ID and password. To do this, set the environment variable SQLPASS.TXT to the name of the text file that contains the logon ID and password. For example:

SET SQLPASS.TXT=D:\BATCH.TXT

Then in the file batch.txt, specify the logon ID and password in the format id.password. For example:

MyId.Mypassword

If the security system used to validate your logon ID and password is case sensitive, you need to specify id.password in the correct case in this text file.

Note: Specifying the logon and password in a text file does raise security concerns, so care should be used when implementing this facility.
Parent topic: Compiling Programs That Use a Remote DB2 Server


DB2 Compiler Directive

You can specify the DB2 Compiler directive anywhere where you can specify any other Compiler directive. For example:

  • in a $SET statement:
    $set db2(init=prot bind collection=myschema)
  • using the Advanced Directives screen
Note: You cannot specify the DB2 directive more than once, so must only specify it in one of the possible places.

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 is dependent on the DB2 configuration, notably whether it is connected 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 will be 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


Linking

To link an application:

  1. Click Project > Properties for your current project.
  2. Click COBOL > Link Settings.
  3. In the Link with libs field, type db2api.lib; then click OK.
    Note: You must use the 32-bit version of db2api.lib even if you are running the 64-bit version of DB2 LUW software. In this case, include the full path to and filename of the 32-bit version of db2api.lib into the Link with libs field. The 32-bit version of db2api.lib is usually found in your \Program Files\IBM\SQLLIB\lib\Win32 directory.
Parent topic: DB2 External Compiler Module


Binding

If you use the NOACCESS option of the DB2 Compiler directive or intend to execute the application on a machine other than the one it was compiled on, bind the application to a particular database before execution. In this case, you should use the BIND option to create a bind file that can then be used to bind the program to the database using the DB2 BIND command. For details on doing this, see the documentation supplied with your SQL system.

You can direct the DB2 ECM to store bind files in a directory other than the current source directory by specifying the enviroment variable HCOBND, for example:

SET HCOBND=d:\production\binds

The directory you specify in the HCOBND environment variable is used to all bind files until you unset or reset the environment variable or unless you specify a specific bind file name using the DB2 BIND directive option, for example:

DB2(bind=d:\test\test1.bnd)

The DB2 BIND directive option overrides the HCOBND environment variable.

Parent topic: DB2 External Compiler Module


DB2 Stored Procedures

A stored procedure is a compiled program that can execute SQL statements.You need to use stored procedures if your 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.

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, 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 Stored Procedures under DB2 LUW
Parent topic: DB2
Related reference
CALL


Working with Stored Procedures

To get a stored procedure up and running:

  1. 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
      • mffh.dll
      • mfhcolib.dll
      • mfsqlsmf.dll
  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. See the section 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 the section Defining Stored Procedures under DB2 LUW for additional details.
  5. Compile your stored procedure. See the section Compiling Stored Procedures under DB2 LUW for additional details.
  6. Debug and test your stored procedure. See the section Debugging Stored Procedures under DB2 LUW for additional details.
Parent topic: DB2 Stored Procedures
Related concepts
Writing and Preparing Stored Procedures
Writing and Preparing Applications to Use 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.

  • Features of a Stored Procedure
  • Preparing Stored Procedures
  • How an Application Works With a Stored Procedure
Parent topic: DB2 Stored Procedures
Related concepts
Working with Stored Procedures
Writing and Preparing Applications to Use Stored Procedures


Features of a Stored Procedure

A stored procedure is similar to any other SQL application.

The following restrictions apply to stored procedures:

  • A C or COBOL stored procedure must be a dynamic link library (DLL) when built to run under Windows server.
  • To use SQL Procedure Language, you need to have a C compiler installed since the SQL statements generate a C program.
  • The following SQL statements are not allowed in a stored procedure:
    • CONNECT
    • DISCONNECT
    • SET CONNECTION
Parent topic: Writing and Preparing Stored Procedures


Preparing Stored Procedures

The following are tasks which must be completed before a stored procedure can be run on an 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 or JAVA routine on the DB2 LUW Server machine in a location specified in the CREATE PROCEDURE. If not specified, the default location is the sqllib\function subdirectory where DB2 LUW is installed.
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, 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: DB2 Stored Procedures
Related concepts
Working with Stored Procedures
Writing and Preparing Stored Procedures


Executing the SQL Statement CALL

Use the CALL statement to execute each series of SQL statements in your application.

Example 1

To call the stored procedure described in How an Application Works with a Stored Procedure, your application might use this statement:

EXEC SQL
 CALL GETEMPSVR (:V1, :V2)
END-EXEC

If you use host variables in the CALL statement, you must declare them before using them.

Example 2

The example above is based on the assumption that none of the input parameters can have null values. To allow null values, code a statement like this:

EXEC SQL
 CALL GETEMPSVR (:V1 :IV1, :V2 :IV2)
END-EXEC

where :IV1 and :IV2 are indicator variables for the parameters.

Example 3

To pass integer or character string constants or the null value to the stored procedure, code a statement like this:

EXEC SQL
 CALL GETEMPSVR (2, NULL)
END-EXEC

Example 4

To use a host variable for the name of the stored procedure, code a statement like this:

EXEC SQL
 CALL :PROCNAME (:V1, :V2)
END-EXEC

Example 5

Assume that the stored procedure name is GETEMPSVR. The host variable PROCNAME is a character variable of length 254 or less that contains the value GETEMPSVR. You should use this technique if you do not know in advance the name of the stored procedure, but you do know the parameter list convention.

To pass your parameters in a single structure, rather than as separate host variables, code a statement like this:

EXEC SQL
 CALL GETEMPSVR USING DESCRIPTOR :ADDVALS
END-EXEC

where ADDVALS is the name of an SQLDA.

Example 6

To use a host variable name for the stored procedure with an SQLDA, code a statement like this:

EXEC SQL
 CALL :PROCNAME USING DESCRIPTOR :ADDVALS
END-EXEC

This form gives you extra flexibility because you can use the same CALL statement to invoke different stored procedures with different parameter lists.

Your client program must assign a stored procedure name to the host variable PROCNAME and load the SQLDA ADDVALS with the parameter information before making the SQL CALL statement.

Each of the above CALL statement examples uses an SQLDA. If you do not explicitly provide an SQLDA, the precompiler generates the SQLDA based on the variables in the parameter list.

You can execute the CALL statement only from an application program. You cannot use the CALL statement dynamically.

Parent topic: Writing and Preparing Applications to Use Stored Procedures


Parameter Conventions

When an application executes the CALL statement, the DB2 LUW Server builds a parameter list for the stored procedure, using the parameters and values provided in the statement. The DB2 LUW Server obtains information about parameters from the system tables. See the section Defining Stored Procedures under DB2 LUW for more information. Parameters are defined as one of these types:

  • 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 DB2 LUW Server simply returns the output parameters to the calling program, with the values established on entry to the stored procedure. COBOL supports three parameter list conventions. Other languages support other conventions. The parameter list convention is chosen based on the parameter style defined in the CREATE PROCEDURE statement.

Parameter Style | Description
SIMPLE | Use SIMPLE (or GENERAL) to prevent the calling program passing null values for input parameters (IN or INOUT) to the stored procedure. The stored procedure must declare a variable for each parameter passed in the CALL statement.
SIMPLE WITH NULLS Use SIMPLE WITH NULLS (or GENERAL WITH NULLS) to allow the calling program to supply a null value for any parameter passed to the stored procedure. The following rules apply:
  • An indicator variable must follow each parameter in the calling program's CALL statement, using one of the following two forms:
    • host variable :indicator variable

      or:

    • host variable INDICATOR :indicator variable
  • The stored procedure must declare a variable for each parameter passed in the CALL statement.
  • The stored procedure must declare a null indicator structure containing an indicator variable for each parameter passed in the CALL statement.
  • On entry, the stored procedure must examine all indicator variables associated with input parameters to determine which parameters contain null values.
  • On exit, the stored procedure must assign values to all indicator variables associated with output variables. An indicator variable for an output variable that returns a null value to the caller must be assigned a negative number. Otherwise, the indicator variable must be assigned the value zero (0).
DB2SQL In addition to the parameters on the CALL statement, the following arguments are passed to the stored procedure:
  • a NULL indicator for each input 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.
Parent topic: Writing and Preparing Applications to Use Stored Procedures


Using Indicator Variables to Speed Processing

If any of your output parameters require a lot of storage, do not pass the entire storage areas to your stored procedure, but declare an indicator variable for every large output parameter in your SQL statement CALL. Indicator variables are used in the calling program to pass only a two-byte area to the stored procedure and to receive the entire area from the stored procedure.

Note: If you are using the SIMPLE WITH NULLS linkage convention, you must declare indicator variables for all of your parameters, so you do not need to declare another indicator variable for the large output parameters.

Assign a negative value to each indicator value associated with a large output variable. Then include the indicator variables in the CALL statement. This technique can be used whether the stored procedure linkage is SIMPLE or SIMPLE WITH NULLS.

For example, suppose that a stored procedure, STPROC2 defined with the SIMPLE linkage convention takes one integer input parameter and one character output parameter of length 5000. It is wasteful to pass the 5000 byte storage area to the stored procedure. Instead, a COBOL program containing these statements passes only two bytes to the stored procedure for the output variable and receives all 5000 bytes from the stored procedure:

INNUM  PIC S9(9) COMP
OUTCHAR PIC X(5000)
IND  PIC S9(4) COMP
.
.
.
MOVE -1                      TO IND
EXEC SQL CALL STPROC2(:INNUM, :OUTCHAR :IND)  END-EXEC
Parent topic: Writing and Preparing Applications to Use Stored Procedures


Declaring Data Types for Passed Parameters

A stored procedure must declare each parameter passed to it. In addition, the DATA TYPE declared in the declaration must be valid for the data source being used and must use a compatible host variable data type when calling the stored procedure. For more information on data types, see the chapter SQL Data Types earlier in this book.

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 precompiler and a ODBC connection.

Parent topic: Writing and Preparing Applications to Use Stored Procedures


Defining Stored Procedures under DB2 LUW

A stored procedure is unusable until it is defined. Use the CREATE PROCEDURE command to do this. You can either use the DB2 command prompt or place the command in a program and compile and run it. If you use the DB2 command prompt, you first connect to the DB2 LUW Server where the stored procedure will be executed.

For example:

C:> db2 connect to sample

You can type in the command at the DB2 command prompt making sure you include continuation characters and command delimiters, or you can place the CREATE PROCEDURE in an ANSI text file. For example, if we placed the previous command in text file creproc.sql, the command that you would enter would be:

C:> db2 -td; -vf creproc.sql

where:

  • the "-td" option indicates the next character is the delimiter to end the command. In our example, it is a semicolon (;).
  • the "-vf" option indicates that the next token is the file to process that contains the SQL command script.

The create procedure statement must uniquely identify a stored procedure. If you want to change the stored procedure to either add or drop parameters or change functionality, you must use the DROP PROCEDURE command and then re-add it with the CREATE PROCEDURE command.

When DB2/2 was originally developed, DB2/2 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: DB2 Stored Procedures


Compiling Stored Procedures under DB2 LUW

You can compile a COBOL stored procedure using DB2 LUW.

  1. Compile the program you want to use as a stored procedure with the DB2 directive, just like any DB2 LUW program. Do this by adding a $SET statement to your program.
    Note: If your program contains stored procedure CALL statements, you must specify the CALL_RESOLUTION DB2 directive to avoid an SQL0204 error.
  2. After the program has been added to the project, package it as a Dynamic Link Library (.dll).
  3. Click Project > Properties for your current project.
  4. Click COBOL > Link Settings.
  5. In the Link with libs field, type db2api.lib; then click OK.
  6. Right-click the .dll file; then click Rebuild object from the context menu.
  7. From the Rebuild object command, click Project > Deployment; then select the file and copy it to the sqllib\function directory.
Parent topic: DB2 Stored Procedures


COBSQL

You can use COBSQL to access the SQL functions offered by the Oracle, Sybase or Informix Database Management System (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"FREE". You must use OpenESQL if your programs are free format.
  • Using COBSQL
  • Using the CP Preprocessor to Expand Copybooks
  • National Locale Support (NLS)
  • Examples
  • Troubleshooting
Parent topic: Database Access
Related concepts
Database Access Preprocessors
Compiling SQL Applications


Using COBSQL

To use COBSQL, specify the PREPROCESS(cobsql) Compiler directive when you compile your program. All directives following it are passed from the Compiler to COBSQL. You can specify Compiler directives by using $SET statements in your program or via the Additional Directives field, located on the COBOL tab of your project's Properties dialog box.

To terminate the directives to be passed to COBSQL, you must use the ENDP COBOL directive.

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 precompiler
  • Directives placed after ENDP pass to the COBOL compiler. Therefore, without the ENDP directive, compiler directives continue to pass to COBSQL rather than to the COBOL compiler.
preprocess(cobsql) csqltype=database_product end-c
    comp5=yes endp;

where database_product is one of Oracle, Sybase or Informix. For example, for Oracle:

preprocess(cobsql) csqltype=oracle end-c comp5=yes endp;
Note: Visual COBOL ignores any directives placed after the semi-colon (;) in the Additional Directives field. Therefore, if you add the above line to the additional directives, you must position the line at the end of the settings.

Because the system sets extra default COBOL directives, the above line is required when putting directives into the Additional Directives field.

Examples

cobol testprog p(cobsql) cobsqldirectives END-C precompileroptions ENDP compilerdirectives;

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 Compiler directive is list().

  • Specifying Directives
  • COBOL Directives
  • Building COBSQL Applications
Parent topic: COBSQL


Specifying Directives

You specify directives to COBSQL as if they were Compiler directives, but you must put them after the directive PREPROCESS(cobsql).

It is also possible to add the COBSQL directives to the directives file cobol.dir.

Note:
  • Each line in the cobol.dir file may contain one or more compiler directives
  • Don't split a compiler directive across multiple lines in the cobol.dir file
  • When the compiler encounters either P(cobsql) or PREPROCESS(cobsql) in the cobol.dir file, the compiler passes the rest of the line to the pre-processor until it reaches an 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 the options must all appear on a single line in the cobol.dir file.

Alternatively, you can put COBSQL and precompiler directives in a file, cobsql.dir. This file should reside either in the current directory or in a directory specified by the environment variable COBDIR. COBSQL searches the current directory and then along the COBDIR path for a cobsql.dir file. Once COBSQL finds a cobsql.dir file, it stops searching. So, if you have a cobsql.dir file in the current directory, the COBDIR path is not searched.

Note:
  • Each line in the file cobsql.dir can contain one or more COBSQL directives
  • Since COBOL does not read the file cobsql.dir, don't put COBOL compiler directives into the file
  • Don't split a COBSQL directive across multiple lines in the file cobsql.dir
  • When COBSQL encounters either END-C, END or END-COBSQL in the cobsql.dir file, 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 file cobsql.dir

COBSQL processes cobsql.dir first and then any directives specified via the Build Settings screen or command line.

A number of the directives can be reversed by placing NO in front of them, for example, DISPLAY can be reversed using NODISPLAY. By default, the NO version of a directive is set.

You can specify shortened versions of some of the directives. If applicable, the shortened version of a directive is shown in the lists below, immediately after the full length version.

Some directives can be passed to COBSQL by the COBOL Compiler (see the section COBOL Directives below), removing the need to specify common directives more than once. Directives that can be retrieved from the COBOL Compiler are processed before COBSQL directives.

For example, in the following:

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 Compiler directive is list().
Parent topic: Using COBSQL


COBOL Directives

The following are COBOL directives that the Compiler also passes to 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.
Parent topic: Using COBSQL


Building COBSQL Applications

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. To do this, go to your project's properties page, COBOL tab, and click Link Settings. Type csqlsupp.lib into the Link with libs field.

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: Using COBSQL


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%\Micro Focus\Visual COBOL\cpylib directory. If the SQLCA file supplied by the database vendor is not located on the COBCPY path, this example of the SQLCA will be used.
Note: Using the file sqlca.cpy can result in errors when the program is run.

You can specify the CP preprocessor's SY directive to prevent CP expanding the SQLCA include file, for example:

preprocess(cobsql) preprocess(cp) sy endp

You should always use CP's SY directive when processing Sybase code because Sybase expects to expand the SQLCA itself.

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)

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


Examples

The following examples show, for the Oracle and Sybase precompilers, command lines which can be entered at the Visual COBOL command prompt to compile a program using COBSQL.

Oracle
cobol sample.pco anim  preprocess(cobsql)
   cstart cstop CSQLT=ORA end-c comp5=yes endp;
Sybase
cobol example1.pco confirm preprocess(cobsql)
   cstop csp cobsqltype=sybase preprocess(cp) sy endp;
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 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


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

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

COBOL -k PROG P(HTMLPP) PREPROCESS(cobsql) CSQLT=ORACLE8

whereas this line does not:

COBOL -k PROG PREPROCESS(cobsql) CSQLT=ORACLE8 P(HTMLPP)

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 change to your system:

  • 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
  • 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 errror; 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.
  • When the Sybase precompiler runs, it can generate useful information. If the COBSQL directive VERBOSE is set, COBSQL displays as much of this information as it can.
  • By using the COBSQL DISPLAY directive, the statistical information created by the Sybase precompiler can be seen on the screen.
  • If the COBOL LIST directive is set, COBSQL passes any information it has collected from the precompiler to the COBOL checker for inclusion at the end of the COBOL listing.
  • The Sybase precompiler accepts programs that do not contain any SQL statements, and produces an output file. This means that all of the programs in a project can be compiled successfully. However, it also means that the Sybase precompiler inserts all the Working-Storage items and COBOL support code that it would insert for a program that contains Sybase SQL statements into a non-Sybase program. This makes the program larger, and may effect its performance.
  • The Sybase COBOL precompiler can be supplied separately to the Sybase System 11 Server. If this is the case, care must be taken when installing the Sybase COBOL precompiler as it is supplied with its own version of the Open Client support files and problems can arise if the two products have different versions of these files. In this situation, we strongly recommend that you contact Sybase support before proceeding with the installation of the Sybase System 11 COBOL precompiler.
  • You should take particular care if you are installing the Sybase client onto a machine that has the Server installed onto it (or vice versa). Installing the Sybase client only does not cause any problems.
Parent topic: Troubleshooting


Informix Considerations

  • Informix uses the .eco, .cob and .mf2 file extensions. For CP to resolve copybooks and include statements correctly, use the following COBOL Compiler directives:
    copyext(eco,mf2,cob,cpy,cbl) osext(eco)
  • 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...

How to use the database access utilities and editors available to help you develop and deploy your SQL applications.

  • OpenESQL Configuration Utility
  • OpenESQL Assistant
  • ADO.NET Connection Editor
  • SQL CLR Databases
Parent topic: Database Access


OpenESQL Configuration Utility

  • To start the OpenESQL Configuration Utility
  • To set a default for SQL(BEHAVIOR)
Parent topic: How to...


To start the OpenESQL Configuration Utility

  • Click Start > All Programs > Micro Focus Visual COBOL > Configuration > OpenESQL Configuration Utility.
Parent topic: OpenESQL Configuration Utility
Related reference
esqlconfig command
Related information
OpenESQL Configuration Utility


To set a default for SQL(BEHAVIOR)

  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 reference
BEHAVIOR
Related information
OpenESQL Configuration Utility
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


OpenESQL Assistant

  • To add a column to a query
  • To add all columns in a table to a query
  • To add an XML data source
  • To add or update a SQL CLR Stored Procedure in a SQL CLR Database project
  • To change a SELECT (cursor) query to do an array FETCH
  • To close a query
  • To close the OpenESQL Assistant
  • To configure the OpenESQL Assistant
  • To connect to a data source
  • To connect to a different data source
  • To create a table join
  • To create an SQL query
  • To create a SQL CLR stored procedure 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 COBOL program
  • To generate a DCLGEN copybook
  • 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 a DECLARE DATATABLE statement
  • To generate an INSERT statement
  • To generate an UPDATE statement
  • To generate and embed auxiliary code
  • To perform an aggregate function
  • To refresh the list of data sources
  • To remove a table from a SELECT query
  • To run a query
  • To sort returned data (an ORDER BY clause)
  • To specify search criteria (a WHERE clause)
  • To start the OpenESQL Assistant
  • 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
OpenESQL Assistant
Selecting Columns
Related tasks
To add all columns in a table to a query
To create an SQL query


To add all columns in a table to a query

  1. In the OpenESQL Assistant, identify a table in the tree view that has been selected for the query and contains the columns you want to add to the query.
  2. Right-click the table name.
  3. Click Select All Columns.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Selecting Columns
Related tasks
To add a column to a query


To add an XML data source

  1. Start the OpenESQL Assistant.
  2. Right-click on the data source list.
  3. Click Add XML Data Source.
  4. Browse to the XML file you want to use as a data source and double-click to select it. This file must contain an embedded XML schema for the file as well as data.
Note:

This feature is available only when you set the following Visual Studio options for OpenESQL Assistant as follows:

  • Mode option set to ADO.NET
  • Generate option set to EXEC ADO - disconnected model
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Setting OpenESQL Assistant Options
Related tasks
To start the OpenESQL Assistant


To add or update a SQL CLR Stored Procedure in a SQL CLR Database project

  1. In Visual Studio, make your SQL CLR Database project the active project.
  2. Start OpenESQL Assistant.
  3. Right-click over the toolbar and select Add SP to SQLCLR project.
  4. If the stored procedure already exists, OpenESQL prompts you to replace the program in the project.
Note: To ensure that the program compiles properly and deploys the appropriate runtime, set the following properties, found on the project properties SQL tab:
ESQL Preprocessor | OpenESQL
DBMAN Directive | ADO
Parent topic: OpenESQL Assistant
Parent topic: SQL CLR Databases
Related concepts
Generating a SQL CLR Stored Procedure Query
Testing a SQL CLR Stored Procedure Query in a SQL CLR Project
Related tasks
To create a SQL CLR stored procedure query
To create a SQL CLR database project
To generate a SQL CLR stored procedure


To change a SELECT (cursor) query to do an array FETCH

  1. Check your OpenESQL Assistant configuration and be sure that the Use SQL TYPE check box is unchecked. This is necessary because the compiler does not support OCCURS clauses defined with SQL TYPE host variables.
  2. In the IDE, open the project that contains the program that contains the SELECT (cursor) query you want to modify.
  3. Open the appropriate program in the program editor.
  4. Locate the FETCH statement in the code generated for SELECT (cursor) statements.
  5. Remove the comments that appear before and between the PERFORM and END-PERFORM statements.
  6. Place your cursor between the PERFORM and END-PERFORM statements.
  7. In the OpenESQL Assistant, click the Auxiliary Code tab.
  8. Click Host Variables.
  9. In the Host Variable Array Size field, type the number that represents the maximum number of rows you want returned for each array FETCH.
  10. Click Insert Query into Current Program Insert Query into Current Program.
Note: If you decide to code the PERFORM without using code generated byOpenESQL Assistant, you should either define the index variable IDX or modify the code to use a variable that has been already defined to process the array loop.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Setting OpenESQL Assistant Options
Embedding SQL into a Program
Auxiliary Code
Embedding Auxiliary Code
Generating EXEC SQL Auxiliary Code
Changing a SELECT (cursor) query to do an Array FETCH
Related tasks
To generate and embed auxiliary code


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
OpenESQL Assistant
Close a Query
Related tasks
To create an SQL query


To close the OpenESQL Assistant

  • From the OpenESQL Assistant, click Close Close.
Parent topic: OpenESQL Assistant


To configure the OpenESQL Assistant

  1. From Visual Studio, click Tools > Options; then expand Micro Focus Visual COBOL 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


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
OpenESQL Assistant
Building Queries
Connecting to a Data Source
Related tasks
To start the OpenESQL Assistant
To connect to a different data source
To create a TSQL stored procedure query


To connect to a different data source

  1. On the OpenESQL Assistant, click Create a new query Create a 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
OpenESQL Assistant
Connecting to a Data Source
Related tasks
To connect to a data source
To view data source properties
Related information
To connect to a data source
To view data source properties
The OpenESQL Assistant


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 an SQL query

  1. Start the OpenESQL Assistant.
  2. Double-click a data source.
  3. Check the box next to a table name.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Building Queries
Selecting a Table and a Query Type
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 SQL CLR stored procedure query

  1. Be sure that you have enabled SQL CLR and that you have created a SQL CLR database.
  2. From the Visual Studio IDE, set the Type Stored Procedure option in your OpenESQL Assistant options to SQLCLR.
  3. Create a new SQL CLR database project.
  4. Start the OpenESQL Assistant.
  5. Connect to a Microsoft SQL Server data source.
  6. Check the box next to a table name.
  7. Click a query type from the list.
  8. Check Generate Query as a SQLCLR Stored Procedure.
  9. In the SP name field, type a name for the stored procedure. Alternatively, accept the default value. The generated program name is the same as the stored procedure name.
  10. Click OK.
  11. Continue to build your query.
Note: For detailed information on building a query, see the topic Building Queries.
Parent topic: OpenESQL Assistant
Parent topic: SQL CLR Databases
Related concepts
Building Queries
SQL CLR Stored Procedures
Generating a SQL CLR Stored Procedure Query
Stored Procedures
Setting OpenESQL Assistant Options
Prerequisites for SQL CLR Integration
Related tasks
To create a SQL CLR database project
To generate a SQL CLR stored procedure
To add or update a SQL CLR Stored Procedure in a SQL CLR Database project


To create a TSQL stored procedure query

  1. In your OpenESQL Assistant Options, set Query > Type Stored Procedure to TSQL.
  2. Start the OpenESQL Assistant.
  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.
Note: For detailed information on building a query, see the topic Building Queries.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Building Queries
Setting OpenESQL Assistant Options
Stored Procedures
Generating a TSQL Stored Procedure Query
Related tasks
To start the OpenESQL Assistant
To connect to a data source


To disconnect from a data source

  • On the OpenESQL Assistant, click Create a new query Create a new query, or uncheck the box next to the data source name.
Parent topic: OpenESQL Assistant
Related concepts
Disconnect from a Data Source


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 COBOL program

  1. In the OpenESQL Assistant, create an SQL query.
  2. In the IDE, open the project that contains the program into which you want to embed the SQL.
  3. Open the appropriate program in the program editor.
  4. Place your cursor at the point in your program where you want the query to appear.
  5. On the OpenESQL Assistant, click Insert Query into Current Program Insert Query into Current Program.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Setting OpenESQL Assistant Options
Embedding SQL into a Program
Auxiliary Code
Embedding Auxiliary Code
Generating EXEC SQL Auxiliary Code
Embedding a TSQL Stored Procedure into a Program
Related tasks
To generate and embed auxiliary code


To generate a DCLGEN copybook

  1. Start the OpenESQL Assistant.
  2. Connect to a data source.
  3. Check the box next to a table name.
  4. Click Generate DCLGEN.
Note: This feature is available only when you set the following Visual Studio options for OpenESQL Assistant as follows:
  • Mode option set to ADO.NET
  • Generate option set to EXEC ADO - disconnected model
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Setting OpenESQL Assistant Options


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
Selecting a Table and a Query Type
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
Selecting a Table and a Query Type
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
Selecting a Table and a Query Type
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 a DECLARE DATATABLE statement

  1. Start the OpenESQL Assistant.
  2. Connect to a data source.
  3. Check the box next to a table name.
  4. Click Generate DataTable.
Note:

This feature is available only when you set the following Visual Studio options for OpenESQL Assistant as follows:

  • Mode option set to ADO.NET
  • Generate option set to EXEC ADO - disconnected model
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Setting OpenESQL Assistant Options


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
Selecting a Table and a Query Type


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
Selecting a Table and a Query Type
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, EXEC ADO connected, or EXEC ADO disconnected, depending on the type of code you want to generate.
  6. If you want to specify a data set name for EXEC ADO, type the data set name into the Dataset name field. Optional.
  7. Click Insert Query into Current Program Insert Query into Current Program.
Note: To enable OpenESQL Assistant to generate EXEC ADO code, be sure to check the Generate EXEC ADO option when you set options for OpenESQL.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Setting OpenESQL Assistant Options
Embedding SQL into a Program
Auxiliary Code
Embedding Auxiliary Code
Generating EXEC SQL Auxiliary Code
Generating a SQL CLR Stored Procedure Query
Related tasks
To embed an SQL query into a COBOL program
To change a SELECT (cursor) query to do an array FETCH


To perform an aggregate function

  1. In the OpenESQL Assistant, create a SELECT (cursor) or a SELECT DISTINCT (cursor) query.
  2. On the tree view, right-click a column name.
  3. Click an aggregate function to perform on the column.
Note: For more information about aggregate functions, see the SQL documentation for your DBMS.
Parent topic: OpenESQL Assistant
Related concepts
Specifying Aggregate Functions for Columns


To refresh the list of data sources

  • In the OpenESQL Assistant, click Refresh list of available data sources Refresh list of available data sources.
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
OpenESQL Assistant
Remove a Table from a SELECT Query
Related tasks
To create an SQL query


To run a query

  1. In the OpenESQL Assistant, create an SQL query.
  2. Click Run the Query Insert Query into Current Program.
Parent topic: OpenESQL Assistant


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
OpenESQL Assistant
Specifying the Order in which Data is Retrieved
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


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
OpenESQL Assistant
Specifying Search Criteria
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


To start the OpenESQL Assistant

  1. Click Tools > Micro Focus Visual COBOL > OpenESQL Assistant.
  2. If prompted, type your user name and password and click OK.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Setting OpenESQL Assistant Options
Building Queries
Starting the OpenESQL Assistant
Related tasks
To add an XML data source
To connect to a data source
To create a TSQL stored procedure query
To create an SQL query


To view data source properties

  • In the OpenESQL Assistant, right-click a data source on the tree view, then click Data Source Properties from the popup menu.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Related tasks
To connect to a different data source


ADO.NET Connection Editor

  • To start the ADO.NET Connection Editor
  • To catalog an ADO.NET data provider
  • To uncatalog an ADO.NET data provider
  • To test an ADO.NET connection
  • To export ADO.NET connection settings
  • To import ADO.NET connection settings
Parent topic: How to...


To start the ADO.NET Connection Editor

  1. Do one of the following:
    • From your desktop, click Start > All Programs > Micro Focus Visual COBOL > Data Tools > Data Connections > ADO.NET Connection Editor.
    • From the Visual Studio IDE, click Tools > Micro Focus Visual COBOL > ADO.NET Connection Editor.
    • From the OpenESQL Assistant, click ADO.NET Connection Editor Button ADO.NET Connection Editor.
Parent topic: ADO.NET Connection Editor
Related concepts
ADO.NET Connection Editor
Related tasks
To catalog an ADO.NET data provider
To uncatalog an ADO.NET data provider


To catalog an ADO.NET data provider

  1. Start the ADO.NET Connection Editor.
  2. On the Connection tab, select a Connection Type, Framework, and Connection Availability for this connection; then click Add.
  3. On the Provider tab, click the ADO.NET data provider that you want to use, then type a data source name into the Data Source Name field. All data providers installed on your machine appear on this list.
  4. If you want the connection settings for your data source to be encrypted in the repository, check Encrypt connection settings. Optional.
  5. Click Next. This automatically saves your new connection information.
  6. Do one of the following:
    • If your ADO.NET data provider is an OleDb provider, the Microsoft Data Link Properties dialog box appears. Select an OLE DB provider from the Provider tab. Depending on the provider you select, you might need to also select a data source and set security on the Connection tab, then click OK. For more information, click the Help button on the dialog box.
      Note:

      If the Data Link Properties dialog box provides a Test button for your data provider, we recommend that you click it to test the connection. If the connection fails here it will also fail in ADO.

    • If your ADO.NET data provider is not an OleDb provider, proceed to step 7.
  7. On the Connection tab, ensure that each default value listed in the Value column is valid, editing incorrect values when necessary. If you make changes, click Save.
  8. Optionally test your connection.
  9. Click OK to exit the ADO.NET Connection Editor.
Parent topic: ADO.NET Connection Editor
Related concepts
ADO.NET Connection Editor
Cataloging an ADO.NET Connection
Related tasks
To start the ADO.NET Connection Editor
To test an ADO.NET connection
To uncatalog an ADO.NET data provider


To uncatalog an ADO.NET data provider

  1. Start the ADO.NET Connection Editor.
  2. On the Connection tab, select a Connection Type, Framework, and Connection Availability for the connection you want to uncatalog. This populates the Data Source Name list with connections that fit your selections.
  3. On the Data Source Name list, click connection you want to remove.
  4. Click Remove.
  5. Click OK.
  6. Click Yes at the prompt to save your changes and exit.
Parent topic: ADO.NET Connection Editor
Related concepts
ADO.NET Connection Editor
Cataloging an ADO.NET Connection
Related tasks
To catalog an ADO.NET data provider
To start the ADO.NET Connection Editor
To test an ADO.NET connection


To test an ADO.NET connection

  1. Start the ADO.NET Connection Editor.
  2. On the Connection tab, select a Connection Type, Framework, and Connection Availability for the connection you want to test. This populates the Data Source Name list with connections that fit your selections.
  3. On the Data Source Name list, click the connection you want to test.
  4. If your application requires a user ID and password to connect to a data source, type these into the User ID and Password fields. Optional.
  5. Click Test Connection. A message box appears reporting the status of the connection attempt.
  6. Click OK to clear the prompt.
Note: If your application requires a user ID and password to connect to a data source, then for security reasons, do not save the user ID and password in the Connection Settings table. Information in those fields is used only to test the connection and is ignored when a CONNECT statement is executed. To provide your application with a user ID and password, pass the values as parameters in the CONNECT statement.
Parent topic: ADO.NET Connection Editor
Related concepts
ADO.NET Connection Editor
Related tasks
To catalog an ADO.NET data provider
To uncatalog an ADO.NET data provider


To export ADO.NET connection settings

  1. From the Export tab in the ADO.NET Connection Editor, click the connections you want to export, or check Select all connection names.
  2. In the Export to field, type the full path to and filename of an XML file you want to contain exported information, or click Browse Browse to select a directory.
    Note:
    • If you choose to type in the full path and filename, you can name the file anything you want.
    • If you choose to browse to select a directory, the Connection Editor uses the default filename MFconnectInfo.xml. You can overtype the filename with a different name of your choice.
  3. Click Export.
  4. Click OK to clear the prompt.
Parent topic: ADO.NET Connection Editor
Related concepts
ADO.NET Connection Editor
Related tasks
To import ADO.NET connection settings
Related reference
MFImportConn command


To import ADO.NET connection settings

  1. From the Import tab in the ADO.NET Connection Editor, type the full path to and filename of the XML file that contains exported information, or click Browse Browse to select a file.
  2. Click Import.
  3. Click OK to clear the prompt.
Note: You can also import connection settings using the MFImportConn command.
Parent topic: ADO.NET Connection Editor
Related concepts
ADO.NET Connection Editor
Related tasks
To export ADO.NET connection settings
Related reference
MFImportConn command


SQL CLR Databases

  • To create a SQL CLR database project
  • To create a SQL CLR stored procedure query
  • To generate a SQL CLR stored procedure
  • To add or update a SQL CLR Stored Procedure in a SQL CLR Database project
  • To generate a COBOL wrapper for a SQL CLR stored procedure
Parent topic: How to...


To create a SQL CLR database project

  1. Be sure that you have enabled SQL CLR and that you have created a SQL Server database.
  2. From the Visual Studio IDE, click File > New > Project.
  3. Under Installed Templates, click COBOL > Database.
  4. From the drop-down list above SQL CLR Database Project, select .NET Framework 3.5.
    Note: SQL Server 2008 R2 cannot run SQL CLR assemblies created using .NET Framework 4.0.
  5. Click SQL CLR Database Project.
  6. Complete the Name and Location fields; then click OK. Visual COBOL launches the Add Database Reference dialog box.
  7. On the Add Database Reference dialog box, provide your SQL Server instance name, select a login authentication method, provide a user name and password if required, and specify the the name of your SQL Server database.
  8. Click Test Connection to verify that you have a valid SQL Server connection; then click OK to clear the message.
  9. Click OK to close the Add Database Reference dialog box.
Parent topic: SQL CLR Databases
Related concepts
Prerequisites for SQL CLR Integration
Generating a SQL CLR Stored Procedure Query
SQL CLR Database Project Template
Setting OpenESQL Assistant Options
Building Queries
SQL CLR Stored Procedures
Related tasks
To generate a SQL CLR stored procedure
To create a SQL CLR stored procedure query
To add or update a SQL CLR Stored Procedure in a SQL CLR Database project


To generate a SQL CLR stored procedure

  1. In Visual COBOL, open a SQL CLR database project that contains a SQL CLR stored procedure.
  2. From the Solution Explorer, open the project properties.
  3. On the SQL tab, set the DBMAN directive to ADO.
  4. Ensure that the BEHAVIOR compiler directive option is set to MAINFRAME for optimized performance.
  5. Build and deploy your SQL CLR stored procedure.
Note: If you make changes at a later date, you can update the project using the Add SP to SQLCLR option from the context menu in the OpenESQL Assistant.
Parent topic: SQL CLR Databases
Related concepts
SQL CLR Stored Procedures
Generating a SQL CLR Stored Procedure Query
Generating EXEC SQL Auxiliary Code
Prerequisites for SQL CLR Integration
Testing a SQL CLR Stored Procedure Query in a SQL CLR Project
Building Queries
Related tasks
To create a SQL CLR database project
To create a SQL CLR stored procedure query
To add or update a SQL CLR Stored Procedure in a SQL CLR Database project
Related reference
BEHAVIOR
DBMAN


To generate a COBOL wrapper for a SQL CLR stored procedure

  1. From the Visual Studio IDE, open a SQL CLR Database project that contains a stored procedure definition (.spd) file, or add an existing stored procedure definition file to an open SQL CLR Database project.
  2. Right-click the stored procedures definition file, and select Properties.
  3. In the Custom Tool field, type SPDFileCodeGenerator.
  4. From the Solution Explorer, right-click the stored procedures definition file, and select Run Custom Tool.
Parent topic: SQL CLR Databases
Related concepts
COBOL Wrapper Programs
SQL CLR Integration Process


Reference

Reference information for embedded statements, compiler directives, and other coding standards associated with database access.

  • OpenESQL
  • DB2
  • COBSQL
  • SQL Data Types
  • SQL TYPEs
  • Data Structures
  • Keywords
Parent topic: Database Access


OpenESQL

  • Embedded SQL Statements
  • Embedded ADO Statements
  • SQL Compiler Directive Options
  • DBMAN Directive Settings
  • SQL/COBOL Data Type Mappings
  • OpenESQL 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.
  • MFImportConn command
    Enables you to import connection settings previously exported from the ADO.NET Connection Editor.
Parent topic: Reference


Embedded SQL Statements

With the exception of INSERT, DELETE(SEARCHED) and UPDATE(SEARCHED) which are included for your convenience, the embedded SQL statements described here work somewhat differently, or are in addition to, standard SQL statements.

  • BEGIN DECLARE SECTION
    Signals the beginning of the DELCARE 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.
  • 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.
  • 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.
  • 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 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.
  • 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.
  • ROLLBACK
    Backs out any changes made to the database by the current transaction on the current connection.
  • 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 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.
  • SET TRANSACTION ISOLATION
    Sets the transaction isolation level for the current connection to one of the isolation level modes specified by ODBC.
  • UPDATE (Positioned)
  • UPDATE (Searched)
    Updates a table or view based on specified search conditions.
  • WHENEVER
    Specifies the default action after running an Embedded SQL statement when a specific condition is met.
Parent topic: OpenESQL
Related concepts
Embedded SQL
Related reference
SQL


BEGIN DECLARE SECTION

Signals the beginning of the DELCARE 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


CALL

Executes a stored procedure.

Syntax:

>>--EXEC SQL--.-----------------.--.----------------.->
              +-FOR :host_integer--+  +- :result_hvar -+

 >---CALL stored_procedure_name-.------------.-END-EXEC-><
                                | +-- , --+  |
                                | V       |  |
                                +(parameter)-+

Parameters:

host_integer | A host variable that specifies the maximum number of host array elements processed. Must be declared as PIC S9(4) COMP-5 or PIC S9(9) COMP-5.
result_hvar | A host variable to receive the procedure result.
stored_procedure_name | The name of the stored procedure.
parameter A literal, a DECLARE CURSOR statement1, or a host variable parameter of the form:
[keyword=]:param_hvar [IN | INPUT |
INOUT | OUT | OUTPUT]

where:

keyword | The formal parameter name for a keyword parameter. Keyword parameters can be useful as an aid to readability and where the server supports default parameter values and optional parameters.
param_hvar | A host variable.
IN | An input parameter.
INPUT | An input parameter (default).
INOUT | An input/output parameter.
OUT | An output parameter.
OUTPUT | An output parameter.

1 Specify DECLARE CURSOR only with Oracle 8 or later and for stored procedures that return a result set. The use of DECLARE CURSOR unbinds the corresponding parameter.

Comments:

Do not use the FOR clause if the CALL is part of a DECLARE CURSOR statement.

For maximum portability, observe the following as general rules:
  • Avoid literal parameters
  • Use host variable parameters
  • Avoid mixing positional parameters and keyword parameters
  • If your server supports a mixture of positional and keyword parameters, list keyword parameters after positional parameters

Examples:

Call a stored procedure using two positional host variables as input parameters:
   EXEC SQL
      CALL myProc(param1,param2)
   END-EXEC
Call a stored procedure using a keyword host variable as an input parameter:
   EXEC SQL
      CALL myProc (namedParam=:paramValue)
   END-EXEC
Call a stored procedure using a result host variable and a keyword host variable as an input parameter:
   EXEC SQL
      :myResult = CALL myFunction(namedParam=:paramValue)
   END-EXEC
Call a stored procedure using two positional host variables, one as an input parameter and one as an output parameter:
   EXEC SQL
      CALL getDept(:empName IN, :deptName OUT)
   END-EXEC
Call a stored procedure using a DECLARE CURSOR statement and a positional host variable as an input parameter (Oracle only):
   EXEC SQL
      DECLARE cities CURSOR FOR CALL locateStores(:userState)
   END-EXEC
Parent topic: Embedded SQL Statements
Related concepts
OpenESQL
Working With OpenESQL Stored Procedures and Result Sets
Related reference
DECLARE CURSOR
EXECSP


CLOSE

Discards unprocessed rows and frees any locks held by the cursor.

Syntax:

>>---EXEC SQL---CLOSE---cursor_name---.------------.---END-EXEC---><
                                      +WITH RETURN-+

Parameters:

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.

You can specify WITH RETURN in a SQL CLR stored procedure not compiled with DIALECT=MAINFRAME. If you do so, the client application must use the GET NEXT RESULT SET statement to retrieve the result set(s).

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---COMMIT----.--------------.--->
                          +-WORK---------+
                          +-TRAN---------+
                          +-TRANSACTION--+

 >---.-----------.---END-EXEC--><
     +--RELEASE--+

Parameters:

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 reference
CONNECT
DISCONNECT
ROLLBACK
SET CONNECTION


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 or ADO.NET data store. For ODBC data stores, this is the DSN created via the Microsoft ODBC Data Source Administrator. For ADO.NET data stores, this is a data source name created via the Micro Focus ADO.NET Connection Editor.

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.

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:
  • The CONNECT WITH PROMPT syntax is not supported for applications compiled with SQL(DBMAN=ADO).
  • 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.
  • If you are using the ADO.NET runtime and Format 6, you must add factory=invariantname to the input_connection specification. You can find the invariant name on the Add page of the ADO.NET Connection Editor.

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.

 01  connString    string.
 set connString    to  "Trusted_Connection=yes;Database=Northwind;server=localhost;factory=System.Data.SqlClient;"

 procedure division.

     EXEC SQL
         CONNECT USING :connString
     END-EXEC

The above example shows appropriate syntax for the ADO.NET runtime.

Parent topic: Embedded SQL Statements
Related concepts
Compiling Multiple Program Modules
Database Connections
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:

>>--EXEC SQL---.------------.------DECLARE cursor_name------>
               +-AT db_name-+

 >--.-------------.-----.---------.------.--------------.--->
    +-SENSITIVE---+     +-FORWARD-+      +-LOCK---------+
    +-INSENSITIVE-+     +-KEYSET--+      +-LOCKCC-------+
                        +-DYNAMIC-+      +-OPTIMISTIC---+
                        +-STATIC--+      +-OPTCC--------+
                        +-SCROLL--+      +-OPTCCVAL-----+
                                         +-READ ONLY----+
                                         +-READONLY-----+
                                         +-FASTFORWARD--+
                                         +-FAST FORWARD-+

 >--CURSOR-------.----------------.---------FOR------------->
                 +----WITH HOLD---+
                 +----WITH RETURN-.----------.-|
                                  +TO CALLER-+

      +-- ; ---------------------------------+
      V                                      |
 >----.----select_stmt-----------------------.-------------->
      +----stored_procedure_call_statement---+
      +----prepared_stmt_name----------------+
      +----OPTIMIZE FOR n ROWS---------------+
 >--.-------------------------------.----------------------->
    +-FOR READ ONLY-----------------+
    +-FOR UPDATE-.----------------.-+
                 +-OF column_list-+
 >------END-EXEC--------><

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

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 WITH RETURN in a SQL CLR stored procedure compiled with DIALECT=MAINFRAME. If you do so, the client application must use the ALLOCATE CURSOR and ASSOCIATE LOCATOR statements to retrieve the result set(s).

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


DELETE (Positioned)

Deletes the row most recently fetched by using a cursor.

Syntax:

>>---EXEC SQL---DELETE---FROM---table_name--------------->

 >----WHERE CURRENT OF---cursor_name---END-EXEC---><

Parameters:

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--.-------------------.---DELETE--.------.--->
              +-FOR :host_integer-+           +-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.
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.

Syntax:

>>---EXEC SQL-----DESCRIBE---.----------------------.----->
                             +---SELECT LIST FOR----+
                             +---BIND VARIABLES FOR-+

 >--prepared_stmt_name---INTO---:sqlda_struct---END-EXEC--><

Parameters:

prepared_stmt_name | The name of a prepared SQL SELECT statement or QUERY ODBC statement.
: 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 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 accomodate.
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=MAINFRAME 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:

     EXEC SQL INCLUDE SQLDA END-EXEC
     EXEC SQL BEGIN DECLARE SECTION END-EXEC
     01 statement   pic x(80).
     EXEC SQL END DECLARE SECTION END-EXEC

     EXEC SQL
         DECLARE C1 CURSOR FOR stmt1
     END-EXEC

     move "select * from dept" into 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

     EXEC SQL
         FETCH C1 USING DESCRIPTOR :sqlda
     END-EXEC
Parent topic: Embedded SQL Statements
Related concepts
Dynamic SQL
Data Structures
Related reference
PREPARE
FETCH
INCLUDE


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 backwards 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 OpenESQL 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-------.-------------.------cursor_name-->
                +---PREVIOUS--+
                +---LAST------+
                +---PRIOR-----+
                +---FIRST-----+
                +---NEXT------+

 >--.-------------------------------------.------->
    +-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.
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 OpenESQL 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 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 HENV INTO :HENV
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---GET NEXT RESULT SET FOR ---cursor_name---END-EXEC---><

Parameter:

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 OpenESQL 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.
db_name | The name of a database that has been declared using DECLARE DATABASE.
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)


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
Parent topic: Embedded SQL Statements
Related concepts
Cursors
Data Structures
Dynamic SQL
Related reference
CLOSE
DECLARE CURSOR
FETCH
INCLUDE
QUERY ODBC


PERSIST

Saves information defined in a cursor SELECT statement as XML files.

Syntax:

>>-EXEC SQL--PERSIST cursor_name TO xml_destination->
>-----END-EXEC-----<>

Parameters:

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 reference
SET SCROLLOPTION
Related information
XML Support


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


ROLLBACK

Backs out any changes made to the database by the current transaction on the current connection.

Syntax:

>>---EXEC SQL---ROLLBACK----.-WORK---------.------------->
                            +-TRAN---------+
                            +-TRANSACTION--+

 >---.-----------.---END-EXEC---><
     +--RELEASE--+

Comment:

If RELEASE is specified and the transaction was successfully rolled back, the current connection is closed.

Example:

EXEC SQL
   ROLLBACK
END-EXEC

EXEC SQL
    ROLLBACK WORK RELEASE
END-EXEC
Parent topic: Embedded SQL Statements
Related reference
COMMIT
CONNECT
DISCONNECT
SET CONNECTION


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 ANSI92ENTRY is set and a singleton SELECT retrieves more than 1 row, SQLCODE will be -811, SQLSTATE will be 21000 and SQLWARN4 will be W. If ANSI92ENTRY is not set, no error or warning conditions will be set.

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)


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.

This statement overrides the AUTOCOMMIT SQL compiler directive.

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 OPTION

Enables you to set OpenESQL options.

Syntax:

>>---EXEC SQL---SET OPTION----.-QUERYTIME---.--->
                              +-LOGINTIME---+
                              +-APPLICATION-+
                              +-HOST--------+

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

Comment:

The SET OPTION statement is not supported by all ODBC drivers.

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


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

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


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.
db_name | The name of a database that has been declared using DECLARE DATABASE.
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.
db_name | The name of a database that has been declared using DECLARE DATABASE.
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


Embedded ADO Statements

  • ACCEPT CHANGES
    Commits all pending changes made in the specified DataTables of the DataSet.
  • BIND
    Allows an ADO.NET DataSet or DataTable to be shared with OpenESQL.
  • BIND CONNECTION
    Enables the pair of ADO.NET connection and transaction objects to be shared with OpenESQL.
  • CLEAR
    Clears the data in the specified DataTables of a DataSet.
  • CLOSE
    Closes a previously declared and opened DataRows cursor.
  • DECLARE DATAROWS
    Declares an ADO.NET DataRows cursor (similar to an SQL cursor) based on criteria established against a particular DataTable.
  • DECLARE DATASET
    Defines a typed or an untyped DataSet.
  • DECLARE DATATABLE
    Defines an ADO.NET DataTable.
  • DELETE (POSITIONED)
    Deletes the row most recently fetched by a DataRows cursor.
  • DELETE (SEARCHED)
    Removes the DataRows that meet the row state and/or search criteria from the named DataTable.
  • FETCH
    Transfers all or a subset of a DataRows cursor into host variables or host arrays.
  • FILL
    Adds new DataRows to (or refreshes the existing DataRows of) the DataTables in a DataSet using data from the data source.
  • GET CHANGES
    Creates a new DataSet containing only DataRows that have been modified (deleted, added or changed).
  • GET CONNECTION
    Places the current OpenESQL connection and transaction objects into the supplied host variables such that the objects can then be shared with other ADO.NET programs.
  • GET CURSOR
    Places a DataReader or a DataSet ADO.NET object used by the OpenESQL EXEC SQL cursor into the supplied host variable such that the object can then be shared with other ADO.NET programs.
  • GET DATATABLE
    Copies a DataTable object into a host variable or creates a DataTable object within a host variable, enabling you to share the DataTable object with other .NET languages.
  • GET RUNTIME
    Places the current OpenESQL MFADORTS object into the supplied host variable.
  • INITIALIZE DATASET
    Creates an empty DataSet for a previously declared one and optionally stores a reference to that DataSet.
  • INITIALIZE DATATABLE
    Creates an empty DataTable for a previously declared one, and optionally stores a reference to that DataTable.
  • INSERT
    Adds new DataRows to a DataTable. It is similar to the EXEC SQL INSERT statement which adds new rows into a SQL table.
  • LOAD DATASET
    Loads a DataSet that has been stored as an XML file and provides addressability to the corresponding ADO.NET DataSet.
  • LOAD DATATABLE
    Loads a DataTable that has been stored as an XML file and provides addressability to the corresponding ADO.NET DataTable.
  • MERGE
    Merges new data into a target DataSet or DataTable.
  • OPEN
    Opens a previously declared DataRows cursor.
  • PREPARE TO FILL
    Begins the process of loading the DataTables in a DataSet from a data source.
  • PREPARE TO UPDATE
    Begins the process of updating a data source with changes made in the DataTables of a DataSet.
  • REBIND CONNECTION
    Informs OpenESQL that a shared connection transaction has been terminated and supplies a new transaction object for subsequent processing.
  • REJECT CHANGES
    Rolls back all pending changes made in the DataTables of a DataSet.
  • SAVE DATASET
    Saves the schema and data of a DataSet to an XML file.
  • SAVE DATATABLE
    Saves the data and optionally the schema of a DataTable to an XML file.
  • SELECT INTO
    Retrieves one or more DataRows from a DataTable into host variables or host arrays, enabling you to select information from a DataTable without declaring a DataRows cursor.
  • TO DELETE USE
    Specifies, for a specific DataTable, the SQL logic necessary to make deletes from a data source.
  • TO FILL USE
    Specifies, for a specific DataTable, the SQL logic necessary to load the columns of that DataTable with data from a data source.
  • TO INSERT USE
    Specifies, for a specific DataTable, the SQL logic necessary to make inserts into in a data source.
  • TO REFRESH USE
    Specifies, for a specific DataTable, the SQL logic necessary to refresh the rows of a DataTable, showing the changes made to the data source after the UPDATE DATASOURCE statement was executed.
  • TO UPDATE USE
    Specifies, for a specific DataTable, the SQL logic necessary to make updates to a data source.
  • UNBIND
    Disassociates OpenESQL from a DataSet or DataTable in another ADO.NET application.
  • UNBIND CONNECTION
    Disassociates OpenESQL from the original ADO.NET connection object.
  • UPDATE
    Updates a data source with changes made in the DataTables of a DataSet.
  • UPDATE (POSITIONED)
    Updates the DataRow most recently fetched by using a DataRows cursor.
  • UPDATE (SEARCHED)
    Updates a DataTable either by using a standard SQL WHERE clause or by replacement via a host variable array.
  • USING
    Specifies the current DataSet name to be used in subsequent processing.
Parent topic: OpenESQL


ACCEPT CHANGES

Commits all pending changes made in the specified DataTables of the DataSet.

Syntax:

>>--EXEC ADO-.--------------------.-ACCEPT CHANGES FOR--------->
             +-USING dataset_name-+

 >-------------.-ALL DATATABLES-.----END-EXEC------------------><
               | +------,-----+ |
               | V            | |
               +-datatable_name-+

Parameters:

dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
datatable_name | The DataTables where the changes are accepted.

Comments:

The row state of the added and modified DataRows is modified to unchanged and deleted DataRows are removed.

No changes are made to the underlying data source. Only the DataTables in the DataSet accept changes. Use UPDATE DATASOURCE to change the underlying data source.

DataTables can be changed directly with INSERT, DELETE (SEARCHED) and UPDATE and via a DataRows cursor with DELETE (POSITIONED) and UPDATE.

Example:

     EXEC ADO
        ACCEPT CHANGES FOR ALL DATATABLES
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
DELETE (POSITIONED)
DELETE (SEARCHED)
INSERT
REJECT CHANGES
UPDATE (POSITIONED)
UPDATE (SEARCHED)


BIND

Allows an ADO.NET DataSet or DataTable to be shared with OpenESQL.

Syntax:

>>--EXEC ADO---.--------------------------.-BIND TO :dataset_hv-------->
               +-USING dataset_name-------+
               +-DATATABLE datatable_name-+

 >--.-------------------.---END-EXEC----><
    +-WITH SCHEMA CHECK-+

Parameters:

dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
datatable_name | The name of the DataTable you want to share with OpenESQL.
dataset_hv | Host variable which identifies an ADO.NET DataSet object.
WITH SCHEMA CHECK | Runtime check that verifies that the current schema is the same as one declared at compile-time.

Comments:

Subsequent EXEC ADO statements in OpenESQL referencing dataset_name (or the current OpenESQL DataSet if dataset_name is not specified) use the current ADO.NET DataSet if it has been defined.

Examples:

     EXEC ADO
        USING changesDS BIND TO :changesDSobj
     END-EXEC

     EXEC ADO
        BIND DATATABLE TABLE1 TO :HV-CHGS
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
UNBIND
GET DATATABLE
GET CHANGES


BIND CONNECTION

Enables the pair of ADO.NET connection and transaction objects to be shared with OpenESQL.

Syntax:

>>--EXEC ADO--BIND CONNECTION--.-----------------.-TO :conn_obj_hv---->
                               +-connection_name-+
                               +- :conn_name_hv -+

 >------------------WITH +-TRANSACTION-+ :tran_obj_hv----------------->
                         +-TRAN       -+

 >--END-EXEC----><

Parameters:

connection_name | The connection name OpenESQL uses to refer to the ADO.NET connection object.
conn_name_hv | Host variable which contains the connection name OpenESQL uses to refer to the ADO.NET connection object.
conn_obj_hv | Host variable where the ADO.NET connection object is specified.
tran_obj_hv | Host variable where the ADO.NET transaction object is specified.

Comments:

The named OpenESQL connection can use the existing ADO.NET connection and transaction objects in further EXEC SQL and EXEC ADO processing.

Example:

     EXEC ADO
        BIND CONNECTION fred TO :con WITH TRANSACTION :tran
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
REBIND CONNECTION
UNBIND CONNECTION


CLEAR

Clears the data in the specified DataTables of a DataSet.

Syntax:

>>--EXEC ADO---.--------------------.—CLEAR------------>
               +-USING dataset_name-+

 >-------------+-ALL DATATABLES-+---------------------->
               | +- ,        -+ |
               | V            | |
               +-datatable_name-+

 >--END-EXEC----><

Parameters:

dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
datatable_name | A list of the DataTables to be cleared.

Example:

     EXEC ADO
        CLEAR ALL DATATABLES
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
DECLARE DATASET
DECLARE DATATABLE
INITIALIZE DATASET


CLOSE

Closes a previously declared and opened DataRows cursor.

Syntax:

>>--EXEC ADO---CLOSE datarows_name-----END-EXEC-----><

Parameters:

datarows_name The name of a DataRows cursor.

Example:

     EXEC ADO
        CLOSE drOrder
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
DECLARE DATAROWS
DELETE (POSITIONED)
FETCH
OPEN
UPDATE (POSITIONED)


DECLARE DATAROWS

Declares an ADO.NET DataRows cursor (similar to an SQL cursor) based on criteria established against a particular DataTable.

Syntax:

>>--EXEC ADO---.--------------------.--DECLARE datarows_name DATAROWS->
               +-USING dataset_name-+

 >--.------------------------------------.—-FROM datatable_name------->
    |              +--- , ---+           |
    |              V         |           |
    +--FOR SELECT--column_name-----------+

 >--.-----------------------------------.—---------------------------->
    +-FOR-.-ADDED-------------.-DATAROWS+
          +-CURRENT-----------+
          +-DELETED-----------+
          +-MODIFIED CURRENT--+
          +-MODIFIED ORIGINAL-+
          +-ORIGINAL----------+
          +-UNCHANGED---------+

 >-.----------------------------------------------------.--—END-EXEC--><
   |                                                    |
   +-WHERE search_conditions--.----------------------.--+
   |                          +-ORDER BY sort_clause-+  |
   |                                                    |
   +-WHERE CHILDREN OF cursor_name (relation_name)------+
   +-WHERE PARENTS  OF cursor_name (relation_name}------+
   +-ORDER BY sort_clause-------------------------------+

Parameters:

dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
datarows_name | The name of a DataRows cursor.
column_name | The names of the columns in the DataTable to specify in the DataRows cursor.
FOR row_state DATAROWS | Identifies the DataRows to use in a DataTable based on the row_state value.
datatable_name | The name of the DataTable on which the DataRows cursor is defined.
search_conditions | Any valid expression that can follow the standard SQL WHERE clause.
sort_clause | Any valid expression that can follow the standard SQL ORDER BY clause.
cursor_name | The name of a DataRows cursor to be associated with this DataRows cursor (as either a parent or a child.)
relation_name | The name of the constraint which specifies the parent-child relationship between this DataRows cursor and the cursor_name cursor referenced above. relation_name is defined in the DECLARE DATASET statement.

Comments:

The standard cursor manipulation statements (OPEN, FETCH, DELETE (POSITIONED), UPDATE (POSITIONED) and CLOSE) are also applicable to an ADO.NET DataRows cursor.

In addition to the standard WHERE clause, the DECLARE DATAROWS statement allows you to navigate parent-child relationships of related DataRows cursors with the WHERE CHILDREN and WHERE PARENTS clauses.

Example:

     EXEC ADO
        DECLARE drOrder DATAROWS
        FOR SELECT OrderID, OrderDate FROM Orders
        WHERE CHILDREN OF drCust(custord)
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
CLOSE
DELETE (POSITIONED)
FETCH
OPEN
UPDATE (POSITIONED)


DECLARE DATASET

Defines a typed or an untyped DataSet.

Syntax:

DECLARE <typed> DATASET
>>--EXEC ADO---DECLARE dataset_name DATASET----------------------->

 >--+-FROM dataset_xml_file_spec---------------------------------+
    +-LIKE src_dataset_name--------------------------------------+
    |                                                            |
    |       +---- , -----+                                       |
    |       V            |                                       |
    +-FOR---datatable_name---.--------------.----.-------------.-+
                             +-optrelations-+    +optschemasave+

 >--END-EXEC----><

where

optrelations:
 >-.------------------------------------------------------------------------.--><
   |                                                                        |
   | + ----------------- , ---------------------------------------------+   |
   | V                                                                  |   |
   +---.--------.-RELATION rel_name child_tbl (column_list)REFERENCES-> |   |
       +-NESTED-+                                                       |   |
              >--parent_tbl (column_list)-.------------------.----------+---+
                                          +optwithconstraints+

optschemasave:
 >----.--------------------------------------.--------------------><
      +-SAVE SCHEMA TO dataset_xml_file_spec-+

optwithconstraints:
>--.------------------------------------------------------------.-><
   +-WITH CONSTRAINTS-.-------------.-.----------.-.----------.-+
                      +-accrej_rule-+ +-del_rule-+ +-upd_rule-+

accrej_rule:
>---ON ACCEPT OR REJECT -.-CASCADE---.----------------------------><
                         +-NO ACTION-+

del_rule:
>---ON DELETE -.-CASCADE-----.------------------------------------><
               +-NO ACTION---+
               +-SET DEFAULT-+
               +-SET NULL----+

upd_rule:
>---ON UPDATE -.-CASCADE-----.------------------------------------><
               +-NO ACTION---+
               +-SET DEFAULT-+
               +-SET NULL----+

DECLARE <untyped> DATASET
>>--EXEC ADO---DECLARE dataset_name UNTYPED DATASET----END-EXEC---><

Parameters:

dataset_name | The DataSet to be declared.
dataset_xml_file_spec | The location of the DataSet XML file that specifies the characteristics for the declared DataSet.
src_dataset_name | The name of the DataSet that specifies the characteristics for the declared DataSet.
datatable_name | The declared DataTable to be included in this DataSet.
rel_name | The name of a relation.
child_tbl (column_list) | A specification of the table and columns which define the child key (foreign).
parent_tbl (column_list) | A specification of the table and columns which define the parent key.
SAVE SCHEMA TO | Saves the schema of the DataSet into an XSD file.

Comments:

When you declare a schema with a DataSet (typed), it is checked at compile time and optionally stored in an XSD file. If you do not declare a schema with the DataSet (untyped), then no compile time checking is done.

A DataSet consists of DataTables and the relationships between these tables.

All DataTables specified in a DECLARE DATASET statement must have a corresponding DECLARE DATATABLE. You can optionally specify parent key and child key relationships between these tables with the RELATION clause.

If WITH CONSTRAINTS is specified, then primary key and foreign key constraints will be created (if they do not already exist) in the parent and child DataTables, respectively. You can set rules to specify the effect of changes to a parent row on related child rows if WITH CONSTRAINTS is specified.

Example:

     EXEC ADO
        DECLARE ds DATASET
        FOR Customers, Orders, "Order Details"
        RELATION custord Orders(CustomerID) REFERENCES Customers(CustomerID),
        RELATION orditems "Order Details"(OrderID) REFERENCES Orders(OrderID)
     END-EXEC

     EXEC ADO
        DECLARE ds UNTYPED DATASET
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
CLEAR
DECLARE DATATABLE
INITIALIZE DATASET
GET CHANGES


DECLARE DATATABLE

Defines an ADO.NET DataTable.

Syntax:

>>--EXEC ADO---DECLARE datatable_name DATATABLE---------------------->

 >-------------( table_item_list )---------------------END-EXEC------><

where

table_item_list:

      +------------------   ,   ----------------------+
      V                                               |
 >-.--+-column_name data_type .----------------.------+--------------><
      |                       +-column_options-+      |
      |                                               |
      +-CONSTRAINT constraint_name constraint_def-----+

data_type:

 >-+-BOOLEAN---+---><
   +-SBYTE-----+
   +-INT16-----+
   +-INT32-----+
   +-INT64-----+
   +-DATETIME--+
   +-DECIMAL---+
   +-SINGLE----+
   +-DOUBLE----+
   +-STRING(N)-+
   +-OBJECT----+

column_options:

 >-.----------.---.-----------------.---.----------.---.--------.---->
   +-NULL-----+   +-DEFAULT literal-+   +-READONLY-+   +-UNIQUE-+
   +-NOT NULL-+   +-DEFAULT ident---+

 >-.---------------------------.--.---------------.------------------><
   +-AUTOINCREMENT FROM N BY N-+  +-CAPTION ident-+

constraint_def:

 >--+--PRIMARY KEY (column_list)--+--><
    +--UNIQUE (column_list)-------+

Parameters:

datatable_name | The DataTable to be declared.
column_name | The name of a column in the DataTable
data_type | The column data types available.
column_options | The column options available.
constraint_name | The name of a constraint for the DataTable.
constraint_def | The definition of the primary or unique key for the DataTable, as specified with columns.
column_list | A list of columns in the DataTable, separated by commas.

Comments:

A DECLARE DATATABLE statement is required for each DataTable specified in a DECLARE DATASET statement.

The DECLARE DATATABLE statement syntax is similar to the embedded EXEC SQL CREATE TABLE statement.

Example:

     EXEC ADO
        DECLARE Orders DATATABLE
        ( OrderID               INT32           AUTOINCREMENT FROM -1 BY -1
         ,CustomerID            STRING(5)
         ,EmployeeID            INT32
         ,OrderDate             DATETIME
         ,RequiredDate          DATETIME
         ,ShippedDate           DATETIME
         ,ShipVia               INT32
         ,Freight               DECIMAL
         ,ShipName              STRING(40)
         ,ShipAddress           STRING(60)
         ,ShipCity              STRING(15)
         ,ShipRegion            STRING(15)
         ,ShipPostalCode        STRING(10)
         ,ShipCountry           STRING(15)
         , CONSTRAINT pk_Orders primary key(OrderID))
     END-EXEC.
Parent topic: Embedded ADO Statements
Related reference
CLEAR
DECLARE DATASET
DELETE (SEARCHED)
INSERT
UPDATE (SEARCHED)


DELETE (POSITIONED)

Deletes the row most recently fetched by a DataRows cursor.

Syntax:

>>-EXEC ADO-.--------------------.-DELETE---FROM---datatable_name---->
            +-USING dataset_name-+

 >----WHERE CURRENT OF---datarows_name---END-EXEC---><

Parameters:

dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
datatable_name | The same DataTable used in the SELECT FROM option (see DECLARE CURSOR).
datarows_name | A previously declared, opened, and fetched DataRows cursor.

Comments:

EXEC ADO supports positioned delete; however, you cannot use host arrays with positioned delete.

The other type of DELETE used in standard EXEC ADO statements is known as a searched delete.

Example:

* Declare the cursor
     EXEC ADO
        DECLARE c1 DATAROWS FROM oline
     END-EXEC

* Open the cursor
     EXEC ADO
        OPEN c1
     END-EXEC

* Modify the table using positioned updates and deletes
     PERFORM UNTIL EXIT
        * Delete row 1, 4, 7, ...
        EXEC ADO FETCH c1 INTO :oline END-EXEC
        IF SQLCODE NOT = 0
           EXIT PERFORM
        END-IF
        EXEC ADO DELETE FROM oline WHERE CURRENT OF c1 END-EXEC

        * Update row 2, 5, 8, ...
        EXEC ADO FETCH c1 INTO :oline END-EXEC
        IF SQLCODE NOT = 0
           EXIT PERFORM
        END-IF
        MOVE 99 TO qty
        EXEC ADO UPDATE oline SET qty = :qty WHERE CURRENT OF c1 END-EXEC

        * Leave alone row 3, 6, 9, ...
        EXEC ADO FETCH c1 INTO :oline END-EXEC
        IF SQLCODE NOT = 0
           EXIT PERFORM
        END-IF
     END-PERFORM
Parent topic: Embedded ADO Statements
Related reference
ACCEPT CHANGES
CLOSE
DECLARE DATAROWS
FETCH
OPEN
UPDATE (POSITIONED)
REJECT CHANGES


DELETE (SEARCHED)

Removes the DataRows that meet the row state and/or search criteria from the named DataTable.

Syntax:

>>--EXEC ADO--.-------------------.---DELETE---FROM------->
              +-USING dataset_name+

>--datatable_name--.------------------------------------.—>
                   +-FOR-.-ADDED-------------.-DATAROWS-+
                         +-CURRENT-----------+
                         +-DELETED-----------+
                         +-MODIFIED CURRENT--+
                         +-MODIFIED ORIGINAL-+
                         +-ORIGINAL----------+
                         +-UNCHANGED---------+

>----.-------------------------.----------------END-EXEC--><
     +-WHERE search_conditions-+

Parameters:

dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
datatable_name | The target DataTable for the delete operation.
search_conditions | Any valid expression that can follow the standard SQL WHERE clause.

Comment:

If no criteria are specified, then all of the DataRows in the named DataTable are removed.

Example:

     EXEC ADO
        DELETE FROM Customers
        WHERE CustomerID = 'ZZZZ1'
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
ACCEPT CHANGES
DECLARE DATATABLE
REJECT CHANGES


FETCH

Transfers all or a subset of a DataRows cursor into host variables or host arrays.

Syntax:

>>--EXEC ADO--.-------------------.----------------->
              +-FOR :host_integer-+

 >-FETCH-------.----------.---.----------.—VALUES--->
               +---SAME---+   +-CURRENT--+
               +---LAST---+   +-DEFAULT--+
               +---PRIOR--+   +-ORIGINAL-+
               +---FIRST--+   +-PROPOSED-+
               +---NEXT---+

 >--.------.—-datarows_name--.---------------.------>
    +-FROM-+                 +-(column_list)-+

 >--.--------------------------------.---END-EXEC---><
    |      +--- , -----+             |
    |      V           |             |
    +-INTO :col_value_hv-------------+

Properties:

: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.
datarows_name | A previously declared and opened DataRows cursor
column_list | A list of one or more columns for which data is to be retrieved. The column list determines the order in which values are received. Items in the column list must be enclosed in parentheses. If no column list is given, all of the columns in the receiving table (in DECLARE DATATABLE order) are assumed. The column list is only necessary when some but not all of the columns in the DataRows cursors are to retrieve data.
:col_value_hv | Identifies one or more host variables to receive the data from the columns.

Comments:

This statement is similar to the embedded EXEC SQL FETCH statement.

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 ADO
        DECLARE drCust DATAROWS FROM Customers
     END-EXEC

     EXEC ADO OPEN drCust 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 EXIT
        EXEC ADO
           FETCH NEXT drCust (CustomerID, CompanyName)
           INTO :Customers-CustomerID, :Customers-CompanyName
        END-EXEC
        IF SQLCODE < 0 or SQLCODE = 100
           EXIT PERFORM
        END-IF
        DISPLAY "Customer ID  = " Customers-CustomerID " Company Name = " Customers-CompanyName
     END-PERFORM
Parent topic: Embedded ADO Statements
Related reference
CLOSE
DECLARE DATAROWS
DELETE (POSITIONED)
OPEN
UPDATE (POSITIONED)


FILL

Adds new DataRows to (or refreshes the existing DataRows of) the DataTables in a DataSet using data from the data source.

Syntax:

>>--EXEC ADO--FILL--DATASET--.--------------.-->
                             +-dataset_name-+
>--END-EXEC--><

Parameters:

dataset_name The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.

Comments:

This statement can only be executed after a PREPARE TO FILL and subsequent TO FILL statements. The TO FILL statements specify the SQL logic necessary to fill different DataTables from a data source.

If no TO FILL statements are used, OpenESQL attempts to supply default SQL. For a table with no parent tables the default SQL will select all rows in the table. For a table with a parent table, the default SQL selects the rows for which the parent rows have been selected. Tables are filled in the correct order to satisfy relationships between tables, for example, parent before children. The generation of default SQL searchs all relationships between tables, allowing a FILL statement for a parent table to be used to generate queries for children, grandchildren, great grandchildren and so on.

Example:

     EXEC ADO
        FILL DATASET
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
PREPARE TO FILL
TO FILL USE
INITIALIZE DATASET


GET CHANGES

Creates a new DataSet containing only DataRows that have been modified (deleted, added or changed).

Syntax:

>>-EXEC ADO-.--------------------.-GET CHANGES INTO— :dataset_hv---->
            +-USING dataset_name-+

 >--END-EXEC----><

Parameters:

dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
dataset_hv | Host variable where the DataSet object is placed. This DataSet only contains changed data from the source DataSet.

Comment:

Because the resultant DataSet only contains change information, it can be used (rather than the entire DataSet) to minimize network traffic when updating a data source.

Example:

     EXEC ADO
        GET CHANGES INTO :changesDSobj
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
BIND
DECLARE DATASET


GET CONNECTION

Places the current OpenESQL connection and transaction objects into the supplied host variables such that the objects can then be shared with other ADO.NET programs.

Syntax:

>>--EXEC ADO---GET CONNECTION INTO :conn_obj_hv---------->

 >--------------+-TRANSACTION-+ INTO :tran_obj_hv-------->
                +-TRAN--------+

 >--END-EXEC----><

Parameters:

conn_obj_hv | Host variable where the current OpenESQL ADO.NET connection object is placed.
tran_obj_hv | Host variable where the current OpenESQL ADO.NET transaction object is placed.

Example:

     EXEC ADO
        GET CONNECTION INTO :con TRANSACTION INTO :tran
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
GET CURSOR
GET RUNTIME


GET CURSOR

Places a DataReader or a DataSet ADO.NET object used by the OpenESQL EXEC SQL cursor into the supplied host variable such that the object can then be shared with other ADO.NET programs.

Syntax:

>>--EXEC ADO---GET CURSOR cursor_name INTO :cursor_obj_hv-------->

 >---.------------------------------------------.---------------->
     +--RENAME DATATABLE AS new_datatable_name--+

 >--END-EXEC----><

Parameters:

cursor_name | Name of an EXEC SQL cursor.
cursor_obj_hv | Host variable where the OpenESQL ADO.NET object will be placed.
new_datatable_name | The new name of the underlying DataTable in the cursor.

Purpose:

If the ADO.NET object is a DataSet, then the DataTable containing the data for the cursor can optionally be renamed. The default name, if no renaming is undertaken, is "Table".

Example:

     EXEC ADO
        GET CURSOR CSR5 INTO :ws-dataset
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
GET CONNECTION
GET RUNTIME


GET DATATABLE

Copies a DataTable object into a host variable or creates a DataTable object within a host variable, enabling you to share the DataTable object with other .NET languages.

Syntax:

>>-EXEC ADO---GET DATATABLE datatable_name-+-INTO :datatable_hv---------+---END-EXEC---------><
                                           +-CHANGES INTO :datatable_hv-+

Parameters:

datatable_name | The ADO.NET DataTable object to be shared
INTO | Copy a DataTable object into a COBOL host variable
CHANGES INTO | Create a new DataTable object that contains only the DataRows that have been modified (deleted, added or changed).
datatable_hv | Host variable where the DataTable object is placed.

Comment:

When you create a DataTable object, the new object contains only changed information rather than the entire DataTable. This can minimize network traffic when updating a data source.

Example:

     EXEC ADO
        GET DATATABLE TABLE1 CHANGES INTO :HV-CHGS
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
BIND
UNBIND


GET RUNTIME

Places the current OpenESQL MFADORTS object into the supplied host variable.

Syntax:

>>--EXEC ADO---GET RUNTIME INTO :runtime_hv----END-EXEC---><

Parameters:

runtime_hv Host variable where the current OpenESQL MFADORTS object is placed.

Comment:

Investigating the OpenESQL MFADORTS object can provide valuable insight in debugging scenarios.

Example:

     EXEC ADO
        GET RUNTIME INTO :runtime
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
GET CONNECTION
GET CURSOR


INITIALIZE DATASET

Creates an empty DataSet for a previously declared one and optionally stores a reference to that DataSet.

Syntax:

>>--EXEC ADO--.-------------------.—INITIALIZE DATASET------>
              +-USING dataset_name+

 >---.-------------------------.-----------EXEC-END---------><
     +-RETURNING :dataset_hv---+

Parameters:

dataset_name | The DataSet to be created.
dataset_hv | Host variable where the DataSet object is placed.

Example:

     EXEC ADO
        INITIALIZE DATASET
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
CLEAR
DECLARE DATASET
FILL


INITIALIZE DATATABLE

Creates an empty DataTable for a previously declared one, and optionally stores a reference to that DataTable.

Syntax:

>>--EXEC ADO--INITIALIZE DATATABLE datatable_name----->

 >---.-------------------------.-----------END-EXEC---><
     +-RETURNING :datatable_hv-+

Parameters:

datatable_name | The DataTable to be created.
datatable_hv | Host variable where the DataTable object is placed.

Example:

     EXEC ADO
        INITIALIZE TABLE TABLE1
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
SAVE DATATABLE
LOAD DATATABLE


INSERT

Adds new DataRows to a DataTable. It is similar to the EXEC SQL INSERT statement which adds new rows into a SQL table.

Syntax:

>>--EXEC ADO--.--------------------.--.-----------------.---->
              +-USING dataset_name-+  +-FOR :host_integer-+

 >--INSERT INTO datatable_name--.---------------.------------>
                                |               |
                                |  +--- , ---+  |
                                |  V         |  |
                                +-(column_name)-+

            +---------- , ---------+
            V                      |
 >--VALUES (.----------------------.)---END-EXEC-------------><
            +-- :column_value_hv --+
            +-- column_value     --+

Parameters:

dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
: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.
datatable_name | The DataTable that will receive the new DataRows.
column_name | A column in the DataTable.
:column_value_hv | The corresponding column value for column_name.
column_value | The corresponding literal column value for column_name.

Comment:

After execution, SQLERRD(3) contains the number of elements processed. For INSERT it is the total number of rows inserted.

Example:

     EXEC ADO
        INSERT INTO Customers
        (CustomerID, CompanyName, ContactName)
        VALUES ('ZZZZ2', 'Java Jugglers', 'Mike Smith')
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
ACCEPT CHANGES
DECLARE DATATABLE
REJECT CHANGES


LOAD DATASET

Loads a DataSet that has been stored as an XML file and provides addressability to the corresponding ADO.NET DataSet.

Syntax:

>>--EXEC ADO---.--------------------.---LOAD DATASET FROM ----------->
               +-USING dataset_name-+

 >--xml_file_spec--.-------------------.--.----------------------.--->
                   +-WITH SCHEMA CHECK-+  +-RETURNING :ds_obj_hv-+

 >--END-EXEC----><

Parameters:

dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
xml_file_spec | Location of the XML file that contains the DataSet’s schema and data.
WITH SCHEMA CHECK | Verifies that the DECLARE DATASET used at compile time matches the one stored in the XML file.
ds_obj_hv | Host variable where the DataSet object is placed.

Example:

     EXEC ADO
        LOAD DATASET FROM "c:\work\adotests\net_order_status.xml"
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
SAVE DATASET


LOAD DATATABLE

Loads a DataTable that has been stored as an XML file and provides addressability to the corresponding ADO.NET DataTable.

Syntax:

>>--EXEC ADO---LOAD DATATABLE datatable_name FROM ------------------->

 >--xml_file_spec--.-------------------.--.----------------------.--->
                   +-WITH SCHEMA CHECK-+  +-RETURNING :dt_obj_hv-+

 >--END-EXEC----><

Parameters:

datatable_name | The DataTable reference to be used.
xml_file_spec | Location of the XML file that contains the DataTable’s schema and data.
WITH SCHEMA CHECK | Verifies that the DECLARE DATATABLE used at compile time matches the one stored in the XML file.
dt_obj_hv | Host variable where the DataTable object is placed.

Example:

     EXEC ADO
        LOAD DATATABLE  TABLE1 FROM "C:\DATA\EMPLOYEE.XML"
        WITH SCHEMA CHECK RETURNING :DATATBL-OBJ
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
INITIALIZE DATATABLE
SAVE DATATABLE


MERGE

Merges new data into a target DataSet or DataTable.

Syntax, Format 1:

>>--EXEC ADO--.-------------------.-MERGE DATASET FROM ------->
              +-USING dataset_name+

 >---:src_dataset_hv --.--------------------.----------------->
                       +--PRESERVE CHANGES--+

 >---.--------------------------------------.-END-EXEC--------><
     |                                      |
     +-ON SCHEMA DIFFERENCE--+-ADD         -+
                             +-ADD WITH KEY-+
                             +-ERROR       -+
                             +-IGNORE      -+

Syntax, Format 2:

>>--EXEC ADO--.-------------------.-MERGE DATASET ------------>
              +-USING dataset_name+

 >---src_dataset_name -----.--------------------.------------->
                           +--PRESERVE CHANGES--+

 >---.--------------------------------------.-END-EXEC--------><
     |                                      |
     +-ON SCHEMA DIFFERENCE--+-ADD         -+
                             +-ADD WITH KEY-+
                             +-ERROR       -+
                             +-IGNORE      -+

Syntax, Format 3:

>>--EXEC ADO--.-------------------.-MERGE DATATABLE----------->
              +-USING dataset_name+

 >---dest_datatable FROM DATASET src_dataset_name------------->

 >-------------.------------------------------------.--------->
               +-FOR-.-ADDED-------------.-DATAROWS-+
                     +-CURRENT-----------+
                     +-DELETED-----------+
                     +-MODIFIED CURRENT--+
                     +-MODIFIED ORIGINAL-+
                     +-ORIGINAL----------+
                     +-UNCHANGED---------+

 >--.-------------------------.---.--------------------.------>
    +-WHERE search conditions-+   +--PRESERVE CHANGES--+

 >---.--------------------------------------.-END-EXEC--------><
     |                                      |
     +-ON SCHEMA DIFFERENCE--+-ADD         -+
                             +-ADD WITH KEY-+
                             +-ERROR       -+
                             +-IGNORE      -+

Syntax, Format 4:

>>--EXEC ADO---MERGE DATATABLE-------------------------------->

 >---dest_datatable FROM DATATABLE src_datatable_name--------->

 >---.------------------------------------.------------------->
     +-FOR-.-ADDED-------------.-DATAROWS-+
           +-CURRENT-----------+
           +-DELETED-----------+
           +-MODIFIED CURRENT--+
           +-MODIFIED ORIGINAL-+
           +-ORIGINAL----------+
           +-UNCHANGED---------+

 >---.-------------------------.---.--------------------.---->
     +-WHERE search conditions-+   +--PRESERVE CHANGES--+

 >---.--------------------------------------.-END-EXEC---><
     |                                      |
     +-ON SCHEMA DIFFERENCE--+-ADD         -+
                             +-ADD WITH KEY-+
                             +-ERROR       -+
                             +-IGNORE      -+

Parameters:

dataset_name | The target DataSet to be used. If you do not specify dataset_name, the current DataSet is used.
src_dataset_hv | The host variable that contains the source DataSet for the merge.
src_dataset_name | The source DataSet name that specifies which DataRows of a DataTable to use as the source for the merge.
dest_datatable | The destination into which DataTable data is to be merged.
src_datatable | The source that the DataTable data is to be copied from.
search_conditions | Any valid expression that can follow the standard SQL WHERE clause.
PRESERVE CHANGES | Prevents incoming values from the source overwriting the current values in the target (only Original).
ON SCHEMA DIFFERENCE | Specifies what happens if the DataSet or DataTable schemas of the source and target are different.

Comments:

The source of the new data is either a complete DataSet, a DataTable from another DataSet, or a set of DataRows from a DataTable in another DataSet.

In accordance with the .NET API standards, there is an option to preserve changes in the target DataSet or DataTable.

You can also specify what actions are taken if a schema difference is encountered.

Examples:

     EXEC ADO
        MERGE DATASET FROM :changesDSobj
     END-EXEC

     EXEC ADO
        MERGE DATATABLE TABLE2 FROM DATATABLE TABLE1 FOR ADDED ROWS
     END-EXEC
Parent topic: Embedded ADO Statements


OPEN

Opens a previously declared DataRows cursor.

Syntax:

>>--EXEC ADO---OPEN datarows_name-----END-EXEC----><

Parameters:

datarows_name The name of a DataRows cursor.

Comment:

OPEN is similar to the standard EXEC SQL OPEN statement.

Example:

* Declare the cursor...
     EXEC ADO
        DECLARE drCust DATAROWS FROM Customers
     END-EXEC

* Open the cursor...
     EXEC ADO
        OPEN drCust
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
CLOSE
DECLARE DATAROWS
DELETE (POSITIONED)
FETCH
UPDATE (POSITIONED)


PREPARE TO FILL

Begins the process of loading the DataTables in a DataSet from a data source.

Syntax:

                                                    +--   ,    --+
                                                    V            |
>>--EXEC ADO-.--------------------.-PREPARE TO FILL-datatable_name-->
             +-USING dataset_name-+
 >--END-EXEC---><

Parameters:

datatable_name | The DataTables that are prepared to be filled by the data source.
dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.

Comments:

After using PREPARE TO FILL to specify the DataTables that are to be loaded by the data source, use the TO FILL statement to specify how to retrieve the data from the data source. The FILL statement completes the process.

Example:

     EXEC ADO
        PREPARE TO FILL Customers, Orders, "Order Details"
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
FILL
TO FILL USE


PREPARE TO UPDATE

Begins the process of updating a data source with changes made in the DataTables of a DataSet.

Syntax:

                                                      +--    ,   --+
                                                      V            |
>>--EXEC ADO-.--------------------.-PREPARE TO UPDATE-datatable_name-->
             +-USING dataset_name-+
 >--END-EXEC---><

Parameters:

datatable_name | The DataTables whose changes are prepared to be placed in the data source.
dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.

Comments:

After specifying the DataTables whose changes will be loaded to the data source, TO INSERT, TO DELETE and TO UPDATE statements are used to specify for each DataTable how those changes are placed back in the data source. The UPDATE statement completes the process.

If no TO INSERT, TO DELETE or TO UPDATE statements are specified, OpenESQL will generate these statements based on the SQL construct used in the TO FILL statement.

Example:

     EXEC ADO
        PREPARE TO UPDATE Customers, Orders, "Order Details"
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
TO DELETE USE
TO INSERT USE
TO REFRESH USE
TO UPDATE USE
UPDATE


REBIND CONNECTION

Informs OpenESQL that a shared connection transaction has been terminated and supplies a new transaction object for subsequent processing.

Syntax:

>>--EXEC ADO---REBIND CONNECTION--.-----------------.----->
                                  +-connection_name-+
                                  +-:conn_name_hv---+

 >--WITH +-TRANSACTION-+  :tran_obj_hv---END-EXEC---------><
         +-TRAN       -+

Parameters:

connection_name | The connection name OpenESQL uses to refer to the ADO.NET connection object.
conn_name_hv | Host variable that contains the connection name OpenESQL uses for the ADO.NET connection object.
tran_obj_hv | Host variable that contains the new ADO.NET transaction object that OpenESQL is to use.

Comment:

If the transaction object is NULL, then the connection enters AUTOCOMMIT mode.

Example:

     EXEC ADO
        REBIND CONNECTION WITH TRANSACTION :tran
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
BIND CONNECTION
UNBIND CONNECTION


REJECT CHANGES

Rolls back all pending changes made in the DataTables of a DataSet.

Syntax:

>>--EXEC ADO---.--------------------.—REJECT CHANGES FOR-------->
               +-USING dataset_name-+

 >-------------.----------------.------------------------------->
               +-ALL DATATABLES-+
               | +---- ,  ----+ |
               | V            | |
               +-datatable_name-+

 >--END-EXEC----><

Parameters:

dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
datatable_name | The DataTables where the changes are rejected.

Comments:

The row state and contents of the deleted and modified DataRows are returned to their original state and any added DataRows are removed.

Note:

No changes are made to the underlying data source. Only the DataTables in the DataSet reject changes.

Example:

     EXEC ADO
        REJECT CHANGES FOR ALL DATATABLES
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
ACCEPT CHANGES
DELETE (POSITIONED)
DELETE (SEARCHED)
INSERT
REJECT CHANGES
UPDATE (POSITIONED)
UPDATE (SEARCHED)


SAVE DATASET

Saves the schema and data of a DataSet to an XML file.

Syntax:

>>--EXEC ADO--.-------------------.—SAVE--DATASET------>
              +-USING dataset_name+

 >---TO----xml_file_spec--------------------EXEC-END---><

Parameters:

dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
xml_file_spec | A file to contain the XML file that represents the DataSet.

Example:

     EXEC ADO
        SAVE DATASET TO "c:\work\adotests\net_order_status.xml"
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
LOAD DATASET


SAVE DATATABLE

Saves the data and optionally the schema of a DataTable to an XML file.

Syntax:

>>--EXEC ADO--SAVE DATATABLE datatable_name--.-------------.--->
                                             +-WITH SCHEMA-+

 >---TO----xml_file_spec---END-EXEC---><

Parameters:

datatable_name | The DataTable reference to be used.
xml_file_spec | A file to contain the XML file that represents the DataTable and schema.

Example:

     EXEC ADO
        SAVE DATATABLE TABLE1 WITH SCHEMA TO "C:\DATA\NEWEMPLOYEE.XML"
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
INITIALIZE DATATABLE
LOAD DATATABLE


SELECT INTO

Retrieves one or more DataRows from a DataTable into host variables or host arrays, enabling you to select information from a DataTable without declaring a DataRows cursor.

Syntax:

>>---EXEC ADO--.--------------------.—--SELECT---------------->
               +-USING dataset_name-+

                          +--  ,  --+         +---- , ----+
                          V         |         V           |
 >--.-----------------.---column_name---INTO--:col_value_hv--->
    +-CURRENT VALUES--+
    +-DEFAULT VALUES--+
    +-ORIGINAL VALUES-+
    +-PROPOSED VALUES-+

>--FROM datatable_name---------------------------------------->

>--.----------------------------------------------------.--—-->
   |                                                    |
   +-WHERE search_conditions--.----------------------.--+
   |                          +-ORDER BY sort_clause-+  |
   |                                                    |
   +-WHERE CHILDREN OF cursor_name (relation_name)------+
   +-WHERE PARENTS  OF cursor_name (relation_name}------+
   +-ORDER BY sort_clause-------------------------------+

>--END-EXEC---><

Parameters:

dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
VALUES group | Determines which type of DataRows to use in the selection criteria.
column_name | The columns in the DataTable whose data values are retrieved.
col_value_hv | Host variable where the columns data values are stored.
datatable_name | The DataTable used in the selection criteria.
search_conditions | Any valid expression that can follow the standard SQL WHERE clause.
sort_clause | Any valid expression that can follow the standard SQL ORDER BY clause.
cursor_name | The name of the DataRows cursor to be associated with this DataRows cursor (as either a parent or a child.)
relation_name | The name of the constraint which specifies the parent-child relationship between this DataRows cursor and the cursor_name cursor referenced above. relation_name is defined in the DECLARE DATASET statement.

Comment:

This statement is similar to the embedded EXEC SQL SELECT INTO statement.

Example:

     MOVE 99 TO staff-id
     EXEC ADO
        SELECT last_name
        INTO :lname
        FROM staff
        WHERE staff_id=:staff-id
     END-EXEC

     EXEC ADO
        SELECT staff_id
        INTO :staff-id
        FROM staff
        WHERE first_name = 'Phil'
     END-EXEC
Parent topic: Embedded ADO Statements


TO DELETE USE

Specifies, for a specific DataTable, the SQL logic necessary to make deletes from a data source.

Syntax:

>>--EXEC ADO-.--------------------.-TO DELETE-.------.-datatable_name-->
             +-USING dataset_name-+           +-FROM-+

 >--------------USE--+-sql_searched_delete_statement-+----------------->
                     +-stored_procedure_statement----+

 >--END-EXEC---><

Parameters:

datatable_name | The name of a DataTable.
dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
sql_searched_delete_statement | A standard SQL DELETE (SEARCHED) statement that references a table in a data source.
stored_procedure_statement | Specifies which stored procedure to execute.

Comments:

The SQL logic must reference actual tables and columns in the data source.

The SQL logic can refer to column values for the row that has been deleted in the DataTable by using the column name enclosed in braces, optionally followed by the type of value (CURRENT, ORIGINAL, DEFAULT, or PROPOSED), separated by a period. For example, {OrderId} or {OrderID.Original}.

Example:

     EXEC ADO PREPARE TO UPDATE Orders, Customers, "Order Details" END-EXEC
        EXEC ADO TO DELETE FROM Customers USE
           DELETE FROM Customers WHERE CustomerID = {CustomerID}
        END-EXEC
     EXEC ADO UPDATE DATASOURCE END-EXEC
Parent topic: Embedded ADO Statements
Related reference
PREPARE TO UPDATE
TO INSERT USE
TO REFRESH USE
TO UPDATE USE
UPDATE


TO FILL USE

Specifies, for a specific DataTable, the SQL logic necessary to load the columns of that DataTable with data from a data source.

Syntax:

>>--EXEC ADO--.--------------------.--TO FILL  datatable_name-->
              +-USING dataset_name-+

 >---.-------------------------------------------------.------->
     |                                                 |
     |           +---------------  ,  --------------+  |
     |           V                                  |  |
     +- MAPPING--datatable_col_name AS table_col_name--+

 >--------------USE--+-sql_select_statement----------+--------->
                     +-stored_procedure_statement----+

 >--END-EXEC---><

Parameters:

datatable_name | The name of a DataTable.
dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
datatable_col_name | The name of a column in a DataTable.
table_col_name | The name of a column in a table in a data source.
sql_select_statement | A standard SQL SELECT statement that references a table in a data source.
stored_procedure_statement | Specifies the stored procedure to execute.

Comment:

The SQL logic must reference actual tables and columns in the data source.

Example:

     EXEC ADO
        TO FILL Customers USE
        SELECT CustomerID,CompanyName,ContactName,ContactTitle,Address
        ,City,Region,PostalCode,Country,Phone,Fax
        FROM Customers WHERE CustomerID LIKE :pattern
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
FILL
PREPARE TO FILL


TO INSERT USE

Specifies, for a specific DataTable, the SQL logic necessary to make inserts into in a data source.

Syntax:

>>--EXEC ADO--.--------------------.--TO INSERT INTO datatable_name-->
              +-USING dataset_name-+

 >--.----------------------------------------------------------.----->
    |                                                          |
    +--WITH REFRESH USING--+-RETURNED DATAROW                 -+
                           +-RETURNED DATAROW , OUT PARAMETERS-+
                           +-OUT PARAMETERS                   -+

 >--USE--+-sql_insert_statement--.-----------------------.----------->
         |                       +-sql_refresh_statement-+
         |                                               |
         +-stored_procedure_statement--------------------+

 >--END-EXEC---><

Parameters:

datatable_name | The name of a DataTable.
dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
WITH REFRESH USING | Specifies how to retrieve new values in the data source as a result of the execution of the TO INSERT statement.
sql_insert_statement | A standard SQL INSERT statement that references a table in data source.
sql_refresh_statement | The SQL SELECT statement that cites the columns in the DataTable that need to be refreshed.
stored_procedure_statement | Specifies the stored procedure to execute to perform the SQL INSERT statement.

Comments:

The SQL logic must reference actual tables and columns in the data source.

The SQL logic can refer to column values for the row that has been deleted in the DataTable by using the column name enclosed in braces, optionally followed by the type of value (CURRENT, ORIGINAL, DEFAULT, or PROPOSED), separated by a period. For example, {OrderId} or {OrderID.Original}.

Use the WITH REFRESH USING clause to specify how to update the DataSet with new values when the data source is updated. With RETURNED DATAROWS, you must supply sql_refresh_statement, which is an SQL SELECT for the columns which are to have new values. With OUT PARAMETERS, the stored procedure that performs the SQL INSERT will supply the update columns as output parameters.

Example:

     EXEC ADO
        TO INSERT INTO Orders
        WITH REFRESH USING RETURNED DATAROW USE
        INSERT INTO Orders (CustomerID, OrderDate)
        VALUES ({CustomerID}, {OrderDate});
        SELECT @@IDENTITY as OrderID
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
PREPARE TO UPDATE
TO DELETE USE
TO REFRESH USE
TO UPDATE USE
UPDATE


TO REFRESH USE

Specifies, for a specific DataTable, the SQL logic necessary to refresh the rows of a DataTable, showing the changes made to the data source after the UPDATE DATASOURCE statement was executed.

Syntax:

>>--EXEC ADO--.--------------------.TO REFRESH datatable_name-->
              +-USING dataset_name-+

>------+-AFTER UPDATE          -+------------------------------>
       +-AFTER INSERT          -+
       +-AFTER INSERT OR UPDATE-+

>---.-------------------------------------------------.-------->
     |                                                 |
     |           +---------------  ,  --------------+  |
     |           V                                  |  |
     +- MAPPING--datatable_col_name AS table_col_name--+

 >--------------USE--sql_refresh_statement--------------------->

 >--END-EXEC---><

Parameters:

datatable_name | The DataTable to be refreshed.
dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
AFTER | The action to the data source, when the UPDATE DATASOURCE statement is executed, that causes a refresh.
datatable_col_name | The name of a column in a DataTable.
table_col_name | The name of a column in an SQL table.
sql_refresh_statement | The SQL SELECT statement that retrieves the columns that need to be refreshed.

Comments:

The SQL logic must reference actual tables and columns in the data source that needs to be refreshed.

The SQL logic can refer to column values for the row that has been deleted in the DataTable by using the column name enclosed in braces, optionally followed by the type of value (CURRENT, ORIGINAL, DEFAULT, or PROPOSED), separated by a period. For example, {OrderId} or {OrderID.Original}.

Example:

     EXEC ADO
        TO REFRESH Orders USE
        SELECT @@IDENTITY as OrderID
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
PREPARE TO UPDATE
TO DELETE USE
TO INSERT USE
TO UPDATE USE
UPDATE


TO UPDATE USE

Specifies, for a specific DataTable, the SQL logic necessary to make updates to a data source.

Syntax:

>>--EXEC ADO--.---------------------.-TO UPDATE datatable_name-->
               +-USING dataset_name-+

>--.----------------------------------------------------------.->
   |                                                          |
   +--WITH REFRESH USING--+-RETURNED DATAROW                 -+
                          +-RETURNED DATAROW , OUT PARAMETERS-+
                          +-OUT PARAMETERS                   -+

>--USE--+-sql_update_statement--.-----------------------.------->
        |                       +-sql_refresh_statement-+
        |                                               |
        +-stored_procedure_statement--------------------+

 >--END-EXEC---><

Parameters:

datatable_name | The name of a DataTable.
dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
WITH REFRESH USING | Specifies how to retrieve new values in the data source as a result of the execution of the TO UPDATE statement.
sql_update_statement | A standard SQL UPDATE (SEARCHED) statement that references an actual table and its columns in a data source.
sql_refresh_statement | The SQL SELECT statement that cites columns in the DataTable that need to be refreshed.
stored_procedure_statement | Specifies the stored procedure to execute to perform the SQL UPDATE (SEARCHED) statement

Comments:

The SQL logic must reference actual tables and columns in the data source.

The SQL logic can refer to column values for the row that has been deleted in the DataTable by using the column name enclosed in braces, optionally followed by the type of value (CURRENT, ORIGINAL, DEFAULT, or PROPOSED), separated by a period. For example, {OrderId} or {OrderID.Original}.

Use the WITH REFRESH USING clause to specify how to update the DataSet with new values when the data source is updated. With RETURNED DATAROWS, you must supply sql_refresh_statement, which is an SQL SELECT for the columns which are to have new values. With OUT PARAMETERS, the stored procedure that performs the SQL INSERT will supply the update columns as output parameters.

Example:

     EXEC ADO PREPARE TO UPDATE Orders, Customers, "Order Details" END-EXEC
        EXEC ADO TO UPDATE Customers USE
              UPDATE Customers SET
                 ContactName = {ContactName},
                 City = {City}
              WHERE CustomerID = {CustomerID}
        END-EXEC
     EXEC ADO UPDATE DATASOURCE END-EXEC
Parent topic: Embedded ADO Statements
Related reference
PREPARE TO UPDATE
TO DELETE USE
TO INSERT USE
TO REFRESH USE
UPDATE


UNBIND

Disassociates OpenESQL from a DataSet or DataTable in another ADO.NET application.

Syntax, Format 1:

>>--EXEC ADO--.--------------------.--UNBIND---END-EXEC---><
              +-USING dataset_name-+

Syntax, Format 2:

>>--EXEC ADO --UNBIND DATATABLE datatable_name---END-EXEC---><

Parameters:

dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
datatable_name | The name of the DataTable you want to share with OpenESQL.

Examples:

     EXEC ADO
        USING ds UNBIND
     END-EXEC

     EXEC ADO
        UNBIND DATATABLE TABLE1
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
BIND
GET DATATABLE


UNBIND CONNECTION

Disassociates OpenESQL from the original ADO.NET connection object.

Syntax:

>>--EXEC ADO--UNBIND CONNECTION--.-----------------.---->
                                 +-connection_name-+
                                 +-:conn_name_hv---+

 >----END-EXEC----><

Parameters:

connection_name | The connection name OpenESQL uses to refer to the ADO.NET connection object.
conn_name_hv | Host variable which contains the connection name OpenESQL uses to refer to the ADO.NET connection object.

Example:

     EXEC ADO
        UNBIND CONNECTION fred
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
BIND CONNECTION
REBIND CONNECTION


UPDATE

Updates a data source with changes made in the DataTables of a DataSet.

Syntax:

>>--EXEC ADO----—UPDATE DATASOURCE-----END-EXEC--><

Comment:

This statement can only be executed after a PREPARE TO UPDATE statement and subsequent TO INSERT, TO UPDATE and TO DELETE statements. The TO commands specify the SQL logic necessary to change tables in the actual data source. If no TO commands are created, OpenESQL attempts to supply default SQL. For a table with no parent tables the default SQL is to select all rows in the table. For a table with a parent table the default SQL is to select rows for which the parent rows have been selected.

Example:

     EXEC ADO
        UPDATE DATASOURCE
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
PREPARE TO UPDATE
TO DELETE USE
TO INSERT USE
TO REFRESH USE
TO UPDATE USE


UPDATE (POSITIONED)

Updates the DataRow most recently fetched by using a DataRows cursor.

Syntax:

>>-EXEC ADO-.--------------------.--UPDATE-datatable_name---->
            +-USING dataset_name-+

         +-----------  ,  -----------+
         V                           |
>--SET---column_name = -+- :hvar-----+----------------------->
                       -+- col_value-+

>--WHERE CURRENT OF--datarows_name---END-EXEC----------------><

Parameters:

dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
datatable_name | The name of the DataTable to be updated.
column_name | The column to be updated.
hvar | Host variable that contains the column value.
col_value | The column value.
datarows_name | A previously declared, opened, and fetched DataRows cursor.

Comments:

EXEC ADO supports positioned update; however, not all ADO.NET data providers support positioned update.

With some ADO.NET data providers, the SELECT statement used by the cursor must contain a FOR UPDATE clause to enable positioned update.

The other form of UPDATE used in EXEC ADO 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.

Example:

* Declare the cursor
     EXEC ADO
        DECLARE c1 DATAROWS FROM oline
     END-EXEC

* Open the cursor
     EXEC ADO
        OPEN c1
     END-EXEC

* Modify the table using positioned updates and deletes
     PERFORM UNTIL EXIT
        * Delete row 1, 4, 7, ...
        EXEC ADO FETCH c1 INTO :oline END-EXEC
        IF SQLCODE NOT = 0
           EXIT PERFORM
        END-IF
        EXEC ADO DELETE FROM oline WHERE CURRENT OF c1 END-EXEC

        * Update row 2, 5, 8, ...
        EXEC ADO FETCH c1 INTO :oline END-EXEC
        IF SQLCODE NOT = 0
           EXIT PERFORM
        END-IF
        MOVE 99 TO qty
        EXEC ADO UPDATE oline SET qty = :qty WHERE CURRENT OF c1 END-EXEC

        * Leave alone row 3, 6, 9, ...
        EXEC ADO FETCH c1 INTO :oline END-EXEC
        IF SQLCODE NOT = 0
           EXIT PERFORM
        END-IF
     END-PERFORM
Parent topic: Embedded ADO Statements
Related reference
ACCEPT CHANGES
CLOSE
DECLARE DATAROWS
DELETE (POSITIONED)
FETCH
OPEN
REJECT CHANGES


UPDATE (SEARCHED)

Updates a DataTable either by using a standard SQL WHERE clause or by replacement via a host variable array.

Syntax, Format 1:

>>--EXEC ADO--.-------------------.---UPDATE—datatable_name--------->
              +-USING dataset_name+

         +-----------  ,  -----------+
         V                           |
>--SET---column_name = -+- :hvar-----+------------------------------>
                       -+- col_value-+

>-.------------------------------------.—.-------------------------.>
  +-FOR-.-ADDED-------------.-DATAROWS-+ +-WHERE search_conditions-+
        +-CURRENT-----------+
        +-DELETED-----------+
        +-MODIFIED CURRENT--+
        +-MODIFIED ORIGINAL-+
        +-ORIGINAL----------+
        +-UNCHANGED---------+

>--END-EXEC-><

Syntax, Format 2:

>>--EXEC ADO--.-------------------.---FOR :host_integer UPDATE—------->
              +-USING dataset_name+

                          +-----------  ,  -----------+
                          V                           |
>-- datatable_name  SET---column_name = -+- :hvar-----+----END-EXEC-><

Parameters:

dataset_name | The DataSet reference to be used. If you do not specify dataset_name, the current DataSet is used.
datatable_name | The name of the DataTable to be updated.
column_name | The name of a column in a DataTable.
:hvar | Host variable that contains the column value.
col_value | The column value.
FOR DATAROWS | The row state of the DataRows to be updated.
search_condition | Any valid expression that can follow the standard SQL WHERE clause.
: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.

Comments:

This statement is similar to the embedded EXEC SQL UPDATE (SEARCHED) statement.

After execution, SQLERRD(3) contains the number of elements processed. For UPDATE it is the total number of rows updated.

Example:

     EXEC ADO
        UPDATE Customers
        SET
        ContactName = 'Alan Jones',
        ContactTitle = 'Managing Director',
        City = 'Norwich'
        WHERE CustomerID = 'ZZZZ2'
     END-EXEC
Parent topic: Embedded ADO Statements
Related reference
ACCEPT CHANGES
REJECT CHANGES
DECLARE DATATABLE


USING

Specifies the current DataSet name to be used in subsequent processing.

Syntax:

>>--EXEC ADO---USING dataset_name----END-EXEC----><

Parameters:

dataset_name The name of the DataSet that becomes the current DataSet for subsequent EXEC ADO processing.

Comment:

References to DataTables in EXEC ADO statements that have no USING clause use the current DataSet name.

Example:

     EXEC ADO
        USING ds
     END-EXEC
Parent topic: Embedded ADO Statements


SQL Compiler Directive Options

  • ADOPICXISANSI
    Instructs OpenESQL to pass string and character variables as ANSI.
  • ALLOWNULLCHAR
    Allows programs to use PIC X(n) host variables, and to select/insert/update hexadecimal characters in CHAR columns without changing source to use SQL TYPE BINARY host variables.
  • ANSI92ENTRY
    If this is set, OpenESQL conforms to the SQL ANSI'92 entry level standard.
  • AUTOCOMMIT
    If this is set, each SQL statement is treated as a separate transaction and is committed immediately upon execution. If this is not set, and the ODBC driver you are using supports transactions, statements must be explicitly committed (or rolled back) as part of a 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.
  • BEHAVIOR
    Instructs OpenESQL to properly match your COBOL cursors with the database you specify with the TARGETDB directive, thus maximizing database cursor performance. BEHAVIOR makes use of multiple primitive directives and associates a default value for each primitive directive depending on the DBMS you are using. You can also override the default setting of any primitive directive.
  • CHECK
    Sends each SQL statement to the database at compilation time.
  • CHECKDUPCURSOR
    Instructs OpenESQL to determine if the cursor has been opened twice, and if so takes action accordingly.
  • CHECKSINGLETON
    Instructs OpenESQL to check if singleton SELECTs return more than one row when executed. If this is the case, OpenESQL returns SQLCODE -811.
  • 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.
  • DB
    The name of the data source to connect to. This option works in conjunction with the INIT and/or CHECK options. The .int file generated is the same except for the TARGETDB number embedded in the file.
  • DBMAN
    Specifies the preprocessor to use. This directive is not required when compiling programs with OpenESQL.
  • DECDEL
    Eliminates the need for OpenESQL to call the routine GetLocaleInfo for any variable that would store decimal data. This routine is called every time the variable is accessed to return the decimal delimiter used. In most cases, this is a period or comma. The options for this directive are:
  • DETECTDATE
    Enables recognition of date, time and datetime values in character host variables.
  • 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-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.
  • HSFTRACE
    Generates calls around each SQL statement to the HSF trace routine. In some cases, the application must be linked with mfsqlSMF.lib.
  • IGNORE-NESTED
    In nested programs, this is the program-id at which to start generating the database interface code. If the program file name matches the program-id, you can just specify IGNORE-NESTED.
  • INIT
    If this is set, the preprocessor automatically generates code to make the connection to the database. If you specify INIT, you must also specify DB and PASS. We highly recommend that you use EXEC SQL CONNECT statements in your application instead.
  • 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.
  • MARS
    Enable multiple active results sets when connecting to an MS SQL Server 2005 or later. To use this directive, you must also specify TARGETDB=MSSQLSERVER.
  • 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 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. 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.
  • 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.
  • PRE
    PRE causes the preprocessor to generate code to load the OpenESQL runtime module (odbcrw32.dll) dynamically at runtime. This conflicts with the LITLINK compiler directive. So if you use LITLINK, specify NOPRE to stop the dynamic loading code being generated. In this case, you must add odbcrw32.lib to the list of LIBs to be linked in your build settings. Then the linker generates code into the executable which causes the operating system to load odbcrw32.dll implicitly when the executable is loaded.
  • 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.
  • 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
    If THREAD is set to ISOLATE, all connections, cursors and so on are local to the thread that creates them. This is required for multi-threaded application server environments such as IIS/ISAPI. With THREAD=SHARE, 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. With THREAD=ISOLATE, each thread gets its own connection.
  • TRACELEVEL
    Produces a statistical analysis of application behavior by tracing certain operations. The report produced by this directive provides better readability and is inherently more useful than a traditional ODBC trace.
  • 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.
Parent topic: OpenESQL
Related concepts
DBMAN Directive Settings


ADOPICXISANSI

Instructs OpenESQL to pass string and character variables as ANSI.
Note: By default, the OpenESQL Managed .NET Runtime maps PIC X host variables to ANSI strings when data is sent to the server. The default behavior in earlier versions of the runtime mapped the variable to Unicode strings, occasionally causing performance problems on some servers. The current default corrects these problems in most cases; however, in rare cases where this change causes decreased performance, specify NOADOPICXISANSI to restore the original behavior.

Syntax:

ADOPICXISANSI
NOADOPICXISANSI

Properties:

Default: ADOPICXISANSI

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comment:

ADOPICXISANSI applies to managed ADO.NET runtime and safe runtime only.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


ALLOWNULLCHAR

Allows programs to use PIC X(n) host variables, and to select/insert/update hexadecimal characters in CHAR columns without changing source to use SQL TYPE BINARY host variables.

Syntax:

ALLOWNULLCHAR
NOALLOWNULLCHAR

Properties:

Default: NOALLOWNULLCHAR

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comment:

ALLOWNULLCHAR applies to native runtime only.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related information
Fixed-length Binary Strings


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.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DBMAN Directive Settings


AUTOCOMMIT

If this is set, each SQL statement is treated as a separate transaction and is committed immediately upon execution. If this is not set, and the ODBC driver you are using supports transactions, statements must be explicitly committed (or rolled back) as part of a transaction.

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.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DBMAN Directive Settings
SET AUTOCOMMIT


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:
  • BEHAVIOR=MAINFRAME 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 specify with the TARGETDB directive, thus maximizing database cursor performance. BEHAVIOR makes use of multiple primitive directives and associates a default value for each primitive directive depending on the DBMS you are using. You can also override the default setting of any primitive directive.
Note:
  • To use the BEHAVIOR directive, you must first define the TARGETDB in your SQL definition.
  • Setting this directive can also affect the SQL types returned when using Dynamic SQL. See the DESCRIBE Statement topic for more information.

Syntax:

BEHAVIOR={ANSI | MAINFRAME | UNOPTIMIZED } [primitivedirective [value]]...

Parameters:

ANSI | Enables OpenESQL to work like the ANSI standard, and enhances the access speed
MAINFRAME | Enables OpenESQL to work as it does on the mainframe, and enhances the access speed
UNOPTIMIZED | Provides backward compatibility with earlier Micro Focus products
primitivedirective | Optional directives that enable the fine-tuning of BEHAVIOR

Scope:

Used at compile time: | No
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Default:

BEHAVIOR=MAINFRAME

Default Primitive Directives:

The following tables show default primitive directive values for the following combinations:

SQL(TARGETDB=dbtarget BEHAVIOR=MAINFRAME)
SQL(TARGETDB=dbtarget BEHAVIOR=ANSI)
SQL(TARGETDB=dbtarget BEHAVIOR=CICS)
SQL(TARGETDB=dbtarget
SQL(TARGETDB=MSSQLSERVER BEHAVIOR=MAINFRAME)
SQL(TARGETDB=MSSQLSERVER BEHAVIOR=ANSI)
SQL(TARGETDB=MSSQLSERVER BEHAVIOR=CICS)
SQL(TARGETDB=MSSQLSERVER)

Where dbtarget is any database target except MS SQL Server. To use these defaults, you do not specify any primitive directives.

Table 1. Defaults for SQL(TARGETDB=dbtarget BEHAVIOR=MAINFRAME)
AUTOFETCH | The AUTOFETCH flag is ON
DEF_CURSOR=RO | Ambiguous COBOL cursors are assumed to be read only
ISOLATION=CR | The isolation level is committed read
PF_RO_CURSOR=8 | Read only COBOL cursors prefetch eight records at a time
PF_UPD_CURSOR=8 | Updateable COBOL cursors prefetch eight records at a time
RO_CURSOR=FORWARD | Read only COBOL cursors are FORWARD only
TRANSACTION=LOCAL | Manages transactions using the data source
UPD_CONCURRENCY=LOCK | Updateable COBOL cursors have locked concurrency
UPD_CURSOR=KEYSET | Updateable COBOL cursors are KEYSET database cursors
Table 2. Defaults for SQL(TARGETDB=dbtarget BEHAVIOR=ANSI)
AUTOFETCH | The AUTOFETCH flag is OFF (NOAUTOFETCH)
DEF_CURSOR=UPD | Ambiguous COBOL cursors are assumed to be updateable
ISOLATION=CR | The isolation level is committed read
PF_RO_CURSOR=8 | Read only COBOL cursors prefetch eight records at a time
PF_UPD_CURSOR=8 | Updateable COBOL cursors prefetch eight records at a time
RO_CURSOR=FORWARD | Read only COBOL cursors are forward only
TRANSACTION=LOCAL | Manages transactions using the data source
UPD_CONCURRENCY=LOCK | Updateable COBOL cursors have locked concurrency
UPD_CURSOR=KEYSET | Updateable COBOL cursors are keyset database cursors
Table 3. Defaults for SQL(TARGETDB=dbtarget)- no BEHAVIOR directive specified
NOAUTOFETCH | The AUTOFETCH flag is OFF
DEF_CURSOR=UPD | Ambiguous COBOL cursors are assumed to be updateable
ISOLATION=CR | The isolation level is committed read
PF_RO_CURSOR=1 | Read only COBOL cursors prefetch one record at a time
PF_UPD_CURSOR=1 | Updateable COBOL cursors prefetch one record at a time
RO_CURSOR=FORWARD | Read only COBOL cursors are forward only
TRANSACTION=LOCAL | Manages transactions using the data source
UPD_CONCURRENCY=LOCK | Updateable COBOL cursors have locked concurrency
UPD_CURSOR=KEYSET | Updateable COBOL cursors are keyset database cursors
Table 4. Defaults for SQL(TARGETDB=MSSQLSERVER BEHAVIOR=MAINFRAME)
AUTOFETCH | The AUTOFETCH flag is ON
DEF_CURSOR=RO | Ambiguous COBOL cursors are assumed to be read only
IC_FH_ISOLATION=UR | The isolation level for independent connect firehose cursors; use only when RO_CURSOR=IC_FH is set
ISOLATION=CR | The isolation level is committed read
PF_RO_CURSOR=1 | Read only COBOL cursors prefetch one record at a time
PF_UPD_CURSOR=8 | Updateable COBOL cursors prefetch eight records at a time
TRANSACTION=LOCAL | Manages transactions using the data source
RO_CURSOR=IC_FH | Read only COBOL cursors are independent-connection fire-hose database cursors
UPD_CONCURRENCY=LOCK | Updateable COBOL cursors have locked concurrency
UPD_CURSOR=DYNAMIC | Updateable COBOL cursors are dynamic database cursors
Table 5. Defaults for SQL(TARGETDB=MSSQLSERVER BEHAVIOR=ANSI)
AUTOFETCH | The AUTOFETCH flag is ON
DEF_CURSOR=UPD | Ambiguous COBOL cursors are assumed to be updateable
IC_FH_ISOLATION=UR | The isolation level for independent connect firehose cursors; use only when RO_CURSOR=IC_FH is set
ISOLATION=CR | The isolation level is committed read
PF_RO_CURSOR=1 | Read only COBOL cursors prefetch one record at a time
PF_UPD_CURSOR=8 | Updateable COBOL cursors prefetch eight records at a time
RO_CURSOR=IC_FH | Read only COBOL cursors are independent-connection fire-hose database cursors
TRANSACTION=LOCAL | Manages transactions using the data source
UPD_CONCURRENCY=LOCK | Updateable COBOL cursors have locked concurrency
UPD_CURSOR=DYNAMIC | Updateable COBOL cursors are dynamic database cursors
Table 6. Defaults for SQL(TARGETDB=MSSQLSERVER BEHAVIOR=CICS)
AUTOFETCH | The AUTOFETCH flag is ON
DEF_CURSOR=RO | Ambiguous COBOL cursors are assumed to be read only
IC_FH_ISOLATION=UR | The isolation level for independent connect firehose cursors; use only when RO_CURSOR=IC_FH is set
ISOLATION=CR | The isolation level is committed read
PF_RO_CURSOR=1 | Read only COBOL cursors prefetch one record at a time
PF_UPD_CURSOR=8 | Updateable COBOL cursors prefetch eight records at a time
TRANSACTION=GLOBAL | Manages transactions using a distributed transaction manager such as CICS, Tuxedo, or COM+
RO_CURSOR=IC_FH | Read only COBOL cursors are independent-connection fire-hose database cursors
UPD_CONCURRENCY=LOCK | Updateable COBOL cursors have locked concurrency
UPD_CURSOR=DYNAMIC | Updateable COBOL cursors are dynamic database cursors
Table 7. Defaults for SQL(TARGETDB=MSSQLSERVER) - no BEHAVIOR directive specified
NOAUTOFETCH | The AUTOFETCH flag is OFF
DEF_CURSOR=UPD | Ambiguous COBOL cursors are assumed to be updateable
ISOLATION=CR | The isolation level is committed read
PF_RO_CURSOR=1 | Read only COBOL cursors prefetch one record at a time
PF_UPD_CURSOR=1 | Updateable COBOL cursors prefetch one record at a time
RO_CURSOR=DYNAMIC | Read only COBOL cursors are dynamic database cursors
TRANSACTION=LOCAL | Manages transactions using the data source
UPD_CONCURRENCY=LOCK | Updateable COBOL cursors have locked concurrency
UPD_CURSOR=DYNAMIC | Updateable COBOL cursors are dynamic database cursors

For more information on using BEHAVIOR to migrate your COBOL cursors, see the topic Easing COBOL Program Migration.

You can fine tune the BEHAVIOR directive and override these default settings by providing alternate values for primitive directives.

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
COBOL Program Migration Support
Scope - OpenESQL SQL Compiler Directive Options
Related tasks
To generate a SQL CLR stored procedure
Related reference
DBMAN Directive Settings
esqlconfig command
SET CONCURRENCY
SET SCROLLOPTION
Related information
To set a default for SQL(BEHAVIOR)
OpenESQL Configuration Utility
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


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=MAINFRAME 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.
  • TRANSACTION
    This directive provides OpenESQL with specifications for managing run-time transactions and, in some cases, enabling compile-time checking.
  • UPD_CONCURRENCY
    This directive enables you to choose the level of concurrency for updateable COBOL cursors.
  • UPD_CURSOR
    This directive determines what type of database cursor updateable COBOL cursors use.
Parent topic: BEHAVIOR
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


DEF_CURSOR

This cursor directive specifies the default cursor type for ambiguous COBOL cursors, either read only or updateable. Use this directive when the DECLARE CURSOR statement has neither the FOR READONLY nor the FOR UPDATE OF clause.

Syntax:

DEF_CURSOR={RO | UPD}

Parameters:

RO | Read Only
UPD | Updateable

Scope:

Used at compile time: | No
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comment:

While the default when BEHAVIOR=ANSI is DEF_CURSOR=UPD, if the original developer assumed RO, then use of UPD could adversely affect performance.

Parent topic: Primitive Directives
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


IC_FH_ISOLATION

This directive sets the transaction isolation for independent firehose cursor connections, enabling simultaneous access to firehose cursors.

Syntax:

 IC_FH_ISOLATION={UR | CR | RR | SZ}

Parameters:

UR | Uncommitted Read
CR | Committed Read
RR | Repeatable Read
SZ | Serializable isolation in ODBC and ADO.NET

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}

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.

Comment:

Does not work with FORWARD or IC_FH selection in RO_CURSOR.

Parent topic: Primitive Directives
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


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.

Comment:

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


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}

Parameters:

GLOBAL | Manages transactions using a distributed transaction manager such as CICS, Tuxedo, or COM+.
LOCAL | Manages transactions using the data source (default).
MIXED | Manages transactions using a distributed transaction manager, but does not perform compile-time checking. Use this option when you need to mix GLOBAL and LOCAL transaction behavior with different data sources.

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: Primitive Directives
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


UPD_CONCURRENCY

This directive enables you to choose the level of concurrency for updateable COBOL cursors.

Syntax:

UPD_CONCURRENCY={LOCK | OPTIMISTIC | OPTCC | OPTCCVAL}

Scope:

Used at compile time: | No
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comment:

LOCK, OPTIMISTIC, OPTCC, and OPTCCVAL are standard ODBC types.

Parent topic: Primitive Directives
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DBMAN Directive Settings


UPD_CURSOR

This directive determines what type of database cursor updateable COBOL cursors use.

Syntax:

UPD_CURSOR={SCROLL | FORWARD | DYNAMIC | KEYSET | STATIC}

Scope:

Used at compile time: | No
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

  • SCROLL, FORWARD, DYNAMIC, KEYSET, and STATIC are standard ODBC types.
  • Prefetching does not work with FORWARD.
Parent topic: Primitive Directives
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


CHECK

Sends each SQL statement to the database at compilation time.

Syntax:

[NO]CHECK

Properties:

Default: NOCHECK

Dependencies:

CHECK requires that you also set the DB and PASS compiler directive options.

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.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


CHECKDUPCURSOR

Instructs OpenESQL to determine if the cursor has been opened twice, and if so takes action accordingly.

Syntax:

CHECKDUPCURSOR
NOCHECKDUPCURSOR

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 NOANSI92ENTRY has not been specified, OpenESQL automatically closes the cursor and then re-opens it.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DBMAN Directive Settings


CHECKSINGLETON

Instructs OpenESQL to check if singleton SELECTs return more than one row when executed. If this is the case, OpenESQL returns SQLCODE -811.

Syntax:

CHECKSINGLETON
NOCHECKSINGLETON

Properties:

Default: NOCHECKSINGLETON

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

Iif CHECKSINGLETON is not specified, or NOCHECKSINGLETON is specified, and more than one row is returned, then OpenESQL returns SQLCODE -1.

CHECKSINGLETON is provided for DB2 compatibility.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DBMAN Directive Settings


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.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


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


DB

The name of the data source to connect to. This option works in conjunction with the INIT and/or CHECK options. The .int file generated is the same except for the TARGETDB number embedded in the file.

Syntax:

DB=databaseName
NODB

Properties:

Default: NODB

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
INIT
CHECK


DBMAN

Specifies the preprocessor to use. This directive is not required when compiling programs with OpenESQL.

Syntax:

DBMAN={ODBC | ADO}

Parameters:

ODBC | For native code
ADO | For .NET managed code

Properties:

Default: DBMAN=ODBC

Scope:

Used at compile time: | Yes
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

Applications compiled with SQL(DBMAN=ODBC) for .NET must be compiled with the ILTARGET directive specifying the appropriate platform. You cannot specify ILTARGET(AnyCPU) in this case.

Parent topic: SQL Compiler Directive Options
Related concepts
ODBC
ADO.NET
Scope - OpenESQL SQL Compiler Directive Options
Related tasks
To generate a SQL CLR stored procedure
Related reference
DBMAN Directive Settings


DECDEL

Eliminates the need for OpenESQL to call the routine GetLocaleInfo for any variable that would store decimal data. This routine is called every time the variable is accessed to return the decimal delimiter used. In most cases, this is a period or comma. The options for this directive are:
DECDEL=PERIOD | Always use a period as a decimal delimiter
DECDEL=COMMA | Always use a comma as a decimal delimiter
DECDEL=LOCAL | Call GetLocaleInfo one time to get the decimal delimiter

Syntax:

DECDEL={PERIOD | COMMA | LOCAL}
NODECDEL

Properties:

Default: NODECDEL, which causes OpenESQL to call GetLocaleInfo every time a decimal variable is referenced.

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


DETECTDATE

Enables recognition of date, time and datetime values in character host variables.

Syntax:

[NO]DETECTDATE

Properties:

Default: NODETECTDATE

Scope:

Used at compile time: | Yes
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options and Scope - HCOSS SQL Compiler Directive Options for more information.

Comments:

The following comments apply to DETECTDATE as a generic SQL compiler directive:
  • Use DETECTDATE if your server does not have a suitable native character string date representation (for example, Microsoft Access). It is also useful for generic applications.
  • DETECTDATE identifies the following escape sequences:
    • {dData} - date
    • {tData} - time
    • {tsData} - timestamp
  • Once identified, DETECTDATE binds the host variables as date, time, and timestamp columns as appropriate instead of binding them as character columns.
  • The use of DETECTDATE can cause problems if your database contains character columns not related to date or time data that can legitimately contain data that starts with {d, {t or {ts.
Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


ESQLVERSION

Sets OpenESQL syntax level.

Syntax:

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.

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


HSFTRACE

Generates calls around each SQL statement to the HSF trace routine. In some cases, the application must be linked with mfsqlSMF.lib.

Syntax:

HSFTRACE
NOHSFTRACE

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
Parent topic: DB2 Compiler Directive Options
Parent topic: COBSQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


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


INIT

If this is set, the preprocessor automatically generates code to make the connection to the database. If you specify INIT, you must also specify DB and PASS. We highly recommend that you use EXEC SQL CONNECT statements in your application instead.

Syntax:

INIT[=PROT]
NOINIT

Parameters:

PROT In the event that the application terminates abnormally, correctly closes down the database connection and rolls back all changes since the last COMMIT, avoiding potential database corruption.

Properties:

Default: NOINIT

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
Compiling Multiple Program Modules
Database Connections
Scope - OpenESQL SQL Compiler Directive Options


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 and ADO.NET

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


MARS

Enable multiple active results sets when connecting to an MS SQL Server 2005 or later. To use this directive, you must also specify TARGETDB=MSSQLSERVER.

Syntax:

MARS

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


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

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


ODBCTRACE

ODBCTRACE=USER enables you to control ODBC tracing via the ODBC control panel 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.

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

Syntax:

[NO]ODBCV3

Properties:

Default: ODBCV3

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


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
INIT
CHECK


PRE

PRE causes the preprocessor to generate code to load the OpenESQL runtime module (odbcrw32.dll) dynamically at runtime. This conflicts with the LITLINK compiler directive. So if you use LITLINK, specify NOPRE to stop the dynamic loading code being generated. In this case, you must add odbcrw32.lib to the list of LIBs to be linked in your build settings. Then the linker generates code into the executable which causes the operating system to load odbcrw32.dll implicitly when the executable is loaded.

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.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


PREFETCH

An application can use this directive to request that OpenESQL use block fetches for cursors. This can provide performance benefits, similar to array fetching, without having to change program logic. The performance benefit depends on the value of n and on whether the ODBC driver in use is already configured to use prefetching.

If n is less than 1000, it controls the number of rows to be fetched per batch and the same number of rows is fetched for all cursors. If n is greater than or equal to 1000, it sets the size of the prefetch buffer for each cursor. All cursors will have the same buffer size but the number of rows prefetched will depend on the overall size of the row returned by the query for each cursor.

When PREFETCH=n is used with Microsoft SQL Server, AUTOFETCH is also used for read only cursors. Cursors which are not read only are forced to be keyset cursors and can be used for positioned updates. PREFETCH=n is only supported with DB2, Oracle and MS 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.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


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


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
NOSTMTCACHE

Parameter:

n Any number; however we recommend that you set this to a number between 20 and 300

Properties:

Default: NOSTMTCACHE

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

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DBMAN Directive Settings


TESTSQLSTATE

Instructs OpenESQL to generate code that tests SQLSTATE rather than SQLCODE after an SQL statement is executed.

Syntax:

TESTSQLSTATE
NOTESTSQLSTATE

Properties:

Default: NOTESTSQLSTATE

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Example:

           invoke wCLRRTS "adoastop" using
               by reference SQLCA
           move SQLCA(13:4) to MFSQLECM-SQLCODE-2(1:4)
           move SQLCA(101:1) to MFSQLECM-SQLWARN
           move SQLCA(132:2) to MFSQLECM-SQLSTATE-2
           perform MFSQLECM-UPD-SQLCA-2
           if MFSQLECM-SQLSTATE-2 not = "00" and MFSQLECM-SQLSTATE-2 not
      -        = "01" and MFSQLECM-SQLSTATE-2 not = "02"
               go to SQL-ERROR
           end-if
           if MFSQLECM-SQLCODE-2 > 0 and MFSQLECM-SQLCODE-2 not = 100
               move "W" to MFSQLECM-SQLWARN
           else
               if MFSQLECM-SQLCODE-2 not = 0
                   move " " to MFSQLECM-SQLWARN
               end-if
           end-if
           if MFSQLECM-SQLSTATE-2 = "01"
               go to SQL-ERROR
           end-if
Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


THREAD

If THREAD is set to ISOLATE, all connections, cursors and so on are local to the thread that creates them. This is required for multi-threaded application server environments such as IIS/ISAPI. With THREAD=SHARE, 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. With THREAD=ISOLATE, each thread gets its own connection.

Syntax:

THREAD={SHARE | ISOLATE}

Properties:

Default: THREAD=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


TRACELEVEL

Produces a statistical analysis of application behavior by tracing certain operations. 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.

When you compile with SQL(DBMAN=ADO TRACELEVEL), the statistical analysis is stored in a file named ADOTrace.processID.sessionID.log, where SessionID is in the context of our Multiple Run Unit support. This logfile 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.

For information on session IDs, see the topic Multiple User COBOL Applications in .NET.

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
Multiple User COBOL Applications in .NET
Scope - OpenESQL SQL Compiler Directive Options
Related information
Multiple User COBOL Applications in .NET


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


DBMAN Directive Settings

This table shows all of the SQL compiler directive options and the DBMAN preprocessor options with which they are valid.

Other Directives |  | DBMAN=ODBC | DBMAN=ADO
ADOPICXISANSI |  |  | 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 | X (SQL Server only)
 | RO_CURSOR | X |
 | TRANSACTION | X |
 | UPD_CONCURRENCY | X | X
 | UPD_CURSOR | X |
CHECK |  | X | X
CHECKDUPCURSOR |  | X | X
CHECKSINGLETON |  | X | X
CONCAT |  | X |
CONNECTIONPOOL |  | X |
CTRACE |  | X | X
CURSORCASE |  | X |
DB |  | X | X
DECDEL |  | X |
DETECTDATE |  | X |
ESQLVERSION |  | X |
FIPSFLAG |  | X |
GEN-INIT-FLAG |  | X | X
HSFTRACE |  | X |
IGNORE-NESTED |  | X | X
INIT |  | X | X
ISOLATION |  | X |
JIT |  | X | X
MARS |  | X | X
NIST |  | X | X
NOT |  | X | X
ODBCTRACE |  | X |
ODBCV3 |  | X | X
PARAMARRAY |  | X |
PASS |  | X | X
PRE |  | X |
PREFETCH |  | X |
RESULTARRAY |  | X |
STMTCACHE |  | X | X
TARGETDB |  | X | X
TESTSQLSTATE |  | X |
THREAD |  | X |
TRACELEVEL |  | X |
USECURLIB |  | X |
Parent topic: OpenESQL
Related concepts
OpenESQL Configuration Utility
Related reference
SQL Compiler Directive Options
ANSI92ENTRY
AUTOCOMMIT
BEHAVIOR
CHECKDUPCURSOR
CHECKSINGLETON
DBMAN
ESQLVERSION
NIST
PF_UPD_CURSOR
TARGETDB
UPD_CONCURRENCY


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) | PIC X(n) |
SQL_NCHAR(n) | PIC X(n) or PIC N(n) |
SQL_VARCHAR(n) | PIC X(n) |
SQL_NVARCHAR(n) | PIC X(n) or PIC N(n) |
SQL_LONGVARCHAR | PIC X(max) or SQL TYPE LONG-VARCHAR(max) | max = 65000
SQL_NTEXT | PIC X(max) or PIC N(max) | max = 65000
SQL_DECIMAL(p,s) or SQL_NUMERIC(p,s) | PIC 9(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) | max = 65000
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
Parent topic: OpenESQL
Related concepts
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


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.
100 | Data matching the query was not found or the end of the results set has been reached. No rows were processed.
< 0 (negative) | The statement did not run due to an application, database, system, or network error.

OpenESQL

If you are using OpenESQL, the following error codes are defined for SQLCODE

SQLCODE | Message | Meaning
0 | Mismatch between number of parameter markers and host variables/user sqldas | Only used for special Embedded SQL statements, such as CONNECT.
1 | NULL value returned but no indicator variable supplied |
-1 | Autoconnect failure | SQL(INIT) was used, and automatic CONNECT failed. Programs which use SQL(INIT) need to check SQLCODE immediately on startup.
-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. |
-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 will result.
Parent topic: OpenESQL Messages
Related concepts
The SQLCODE Variable


OpenESQL Preprocessor Error Messages

  • ES0002 token is badly defined.
    One of the following occurred:
  • ES0003 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.
  • ES0004 Nested or multi-source programs not allowed.
    You are trying to compile a program that is nested or multi-source. This is not supported.
  • ES0005 An error occurred whilst processing the internal dictionary.
    A system error has occurred trying to read the internal dictionary that the preprocessor creates of all host variables used in the program.
  • ES0006 No DB engine could be found.
    The required OpenESQL system software was not installed.
  • ES0007 Source file name is invalid.
    A system error has occurred. The source file name passed to the preprocessor is not valid.
  • ES0010 OESQL rejected an unspecified option.
    OESQL precompiler services returned a -4905 sql error on initialization.
  • ES0101 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 may have comments included in the source as well as leading and trailing blanks.
  • ES0102 Statement contains too many host variables.
    The SQL statement contains more than 8000 host and indicator variables.
  • ES0103 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.
  • ES0104 Bad SQL data declaration.
    An unexpected SQL declaration is passed to the preprocessor. Generally this error occurs only when the host variable is defined as:
  • ES0105 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:
  • ES0106 Filename too long.
    A filename used in the program to specify a copybook or INCLUDE file is more than 260 characters long.
  • ES0107 File token not found.
    The copybook specified in token was not found.
  • ES0108 token is non-unique and should be qualified.
    The host variable displayed in token is not unique.
  • ES0109 token is not a data item.
    The host variable displayed in token was not defined or defined incorrectly.
  • ES0110 Statement contains more than one SQLDA.
    More than one SQLDA has been defined in the Working-Storage Section.
  • ES0111 token is not a table of null indicator variables.
    The preprocessor believes the token displayed should either be a null indicator or a null indicator table.
  • ES0112 token should not be a defined with an OCCURS clause.
    A host variable is defined as part of an OCCURS clause.
  • ES0113 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.
  • ES0114 Statement only allowed in the PROCEDURE DIVISION.
    A SQL statement such as EXEC SQL SELECT was coded in the Working-Storage Section.
  • ES0115 Statement not allowed in the PROCEDURE DIVISION.
    A SQL statement such as EXEC SQL DECLARE TABLE was coded in the Procedure Section.
  • ES0116 An error occurred whilst processing the trace file.
    A file error occurred while trying to write information to the preprocessor trace file.
  • ES0118 Mismatched DECLARE.
    More than one DECLARE statement was found within an EXEC SQL statement.
  • ES0119 Host variable name is too long.
    The host variable name is too long. The maximum length of the host variable is 30 characters.
  • ES0120 Internal error - dictionary handle is too big.
    A system error has occurred while the preprocessor was creating an internal dictionary of all host variables used in a program.
  • ES0121 ESQL SQL directive OPTION = token SETTING = token2 is invalid - all future SQL statements are ignored.
    A preprocessor directive was rejected by OESQL precompiler services. Any further OESQL directives and SQL statements will be ignored.
  • ES0900 An internal error occurred. Create a trace file using the compiler directive CHKECM(TRACE) and contact your support representative.
    An unexpected error occurred in the preprocessor.
  • ES0901 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.
  • ES1000W Use of EXEC SQL INCLUDE SQLCA END-EXE
Parent topic: OpenESQL Messages


ES0002 token is badly defined.

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 your support representative. Trace files may be needed to resolve this problem. See Creating Debug Files for details on how to create additional trace files that may be requested by your support representative.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


ES0003 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


ES0004 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


ES0005 An error occurred whilst processing the internal dictionary.

A system error has occurred trying to read the internal dictionary that the preprocessor creates of all host variables used in the program.

Resolution:

Report this error to your support representative. Trace files may be needed to resolve this problem. See Creating Debug Files for details on how to create additional trace files that might be requested by your support representative.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


ES0006 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


ES0007 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 your support representative. Trace files may be needed to resolve this problem. See Creating Debug Files for details on how to create additional trace files that may be requested by your support representative.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


ES0010 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. Trace files may be needed to resolve this problem. See Creating Debug Files for details on how to create additional trace files that may be requested by your support representative.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


ES0101 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 may have comments included in the source 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


ES0102 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


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

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
SQL Data Types


ES0104 Bad SQL data declaration.

An unexpected SQL declaration is 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 your support representative. Trace files may be needed to resolve this problem. See Creating Debug Files for details on how to create additional trace files that may be requested by your support representative.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


ES0105 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


ES0106 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


ES0107 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 drive/directory to look in to find the copybook. You should also check your COPYEXT setting in case your copybook files have some other extension other than "CBL" or "CPY".

Parent topic: OpenESQL Preprocessor Error Messages


ES0108 token is non-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


ES0109 token is not a data item.

The host variable displayed in token was not defined or 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


ES0110 Statement contains more than one SQLDA.

More than one SQLDA has been defined in the Working-Storage Section.

Resolution:

The preprocessor has a limit of only one SQLDA definition per program. If this becomes an issue, contact your support representative.

Parent topic: OpenESQL Preprocessor Error Messages


ES0111 token is not a table of null indicator variables.

The preprocessor believes the token displayed should either be 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


ES0112 token should not be a defined with an OCCURS clause.

A host variable is defined as part of an OCCURS clause.

Resolution:

The preprocessor does not allow host variables to be defined this way.

Parent topic: OpenESQL Preprocessor Error Messages


ES0113 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


ES0114 Statement only allowed in the PROCEDURE DIVISION.

A SQL statement such as EXEC SQL SELECT was coded in the Working-Storage Section.

Resolution:

This statement can not be coded in Working-Storage Section. Move the statement to the Procedure Section and then recompile the program.

Parent topic: OpenESQL Preprocessor Error Messages


ES0115 Statement not allowed in the PROCEDURE DIVISION.

A SQL statement such as EXEC SQL DECLARE TABLE was coded in the Procedure Section.

Resolution:

This statement can not be coded in the Procedure Section. Move it into Working-Storage Section and then recompile the program.

Parent topic: OpenESQL Preprocessor Error Messages


ES0116 An error occurred whilst processing the trace file.

A file error occurred while trying to write information to the preprocessor trace file.

Resolution:

Make sure you have write permissions on the drive/directory where the file is being written to and that there is enough space left on the drive.

Parent topic: OpenESQL Preprocessor Error Messages


ES0118 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


ES0119 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


ES0120 Internal error - dictionary handle is too big.

A system error has occurred while the preprocessor was creating an internal dictionary of all host variables used in a program.

Resolution:

Report this error to your support representative. Trace files may be needed to resolve this problem. See Creating Debug Files for details on how to create additional trace files that may be requested by your support representative.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


ES0121 ESQL SQL directive OPTION = token SETTING = token2 is invalid - all future SQL statements are ignored.

A preprocessor directive was rejected by OESQL precompiler services. Any further OESQL directives and SQL statements will be ignored.

Resolution:

Correct the options and recompile. You can see a list of valid directive options by displaying the Build Settings dialog box for the program and clicking Advanced on the Compile tab.

Parent topic: OpenESQL Preprocessor Error Messages


ES0900 An internal error occurred. Create a trace file using the compiler directive CHKECM(TRACE) and contact your support representative.

An unexpected error occurred in the preprocessor.

Resolution:

Report this error to your support representative. Trace files may be needed to resolve this problem. See Creating Debug Files for details on how to create additional trace files that may be requested by your support representative.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


ES0901 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


ES1000W Use of EXEC SQL INCLUDE SQLCA END-EXE

   EXEC SQL
      INCLUDE SQLCA
   END-EXEC

FIPS certification (reference X/OPEN CAE SQL 8.1.1) requires that a warning is generated if this syntax is supported.

Resolution:

No action is required.

Parent topic: OpenESQL Preprocessor Error 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.

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.

Parent topic: OpenESQL
Related concepts
OpenESQL Configuration Utility
Related reference
BEHAVIOR
Related information
To start the OpenESQL Configuration Utility
OpenESQL Configuration Utility


MFImportConn command

Enables you to import connection settings previously exported from the ADO.NET Connection Editor.

Important: You must run this command from a 32-bit or a 64-bit Visual COBOL command prompt, available from Start > All Programs > Micro Focus Visual COBOL.

Syntax

{MFImportConn32_v2 | MFImportConn32_v4 | MFImportConn64_v2 | MFImportConn64_v4} path:\exportedXMLfile {System | User} {32BIT | 64BIT}
Important: Use the executable that fits the type of connection you're importing to. In the executable file names, 32 represents 32-bit, 64 represents 64-bit, v2 represents .NET Framework versions 2.0, 3.0, or 3.5, and v4 represents .NET Framework 4.0.

Parameters

path | The full path to the XML file containing the exported connection settings
exportedXMLfile | The filename of the XML file containing the exported connection settings
System | Specify this to import the connection settings into the machine.config file for use by all users
User | Specify this to import the connection settings into the UserConnections32.config or UserConnections64.config file for use by the current user only
32BIT | Specify this for 32-bit connections
64BIT | Specify this for 64-bit connections
Parent topic: OpenESQL
Related concepts
Copying Connection Settings
Related tasks
To export ADO.NET connection settings
To import ADO.NET connection settings


DB2

  • DB2 Compiler Directive Options
  • DB2 ECM Error Messages
Parent topic: Reference


DB2 Compiler Directive Options

  • ACCESS
    Specifies the name of the package to be created and stored in the database. If ACCESS is specified without a parameter, the package name defaults to the program name (without the .CBL extension).
  • ACTION
    Indicates whether the package can be added or replaced.
  • BIND
    Specifies the name of the bind file to be created. When BIND is specified without a parameter, the bind file defaults to the program name with the filename extension replaced by .BND, and is created in the current source directory.
  • 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 (|).
  • 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.
  • 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.
  • 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-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.
  • HOSTVAR
    Enables the precompiler to compile a program when host variables are defined on multiple lines. If host variables are defined on multiple lines, the precompiler generates a COBDB0100S error. If this error occurs, compile the program using DB2(HOSTVAR).
  • HSFTRACE
    Generates calls around each SQL statement to the HSF trace routine. In some cases, the application must be linked with mfsqlSMF.lib.
  • IGNORE-NESTED
    In nested programs, specifies the program-id at which to start generating DB2 interface code. Any nested program encountered before the program-id is ignored and no DB2 interface code is generated. You must specify a program-id in the COBOL source code; otherwise, a compile error results. If you specify IGNORE-NESTED without a parameter, the program-id defaults to the program name with the filename extension replaced by .CBL.
  • 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 to initialize SQL. This option is disabled if it is used within an OO program.
  • 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-NESTED
    Causes the precompiler to generate DB2 interface code in every routine in a source module including mutiple nested subroutines.
  • NOT
    Specifies the character code to use for NOT character (¬).
  • OPTHINT
    Specifies whether or not to use query optimization hints for static SQL.
  • 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.
  • PASS
    Specifies the user ID and password to use when connecting to the database.
  • PRE
    Enables DB2 programs to be animated or executed by pre-loading DB2 API routine entry points. Specify NOPRE if creating an executable or shared object file; otherwise, you may have link problems.
  • 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.
  • QUERYOPT
    Indicates the desired level of optimization for all static SQL statements contained in the package. The default value is 5. For the complete range of optimization levels available, see the SET CURRENT QUERY OPTIMIZATION statement in the SQL Reference. This DB2 precompile/bind option is not supported by DRDA.
  • 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.
  • 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.
  • 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.
  • 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.
Parent topic: DB2
Related concepts
DB2 Compiler Directive
Error Codes


ACCESS

Specifies the name of the package to be created and stored in the database. If ACCESS is specified without a parameter, the package name defaults to the program name (without the .CBL extension).

Syntax:

ACCESS=package name
ACCESS
NOACCESS

Properties:

Default: | ACCESS
Synonym: | PACKAGE.
Parent topic: DB2 Compiler Directive Options


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


BIND

Specifies the name of the bind file to be created. When BIND is specified without a parameter, the bind file defaults to the program name with the filename extension replaced by .BND, and is created in the current source directory.

Bind files can be written to a specific directory other than the current source directory or a directory specified by the BIND directive. To do this, you set the HCOBND environment variable. For example:

HCOBND=d:\mydir\binds

The directory you specify in the HCOBND environment variable applies to all bind files created by Visual COBOL until you unset the environment variable or specify a specific build setting for a program using the DB2 bind directive. For example:

db2(bind=d:\mybinds\test.bnd)

would cause the HCOBND environment variable setting to be ignored.

Syntax:

BIND=bindfile
BIND
NOBIND

Properties:

Default: | NOBIND
Synonym: | BINDFILE.
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


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


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


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


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


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


IGNORE-NESTED

In nested programs, specifies the program-id at which to start generating DB2 interface code. Any nested program encountered before the program-id is ignored and no DB2 interface code is generated. You must specify a program-id in the COBOL source code; otherwise, a compile error results. If you specify IGNORE-NESTED without a parameter, the program-id defaults to the program name with the filename extension replaced by .CBL.

Syntax:

IGNORE-NESTED=program-id
IGNORE-NESTED
NOIGNORE-NESTED

Properties:

Default: NOIGNORE-NESTED
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 to initialize SQL. This option is disabled if it is used within an OO program.

Syntax:

INIT={PROT | S | X }
NOINIT

Parameters:

PROT | In the event that the application terminates abnormally, correctly closes down the database connection and rolls back all changes since the last COMMIT, avoiding potential database corruption.
S | Database to be used in shared mode
X | Database to be used in exclusive mode

Properties:

Default: NOINIT

Comments:

  • Set INIT 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.
  • If you use DB2 LUW 7.2 with fixpack 8 or later, do not compile an application using both the INIT and the PASS directives. Instead, we recommend that you code a CONNECT statement directly into your programs. Because these versions of DB2 LUW generate an SQL error when host variables are passed with spaces or low values on a CONNECT, INIT does not generate the CONNECT statement with the blank host variables needed by the PASS directive for the user ID and password.
  • In some additional circumstances, you might find it best to code a CONNECT statement into your programs rather than using the DB2(INIT) directive. Consider the following:
    • In the past, IBM has occasionally changed the equivalent APIs used in the SQL CONNECT statement. Therefore, we cannot guarantee that the implicit code generated by the DB2(INIT) compiler directive will function with new releases of DB2 LUW.
    • Because the DB2(INIT) directive can generate and store user ID and password information, security is a consideration.
Parent topic: DB2 Compiler Directive Options
Related reference
PASS


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

Causes the precompiler to generate DB2 interface code in every routine in a source module including mutiple nested subroutines.

Syntax:

MULTI-NESTED
NOMULTI-NESTED

Properties:

Default: NOMULTI-NESTED
Parent topic: DB2 Compiler Directive Options


NOT

Specifies the character code to use for NOT character (¬).

Syntax:

 NOT={ascii-character-code | 170}

Properties:

Default: NOT=170
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


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


PASS

Specifies the user ID and password to use when connecting to the database.

Syntax:

PASS={password | userid.password}
NOPASS

Properties:

Default: NOPASS

Comment:

For information about using PASS with INIT see the topic INIT.

Parent topic: DB2 Compiler Directive Options
Related reference
INIT


PRE

Enables DB2 programs to be animated or executed by pre-loading DB2 API routine entry points. Specify NOPRE if creating an executable or shared object file; otherwise, you may have link problems.

Syntax:

PRE
NOPRE

Properties:

Default: PRE
Parent topic: DB2 Compiler Directive Options


QUALFIX

Causes the DB2 ECM to append three characters to the name of the host variables when declaring them to DB2. This ensures problems caused by qualification (where two or more host variables have identical names when not qualified) are avoided but has the side-effect that DB2 error messages sometimes display the names of host variables with the three additional characters appended to them.

Syntax:

[NO]QUALFIX

Properties:

Default: NOQUALFIX
Parent topic: DB2 Compiler Directive Options
Related concepts
Error Codes


QUALIFIER

Provides a 128-character implicit qualifier for unqualified table names, views, indexes, and aliases contained in the package. The default is the owner's authorization ID.

Syntax:

QUALIFIER=qualifier-name
NOQUALIFIER

Properties:

Default: NOQUALIFIER
Parent topic: DB2 Compiler Directive Options


QUERYOPT

Indicates the desired level of optimization for all static SQL statements contained in the package. The default value is 5. For the complete range of optimization levels available, see the SET CURRENT QUERY OPTIMIZATION statement in the SQL Reference. This DB2 precompile/bind option is not supported by DRDA.

Syntax:

QUERYOPT= optimization-level
NOQUERYOPT

Properties:

Default: NOQUERYOPT
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


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


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


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}

Properties:

Default: DB2 LUW Server Version from connection
Parent topic: DB2 Compiler Directive Options
Related concepts
UDB-VERSION DB2 Directive Option
Related information
UDB-VERSION DB2 Directive Option


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


DB2 ECM Error Messages

  • COBDB0002 - COBDB0021
    Lists the DB2 ECM error messages from COBDB0002 through COBDB0021.
  • COBDB0100 - COBDB0115
    Lists the DB2 ECM error messages from COBDB0100 through COBDB0115.
  • COBDB0116 - COBDB0901
    Lists the DB2 ECM error messages from COBDB0116 through COBDB0901.
Parent topic: DB2


COBDB0002 - COBDB0021

Lists the DB2 ECM error messages from COBDB0002 through COBDB0021.
  • COBDB0002 token is badly defined.
    One of the following occurred:
  • 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 whilst processing the internal dictionary.
    A system error has occurred trying to read an internal dictionary that the preprocessor creates of all host variables used in the program.
  • COBDB0006 Required DB software token could 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 an older version of the program was used.
  • 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 attempting to connect.
  • COBDB0010 DB2 rejected an unspecified option.
    A sqlcode of -4905 was reported processing the DB2 directives specified.
  • COBDB0011 No database name was specified.
    One of the following has happened:
  • 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.
Parent topic: DB2 ECM Error Messages


COBDB0002 token is badly defined.

One of the following occurred:
  • 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 this COBOL development software. If problem persists, report this error to your support representative. Trace files may be need to resolve this problem. See Creating Debug Files for details on how to create additional trace files that may be requested by your support representative.

Parent topic: COBDB0002 - COBDB0021
Related concepts
Creating Debug Files


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


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


COBDB0005 An error occurred whilst processing the internal dictionary.

A system error has occurred trying to read an internal dictionary that the preprocessor creates of all host variables used in the program.

Resolution:

Report this error to your support representative. Trace files may be need to resolve this problem. See Creating Debug Files for details on how to create additional trace files that might be requested by your support representative.

Parent topic: COBDB0002 - COBDB0021
Related concepts
Creating Debug Files


COBDB0006 Required DB software token could 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 DB2 database and tables to compile the program against. If the token is "db2agapi" then either the DB2 software was not installed or the PATH statement may need to be modified so that the DB2 installation directory is found. If the token is "db2aprep", make sure that the DB2 Application Development Client software is installed.

Parent topic: COBDB0002 - COBDB0021


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 your support representative. Trace files may be needed to resolve this problem. See Creating Debug Files for details on how to create additional trace files that might be requested by your support representative.

Parent topic: COBDB0002 - COBDB0021
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 an older version of the program was used.

Resolution:

Uninstall any older versions of this Micro Focus COBOL development system, and then reinstall.

Parent topic: COBDB0002 - COBDB0021


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 attempting to connect.

Resolution:

token provides additional information about the error. You can use the IBM DB2 Error Reference manual to get additional information as to what is causing the connection error.

Parent topic: COBDB0002 - COBDB0021


COBDB0010 DB2 rejected an unspecified option.

A sqlcode of -4905 was reported processing the DB2 directives specified.

Resolution:

Verify the directives specified are valid for the DB2 server that you are trying to compile the program against. Make any corrections necessary and then recompile the program.

Parent topic: COBDB0002 - COBDB0021


COBDB0011 No database name was specified.

One of the following has happened:
  • you did not specify a database name in your project
  • you did not set environment variable DB2DBDFT

Resolution:

Click Project Settings from the Project menu and click the SQL tab. Fill in the database name then recompile your program.

Parent topic: COBDB0002 - COBDB0021


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


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 greater than 65536 characters long. The preprocessor gets passed a compressed version of the SQL statement rather than the original source which may have comments included in the source as well as leading and trailing blanks.
  • COBDB0102 Statement contains too many host variables.
    The SQL statement contains more than 8000 host and indicator variables.
  • COBDB0103 host-var does not have a suitable definition to be used as a host variable.
    The host variable data definition does not match the column type associated with it in the SQL statement. For example, you are trying to use a host variable defined as PIC X(n) with a column defined as SMALLINT.
  • COBDB0104 Bad SQL data declaration.
    An unexpected SQL declaration is passed to the preprocessor. Generally this error occurs only for host variables defined as:
  • COBDB0105 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:
  • 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 <token> was not found.
  • COBDB0108 host-var is non-unique and should be qualified.
    The host variable host-var is not unique.
  • 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 defined in the Working-Storage Section.
  • 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.
  • 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.
  • 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.
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 greater than 65536 characters long. The preprocessor gets passed a compressed version of the SQL statement rather than the original source which may have comments included in the source as well as leading and trailing blanks.

Resolution:

Look at breaking the SQL statement into multiple SQL statements and then try recompiling the program.

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


COBDB0103 host-var does not have a suitable definition to be used as a host variable.

The host variable data definition does not match the column type associated with it in the SQL statement. For example, you are trying to use a host variable defined as PIC X(n) with a column defined as SMALLINT.

Resolution:

Verify that the host variable corresponds 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.

Parent topic: COBDB0100 - COBDB0115


COBDB0104 Bad SQL data declaration.

An unexpected SQL declaration is 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 your support representative. Trace files may be needed to resolve this problem. See Creating Debug Files for details on how to create additional trace files that may be requested by your support representative.

Parent topic: COBDB0100 - COBDB0115
Related concepts
Creating Debug Files


COBDB0105 Syntax error.

The SQL statement includes invalid syntax or does not include required information. For example, this error would be generated if you 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: 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 <token> was not found.

Resolution:

The preprocessor looks first in the current directory, and then down the paths specified by environment variables SQLCPY and COBCPY. The COBCPY environment is defined by going into the Dependency Library and Copybook folders and adding a new folder. Either correct the filename or update the Copybook folder to include the drive/folder where the copybook is located.

Parent topic: COBDB0100 - COBDB0115


COBDB0108 host-var is non-unique and should be qualified.

The host variable host-var 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 something like this if you wanted the host variable from the ORDERS copybook to be used in the query:

:ORDERS.ORD-NO

Parent topic: COBDB0100 - COBDB0115


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


COBDB0110 Statement contains more than one SQLDA.

More than one SQLDA has been defined in the Working-Storage Section.

Resolution:

The preprocessor currently has a limit of only one SQLDA definition per program. If this becomes an issue, contact your support representative.

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.

Resolution:

The preprocessor does not allow host variables to be defined this way.

Parent topic: COBDB0100 - COBDB0115


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.

Resolution:

The preprocessor does not allow host variables to be defined this way.

Parent topic: COBDB0100 - COBDB0115


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.

Resolution:

This statement cannot be coded in the Procedure Division. Move it into the Working-Storage Section and then recompile the program.

Parent topic: COBDB0100 - COBDB0115


COBDB0116 - COBDB0901

Lists the DB2 ECM error messages from COBDB0116 through COBDB0901.
  • COBDB0116 An error occurred whilst processing the trace file.
    A file error occurred while trying to write information to the preprocessor trace file.
  • COBDB0117 Invalid format of compound SQL statement. This condition is non-recoverable; subsequent (valid) SQL statements may generate spurious errors.
    A compound SQL statement did not precompile successfully.
  • 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. 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.
  • COBDB0120 Internal error - dictionary handle is too big.
    The preprocessor creates an internal dictionary of all host variables used in a program. A system error has occurred.
  • COBDB0121 Package name is too long, max=8 chars, use ACCESS directive to fix.
    The package name specified is longer than 8 characters. If you did not specify an explicit package name via the ACCESS directive, the preprocessor defaults to use the filename of the program being compiled. If this name is more than 8 characters, this error message is generated.
  • COBDB0122 Nested INCLUDE's not supported
    The DB2 ECM does not support EXEC SQL INCLUDE statements that expand an EXEC SQL INCLUDE statement.
  • COBDB0127 A '(' is illegal in the INTO clause.
    A left parenthesis "(" was found in the SQL statement in error.
  • 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 associate with it in the SQL statement. For example, you are trying to use an indicator variable defined as PIC X(n) rather than PIC S9(04) COMP.
  • COBDB0900 An internal error occurred. Create a trace file using the compiler directive CHKECM(TRACE) and contact your support representative.
    An unexpected error occurred in the preprocessor.
  • COBDB0901 This error prevents SQL processing from continuing - further EXEC SQL statements will be ignored.
    If a severe SQL error occurs, any additional EXEC SQL statements will not be processed by the preprocessor.
Parent topic: DB2 ECM Error Messages


COBDB0116 An error occurred whilst processing the trace file.

A file error occurred while trying to write information to the preprocessor trace file.

Resolution:

Make sure you have write authority on the drive/folder where the file is being written to and that there is enough space left on the drive.

Parent topic: COBDB0116 - COBDB0901


COBDB0117 Invalid format of compound SQL statement. This condition is non-recoverable; subsequent (valid) SQL statements may generate spurious errors.

A compound SQL statement did not precompile successfully.

Resolution:

Look at the IBM SQL Reference for details of how to specify a valid compound SQL statement.

Parent topic: COBDB0116 - COBDB0901


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


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 directive DB2(NOQUALFIX). If you still get the error, make sure the host variable is a valid COBOL name. It should be 30 characters or less in length.

Parent topic: COBDB0116 - COBDB0901


COBDB0120 Internal error - dictionary handle is too big.

The preprocessor creates an internal dictionary of all host variables used in a program. A system error has occurred.

Resolution:

Report this error to your support representative. Trace files may be needed to resolve this problem. See Creating Debug Files for details on how to create additional trace files that may be requested by your support representative.

Parent topic: COBDB0116 - COBDB0901
Related concepts
Creating Debug Files


COBDB0121 Package name is too long, max=8 chars, use ACCESS directive to fix.

The package name specified is longer than 8 characters. If you did not specify an explicit package name via the ACCESS directive, the preprocessor defaults to use the filename of the program being compiled. If this name is more than 8 characters, this error message is generated.

Resolution:

Specify the directive DB2(ACCESS=name) where the name is 8 characters or less.

Parent topic: COBDB0116 - COBDB0901


COBDB0122 Nested INCLUDE's 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.

Parent topic: COBDB0116 - COBDB0901


COBDB0127 A '(' is illegal in the INTO clause.

A left parenthesis "(" was found in the SQL statement in error.

Resolution:

Correct the syntax and recompile your program. See the SQL Reference for the correct syntax.

Parent topic: COBDB0116 - COBDB0901


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


COBDB0137 Indicator variable ind-var is not SMALLINT type.

The indicator variable data definition does not match the data type associate with it in the SQL statement. For example, you are trying to use an indicator variable defined as PIC X(n) rather than PIC S9(04) COMP.

Resolution:

Correct the picture clause for the indicator variable identified in the error message and recompile the program.

Parent topic: COBDB0116 - COBDB0901


COBDB0900 An internal error occurred. Create a trace file using the compiler directive CHKECM(TRACE) and contact your support representative.

An unexpected error occurred in the preprocessor.

Resolution:

Report this error to your support representative. Trace files may be need to resolve this problem. See Creating Debug Files for details on how to create additional trace files that may be requested by your support representative.

Parent topic: COBDB0116 - COBDB0901
Related concepts
Creating Debug Files


COBDB0901 This error prevents SQL processing from continuing - further EXEC SQL statements will be ignored.

If a severe SQL error occurs, any additional EXEC SQL statements will not be processed by the preprocessor.

Resolution:

Correct the severe error and then recompile the program.

Parent topic: COBDB0116 - COBDB0901


COBSQL

  • COBSQL Compiler Directive Options
  • COBSQL Messages
Parent topic: Reference


COBSQL Compiler Directive Options

  • COBSQLTYPE
    Specifies which precompiler to use.
  • CSTART
    Forces COBSQL to load the database support modules at execution time.
  • CSTOP
    Forces COBSQL to load the stop run module that performs a rollback if the application terminates abnormally
  • DEBUGFILE
    Creates a debug (.deb) file
  • DISPLAY
    Displays precompiler statistics. Should only be used when initially verifying that COBSQL is correctly calling the standalone precompiler.
  • END-COBSQL
    Signals the end of COBSQL directives; remaining directives, if any, are passed to the precompiler
  • HSFTRACE
    Generates calls around each SQL statement to the HSF trace routine. In some cases, the application must be linked with mfsqlSMF.lib.
  • KEEPCBL
    Saves precompiled source file (.cbl)
  • MAKESYN
    Converts all COMP host variables to COMP-5 host variables. If neither MAKESYN nor NOMAKESYN is set (the default), all variables (not just host variables) defined as COMP or COMP-4 are converted to COMP-5.
  • SQLDEBUG
    Creates a number of files that we can use to debug COBSQL. These files include the output file from the precompiler (normally this has the extension .cbl), the listing file produced by the precompiler (this has the extension .lis), plus a COBSQL debug file which has the extension .sdb. SQLDEBUG will also turn on KEEPCBL and TRACE.
  • TRACE
  • 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.
Parent topic: COBSQL


COBSQLTYPE

Specifies which precompiler to use.

Syntax:

COBSQLTYPE={ORACLE | ORACLE8 | SYBASE | INFORMIX-NEW}

Properties:

Synonym: CSQLT
Parent topic: COBSQL Compiler Directive Options


CSTART

Forces COBSQL to load the database support modules at execution time.

Syntax:

[NO]CSTART

Properties:

Default: | NOCSTART
Synonym: | CST

Comments:

This directive is not available on UNIX.

Parent topic: COBSQL Compiler Directive Options


CSTOP

Forces COBSQL to load the stop run module that performs a rollback if the application terminates abnormally

Syntax:

[NO]CSTOP

Properties:

Default: | NOCSTOP
Synonym: | CSP

Comments:

This directive is not available on UNIX.

Parent topic: COBSQL Compiler Directive Options


DEBUGFILE

Creates a debug (.deb) file

Syntax:

[NO]DEBUGFILE

Properties:

Default: | NODEBUGFILE
Synonym: | DEB
Parent topic: COBSQL Compiler Directive Options


DISPLAY

Displays precompiler statistics. Should only be used when initially verifying that COBSQL is correctly calling the standalone precompiler.

Syntax:

[NO]DISPLAY

Properties:

Default: | NODISPLAY
Synonym: | DIS
Parent topic: COBSQL Compiler Directive Options


END-COBSQL

Signals the end of COBSQL directives; remaining directives, if any, are passed to the precompiler

Syntax:

END-COBSQL
END-C
END

Properties:

Default: | Not specified
Synonyms: | END-C, END
Parent topic: COBSQL Compiler Directive Options


KEEPCBL

Saves precompiled source file (.cbl)

Syntax:

KEEPCBL
Parent topic: COBSQL Compiler Directive Options


MAKESYN

Converts all COMP host variables to COMP-5 host variables. If neither MAKESYN nor NOMAKESYN is set (the default), all variables (not just host variables) defined as COMP or COMP-4 are converted to COMP-5.

Syntax:

[NO]MAKESYN

Properties:

Default: NOMAKESYN
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. SQLDEBUG will also turn on KEEPCBL and TRACE.

Syntax:

SQLDEBUG

Properties:

Default: | Not specified
Synonym: | SQLDEBUG
Parent topic: COBSQL Compiler Directive Options


TRACE

Syntax:

[NO]TRACE

Properties:

Default: | NOTRACE
Synonym: | Creates a trace file (.trc)
Parent topic: COBSQL Compiler Directive Options


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: Not specified
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-046
    Lists the COBSQL messages from CSQL-E-024 through CSQL-F-046.
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-046

Lists the COBSQL messages from CSQL-E-024 through CSQL-F-046.
  • 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.
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-046


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


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


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


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


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


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


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


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


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


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


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


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


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


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
.NET Host Variables in Managed Code
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 .NET 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 .NET Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL .NET 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 .NET Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL .NET 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 .NET Managed Runtime
In addition to the definitions valid OpenESQL, the following definition is also valid for the OpenESQL .NET 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)
  • XML
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
01 char-field3      SQL TYPE IS CHAR(200).

The char-field3 format uses the CHAR SQL TYPE.

OpenESQL .NET Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL .NET Managed Runtime:
01 char-net         string(200).
Parent topic: Character Data Types
Related reference
CHAR SQL Type


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 must be COMP-5 for OpenESQL. 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).
01 varying1     PIC X(20) VARYING.
  • The varchar3 format uses the CHAR-VARYING SQL TYPE.
  • The longvarchar1 format uses the LONG-VARCHAR SQL TYPE.
OpenESQL .NET Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL .NET Managed Runtime:
01 varchar6           string.
Parent topic: Character Data Types
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
01 clob1     SQL TYPE IS CLOB(2M).
  • OpenESQL native support is limited to handling 65000 bytes.
  • The clob1 format uses the CLOB SQL TYPE.
OpenESQL .NET Managed Runtime
OpenESQL .NET Managed Runtime applications have no byte limit. In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL .NET Managed Runtime:
01 clob2     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 .NET Managed Runtime
In addition to the definition valid for OpenESQL, the following definition is also valid for the OpenESQL .NET Managed Runtime:
01 uni-field2      string.
Parent topic: Character Data Types


Unicode Variable-length Character Strings

Unicode variable-length character strings (NVARCHAR) 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 nvarchar1.
   49 nvarchar1-len        PIC S9(4)  COMP-5.
   49 nvarchar1-data       PIC N(200) USAGE NATIONAL.

01 nvarchar2.
   49 nvarchar1-len        PIC S9(4)  COMP.
   49 nvarchar1-data       PIC N(200) USAGE NATIONAL.
OpenESQL .NET Managed Runtime
In addition to the definition valid for OpenESQL, the following definition is also valid for the OpenESQL .NET Managed Runtime:
01 nvarchar3               string.
Parent topic: Character Data Types


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 dbclob2.
   49 dbclob2-len          PIC S9(9) COMP-5.
   49 dbclob2-data         PIC N(32000) USAGE NATIONAL.
OpenESQL
The following definition is also valid:
01 dbclob1     SQL TYPE IS DBCLOB(2M).
  • OpenESQL native support is limited to handling 65000 bytes.
  • The dbclob1 format uses the DBCLOB SQL TYPE.
OpenESQL .NET Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL .NET Managed Runtime:
01 dbclob3     string.

OpenESQL .NET Managed Runtime applications have no byte limit.

Parent topic: Character Data Types
Related reference
DBCLOB SQL Type


XML

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     SQL TYPE IS XML AS CLOB(2M).

The xmlclob1 format uses 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
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 .NET Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL .NET 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 .NET Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL .NET Managed Runtime:
01 packed4      type system.decimal.
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 .NET Byte host variables
  • OpenESQL native support is limited to handling 65000 bytes.
  • 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 .NET Managed Runtime
In addition to the definitions valid for all databases and for OpenESQL, the following definition is also valid for the OpenESQL .NET Managed Runtime:
01 bin-field3      type System.Byte[].
01 bin-field4      type System.Byte occurs 200 times.

OpenESQL .NET 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
ALLOWNULLCHAR


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 .NET Byte host variables
  • OpenESQL native support is limited to handling 65000 bytes.
  • The varbin-field1 format uses the VARBINARY SQL TYPE.
  • The varbin-field2 format uses the LONG-VARBINARY SQL TYPE.
OpenESQL .NET Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL .NET Managed Runtime:
01 varbin-field4      type System.Byte[].

OpenESQL .NET 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
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 .NET Byte host variables
  • OpenESQL native support is limited to handling 65000 bytes.
OpenESQL .NET Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL .NET Managed Runtime:
01 blob2     type System.Byte[].

OpenESQL .NET 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 .NET Managed Runtime applications that use JVM date and time data types.

  • DATE
  • DATETIMEOFFSET
  • TIME
  • TIMESTAMP
  • TIMESTAMPOFFSET
Parent topic: SQL Data Types


DATE

Data Format

If a COBOL output host variable is defined for an SQL DATE value, the date is specified in the format:
yyyy-mm-dd
For example:
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.
  • When using the date1 format:
    • OpenESQL requires that you compile applications with the DETECTDATE SQL directive.
    • Move date specifications into the host variable in the form:
      {d 'yyyy-mm-dd'}
  • The date2 format uses the DATE SQL TYPE.
  • The date3 format uses the DATE-RECORD SQL TYPE.
OpenESQL .NET 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 .NET Managed Runtime:
01 date4         type System.DateTime.
Parent topic: Date and Time Data Types
Related reference
DATE SQL Type
DATE-RECORD SQL Type


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 information
The SQLDA Data Structure


TIME

Data Format

If a COBOL output host variable is defined for an SQL TIME value, the time is specified in the following format:
hh:mm:ss
For example:
12:34:00

Host Variable Formats

OpenESQL and DB2 ECM
01 time1         PIC X(8).
OpenESQL
01 time2         SQL TYPE IS TIME.
01 time3         SQL TYPE IS TIME-RECORD.
  • When using the time1 format:
    • OpenESQL requires that you compile applications with the DETECTDATE SQL directive.
    • Move time specifications into the host variable in the form:
      {t 'hh:mm:ss'}
  • The time2 format uses the TIME SQL TYPE.
  • The time3 format uses the TIME-RECORD SQL TYPE.
OpenESQL .NET 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 .NET Managed Runtime:
01 time4         type System.TimeSpan.
Parent topic: Date and Time Data Types
Related reference
TIME SQL Type
TIME-RECORD SQL Type


TIMESTAMP

Data Format

If a COBOL output host variable is defined for an SQL timestamp value, the date and time are specified in the following format:
                    yyyy-mm-dd hh:mm:ss[.f[f[...]]]
where the number of fractional digits is driver-defined. For example:
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         SQL TYPE IS TIMESTAMP-RECORD.
  • When using the timestamp1 format:
    • OpenESQL requires that you compile applications with the DETECTDATE SQL directive.
    • To move time specifications into the host variable:
      • To specify a time only, move the time into the host variable in the form:
        {t 'hh:mm:ss'}
      • To specify a time and a date, move them together into the host variable in the form:
        {ts 'yyyy-mm-dd
                                                    hh:mm:ss[.f[f[...]]]'
        For example:
        $set sql(dbman=odbc, detectdate)
 01 timestamp1 pic x(26).
  . . .
     move "{ts'1965-11-02 12:08:30'}" to timestamp1
     exec sql
         insert into emp (TransDate) values (:timestamp1)
     end-exec
  • When using the timestamp2 format, you can just move the date/time literal without the special characters. For example:
    01 timestamp2 SQL TYPE IS TIMESTAMP.
  . . .
     move "1965-11-02 08:12:56"  to timestamp2
     exec sql
         insert into emp (TransDate) values (:timestamp2)
     end-exec
  • The timestamp3 format uses the TIMESTAMP SQL TYPE.
OpenESQL .NET 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 .NET Managed Runtime:
01 timestamp4         type System.DateTime.
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


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 .NET 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 .NET 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
Parent topic: SQL Data Types


BLOB-LOCATOR Data Type

Host Variable Format

DB2 ECM
01 blob-locator-file1 SQL TYPE IS BLOB-LOCATOR.

The blob-locator-file1 format uses the BLOB-LOCATOR SQL TYPE.

Parent topic: Locator Data Types
Related reference
BLOB-LOCATOR SQL Type


CLOB-LOCATOR Data Type

Host Variable Format

DB2 ECM
01 clob-locator1 SQL TYPE IS CLOB-LOCATOR.

The clob-locator1 format uses the CLOB-LOCATOR SQL TYPE.

Parent topic: Locator Data Types
Related reference
CLOB-LOCATOR SQL Type


DBCLOB-LOCATOR Data Type

Host Variable Format

DB2 ECM
01 dbclob-locator-file1 SQL TYPE IS CLOB-LOCATOR.

The dbclob-locator-file1 format uses the DBCLOB-LOCATOR SQL TYPE.

Parent topic: Locator Data Types
Related reference
DBCLOB-LOCATOR SQL Type


File Data Types

  • BLOB-FILE Data Type
  • CLOB-FILE Data File
  • 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 File

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 information
Variable-length Character Strings


ROWID Data Type

Host Variable Format

DB2 ECM
01 rowid1 SQL TYPE IS ROWID.
  • ROWID can be used with DB2 ECM but only for DB2 for z/OS servers.
  • The rowid1 format uses the ROWID SQL TYPE.
Parent topic: Miscellaneous Data Types
Related reference
ROWID SQL Type


SQL TYPEs

  • BINARY SQL Type
  • BLOB SQL Type
  • BLOB-FILE SQL Type
  • BLOB-LOCATOR SQL Type
  • CHAR SQL Type
  • CHAR-VARYING SQL Type
  • CLOB SQL Type
  • CLOB-FILE SQL Type
  • CLOB-LOCATOR SQL Type
  • DATE SQL Type
  • DATE-RECORD SQL Type
  • DBCLOB SQL Type
  • DBCLOB-FILE SQL Type
  • DBCLOB-LOCATOR SQL Type
  • LONG-VARBINARY SQL Type
  • LONG-VARCHAR SQL Type
  • ROWID SQL Type
  • TIME SQL Type
  • TIME-RECORD SQL Type
  • TIMESTAMP SQL Type
  • TIMESTAMP-RECORD SQL Type
  • TIMESTAMP-OFFSET SQL Type
  • TIMESTAMP-OFFSET-RECORD SQL Type
  • VARBINARY SQL Type
  • XML SQL Type
Parent topic: Reference
Related concepts
Setting OpenESQL Assistant Options
COBOL to SQL Data Type Mapping
SQL TYPEs


BINARY SQL Type

Note: OpenESQL 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 concepts
OpenESQL
Related information
Fixed-length Binary Strings


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-len    PIC S9(9) COMP-5.
  03 hv-name-val    PIC X(2097152).
Parent topic: SQL TYPEs
Related information
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 information
BLOB-FILE Data 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 information
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 information
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 information
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-len    PIC S9(9) COMP-5.
  03 hv-name-val    PIC X(2097152).
Parent topic: SQL TYPEs
Related information
Variable-length Character Strings
Large Character Strings (CLOB)


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 information
CLOB-FILE Data File


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 information
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 information
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 information
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-len    PIC S9(9) COMP-5.
  03 hv-name-val    PIC X(2097152).
Parent topic: SQL TYPEs
Related information
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 information
DBCLOB-FILE Data 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 information
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 information
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 information
Variable-length Character Strings


ROWID SQL Type

Note: Valid for DB2 ECM but only for DB2 for z/OS servers

Syntax

SQL [TYPE] [IS] ROWID

Example

01 hv-name SQL TYPE IS ROWID.

generates

01 hv-name.
  03 hv-name-len    PIC S9(4) COMP.
  03 hv-name-data   PIC X(40).
Parent topic: SQL TYPEs
Related information
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 information
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 information
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 information
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 information
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 information
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 information
TIMESTAMPOFFSET


VARBINARY SQL Type

Note: OpenESQL only

Syntax

SQL [TYPE] [IS] VARBINARY(n)

Example

01 hv-name SQL TYPE IS VARBINARY(2000).

generates

01 hv-name.
  03 hv-name-len    PIC S9(4) COMP-5.
  03 hv-name-val    PIC X(2000).
Parent topic: SQL TYPEs
Related information
Variable-length Binary Strings


XML SQL Type

Note: OpenESQL and DB2 ECM only

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 hv-name SQL TYPE IS XML AS CLOB(2M).

generates

01 hv-name.
  03 hv-name-len    PIC S9(9) COMP-5.
  03 hv-name-val    PIC X(2097152).
Parent topic: SQL TYPEs
Related information
XML


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)
The Warning Flags
Related reference
WHENEVER


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)


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


File Handling

  • File Handling Examples
  • File Handling Guide
  • Working with Data Files
  • File Systems
  • Fileshare Guide
Parent topic: Data Access


File Handling Examples

  • Example of Data and Key Compression
  • External Files
  • File Handler
  • File Names
  • File Status
  • Indexed Files
  • Locking Files and Records
  • MFSORT
  • Rebuild
  • Example Relative File Definition
  • Sequential Files
Parent topic: File Handling
Related information
File Handling Guide
Working with Data Files
File Systems
Fileshare Guide


Example of Data and Key Compression

In the following program, data compression is specified for transfile but not for masterfile. For key compression, suppression of trailing spaces and of leading characters that are the same as in the previous key is specified for keys t-rec-key and m-rec-key.

Suppression of repetition of duplicate keys is also turned on for m-alt-key-1 and m-alt-key-2. This is ignored for m-alt-key-1 which does not allow duplicates.

$set callfh"extfh"
$set datacompress"1"
$set keycompress"6"
     select transfile
         assign to "user.dat"
         organization is indexed
         record key is t-rec-key.
$set nokeycompress
$set nodatacompress

     select masterfile
         assign to "stock.dat"
         organization is indexed
$set keycompress"6"
         record key is m-rec-key
$set keycompress"7"
         alternate key is m-alt-key-1 with duplicates
         alternate key is m-alt-key-2.
$set nokeycompress
Parent topic: File Handling Examples
Related information
External Files
File Handler
File Names
File Status
Indexed Files
Locking Files and Records
MFSORT
Rebuild
Example Relative File Definition
Sequential Files


External Files

  • Example External Files
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
File Handler
File Names
File Status
Indexed Files
Locking Files and Records
MFSORT
Rebuild
Example Relative File Definition
Sequential Files


Example External Files

  1$set ans85 mf noosvs
  2*****************************************************
  3*
  4*    (C) 1997-2002 Micro Focus International Ltd.
  5*
  6*      EXTFILE.CBL
  7*
  8* This program demonstrates how to use EXTERNAL files
  9* It calls WRITEFIL to write some records to a data
 10* file and READFILE to read the same records back
 11* (without opening or closing the file between calls
 12* READFILE displays the output.
 13*
 14****************************************************
 15 identification division.
 16 program-id. extfile.
 17 environment division.
 18 input-output section.
 19 file-control.
 20 select finfile assign to "isamfil.dat"
 21  organization is indexed
 22  record key is fd-tran-date
 23  access mode is dynamic.
 24
 25 file section.
 26 fd finfile
 27  is external
 28   record contains 50 characters.
 29 01 fd-finfile-record.
 30   05 fd-tran-date   pic x(4).
 31   05 fd-with-or-dep   pic x(2).
 32   05 fd-amount    pic 9(5)v99.
 33
 34 procedure division.
 35 main-line.
 36   perform open-file
 37   perform write-to-the-file
 38   perform start-file
 39   perform read-the-file
 40   perform close-file
 41   stop run.
 42
 43 open-file.
 44   open i-o finfile.
 45
 46 start-file.
 47   move 1111 to fd-tran-date
 48   start finfile key = fd-tran-date.
 49
 50 write-to-the-file.
 51   call "writefil".
 52
 53 read-the-file.
 54   call "readfile".
 55
 56 close-file.
 57   close finfile.
 58 end program extfile.
 59*****************************************************
 60 identification division.
 61 program-id. readfile.
 62 environment division.
 63 input-output section.
 64 file-control.
 65 select finfile assign to "isamfil.dat"
 66   organization is indexed
 67   record key is fd-tran-date
 68   access mode is dynamic.
 69
 70 file section.
 71 fd finfile
 72   is external
 73   record contains 50 characters.
 74 01 fd-finfile-record.
 75   05 fd-tran-date   pic x(4).
 76   05 fd-with-or-dep  pic x(2).
 77   05 fd-amount    pic 9(5)v99.
 78
 79 working-storage section.
 80 01 ws-end-of-file   pic 9   value 0.
 81 01 ws-subtotal    pic s9(5)v99 value 0.
 82 01 ws-total     pic -(4)9.99.
 83
 84 procedure division.
 85 main-line.
 86   perform read-the-file.
 87   perform until ws-end-of-file = 1
 88   perform calculate-totals
 89   perform read-the-file
 90   end-perform.
 91   perform display-output.
 92   exit program.
 93   stop run.
 94
 95 read-the-file.
 96   read finfile next record at end
 97    move 1 to ws-end-of-file.
 98
 99 calculate-totals.
100   evaluate fd-with-or-dep
101    when "WI"
102     subtract fd-amount from ws-subtotal
103    when "DE"
104     add fd-amount to ws-subtotal
105   end-evaluate.
106
107 display-output.
108   move ws-subtotal to ws-total
109   display "account balance = ", ws-total.
110
111 end program readfile.
112****************************************************
113 identification division.
114 program-id. writefil.
115 environment division.
116 input-output section.
117 file-control.
118 select finfile assign to "isamfil.dat"
119   organization is indexed
120   record key is fd-tran-date
121   access mode is dynamic.
122
123 file section.
124 fd finfile
125  is external
126  record contains 50 characters.
127 01 fd-finfile-record.
128   05 fd-tran-date   pic x(4).
129   05 fd-with-or-dep   pic x(2).
130   05 fd-amount    pic 9(5)v99.
131
132 procedure division.
133 main-line.
134   perform write-records
135   exit program
136   stop run.
137
138 write-records.
139
140* write a WIthdrawal record
141   move 1111 to fd-tran-date.
142   move 'WI' to fd-with-or-dep.
143   move 23.55 to fd-amount.
144   write fd-finfile-record.
145
146* write a DEposit record
147   move 2222 to fd-tran-date.
148   move 'DE' to fd-with-or-dep.
149   move 123.55 to fd-amount.
150   write fd-finfile-record.
151
152 end program writefil.
Parent topic: External Files


File Handler

  • Example Configuration File
  • Example of Creating a New Index File
  • Example of Accessing the FCD
  • Example of Setting Up the Record Area
  • Example of Setting up the Filename Area
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
External Files
File Names
File Status
Indexed Files
Locking Files and Records
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 information
Example of Creating a New Index File
Example of Accessing the FCD
Example of Setting Up the Record Area
Example of Setting up the Filename Area


Example of Creating a New Index File

 78 close-file   value x"fa80"
 78 open-new-index  value x"0007".
 78 get-next-rec  value x"0008".
 78 add-key-value  value x"0009".
  ...

     move open-new-index to fh-opcode
     perform extfh-op
     move get-next-rec to fh-opcode
     perform extfh-op
     perform until fcd-status (1:1) not = "0"
         perform varying fcd-key-id from 0 by 1
                 until fcd-key-id = key-count
                    or fcd-status (1:1) not = "0"
             move add-key-value to fh-opcode
             perform extfh-op
         end-perform
         move get-next-rec to fh-opcode
         perform extfh-op
     end-perform
     move close-file to fh-opcode
     perform extfh-op
       ...

 extfh-op.
     call "EXTFH" using fh-opcode, fcd
     if fcd-status of fcd (1:1) = "1"
         move 1 to return-code
     end-if.
Parent topic: File Handler
Related information
Example Configuration File
Example of Accessing the FCD
Example of Setting Up the Record Area
Example of Setting up the Filename Area


Example of Accessing the FCD

The following program turns on key compression in a file by setting the appropriate bits in the file's Key Definition Block.

$set fcdreg
 select masterfile
     assign to ...
     organization is indexed
     record key is rec-key
     alternate key is m-alt-key-1 with duplicates
     alternate key is m-alt-key-2
     alternate key is m-alt-key-3 with duplicates.

 select indexfile
     assign to ...
     organization is indexed
     record key is rec-key
     alternate key is t-alt-key-1 with duplicates.
 ...
 working-storage section.
 ...
 linkage section.
 01 key-def-block.
     03 filler     pic x(6).
     03 key-count    pic 9(4) comp-x.
     03 filler     pic x(6).
     03 key-def occurs 1 to 4 times depending on key-count.
         05 filler    pic x(5).
         05 key-compression pic 9(2) comp-x.
         05 filler    pic x(10).
   ...
 procedure division.
     set address of key-def-block to address of fh--keydef of masterfile
     move 6 to key-compression (1)
     move 7 to key-compression (2)
     move 6 to key-compression (3)
     move 7 to key-compression (4)
     open I-O masterfile
     ...
     set address of key-def-block to address of fh--keydef of indexfile
     move 4 to key-compression (1)
     move 1 to key-compression (2)
     open input indexfile
Parent topic: File Handler
Related information
Example Configuration File
Example of Creating a New Index File
Example of Setting Up the Record Area
Example of Setting up the Filename Area


Example of Setting Up the Record Area

The following example shows how the FCD is set up to point to the record area:

 01 RECORD-AREA   PIC X(85).
...
     SET FCD-RECORD-ADDRESS TO ADDRESS OF RECORD-AREA
   ...
Parent topic: File Handler
Related information
Example Configuration File
Example of Creating a New Index File
Example of Accessing the FCD
Example of Setting up the Filename Area


Example of Setting up the Filename Area

The following example shows how the FCD is set up to point to the filename area:

 01 FILENAME-AREA PIC X(65) VALUE "master.dat".
...
     SET FCD-FILENAME-ADDRESS TO ADDRESS OF FILENAME-AREA
   ...
Parent topic: File Handler
Related information
Example Configuration File
Example of Creating a New Index File
Example of Accessing the FCD
Example of Setting Up the Record Area


File Names

  • Examples of static filename assignment
  • Example of dynamic filename assignment
  • Example of external filename assignment
  • Examples of device name assignment
  • Example of Forced Filename Mapping
  • Example of Connecting a File to Standard Output
  • Example of Connecting a File to Standard Input
  • Example of Setting up a Two-way Pipe
  • Example of using the External File Mapper
  • Example of Specifying a Fileshare Client User ID and Password
  • Example Fileshare Client Configuration File
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
External Files
File Handler
File Status
Indexed Files
Locking Files and Records
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 command to relate envvar to the physical filename you want to use:

set envvar=c:\test.dat

At run-time, the filename fd-name is assigned to the file test.dat in the root directory on the c: drive.

Parent topic: File Names
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 . If this is not found, the system searches for the environment variable . 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(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: File Names
Related information
Examples of static filename assignment
Example of dynamic filename assignment
Example of external filename assignment
Examples of device name assignment
Example of Forced Filename Mapping
Example of Connecting a File to Standard Output
Example of Connecting a File to Standard Input
Example of Setting up a Two-way Pipe
Example of using the External File Mapper
Example Fileshare Client Configuration File


Example Fileshare Client Configuration File

/s server1
/s server2
/f \orders\* /s server3
/f \accounts\payroll.dat
/f \transport\delivery\*

This example configuration file specifies that server1 and server2 are the default Fileshare Servers. This means that these Fileshare Servers will be searched, in this order, for any file which is not specified as either a local file or as located on a specific Fileshare Server. It also specifies that any files with a filename beginning orders\ are located on server3, that the file accounts\payroll.dat is a local file and that any file with a filename beginning transport\delivery\ is a local file.

Parent topic: File Names
Related information
Examples of static filename assignment
Example of dynamic filename assignment
Example of external filename assignment
Examples of device name assignment
Example of Forced Filename Mapping
Example of Connecting a File to Standard Output
Example of Connecting a File to Standard Input
Example of Setting up a Two-way Pipe
Example of using the External File Mapper
Example of Specifying a Fileshare Client User ID and Password


File Status

  • Example of Displaying File Status Codes
  • Example of Checking File Status Codes
  • Example of Extended File Status Codes
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
External Files
File Handler
File Names
Indexed Files
Locking Files and Records
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 information
Example of Displaying File Status Codes
Example of Checking File Status Codes


Indexed Files

  • Example of Indexed File Definition
  • Example of Primary Key Definition
  • Example of Alternate Key Definition
  • Example of Duplicate Key Definition
  • Example of Sparse Key Definition
  • Example of Indexed File Access Definition
  • Example of Creating Fixed-length Records
  • Example of Creating Variable Length Records
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
External Files
File Handler
File Names
File Status
Locking Files and Records
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


Locking Files and Records

  • Example of Locking a File
  • Examples of Manual Record Locking
  • Examples of Automatic Record Locking
  • Examples of Single Record Locking
  • Examples of Multiple Record Locking
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 of Locking a File

To lock a file:

 select fd-name
     assign to "muser.dat"
     lock mode is exclusive.
Parent topic: Locking Files and Records
Related information
Examples of Manual Record Locking
Examples of Automatic Record Locking
Examples of Single Record Locking
Examples of Multiple Record Locking


Examples of Manual Record Locking

To manually lock a single record:

 select fd-name
     assign to "muser.dat"
     lock mode is manual.
  ...
     read fd-name with lock

To manually lock multiple records:

 select fd-name
     assign to "muser.dat"
     lock mode is manual with lock on multiple records.
  ...
     read fd-name with kept lock
Parent topic: Locking Files and Records
Related information
Example of Locking a File
Examples of Automatic Record Locking
Examples of Single Record Locking
Examples of Multiple Record Locking


Examples of Automatic Record Locking

To specify automatic single record locking:

 select fd-name
     assign to "muser.dat"
     lock mode is automatic.
  ...
     read fd-name

To specify automatic multiple record locking:

 select fd-name
     assign to "muser.dat"
     lock mode is automatic with lock on multiple records.
  ...
     read fd-name
Parent topic: Locking Files and Records
Related information
Example of Locking a File
Examples of Manual Record Locking
Examples of Single Record Locking
Examples of Multiple Record Locking


Examples of Single Record Locking

To lock a single record, using manual record locking:

 select fd-name
     assign to "muser.dat"
     lock mode is manual.
  ...
     read fd-name with lock

To lock a single record, using automatic record locking:

 select fd-name
     assign to "muser.dat"
     lock mode is automatic.
  ...
     read fd-name
Parent topic: Locking Files and Records
Related information
Example of Locking a File
Examples of Manual Record Locking
Examples of Automatic Record Locking
Examples of Multiple Record Locking


Examples of Multiple Record Locking

To lock multiple records, using manual record locking:

 select fd-name
     assign to "muser.dat"
     lock mode is manual with lock on multiple records.
  ...
     read fd-name with kept lock

To lock multiple records, using automatic record locking:

 select fd-name
     assign to "muser.dat"
     lock mode is automatic with lock on multiple records.
  ...
     read fd-name
Parent topic: Locking Files and Records
Related information
Example of Locking a File
Examples of Manual Record Locking
Examples of Automatic Record Locking
Examples of Single Record Locking


MFSORT

  • Example Mfsort Command Line
  • Example Mfsort Fields Instruction
  • Example Mfsort Key Instruction
  • Example Mfsort Instruction File
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
External Files
File Handler
File Names
File Status
Indexed Files
Locking Files and Records
Rebuild
Example Relative File Definition
Sequential Files


Example Mfsort Command Line

The following example shows the Mfsort command to sort four files:

mfsort use file1 record (v,4,8) use file2 use file3 use file4 give file5 sort fields (1, 1, s5, a, 2, 1, c5, d)
Parent topic: MFSORT
Related information
Example Mfsort Fields Instruction
Example Mfsort Key Instruction
Example Mfsort Instruction File


Example Mfsort Fields Instruction

The following example sorts the file on a 6-byte alphanumeric field which starts at the second byte of the record, in ascending order, with a secondary ordering on a 4-byte (PIC 9(8))COMP field starting at the tenth byte of the record, in descending order.

mfsort sort fields (2, 6, ch, a, 10, 4, bi, d)
Parent topic: MFSORT
Related information
Example Mfsort Command Line
Example Mfsort Key Instruction
Example Mfsort Instruction File


Example Mfsort Key Instruction

The following example defines three keys:

key (4,5,p,10,5,c,20,2,ad,40,2,a,46,10,c)

The first key, the primary key, is split with its first component starting at character position 4 with a length of 5 bytes and its second component starting at character position 10 with a length of 5 bytes.

The second key (alternate key) enables duplicates, starts at character position 20 and is 2 bytes in length.

The third key is a split alternate key, with the first component starting at character position 40 with a length of 2 bytes and the second component starting at character position 46 and with a length of 10 bytes.

Parent topic: MFSORT
Related information
Example Mfsort Command Line
Example Mfsort Fields Instruction
Example Mfsort Instruction File


Example Mfsort Instruction File

The following is an example Mfsort instruction file, called sample.srt:

use file1 record (v,4,8)
use file2
use file3
use file4
give file5
merge fields (1,1,S5,a,2,1,c5,d)

Note that ORG is not needed here as SQ is the default, and that file2 through file5 and the merge workfile use the RECORD format specified for file1.

This instruction file would be used as follows:

mfsort take sample.srt
Parent topic: MFSORT
Related information
Example Mfsort Command Line
Example Mfsort Fields Instruction
Example Mfsort Key Instruction


Rebuild

  • Example of Reorganizing an Indexed File
  • Example of recovering a corrupt indexed file
  • Example of using Rebuild to convert a file
  • Example of validating the structure of an indexed file
  • Example of a Rebuild options file
  • Example of calling Rebuild from a COBOL program
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
External Files
File Handler
File Names
File Status
Indexed Files
Locking Files and Records
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
Example of Data and Key Compression
External Files
File Handler
File Names
File Status
Indexed Files
Locking Files and Records
MFSORT
Rebuild
Sequential Files


Sequential Files

  • Example Record Sequential File Definition - Fixed-length Records
  • Example Record Sequential File Definition - Variable Length Records
  • Example Line Sequential File Definition
  • Example Printer Sequential File Definition
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
External Files
File Handler
File Names
File Status
Indexed Files
Locking Files and Records
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
    This chapter provides an overview of file handling.
  • 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
  • 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.
  • Mfsort Utility
    This chapter describes how to use the mfsort facility.
  • 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
    This chapter describes how to use the facilities provided for tracing file operations, which are provided to help in investigations into problems with file handling.
Parent topic: File Handling
Related information
File Handling Examples
Working with Data Files
File Systems
Fileshare Guide


Introduction

This chapter provides an overview of file handling.

  • Overview
  • 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
Mfsort Utility
Data and Key Compression
Tracing File Operations


Overview

One of the main facilities that COBOL has to offer as a programming language is its built-in file handling capabilities. Files of sequential, relative and indexed organization can be handled using simple COBOL syntax.

In addition, Micro Focus COBOL offers the following 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

This chapter describes the file organizations supported by your COBOL system.

  • 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
Mfsort Utility
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, 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" - record present

x"0D00" - 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 information
Overview
Sequential Files
Relative Files
Fixed-length and Variable-length Records
File Headers
Rebuild


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

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.

  • Filename Conventions
  • Assigning Filenames
  • Filename Mapping
  • Assigning Device Names
  • Setting Up Pipes
Parent topic: File Handling Guide
Related information
Introduction
File Organizations
File Status
Sharing Files
File Handler Configuration
File Handler and Sort APIs
Mfsort Utility
Data and Key Compression
Tracing File Operations


Filename Conventions

This COBOL system, and applications created with it, use the standard filename conventions of the operating system on which it runs.

This COBOL system also supports the New Technology File System (NTFS) file naming conventions. This means that each file or directory can consist of up to 254 characters and contain both space characters, other special characters and 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 may remove it when creating its own names.

If you are thinking of using the new file naming conventions, you should be aware of the following:

  • Avoid using the following characters when you are creating Internet applications: % # ( ) @.
  • The Oracle 1.8 version of Pro*Cobol does not support filenames that contain spaces.
Parent topic: Filenames
Related information
Assigning Filenames
Filename Mapping
Assigning Device Names
Setting Up Pipes


Assigning Filenames

The ASSIGN clause in the SELECT clause is used to specify either a physical filename or a logical name which can be mapped to a physical name at run time.

There are three types of filename assignment:

  • STATIC

    The filename is specified as a literal in the ASSIGN clause

  • DYNAMIC

    The filename is specified as a data-item in the ASSIGN clause, and so can be changed by the program at run time

  • EXTERNAL

    The filename is specified as EXTERNAL in the ASSIGN clause and is resolved at run time

Run-time mapping of filenames is available for all three types of filename assignment.

  • Static Filename Assignment
  • Dynamic Filename Assignment
  • External Filename Assignment
Parent topic: Filenames
Related information
Filename Conventions
Filename Mapping
Assigning Device Names
Setting Up Pipes


Static Filename Assignment

With static filename assignment, the filename is specified in the SELECT clause as a literal:

 select filename
     assign to literal.

If the filename of the physical file that you are creating contains spaces, the filename is automatically surrounded by quotes for you.

In the following example, opening stockfile causes the file warehs.buy in the current directory on the b: drive to be opened:

 select stockfile
     assign to "b:warehs.buy".

In this example, a WRITE statement causes data to be output to prn:, the first parallel printer:

 select printfile
     assign to "prn:".

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

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

For further details on run-time system filename mapping, see the section Filename Mapping.

Parent topic: Assigning Filenames
Related information
Static Filename Assignment
Dynamic Filename Assignment
Filename Mapping


Filename Mapping

This COBOL system provides several ways of mapping the filename supplied by the program via the ASSIGN clause onto a different name, for greater flexibility at run time. These rely on the use of environment variables.

Before you run the program, you should give any environment variables you are using an appropriate value using the operating system SET command, for example:

set dir=d2

When presented with a filename (which may be a literal, the contents of a data item, or, in the case of the ASSIGN TO EXTERNAL syntax, an external reference), the File Handler follows this procedure:

  1. Isolates the first element of the filename, that is, all the text before the first slash character (\), all the text if the name does not include such a character or nothing if the filename starts with a slash character.
  2. If the first element begins with two dollar characters ($$), indicating that the file is located on a Fileshare server, switches the search process to that Fileshare server, and continues the filename mapping process with the next element.
  3. Removes the leading dollar character ($) if it is present, prefixes the characters "dd_" to this first element and searches for an environment variable with this name.
  4. If it does not find this environment variable and either the ASSIGN EXTERNAL syntax was used or the element began with a dollar character, looks for an environment variable with the same name as the element (minus the leading dollar character if present).
  5. If the search is unsuccessful, leaves the element unchanged, except in the case where the element begins with a dollar character and the whole filename contains at least one slash character. In this case, the whole of the first element, together with the first slash, is removed from the name.

This procedure is then repeated for the next element in the filename, and continues until all the elements in the name have been processed. The result is then considered to be the filename of the physical file.

Consider the following examples:

Filename in ASSIGN Clause | Environment Variables Searched For | Contents of Environment Variable | Filename of Physical File
dir\file1 | dd_dir | d2 | d2\file1
$dir\file1 | dd_dir;dir | d2\d4 | d2\d4\file1
dir1\dir2\file1 | dd_dir1 | d4 | d4\dir2\file1
$dir1\$dir2\file1 | First iteration: dd_dir1;dir1 Second iteration: dd_dir2;dir2 | dd_dir1 or dir1: d2\d4 dd_dir2 or dir2: d3 | d2\d4\d3\file1
file1 | dd_file1 | d2 | d2

  • Multiple Paths
Parent topic: Filenames
Related concepts
Printer Output is Written to Disk
Related information
Filename Conventions
Assigning Filenames
Assigning Device Names
Setting Up Pipes
External Filename Assignment


Multiple Paths

An environment variable used for filename mapping can specify multiple pathnames. This causes the system to search for subsequent files if a "file not found" condition is returned for the first path specified by the environment variable.

Consider the following example contents of an environment variable named dd_dir.

dd_dir=\a\b;\c\d;
This causes the system to search \c\d for the assigned file if a "file not found" condition is returned on \a\b.
Note:
  • If an existing file is being opened, using OPEN INPUT, OPEN I-O, OPEN EXTEND or the CBL_OPEN_FILE byte stream routine, the environment variable is expanded to the first path on which the file is found.
  • If a new file is being created, using OPEN OUTPUT, OPEN I-O, OPEN EXTEND, or the CBL_CREATE_FILE byte stream routine, the environment variable is expanded to the first path named. For files which are opened with OPEN OUTPUT, you can override this behavior by setting the SEARCHONCREATE File Handler configuration option to ON.
  • The length of each path in a path list in an environment variable must be less than or equal to the permitted maximum number of characters for a path.
Parent topic: Filename Mapping


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
Filename Mapping
Setting Up Pipes


Setting Up Pipes

You can use COBOL file syntax to launch another process (such as the dir command) and either write data to the standard input of that other process or read data coming from the standard output of the other process. The COBOL file organization must be either LINE SEQUENTIAL or RECORD SEQUENTIAL.

  • Output Pipes
  • Input Pipes
  • Two-way Pipes
Parent topic: Filenames
Related information
Filename Conventions
Assigning Filenames
Filename Mapping
Assigning Device Names


Output Pipes

To launch a process and write data to its standard input, the filename must consist of the > sign followed by the name of the command. The file should be opened for output.

For example:

 select output-file
     assign to ">cmd /c sort"
     organization is line sequential.
 fd output-file.
 01 output-file-record pic x(10).
 procedure division.
     open output output-file
     write output-file-record from "Charles"
     write output-file-record from "Bill"
     write output-file-record from "Alan"
     close output-file.
Parent topic: Setting Up Pipes
Related information
Input Pipes
Two-way Pipes


Input Pipes

To launch a process and read data from its standard output, the filename must consist of the < sign followed by the name of the command. The file should be opened for input.

For example:

 select input-file
     assign to "<cmd /c dir"
     organization is line sequential.
  ...
     open input input-file
     read input-file

In this example the program launches the dir process and reads in the first line that it writes to its standard output.

Parent topic: Setting Up Pipes
Related information
Output Pipes
Two-way Pipes


Two-way Pipes

Two-way pipes combine the functions of input and output pipes. To use a two-way pipe, the filename must consist of the pipe symbol (|) followed by the name of the command. The file should be opened for input-output i-o.

For example:

 select i-o-file
     assign to "| cmd /c sort"
     organization is line sequential.
 fd i-o-file.
 01 i-o-file-record pic x(20).
 procedure division.
     open i-o i-o-file
     write i-o-file-record from "Hello world"
     write i-o-file-record from all "A"
     write i-o-file-record from all "Z"
     write i-o-file-record from x"1a"
     perform until exit
         read i-o-file
          at end
             exit perform
         end-read
         display i-o-file-record
     end-perform
     close i-o-file

In this example, the program launches the sort process and passes it three lines of text, followed by an end-of-file marker. The program then reads all three lines back from the standard output of the sort process.

Parent topic: Setting Up Pipes
Related information
Output Pipes
Input Pipes


File Status

File status codes are used by this COBOL system to indicate the success, or otherwise, of any file operation carried out by your program.

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
Mfsort Utility
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
  • Ryan MacFarland 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=
    Ryan MacFarland 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. If creating a linked application, link an object into the application. The object that you link depends upon the compiler:
    Compiler | Object
    Ryan MacFarland COBOL | rmstat.obj
    IBM Mainframe COBOL | hoststat.obj
    Microsoft COBOL V2 | msstat.obj
  3. 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".

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
Extended File Status Codes
Related information
What is File Status?
Defining a File Status Data Item
File Status Conventions


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.

  • 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
Mfsort Utility
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 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 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

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.

  • Configuration File
  • Configuration Options
  • Configurable Behavior
Parent topic: File Handling Guide
Related information
Introduction
File Organizations
Filenames
File Status
Sharing Files
File Handler and Sort APIs
Mfsort Utility
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:

set EXTFH=c:\mydir\test.cfg
sets the filename to c:\mydir\test.cfg.

The File Handler configuration file enables you to alter File Handler parameters for individual files or all files. Settings which apply to all files are listed under the tag:

[XFH-DEFAULT]

Two further tags are available to use within [XFH-DEFAULT] or instead of it. Settings which apply to all indexed files or all sequential files are listed under these tags:

[IDX-DEFAULT] and [SEQ-DEFAULT]

While settings which apply to an individual file are listed under the individual filename, for example:

[TEST.DAT]
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]

The settings for an individual file override the global settings. If you just specify the filename, it must be the resolved filename, that is, the filename that the File Handler uses after it has completed its filename mapping process. Alternatively, you can prefix the filename with the keyword INTERNAL, to signify that the filename is the name that is used in the SELECT clause; the settings will then be applied to the file that is identified at the conclusion of the filename mapping process. For example, if the ASSIGN mode is dynamic, and you code:

[INTERNAL:$myfile\outfile.dat]
IDXFORMAT=8

where myfile is an environment variable holding the name of the directory where the folder is located, the settings will be applied to outfile.dat in that directory.

If the ASSIGN mode is external, and you had:

SELECT MYDATA ASSIGN TO EXTERNAL REALDATA

you could code:

[INTERNAL:REALDATA]

where any options which follow apply to the file to which the logical name "REALDATA" is mapped.

If, however, you have:

    SELECT MYDATA ASSIGN TO '\directory\subdirectory\datadirectory\myfile'

you cannot use the INTERNAL option in extfh.cfg. The literal value in the SELECT statement must be replicated [inside square brackets] in extfh.cfg.

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: File Handler Configuration
Related reference
Filename Mapping
Related information
Configuration Options
Configurable Behavior


Configuration Options

The following table lists the options that you can set via the File Handler configuration file.

ASCIIMAINFRAMEPRINT | Specifies whether to use ASCII printer control characters when CHARSET is set to ASCII.
BASENAME | Specifies whether filenames specified in tags can be expressed without the pathname.
CBL_CFGREAD_DYNFH | Forces the File Handler to reread its configuration file for configurable customer file handlers when DYNREDIR is set to DYNCONFIG.
COMMITFLUSH | In the context of a program that is not using FILESHARE, specifies whether the COMMIT and ROLLBACK statements cause all file updates to be flushed to disk, as well as releasing record locks.
CONCATNAME | Specifies whether filenames including the plus character ("+") are to be interpreted as normal filenames or as file concatenations.
CONVERTDBSPACE | Enables the conversion of double-byte character set (DBCS) spaces to ASCII spaces when reading a line sequential file.
CONVERTEUCKATAKANA | Enables conversion of EUC single-width double-byte characters to their double-width Katakana equivalents when reading a line sequential file.
CONVERTSTATUS | 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 | Specifies whether data compression is in effect and the type of compression.
DATAFILE | Maps the file name, passed to an OPEN statement, onto another name.
EXPANDPOSITIONING | When using the WRITE AFTER POSITIONING statement (OS/VS COBOL compatibility), determines whether the written record includes carriage control information.
EXPANDTAB | Determines whether to expand TAB characters, encountered in line sequential or line advancing files during a READ operation, into the equivalent number of spaces.
FASTREAD | When reading an indexed file, specifies whether or not the File Handler performs extra checking to ensure data integrity.
FHREDIR | Specifies whether files can be handled by a remote server using Fileshare.
FILEMAXSIZE | Specifies the size in bytes for holding offsets used in locking calls, allowing access to very large files.
FILEPOINTERSIZE | For format 8 indexed files, specifies the length in bytes to use to store file pointers.
FSIDXINTEGRITY | Writes to disk any changed nodes held within the File Handlers index cache, before returning status information to the client program.
IDXDATBUF | Determines the size of buffer used when accessing the data portion of a file with organization INDEXED. This option replaces DATACACHE, which is no longer supported.
IDXFORMAT | Specifies the format to use when creating indexed files.
IDXNAMETYPE | Specifies the format of the filename type for both the data file and, if present, the index file.
IGNORELOCK | Specifies whether to ignore locks when reading files open for input.
INDEXCOUNT | Specifies the number of index nodes to be cached for an indexed file. This option replaces INDEXCACHE, which is no longer supported.
INDEXFILE | Maps the name of the index file (for those indexed file formats that have a separate index file).
INSERTNULL | When performing WRITE or REWRITE operations on line sequential or line advancing files, determines whether to insert NULL (x"00") characters before non-printable characters. 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, determines whether to replace TAB characters with sequences of spaces
KEYCHECK | Specifies whether the File Handler checks that the key definition defined in your application matches that of the indexed file you are opening
KEYCOMPRESS | Specifies the type of key compression in use
LOADONTOHEAP | Specifies whether the file handler loads the file into memory before executing any I/O operations.
LOCKTYPE | Specifies the type of record locking in use.
LOG | Specifies whether 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, specifies the name of the logfile to produce.
LSFILETERM | Controls the behaviour of the File Handler upon encountering the EOF character x"1a" when reading line sequential files.
LSRECDELIM | Specifies the characters used as the record delimiter in line sequential files.
MAINFRAMEPRINT | For those files using WRITE AFTER ADVANCING or WRITE BEFORE ADVANCING, determines whether to use mainframe printer format (filetype(11)).
NAMEOPTIONS | Specifies whether the name you pass to the OPEN statement can contain file handler directives enclosed in square brackets.
NFSFILELOCK |
NODESIZE | Specifies the size of the index nodes to use for an indexed file.
NOSEQCHECK | When an indexed file with ACCESS SEQUENTIAL is opened for OUTPUT or EXTEND, specifies whether a check is made that the primary key of each new record written is greater than that of any previous key.
OPENINPUTSHARED | 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 | 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 | 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 | 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.
RELDATBUF | Determines the size of buffer used when accessing a file with organization RELATIVE.
RELRECDELIM | Determines the characters used as the record delimiter in fixed length relative files.
RETRYLOCK | When an operation attempts to access locked records, indicates whether you wish to retry the operation.
RETRYOPEN | When an operation attempts to access locked files, indicates whether you wish to retry the operation.
RETRYTIME | Specifies whether the integer given in the RETRYLOCK or the RETRYOPEN parameter specifies the number of attempts or the number of seconds.
RUNITLOCKDETECT | Specifies whether you can detect that a record has been locked by a separate OPEN statement issued from within the same run unit.
SEARCHONCREATE | 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.
SEQDATBUF | Determines the size of buffer to use when accessing a file with organization SEQUENTIAL. This option replaces DATACACHE, which is no longer supported.
SKIPLOCK | When a locked record is encountered during a sequential READ, specifies whether to advance the current record pointer.
SPACEFILL | When performing READ operations on line sequential or line advancing files, determines whether to fill with spaces that part of the record area beyond the data that is read.
STARTUNLOCK | 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 | When performing WRITE or REWRITE operations on line sequential or line advancing files, determines whether to remove trailing space characters.
SUPPRESSADV | For record sequential files, determines whether to ignore the ADVANCING phrase of the WRITE statement.
TRACE | Specifies whether Xfhtrace is enabled.
TRACEFILEEXTEND | Affects the functioning of File Handler tracing.
TRACEFILENAME | When the TRACE option is active, specifies the name of the trace file to produce.
USEVSAMKEYDEFS | When set to ON, specifies to use the keys defined in the catalog via the JCL and IDCAMS instead of the keys defined in the executing program.
WRITELINE | Determines whether mainframe or PC behavior is used for WRITE record.
WRITETHRU | Determines whether to write file modifications out to disk immediately. Alternatively, the modifications may be buffered internally, either by the COBOL system or by the operating system, and flushed to disk at a later stage.
CAUTION:

The FILEMAXSIZE option specifies the number of bytes used internally to store file offsets. This also affects internal 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.

The FILEMAXSIZE option defaults to 4, limiting file addressability to 32 bit values which is compatible with earlier versions of Micro Focus systems. The other setting for the FILEMAXSIZE option is 8, which 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.

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

See the appendix File Systems for more information on 64-bit and 32-bit file systems.

For an example configuration file see the topic Example Configuration File.

Parent topic: File Handler Configuration
Related reference
ASCIIMAINFRAMEPRINT
BASENAME
COMMITFLUSH
CONCATNAME
CONVERTDBSPACE
CONVERTEUCKATAKANA
CONVERTSTATUS
DATACOMPRESS
DATAFILE
EXPANDPOSITIONING
EXPANDTAB
FASTREAD
FHREDIR
FILEMAXSIZE
FILEPOINTERSIZE
FSIDXINTEGRITY
IDXDATBUF
IDXFORMAT
IDXNAMETYPE
IGNORELOCK
INDEXCOUNT
INDEXFILE
INSERTNULL
INSERTTAB
KEYCHECK
KEYCOMPRESS
LOADONTOHEAP
LOCKTYPE
LOG
LOGFILENAME
LSFILETERM
LSRECDELIM
MAINFRAMEPRINT
NAMEOPTIONS
NODESIZE
NOSEQCHECK
OPENINPUTSHARED
OSVSREWRITE
READSEMA
READTODELIM
RELDATBUF
RELRECDELIM
RETRYLOCK
RETRYOPEN
RETRYTIME
RUNITLOCKDETECT
SEARCHONCREATE
SEQDATBUF
SKIPLOCK
SPACEFILL
STARTUNLOCK
STRIPSPACE
SUPPRESSADV
TRACE
TRACEFILEEXTEND
TRACEFILENAME
WRITELINE
WRITETHRU
File Handler Configuration Options - Overview
Example Configuration File
Related information
Configuration File
Configurable Behavior


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
  • Performance
Parent topic: File Handler Configuration
Related information
Configuration File
Configuration Options


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, a striping option is provided. Striping splits a large logical file into as many physical files as are required (up to a limit of 256).

Parent topic: Configurable Behavior
Related information
File Striping
Performance


File Striping

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.

You can enable striping for a particular file by setting the STRIPING=ON option for that file in the File Handler configuration file.

  • Headers in Striped Files
  • Options
  • Examples
Parent topic: Configurable Behavior
Related information
Large Indexed Files
Performance


Headers in Striped Files

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
Related information
Options
Examples


Options

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
    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
    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
    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
    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
    This option specifies the file naming convention used to name the stripes. The default setting is 0.
  • STRIPING
    Specifies whether a file is a striped file. The default setting is OFF.
Parent topic: File Striping
Related information
Headers in Striped Files
Examples


MAXSTRIPEDIGITS

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.

Syntax:

MAXSTRIPEDIGITS=n
Parent topic: Options
Related reference
MAXSTRIPEFILES
MAXSTRIPESIZE
STRIPE-X
STRIPENAMETYPE
STRIPING


MAXSTRIPEFILES

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.

Syntax:

MAXSTRIPEFILES=n
Parent topic: Options
Related reference
MAXSTRIPEDIGITS
MAXSTRIPESIZE
STRIPE-X
STRIPENAMETYPE
STRIPING


MAXSTRIPESIZE

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

Syntax:

MAXSTRIPESIZE=n
Parent topic: Options
Related reference
MAXSTRIPEDIGITS
MAXSTRIPEFILES
STRIPE-X
STRIPENAMETYPE
STRIPING


STRIPE-X

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.

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
Related reference
MAXSTRIPEDIGITS
MAXSTRIPEFILES
MAXSTRIPESIZE
STRIPENAMETYPE
STRIPING


STRIPENAMETYPE

This option specifies the file naming convention used to name the stripes. The default setting is 0.

Syntax:

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
Related reference
MAXSTRIPEDIGITS
MAXSTRIPEFILES
MAXSTRIPESIZE
STRIPE-X
STRIPING


STRIPING

Specifies whether a file is a striped file. The default setting is OFF.

Syntax:

STRIPING=[ON/OFF]
Parent topic: Options
Related reference
MAXSTRIPEDIGITS
MAXSTRIPEFILES
MAXSTRIPESIZE
STRIPE-X
STRIPENAMETYPE


Examples

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
Related information
Headers in Striped Files
Options


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


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.

  • Calling the File Handler
  • Sort Module
Parent topic: File Handling Guide
Related information
Introduction
File Organizations
Filenames
File Status
Sharing Files
File Handler Configuration
Mfsort Utility
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
  • 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
Parent topic: Calling the File Handler
Related information
Data Structures
Accessing the FCD
Operation Codes
Relative Byte Addressing
Creating Your Own File Handler
Dynamic Redirection to a Custom File Handler
Creating a New Index File
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
Compression Routines


File Control Description (FCD)

The File Control Description (FCD) is a data area which contains information about the file in use. There are two versions of the FCD, and which one is used depends on whether your COBOL development environment is running in 32-bit or 64-bit, as shown in the following table:

COBOL Development System | FCD Used
Visual COBOL | FCD3
Mainframe Express | FCD2
32-bit Visual COBOL | FCD3
64-bit Visual COBOL | FCD3
.NET Support within Visual COBOL | FCD3
32-bit Server Express | FCD2 or FCD3
64-bit Server Express | FCD3

Both FCD2 and FCD3 format can be used in 32-bit compilations. The copybook XFHFCD.CPY defines an FCD3 record unless the program is compiled with the Compiler directive NOFCD3. If the program is compiled with the NOFCD3 directive XFHFCD.CPY defines an FCD2 record. The FCD3 record is directly and unconditionally defined in the file xfhfcd3.cpy and the FCD2 record is directly and unconditionally defined in the file xfhfcd2.cpy.

To use the File Handler your program must set up an FCD, complete the appropriate fields (these vary according to the operation code) and then call the File Handler. The File Handler returns information to your program by writing it to the appropriate fields in the FCD.

All unused or reserved areas of the FCD must be set to binary zeros.

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:

Parameter | Description
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:

Parameter | Description
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
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
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
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
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
Compression Routines


Redirection Using Configurable DYNREDIR

When configured in this way, files are mapped to file handlers using the fhredir.cfgfile. If custom file handlers are not present, an XFHLOG entry will be emitted and the Micro Focus File Handler will be invoked instead. Up to three different custom file handlers can be used at any given time.

Parent topic: Dynamic Redirection to a Custom File Handler
Related information
Specifying a List of Custom File Handlers
Specifying Configurable Custom File Handlers
Writing a Custom File Handler
Restrictions


Specifying a List of Custom File Handlers

To specify your a list of custom file handlers, you use the DYNREDIR environment variable, as shown below:

set DYNREDIR=mod1!ep1[:mod2!ep2[:mod3!ep3]]

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 module1.dll file
  • userfh2
  • userfh3 in the module3.dll file

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


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

Parameter | Description
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: File Handler and Sort APIs
Related reference
Sort Module Function Codes
Sort File Control Description
Related information
Calling the File Handler


Mfsort Utility

This chapter describes how to use the mfsort facility.

  • Introduction
  • Invoking Mfsort
  • Creating a Statistics Report
  • Example Commands
  • Error Messages
Parent topic: File Handling Guide
Related information
Introduction
File Organizations
Filenames
File Status
Sharing Files
File Handler Configuration
File Handler and Sort APIs
Data and Key Compression
Tracing File Operations


Introduction

This COBOL system provides the following methods of sorting and merging files:

Sorting Method | Description
The run-time system COBOL sort module | The default module that executes a SORT statement in your COBOL program. It can also be called directly using the CALL statement.
MFSORT utility | A utility that you can invoke from the command line, which enables you to sort and merge data files.
MFJSORT utility | An emulator of IBM’s DFSORT and ICETOOL utilities and SYNCSORT, which supports many of their major functions .
Note: MFJSORT and MFSORT are updated with new features on a regular basis but they do not offer a complete emulation of third-party sort utilities. If there are particular features that you need to use, please contact SupportLine to establish if they are available in MFJSORT or MFSORT.
Parent topic: Mfsort Utility
Related information
Invoking Mfsort
Creating a Statistics Report
Example Commands
Error Messages
Sort Module


Invoking Mfsort

You can invoke mfsort from the command line in one of the following ways:

mfsort instructions
mfsort take filename

where the parameters are:

Parameter | Description
instructions | Mfsort instructions. When specifying instructions on the command line, remember to observe the maximum command line length imposed by the operating system.
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 of up to 256 characters. If you exceed this, instructions will be split into several records and errors will occur.
  • Instructions
Parent topic: Mfsort Utility
Related information
Introduction
Creating a Statistics Report
Example Commands
Error Messages
Instructions


Instructions

The following is a list of valid mfsort instructions:

Instruction | Meaning
* | The rest of the line is treated as a comment. This is useful if you are supplying instructions via a text file as you can add comments to the file which explain the purpose of each instruction.
CHAR-EBCDIC | EBCDIC data. CHAR-EBCDIC must precede all SORT, MERGE, USE or GIVE instructions.
SIGN-EBCDIC | Numeric DISPLAY items with included signs are interpreted according to the EBCDIC convention. SIGN-EBCDIC is not required when CHAR-EBCDIC is specified; it is required for data that is otherwise ASCII, such as when the program which created the data was compiled with the SIGN"EBCDIC" Compiler directive. SIGN-EBCDIC must precede all SORT, MERGE, USE or GIVE instructions.
SORT-EBCDIC | Record-sequential ASCII files are sorted in EBCDIC order. Important: SORT-EBCDIC cannot sort files that have keys containing non-printable characters.
SORT/MERGE | These instructions specify either a sort or a merge option and must be followed by a FIELDS instruction specifying the field(s) to be used. The FIELDS instruction may optionally be followed by a RECORD instruction specifying the record size and format of the workfile. SORT and MERGE are mutually exclusive.
FIELDS (instructions) | The fields on which the file is to be sorted or merged. See the section Fields Instruction.
RECORD definition | Record size and format. A RECORD instruction can be used to specify these details for the workfile, input file(s) and output file(s). See the section RECORD Instruction.
USE input-file | Each USE instruction specifies an input file. You must specify all USE instructions before any GIVE instructions. See the section Defining Input and Output Files.
GIVE output-file | Each GIVE instruction specifies an output file. See the section Defining Input and Output Files.
INCLUDE/OMIT | Specifies conditions in which records will be included or omitted from the sort process. For details, see the IBM documentation to be found at . INCLUDE and OMIT are mutually exclusive.
INREC | Reformats records before the SORT/MERGE process.
OUTREC | Reformats records following the SORT/MERGE process.
MODS | Specifies external procedures (user exits) that are executed, each time a record is released to or returned from the SORT/MERGE process. This implementation supports the E15 and E35 user exits.
SUM | Specifies that records with the same key value are returned as a single record. Optionally, a field may be specified to accumulate totals for all records with equal keys. The SUM operation can be done for the following control field types:
OUTFIL | This is used to specify complex editing and reporting to one or more output files. Each output file should be specified using a GIVE command. Otherwise, OUTFIL works as described in the IBM documentation to be found at .
OPTION | This can be used to specify various options. One of these options is COPY which results in records being copied, rather than sorted, to the output file.
  • FIELDS Instruction
  • Defining Input and Output Files
Parent topic: Invoking Mfsort
Related information
Invoking Mfsort
Fields Instruction
RECORD Instruction
Defining Input and Output Files


FIELDS Instruction

A SORT or MERGE instruction must be followed by a FIELDS instruction which specifies the fields on which the input file is to be sorted or merged.

A fields instruction takes the following form:

fields({start,length,type,order},...)

where the parameters are:

Parameter | Description
start | The starting position of the field in the record, counting in bytes from 1
length | The length of the field (bytes)
type | The type of data in the field. See the section Field Types .
order | The ordering of output, which can be either of: A - ascending D - descending

You can specify up to 100 fields by repeating the parameter set (start, length, type and order). Use commas to separate the parameters and the parameter sets.

  • Field Types
Parent topic: Instructions


Field Types

The following is a list of some of the available field types:

Field Type | Definition
AQ | Character with alternate collating sequence.
BI | COMP
C5 | COMP-5
C6 | COMP-6
CH | PIC X DISPLAY
CX | COMP-X
FL | Floating point, signed.
FS/CSF | Signed numeric, with optional leading floating sign.
LI/OL/CLO | PIC S9 LEADING INCLUDED
LS/CSL | PIC S9 LEADING SEPARATE
NU | PIC 9 DISPLAY
PD | PIC S9 COMP-3
PD0 | Packed decimal with first semi-byte and sign semi-byte ignored.
SB/FI | PIC S9 COMP
S5 | S9 COMP-5
SS | Substring. Used in conditions only.
TS/CST | PIC S9 TRAILING SEPARATE
TI/ZD/OT/CTO | PIC S9 TRAILING INCLUDED
Y2B | Two-digit, one-byte binary year data.
Y2C/Y2Z | Two-digit, two-byte year data, with optional trailing included sign. PIC 99 or PIC S99.
Y2D | Two-digit, one-byte packed decimal year data. PIC 99 COMP-6.
Y2P | Two-digit, two-byte packed decimal year data. PIC 99 COMP-3.
Y2S | Two-digit, two-byte character year data with special indicators. Binary zeros, blanks and binary ones are treated as special cases.
Y2T | Full date format, yyx...
Y2U | Full date format, yyx..., COMP-3.
Y2V | Full date format, yyx..., COMP-3. Ignores first semi-byte.
Y2W | Full date format, x...yy.
Y2X | Full date format, x...yy, COMP-3.
Y2Y | Full date format, x...yy, COMP-3. Ignores first semi-byte.

You can find other field types defined in the IBM documentation at SORT Control Statement.

Suppose that golf.dat is a relative file defined in a COBOL program as follows:

 file-control.
     select members-file
         assign to "d:\netexpress\base\workarea\golf.dat"
         organization is relative
         access mode is random
         relative key is relative-key.
 data division.
 file section.
 fd members-file
     record contains 28 characters.
 01 members-record.
     03 members-number pic 9(6).
     03 members-lname pic x(10).
     03 members-fname pic x(10).
     03 members-handicap pic 9(2).

You can then use the following mfsort command to sort the file golf.dat on the field containing the membership number in ascending order:

mfsort sort fields(1,6,nu,a)
   use golf.dat record f,28 org rl
   give members.dat

The sorted version of the file is written to the file members.dat.

Parent topic: FIELDS Instruction


Defining Input and Output Files

You need to give instructions to define both the input and output files:

File Instructions
Input
USE input-file [record definition]
   [org organization] [key structure]
Output
GIVE output-file [record definition]
   [org organization] [key structure]

Notes:

  • For input files that are either variable length or indexed files, you do not need to specify RECORD, ORG or KEYcommands as the file characteristics can be deduced from the file itself.
  • If you omit any of the above instructions, the last specified values are used. Therefore, you need only specify values for the first file if the input and output files are all of the same type and format.
  • If the first file is variable length or indexed, you do not need to specify any of the values.
  • You can use embedded library names and environment variables when you specify input and output files, in the same way as you can when you specify them in ASSIGN clauses; for more information see the sections Library Names in Paths and Filename Mapping in the chapter Filenames.
  • You can redirect the output file generated by MFSORT to another filename as follows:
    • If you do not use the SYSOUT environment variable, it is written to a file named SYSOUT.
    • If you do specify the SYSOUT environment variable, you specify the filename to be written to.
  • RECORD Instruction
  • ORG Instruction
  • KEY Instruction
Parent topic: Instructions
Related concepts
Filename Mapping
Related reference
Library Names in Paths


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:

  • If you are not running under mainframe emulation, you can create a statistical report by using the MFJSTATS environment variable.
    Note: Setting the environment variable MFJSTATS to ON creates a report containing statistics for the SORT that is displayed to SYSOUT. If a report file already exists for a previous SORT, the new statistics are appended to the end of the previous one. The syntax is MFJSTATS=ON.
  • If you are running under mainframe emulation, see the section Sort/Merge Operations (MFJSORT) in the chapter Utility Programs of your Mainframe Subsystem Support Developer's Guide for more information.
Parent topic: Mfsort Utility
Related reference
Environment Variables
SortMerge Operations (MFJSORT)
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: Mfsort Utility
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 information
Input Data
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 information
Input Data
Mfsort Command


Workfile

During a sort or merge operation, mfsort uses a temporary workfile. This workfile is paged to disk in the current directory or, if it is set, in the directory specified by the TMP or TEMP environment variable. If not set, the current working directory is used.

Mfsort copies all the records from each of the input files to the temporary workfile, truncated or padded as appropriate. The workfile is then sorted or merged according to its key description. After being sorted or merged in the workfile, the records are copied to each of the output files and truncated or padded as appropriate.

During this operation:

  • If you do not need any of the records to be truncated, you must ensure that the record length of the workfile is sufficient for the longest record to be sorted
  • If your input files are of variable length and the sort workfile is not, all concept of variable-length is lost
  • If your input file is fixed length and the workfile is variable length, the record length of the record in the workfile is either the fixed length of the input file or the maximum record length of the workfile, whichever is the smaller


Error Messages

A full list of mfsort error messages is given in the topic Mfsort Error Messages.

Parent topic: Mfsort Utility
Related reference
Mfsort Error Messages
Related information
Introduction
Invoking Mfsort
Creating a Statistics Report
Example Commands


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.

  • 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
Mfsort Utility
Tracing File Operations


Data Compression

Data compression enables you to compress the data in a sequential or indexed file. There are two compression mechanisms provided with this COBOL system, run-length encoding (type 1), and extended run-length encoding (type 3).

When a file is defined with run-length encoding, any string of repeating characters is stored as a single character with a repetition count.

You enable data compression using the DATACOMPRESS Compiler directive.

Specifying data compression for a fixed structure sequential file changes it into a variable structure sequential file.

The compression used by a file is determined by the last processed DATACOMPRESS directive when the SELECT statement for the file is processed. Consequently, the compression type can be set for an individual file by using a line of the form:

$SET DATACOMPRESS

immediately before its SELECT statement. You must not forget to turn it off with a $SET NODATACOMPRESS before any other files are processed.

For details on the DATACOMPRESS Compiler directive, see the topic DATACOMPRESS.

Note:

We recommend that you do not use the REWRITE statement on compressed sequential files. This is because a REWRITE operation will only succeed if the length of the compressed new record is the same as the length of the compressed old record.

Parent topic: Data and Key Compression
Related reference
Line Sequential File Structure
Printer Sequential File Structure
Fixed Format Record Sequential File
Fixed Format Relative File
Standard File Header
Standard Record Header
Variable Format Record Sequential File
Variable Format Relative Structure
Index Files - Overview
Types of Indexed File
DATACOMPRESS
Related information
Key Compression
Example of Using Data and Key Compression
Compression Routines


Key Compression

Key compression is a technique that can be applied to the keys of an indexed file. There are four types of compression available:

  • Compression of trailing nulls
  • Compression of trailing spaces
  • Compression of identical leading characters
  • Compression of duplicate alternate key values.

You can specify key compression using the KEYCOMPRESS option in the File Handler configuration file. Use the following integers to indicate which type of compression you want:

1 | Duplicate key compression.
2 | Leading character compression.
4 | Trailing space compression.
8 | Trailing null compression.

You can add these numbers together to specify a combination of compression types (with the exception of trailing nulls and trailing spaces which are mutually exclusive).

Alternatively, you can use the KEYCOMPRESS Compiler directive when compiling the program.

The key compression used by a file is determined by the last processed KEYCOMPRESS directive when the SELECT statement for the file is processed so you can set key compression for an individual file by using a line of the form:

$SET KEYCOMPRESS"8"

immediately before its SELECT statement in your program. You can turn it off again by specifying $SET NOKEYCOMPRESS before any other files are processed.

  • Compression of Trailing Nulls
  • Compression of Trailing Spaces
  • Compression of Leading Characters
  • Compression of Duplicate Keys
Parent topic: Data and Key Compression
Related reference
KEYCOMPRESS
Related information
Data Compression
Example of Using Data and Key Compression
Compression Routines


Compression of Trailing Nulls

When a key is defined with compression of trailing nulls, trailing nulls in a key value are not stored in the file.

For example, assume you have a primary or alternate key that is 30 characters long, and that you write a record in which only the first 10 characters of the key are used, the rest being nulls. Without compression, all 30 characters of the key are stored requiring 30 bytes. With compression of trailing nulls, only 11 bytes are required (10 bytes for the 10 characters of the key and 1 byte which is used to maintain a count of the trailing nulls).

Parent topic: Key Compression
Related information
Compression of Trailing Spaces
Compression of Leading Characters
Compression of Duplicate Keys


Compression of Trailing Spaces

When a key is defined with compression of trailing spaces, trailing spaces in a key value are not stored in the file. However, information is stored so that the key can be correctly located.

For example, assume you have a prime or alternate key that is 30 characters long, and that you write a record in which only the first 10 characters of the key are used, the rest being spaces. Without compression, all 30 characters of the key are stored. With compression of trailing spaces, the key only occupies 11 bytes in the index file (10 bytes for the characters of the key and 1 byte as a count of the trailing spaces).

Parent topic: Key Compression
Related information
Compression of Trailing Nulls
Compression of Leading Characters
Compression of Duplicate Keys


Compression of Leading Characters

When a key is defined with compression of leading characters, all leading characters that match leading characters in the preceding key are not stored in the index file. However, information is stored to enable the key to be correctly reconstructed.

For example, assume that records are written with the following key values in a key defined with compression of leading characters:

AXYZBBB BBCDEFG BBCXYZA BBCXYEF BEFGHIJ CABCDEF

The keys actually stored in the index file are:

AXYZBBB BBCDEFG XYZA    EF      EFGHIJ  CABCDEF
Parent topic: Key Compression
Related information
Compression of Trailing Nulls
Compression of Trailing Spaces
Compression of Duplicate Keys


Compression of Duplicate Keys

When an alternate key is defined with compression of duplicates, only the first duplicate key is contained in the file. The rest are not stored, but information is stored to enable correct recreation of the keys.

For example, suppose you write a record with an alternate key value "ABC". If you have enabled compression of duplicate keys, and you write another record with the same key value, the file handler does not physically store the duplicate key value in the index file. However, the record is still available along the alternate key path.

Parent topic: Key Compression
Related information
Compression of Trailing Nulls
Compression of Trailing Spaces
Compression of Leading Characters


Example of Using Data and Key Compression

In the following program, data compression is specified for transfile but not for masterfile. For key compression, suppression of trailing spaces and of leading characters that are the same as in the previous key is specified for keys t-rec-key and m-rec-key. Suppression of repetition of duplicate keys is also turned on for m-alt-key-1 and m-alt-key-2.

$set callfh"extfh"
$set datacompress"1"
$set keycompress"6"
     select transfile
         assign to ...
         key is t-rec-key.
$set nokeycompress
$set nodatacompress
     select masterfile
         assign to ...
         organization is indexed
$set keycompress"6"
         record key is m-rec-key
$set keycompress"7"
         alternate key is m-alt-key-1 with duplicates
         alternate key is m-alt-key-2.
$set nokeycompress
Parent topic: Data and Key Compression
Related information
Data Compression
Key Compression
Compression Routines


Compression Routines

The routines that the File Handler uses to compress data are stand-alone modules. This means that you can use them in your own applications, or alternatively make the File Handler use your own data compression routine.

There can be up to 127 Micro Focus compression routines, and up to 127 user-supplied compression routines.

  • Micro Focus Compression Routines
  • Calling a Micro Focus Compression Routine
  • User-supplied Compression Routines
Parent topic: Data and Key Compression
Related information
Data Compression
Key Compression
Example of Using Data and Key Compression


Micro Focus Compression Routines

Micro Focus routines are stored in modules called CBLDCnnn, where nnn is within the range 001 to 127. To use Micro Focus compression routines, set fcd-data-compress in the FCD to a value between 001 and 127.

Routine CBLDC001

The compression routine CBLDC001 uses a form of run-length encoding. This is a method of compression that detects strings (runs) of the same character and reduces them to an identifier, a count and one occurrence of the character.

Note: The routine is not effective for use with files that contain significant occurrences of double-byte characters, including double-byte spaces, as these are not compressed.

The routine put special emphasis on runs of spaces, binary zeros and character zeros (that can be reduced to a single character) and printable characters (that are reduced to two characters consisting of a count followed by the repeated character).

In the compressed file, bytes have the following meanings (hexadecimal values shown):

20-7F | (most printable characters) normal ASCII meaning.
80-9F | 1-32 spaces respectively.
A0-BF | 1-32 binary zeros respectively.
C0-DF | 1-32 character zeros respectively.
E0-FF | 1-32 occurrences of the character following.
00-1F | 1-32 occurrences of the character following, and that it should be interpreted literally, not as a compression code. This is used when characters in the range 00-1F, 80-9F, A0-BF, C0-DF or E0-FF occur in the original data. (Thus, one such character is expanded to two bytes; otherwise, no penalty is incurred by the compression.)

Routine CBLDC003

Like CBLDC001, the CBLDC003 routine uses run-length encoding, but detects strings (runs) of single- or double-byte characters. This routine is therefore suitable for DBCS characters, but can also be used in place of CBLDC001.

The format of the compression is two header bytes followed by one or more characters. The bits in the header bytes indicate:

bit 15 | Unset - single character.
bit 14 | Set - compressed sequence. Unset - uncompressed sequence.
bit 0-13 | Compressed character(s) or count of uncompressed characters.

The length of the character string depends on the header bits:

bit 14 and 15 set | Two repeating characters.
Only bit 14 is set | One repeating character.
Otherwise | Between 1 and 63 uncompressed characters.
Parent topic: Compression Routines
Related information
Calling a Micro Focus Compression Routine
User-supplied Compression Routines


Calling a Micro Focus Compression Routine

For data file compression the File Handler calls the compression routine that you specify in the DATACOMPRESS Compiler directive.

To call a Micro Focus data compression routine use the syntax:

COBOL:

call "CBLDCnnn" using input-buffer,
                      input-buffer-size,
                      output-buffer,
                      output-buffer-size,
                      compression-type

C:

cbldcnnn(input_buffer, &input_buffer_size,
         output_buffer, &output_buffer_size,
         &compression-type);

where the parameters are:

nnn | A data compression routine in the range 001 to 127.
input_buffer | A PIC X(size) data item. On entry to the routine it must contain the data to compress or decompress; maximum size is 65535.
input_buffer_size | A two-byte (int in C, PIC XX COMP-5 in COBOL) data item. On entry it must contain the length of data in the input buffer.
output_buffer | A PIC X(size) data item. On exit it contains the resulting data.
output_buffer_size | A two-byte (int in C, PIC XX COMP-5 in COBOL) data item. On entry it must contain the size of the output buffer available; on exit it contains the length of the data in the buffer.
compression-type | A one-byte (char in C, PIC X COMP-X in COBOL) data item. On entry this must specify if the input data is to be compressed or decompressed: 0 - compress 1 - decompress.

The RETURN-CODE special register indicates whether the operation succeeded or not. Compression or decompression fails only if the output buffer is too small to accept the results. 0 indicates success and 1 indicates failure.

Parent topic: Compression Routines
Related information
Micro Focus Compression Routines
User-supplied Compression Routines


User-supplied Compression Routines

User-supplied compression routines must be stored in modules called USRDCnnn, where nnn is within the range 128 to 255.

To call a user-supplied routine, use the same syntax as for calling a Micro Focus routine, but use the filename USRDCnnn instead of CBLDCnnn where nnn must be a value in the range 128 through 255.

To make your compression routine available to your system, you must create a callable shared object that can be called when needed.

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

This chapter describes how to use the facilities provided for tracing file operations, which are provided to help in investigations into problems with file handling.

  • Introduction
  • Configuring Tracing and Logging
  • Dynamic Tracing
Parent topic: File Handling Guide
Related information
Introduction
File Organizations
Filenames
File Status
Sharing Files
File Handler Configuration
File Handler and Sort APIs
Mfsort Utility
Data and Key Compression


Introduction

The File Handler facilities for tracing file operations enable you to:

  • Set tracing on or off using file handler configuration parameters
  • Set a further level of tracing known as logging, again using file handler configuration parameters
  • Dynamically turn tracing on or off from your COBOL program, using library routines
Parent topic: Tracing File Operations
Related information
Configuring Tracing and Logging
Dynamic Tracing


Configuring Tracing and Logging

You use the File Handler configuration parameters TRACE, TRACEFILEEXTEND, TRACEFILENAME, LOG and LOGFILENAME to control tracing and logging activities:

  • Set TRACE=ON to turn tracing on
  • Set TRACEFILEEXTEND=ON to indicate that you want trace information to be written to the end of the current trace file, if the trace file already exists
  • Set TRACEFILENAME=filename if you want the trace file to have a name other than the default, which is xfhtrace.xfh
  • Set LOG=ON to indicate that you want any unusual file-related situations, such as corrupted files, or automatic file recovery, to be recorded in a log file for later examination
  • Set LOGFILENAME=filename if you want the log file to have a name other than the default, which is xfhlog

You can set TRACE and LOG either globally or for individual files, but you can only set TRACEFILEEXTEND, TRACEFILENAME and LOGFILENAME globally.

Here is an example configuration file:

[XFH-DEFAULT]
TRACE=OFF
TRACEFILENAME=c:\trace\mftracefile.xfh
TRACEFILEEXTEND=ON
LOG=ON
LOGFILENAME=c:\temp\mflogfile.log

[datafile1.dat]
TRACE=ON

[datafile2.dat]
LOG=OFF

In this example file tracing is set off globally and set on for the data file named datafile1.dat; new trace records are appended to the trace file, c:\trace\mftracefile.xfh, if it already exists. Logging is set on globally and set off for the data file named datafile2.dat.

Note: If the trace file might exceed a size of 4GB, ensure you specify the configuration options FILEMAXSIZE=8 and IDXFORMAT=8 (these are the default values).
Parent topic: Tracing File Operations
Related reference
Configuration File
Related information
Introduction
Dynamic Tracing


Dynamic Tracing

You can turn tracing on and off from within a COBOL program either by setting the appropriate flags in the FCD or by using library routines. You might want to do this to focus on file handling problems in a subset of an application's operations. When you set FCD flags you do it for a particular file. When you use the library routines, the trace settings affect all the file operations executed by the program from that point on.

When you do dynamic tracing, you use two flags together. This is because file operations such as READs and WRITEs can be traced only if the OPEN operation was traced. If you execute a program with tracing turned off, open a file, then switch dynamic tracing on, the tracing mechanism won't be able to trace any subsequent operations. The best way to proceed is to switch dynamic tracing on for OPENs and CLOSEs at the beginning of the program, then switch tracing for all operations on and off as required. However, the tracing of OPEN and CLOSE operations on its own can also be useful.

  • Using the FCD to Control Tracing
  • Using Library Routines to Control Tracing
Parent topic: Tracing File Operations
Related information
Introduction
Configuring Tracing and Logging


Using the FCD to Control Tracing

To use the FCD flags you must have access to the FCD; see the topic Accessing the FCD in the section File Handler and Sort APIs.

File tracing is controlled by two flag bit settings within the FCD:

  • Bit 1 of fcd-flags-1 controls whether all file operations are traced.
  • Bit 3 of fcd-fs-flags controls whether OPEN and CLOSE operations only are traced.

Change these bit settings as required to control tracing for individual files.

Parent topic: Dynamic Tracing
Related information
Using Library Routines to Control Tracing
Accessing the FCD


Using Library Routines to Control Tracing

The library routines provide a means of obtaining the same tracing behavior as setting the FCD flags without the need to have the FCD available. All changes to tracing behavior made using the library routines affect all files subsequently accessed.

To control tracing, issue calls to the MFFH_MODIFY_TRACE library routine. You can:

  • Set the main tracing flag on and off
  • Set the OPEN/CLOSE tracing flag on and off
  • Disable a modification that you set earlier

To disable all the modifications that you have set, issue a call to the library routine MFFH_MODIFY_DISABLE.

For further information see the topics MFFH_MODIFY_TRACE and MFFH_MODIFY_DISABLE.

Parent topic: Dynamic Tracing
Related reference
MFFH MODIFY DISABLE
MFFH MODIFY TRACE
Related information
Using the FCD to Control Tracing


Working with Data Files

  • 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: File Handling
Related information
File Handling Examples
File Handling Guide
File Systems
Fileshare Guide


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.

  • 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: Working with Data Files


Overview

Rebuild is a file management utility invoked from the command prompt which enables you to:

  • Reorganize an indexed file
  • Rebuild a corrupt indexed file
  • Convert files from one organization to another
  • Validate an indexed file

The operation performed on a file by Rebuild depends on the options specified on the Rebuild command line.

Note:
  • If you are using Fileshare to access files, you should use only the Rebuild options that are supported for use through Fileshare. Otherwise, you will obtain undefined results.
  • When working with striped IDXFORMAT "8" files, you should ensure that:
    • All stripes are present
    • Rebuild picks up the File Handler configuration file extfh.cfg file.
    Failure to do this can lead to unpredictable results.
  • You should always take a backup copy of a file before you reorganize, rebuild or convert it. This is simply as a precaution against an incorrectly specified command line which could lead to file corruption. For indexed files, you should save both the index and data parts of the file.
  • Key offsets start at 1.
  • All temporary files are created in the system temporary file directory, unless you set TMP or TEMP to point to the directory where you would like to keep temporary files.
Parent topic: Rebuild
Related information
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Command Line

The format of the Rebuild command line is:

rebuild in-file [,out-file] [options]

Both in-file and out-file must include the filename extension. The filename of out-file must not be the same as in-file. You can use environment variables in place of in-file or out-file to implement filename mapping.

The options specified on the command line define the operation to be carried out by Rebuild.

  • Option Files
  • Redirection of Information
Parent topic: Rebuild
Related information
Overview
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Option Files

On the Rebuild command line, an at character (@) followed by a filename indicates that the named file contains Rebuild command line options.

If you use a file to supply Rebuild command line options, the file must be an ASCII text file.

Within the Rebuild options file:

  • Options should be separated by spaces.
  • Line ends are treated as spaces.
  • Any text between an asterisk (*) and the line end is treated as a comment.

In the following example:

rebuild infile.dat, outfile.dat @conv.par

conv.par is an ASCII text file containing Rebuild options.

Parent topic: Command Line
Related information
Redirection of Information


Redirection of Information

All information displayed by the Rebuild utility can be redirected to a text file using standard operating system redirection:

> | Creates a new file.
>> | Extends an existing file

For example:

rebuild oldms001.dat,ms001.dat -k:1+20<N> -i >> rebuild.prt

redirects the output from Rebuild to the existing file rebuild.prt.

Note: When you are redirecting output, do not use the -v option.
Parent topic: Command Line
Related information
Option Files


Rebuild Options

The processing performed by Rebuild is defined by the option(s) specified on the command line.

The following options are available:

-c | Specifies file compression
-d | Reconstructs an index from the data area of an indexed file
-e | Reports illegal duplicate keys and continues processing
-f | Validates indexed files
-i | Displays information about the files being processed
-k | Defines the key structure for an indexed file
-m | Reserved for future use
-n | Displays information about a file (no other processing is performed)
-o | Specifies the organization of the input and output files
-p | Rebuilds IDXFORMAT "8" file in place
-q | Reserved for future use
-r | Defines the record structure of the input and output files
-s | Specifies the format of the input file
-t | Specifies the format of the output file
-u | Attempts to recover a file for which the last update operation was not completed
-v | Displays a record count which is incremented as the file is processed
-y | Forces Rebuild to ignore file size discrepancies
-x | Specifies the order in which data is written when reorganizing an indexed file
-z | Instructs Rebuild to use a Fileshare server for file access
--q | Suppresses display of the Rebuild banner
--v | Displays the version number of Rebuild

Options can be placed in any order on the command line, except that options beginning with a double hyphen (--) must be placed before options beginning with a single hyphen (-). Options are free-format; spaces are required between options.

A colon (:) is required before parameters of the -f or -v options. For other options, a colon before parameters is optional. Do not insert spaces between the parameters of options.

Parent topic: Rebuild
Related information
Overview
Command Line
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Reorganizing Indexed Files

The format of the command line for reorganizing a file is:

rebuild in-file,out-file
[-c] [-d] [-i] [-k] [-n] [-p] [-s] [-v] [-x]

As indexed files are updated by adding, deleting and altering records, the index and data structures become disjointed, making processing less efficient. In addition, space left by deleted records is not always reused, making the file bigger than it needs to be.

After a large number of changes have been made, it is worth reorganizing an indexed file to rebuild the data and indices in an ordered sequential fashion and to reclaim any free space. This will ensure optimum performance and data integrity.

There are other reasons why you may want to reorganize a file. For example, if a file is processed sequentially, the access time to process the file increases over time, as the records start to become out of sequence due to updates. In this situation, you can reduce access time by reorganizing the file.

A third reason is to rebuild a duplicate key chain. A duplicate key has a duplicate occurrence value appended to it to make it unique. When a new duplicate key is added, the occurrence value of the last added key is incremented by one and used for the newly added key. If keys are deleted, no change is made to the occurrence values of the remaining keys. Therefore, you can reach the maximum number of duplicate values, even if some of those keys have already been deleted. In these circumstances it is a good idea to reorganize the file. For more information on duplicate keys, see the topic Duplicate Keysin the section File Organizations.

For example:

rebuild infile.dat,outfile.dat

causes Rebuild to read the data file (infile.dat) using the index file (infile.idx) and then create the output file (outfile.dat). The deleted records in infile.dat are not written to the output file.

Note: You cannot use the same filename for the input file and the output file.
Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Rebuilding a Corrupt Indexed File

The format of the command line for rebuilding an index is:

rebuild in-file[,out-file]
[-c] [-d] [-e] [-i] [-k] [-n] [-p] [-s] [-v]

The out-file parameter is optional, but recommended, because if you do not specify it, and the Rebuild operation fails, you will lose your original file.

There are a number of reasons why an indexed file becomes corrupt, for example:

  • A close operation on an indexed file fails.
  • A power surge occurs while the indexed file is open.
  • The machine is rebooted or powered off while an indexed file is open.

When a COBOL program attempts to open a corrupt indexed file, the run-time system detects that the file is corrupt and returns an extended file status code.

Rebuild can recover corrupt indexed files for you:

  • If the data portion of the file is intact and only the index portion is corrupt, then Rebuild can generate a new index (.idx) file from the data file with no loss of data.
  • If the data portion of the file is corrupt then Rebuild can rebuild a complete new indexed file, both data and index portions, but there will be loss of data as Rebuild discards any corrupt data records that it encounters.
Note: When you use Rebuild to generate a new index file from an existing data file, the file can grow in size. One reason is that information held in the original index about free space in the data file is lost, which means that the free space cannot be reused. Another reason is that if you specify the -d option, index records are created individually as with normal I/O operations, leading to index nodes that are only partially filled. To overcome this problem, you should reorganize the file after you have rebuilt the index.

In the following example Rebuild reads the .idx file to get the key information, and creates a new index file, by reading the data file, infile.dat:

rebuild infile.dat

In the following example Rebuild reads the input file to get the key information, and creates a new indexed file, by working through the data in physical order, skipping over duplicate records:

rebuild infile.dat, outfile.dat -d -e

If the index file is not present, you must supply information about the key structure using the -k option.

Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Converting a File

The format of the command line for converting a file is:

rebuild in-file,out-file [-c] [-i]
    [-k] [-o] [-r] [-s] [-t] [-v]

Rebuild enables you to convert files from one file organization and format to another.

In the following example Rebuild converts a C-ISAM file into the format used by this system and compresses the data part of the file:

rebuild infile.dat,outfile.dat -s:c-isam -c:d1 -t:mf
Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Validating an Indexed File

The format of the command line for validating an indexed file is:

rebuild in-file -f

Rebuild can perform a number of validation checks and you can request all of them, or just a subset of them. Of course, the more checks you request, the longer the validation process takes.

In the following example Rebuild performs a full integrity check on the file:

rebuild test.dat -f
Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Rebuild through Fileshare

You can use Rebuild on files that reside on Fileshare servers, but only with a limited range of Rebuild options. The format of the command line for using Rebuild through Fileshare is:

rebuild in-file[,out-file] -z:server-name {/l|/n}

where:

server-name The name of a Fileshare server. All occurrences of server-name must refer to the same Fileshare server.

You can also specify a Fileshare server without using the -z Rebuild option. The format of the command line for this is:

rebuild $$server-name\in-file [$$server-name\out-file] {/l|/n}

Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Callable Rebuild
Rebuild Examples


Callable Rebuild

You can call Rebuild from your COBOL program as follows:

call "callrb" using commands status

where the parameters are:

commands | A PIC X(600) item containing the Rebuild command line. This item must be 600 bytes in length because Rebuild scans the command line backwards from offset 599.
status | A PIC XX COMP X item containing the returned file status. This item shows the result of the call to Rebuild.

When called from within a program, Rebuild does not display any of its usual messages.

If an error occurs or the rebuild is unsuccessful, RETURN-CODE contains a non-zero value and status contains the returned file status. You should always check RETURN-CODE and status after a call to Rebuild.

The possible values of RETURN-CODE are shown below.

Value | Description
0 | Rebuild executed successfully
1 | An error occurred on the input file such as file not found or invalid file format - check status parameter
2 | An error occurred on the output file - check status parameter
3 | Error in sort
4 | File is corrupt
5 | Attempt to do a /k:a:exists
6 | Attempt to do a /k:r:onprime
7 | Attempt to do a /k:r:dontexist
8 | Too many duplicates on out
9 | The parameter list contained an error such as an invalid option or an invalid combination of options

If an error occurs, execute Rebuild from the command line on the same file with a set of identical options. The screen output should give a more precise indication as to the cause of the error.

Note: If you are using the -f option (validate an indexed file), then any non-zero RETURN-CODE indicates that the file is corrupt. Again, execute Rebuild from the command line on the same file with a set of identical options to obtain more precise information.

The following example shows Rebuild being called from within a COBOL program.

 01 parameters   pic x(600).
 01 status       pic xx comp-x.
   ...
     move "infile.dat,outfile.dat -s:lii -c:d1" to parameters
     call "callrb" using parameters,status
     end-call
Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Rebuild Examples


Rebuild Examples

The section provides examples of using Rebuild.

rebuild infile.dat,outfile.dat -i

Reorganizes the file. The data is written in the order of the prime record key, and processing information displayed when the reorganization is complete.

rebuild infile.dat,outfile.dat -x:3

Reorganizes the file. The data is written in the order of the third alternate key.

rebuild infile.dat

Rebuilds the indexed file (assuming that the index (.idx) file is still present, and the key information held therein is not corrupt).

rebuild infile.dat -k:1+20 -i

Rebuilds the indexed file. The index (.idx) file does not need to exist, and is ignored if it does. It will be completely recreated using the key definition specified (which need not correspond to the key definition used when the file was created). Processing information will be displayed when the rebuild is complete.

With C-ISAM and Level 2 files that do not have index files, use the -r and -s options to specify the record information and file format.

rebuild infile.dat,outfile.dat -s:c-isam -c:d1 -t:mf

Converts a C-ISAM format index file into the format used by this system and compresses the data part of the file.

rebuild infile.dat,outfile.dat --o:rel,ind -k:1+2:3+10d
-c:i7 -r:f10

Generates an index, with key compression, for a fixed-length relative file.

rebuild infile.dat,outfile.dat -s:lii -t:lii

Reorganizes a LEVEL II V2.5 COBOL format file and retains the LII structure on the output file. It is possible to combine -s and -t with other formats in a similar manner.

set data=/tmp.dat rebuild data -i

Reorganizes and displays information about the file /tmp.dat.

Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild


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

The File Handler is configured to work with either 32-bit or 64-bit addressing. It is vital that all applications sharing a file use a File Handler configured the same, or 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
Working with Data Files
Fileshare Guide


32-bit file systems

  • Windows Millennium
  • Windows 2000 (FAT)
  • Windows XP (FAT)
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)
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
  • Database Integrity
    This chapter describes all of those Fileshare features which enable you to safeguard the integrity of your database:
  • Security
    Fileshare provides security features which enable you to restrict access to a Fileshare Server.
  • Advanced Operation
    This chapter describes the advanced features that are available with Fileshare.
  • Fileshare on UNIX
    This chapter describes Fileshare on UNIX.
  • Error Handling
    Fileshare error messages are listed in the chapter Fileshare Server Messages .
  • Fileshare Server Messages
    There are three levels of messages that can be produced by the Fileshare Server.
Parent topic: File Handling
Related information
File Handling Examples
File Handling Guide
Working with Data Files
File Systems


Introduction

This chapter gives a brief overview of the facilities provided by Fileshare and also describes how Fileshare works.

  • Overview
  • How Fileshare Works
Parent topic: Fileshare Guide
Related information
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
Fileshare on UNIX
Error Handling
Fileshare Server Messages


Overview

Fileshare is best suited to applications that share data files, concurrently, between many users, across a network. It supports all of the functionality provided by the base COBOL file handling system and provides several additional features:

  • Reduced network traffic
  • Transaction processing
  • Rollforward recovery logging
  • Logon and file open security checks

The ability of any one application to take advantage of these features depends on:

  • The way the application processes the shared data files
  • The type of data files the application shares
  • The operating system on which the Fileshare Server is running
  • The communications protocol being used between the Fileshare Client and the Fileshare Server

You do not need to make any program source code changes to use the basic Fileshare system. Source code changes are only needed to take advantage of some of the advanced features provided by Fileshare.

Parent topic: Introduction
Related information
How Fileshare Works


How Fileshare Works

Using the base COBOL file handling system, a typical COBOL I/O request to a shared data file causes the file handler to make several accesses to that data file across the network. See Figure 1.

Figure 1. Conventional Network
Conventional Network

With Fileshare, a program that needs to access a data file has its request processed by the File Handling Redirector (FHRedir) module. The FHRedir module sends the request over the network to a Fileshare Server that performs the low-level I/O operations and then passes the result of the I/O operation, including the file status, back to FHRedir. FHRedir returns the result to the program. See Figure 2.

Figure 2. Fileshare Network
Fileshare Network

A Fileshare System is made up of:

Fileshare Clients | A Fileshare Client comprises a user program, making data file I/O requests, via the FHRedir module. FHRedir redirects the I/O requests to a Fileshare Server.
Fileshare Servers | A Fileshare Server runs on the same machine as the data files that you want to access. The Fileshare Server accepts requests across the network from the Fileshare Client, processes them by calling a local copy of the Micro Focus File Handler and then returns the result to the Fileshare Client.
Note:
  • The Fileshare Server and the Fileshare Client can be running on the same physical machine. For example, with a multi-tasking operating system such as Windows, the Fileshare Client can run in one session and the Fileshare Server can run in another session. Using this method, you can develop Fileshare applications on a single PC without actually sending data across a network. You should be aware, however, that performance improvements will not be observed, as no network is being used.
  • You can also run the Fileshare Server in the same session as the Fileshare Client using the single user mode of operation. This enables you to take advantage of advanced Fileshare features, such as transaction processing, without the need for a network or multiple sessions. For more information on the single user mode of operation, see the section Single User Mode in the chapter Advanced Operations.

Since a single Fileshare Server processes all the requests from several Fileshare Clients, it can use a single copy of the Micro Focus File Handler, regardless of how many users are accessing the Fileshare Server. This has several advantages:

  • The Fileshare Server can open the data files exclusively making full use of both its own cache and the operating system's cache
  • The Fileshare Server does not need to obtain semaphores on the data file. Normally semaphores are needed to control concurrent access to shared data files.
  • The Fileshare Server can process record locks internally without the need to make calls to the operating system
Parent topic: Introduction
Related information
Overview
Single User Mode


Standard Operation

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.

  • Fileshare Client
  • Fileshare Server
Parent topic: Fileshare Guide
Related information
Introduction
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
Fileshare on UNIX
Error Handling
Fileshare Server Messages


Fileshare Client

To enable your COBOL program to use Fileshare at the Fileshare Client machine, you need to do two things:

  • Force your program to pass file I/O requests to the File Handling Redirector module (FHR), thus creating a Fileshare Client
  • Configure your Fileshare Client, specifying the name of the Fileshare Server to connect to, and the communications protocol to use when connecting.

You might also need to configure CCI for the communications protocol you have chosen. For more details, please refer to:

  • Your online book Configuring CCI
  • Specifying the Fileshare Server
  • Specifying the Communications Protocol
  • Configuring Your Fileshare Client
  • Using the File Handling Redirector Module
  • FHREDIR Return Codes
Parent topic: Standard Operation
Related information
Fileshare Server


Specifying the Fileshare Server

Each Fileshare Server on the network is identified by a unique name, assigned when the Fileshare Server is started. The Fileshare Client uses this name to specify which Fileshare Server to use.

There are two ways to specify the Fileshare Server name:

  • As part of the filename in your program.

    This requires changes to your code.

  • In a Fileshare Client configuration file.

    This does not require changes to your code.

These methods are listed in the next two topics.

  • As a Filename
  • In a Configuration File
Parent topic: Fileshare Client
Related information
Specifying the Communications Protocol
Configuring Your Fileshare Client
Using the File Handling Redirector Module
FHREDIR Return Codes


As a Filename

Specifying the server as a filename in your program overrides any configuration file settings.

select account-file assign to	"$$server1\c:\accounts\main.dat"

This SELECT statement tells the File Handling Redirector module to direct requests for this data file to the Fileshare Server named server1. The data file is main.dat in the directory accounts on drive c: on the Fileshare Server machine. The File Handling Redirector module passes the characters appearing after the text string $$server1\ to the Fileshare Server as the name of the file.

Parent topic: Specifying the Fileshare Server
Related information
In a Configuration File


In a Configuration File

To specify a default Fileshare Server, use the /s option in the Fileshare Client configuration file. For example:

/s server2

tells the Fileshare Client to use the default Fileshare Server named server2. The File Handling Redirector module redirects all file I/O to this server unless you:

  • Specifically define a file as a local file. See the section Client Configuration in the chapter Configuration for further information.
  • Specify that a file is on a different Fileshare Server, using the Fileshare Client configuration file. See the section Client Configuration in the chapter Configuration for further information
  • Specify a different Fileshare Server as part of the filename in your program (see above)
Note:

  • The Fileshare Client configuration file can contain a maximum of 16 unique Fileshare Server names
  • Filenames appearing in the configuration file are case-sensitive unless defined by the /r option (DYNCONFIG), in which case they are not case sensitive when run in Windows
  • The filename in the configuration file must appear exactly as it will appear to the File Handling Redirector module on the first OPEN request passed by your program
Parent topic: Specifying the Fileshare Server
Related information
As a Filename
Client Configuration


Specifying the Communications Protocol

Fileshare over CCI supports several communications protocols. The protocol you use depends on the operating system the Fileshare Client and Fileshare Server(s) are running on and the type of network you are using. You specify the Fileshare CCI communications protocols in the client's cci.ini file.

The default protocol is TCP/IP (CCITCP).

If you require a communications protocol other than the default, you must specify it in the Fileshare Client configuration file.

To specify an alternative default CCI protocol, use the /cm option. For example:

  • To make the Novell IPX protocol (CCIIPX) the default:
    /cm cciipx
  • To specify that a particular CCI protocol is used when communicating with a specific Fileshare Server, use the /cm and /s options together:
    /cm cciipx /s server1
    This tells the Fileshare Client to use the CCIIPX for communicating with the Fileshare Server named server1.
  • To make the Fileshare Client use the TCP/IP protocol (CCITCP) as the default and CCIIPX for communicating with server1:
    /cm ccitcp
/cm cciipx /s server1
Note: The cci.ini file that ships with Enterprise Sever contains detailed comments that explain the various cci.ini options that you can use to alter the basic CCISMEM configuration. Most of these are rarely required.
Parent topic: Fileshare Client
Parent topic: Configuring CCI Communications for Fileshare
Related information
Specifying the Fileshare Server
Configuring Your Fileshare Client
Using the File Handling Redirector Module
FHREDIR Return Codes
About Fileshare Communications
Using CCITCP
About CCISMEM
Using CCISMEM
Using UNIX named pipes: ccinampu
Logging Fileshare Messsages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Configuring Your Fileshare Client

The Fileshare Client configuration file is an ordinary text file that you can create using any text editor. By default, it is called fhredir.cfg. The Fileshare Client searches for this file in the current working directory of your application and then along the path specified by the COBDIR environment variable, if one has been set up. Alternatively, you can specify the location of the Fileshare Client configuration file using the FHREDIR environment variable, for example:

set FHREDIR=c:\client.cfg

This example tells the Fileshare Client to use the configuration file client.cfg in the root directory on drive c:.

Configuring the Fileshare Client enables you to specify how you want to treat your data files, that is, as either:

  • Local data files, located on the machine where the Fileshare Client is running. To access local data files, the Fileshare Client uses a local copy of the Micro Focus file handler. This is the default.
  • Remote data files, located on the machine where the Fileshare Server is running. To access remote files, I/O operations are redirected to the appropriate Fileshare Server by the File Handling Redirector module.

In order to redirect I/O operations successfully, the File Handling Redirector module needs to know:

  • Which Fileshare Server to communicate with
  • Which communications protocol to use when contacting the server
  • Fileshare Client Configuration Options
  • Example Client Configuration File
Parent topic: Fileshare Client
Related information
Specifying the Fileshare Server
Specifying the Communications Protocol
Using the File Handling Redirector Module
FHREDIR Return Codes


Fileshare Client Configuration Options

This section describes all of the available Fileshare Client configuration options. These options can appear as many times as necessary within a Fileshare Client configuration file, and in any order, but only one option can be specified per line.

Note:
  • The Fileshare Client configuration file can contain a maximum of 16 unique Fileshare Server names
  • Filenames appearing in the configuration file are case-sensitive unless defined by the /r option (DYNCONFIG), in which case they are not case sensitive when run in Windows
  • The filename in the configuration file must appear exactly as it will appear to FHRedir on the first OPEN request passed by your program
  • The Fileshare Server name is folded to uppercase. Note that it may be necessary to use the name in uppercase in some configuration files to ensure name matching works as expected.
Client Configuration Option Specifying
/bl
 Open a file exclusively to enable blocking, to improve performance.
/cm CCI-Protocol
 The default communications protocol for this Fileshare Client. Valid values for CCI-Protocol are listed in the table below.
/cm CCI-Protocol
/s ServerName
 The communications protocol to use when contacting the Fileshare Server, ServerName. Valid values for CCI-Protocol are listed in the table below.
/ct CCI-Timeout server-name
 The communications timeout period, specified in 1/10th seconds. The default is 1200 (120 seconds). See the section CCI Timeout in the chapter Communications for more information.
/cr CCI-Timeout
 The connection retry timeout period, specified in 1/10th seconds. The default is 0. This timeout is only for the initial connection and only applies if the CCI module returns and is out of memory or resources. The client will reattempt to connect at varying intervals up to the timeout period. However, the default is that the connection is only tried once.
/f Filename
/r Custom-File-Handler
 The data file Filename is a local file and should be actioned by the custom file handler. Repeat this option for eveyr data file you want assigned to a specific custome file handler that is not the default File Handler. Valid values for Filename and Custom-File-Handler are listed in the table below.

This option only applies if the environment variable DYNREDIR is set to DYNCONFIG.

/f Filename
/s ServerName
 The data file Filename is a remote file on the Fileshare Server named server-name. Repeat this option for every data file you want assigned to a specific Fileshare Server that is not the default Fileshare Server. Valid values for Filename and ServerName are listed in the table below.
/f Filename
 Filename is a local data file held on the PC where the Fileshare Client resides. Valid values for Filename are listed in the table below.
/s ServerName
 The ServerName as a default Fileshare Server

Accesses to data files not directed to a particular Fileshare Server or not defined as local data files are directed to the default Fileshare Servers. The order in which the default Fileshare Servers are defined in the Fileshare Client configuration file is the order in which the Fileshare Client contacts each Fileshare Server in an attempt to locate the file.

If the data file is not found on any Fileshare Server, the request for that data file is directed to the first default Fileshare Server listed in the configuration file.

Valid values for options in the Fileshare Client configuration file are:

Option | Valid Values
CCI-Protocol

Windows:

  • TCP IP: /ccitcp
  • CCISMEM: /ccism

UNIX:

  • TCP IP: -ccitcp: ccitcp
  • UNIX named pipes: -ccinampu
ServerName | Any character string up to 16 characters long depending on the CCI protocol you are using. The Fileshare Client configuration file can contain a maximum of 16 unique Fileshare Server names.
Filename Any valid filename that is supported by the operating system. Filenames cannot contain embedded space characters. You can use terminating wildcard characters in Filename to designate groups of files. For example, use
/f \accounts\*

to specify all files starting with the string "\accounts\".

Parent topic: Configuring Your Fileshare Client
Related information
Example Client Configuration File


Example Client Configuration File

This example shows a typical Fileshare Client configuration file.

/s server1
/s server2
/cm cciipx
/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 cciipx

Specifies that the default communications protocol is CCIIPX. When the Fileshare Client tries to contact a Fileshare Server that does not have a specific CCI protocol defined (see Lines 1 and 2), this is the one used.

Line 4:
/f \orders\* /s server3

Specifies that FHRedir should direct all accesses to files with a name beginning with the string \orders\ to the Fileshare Server named server3.

Line 5:
/cm ccitcp /s server3

Specifies that the communications protocol to use when communicating with the Fileshare Server, server3 is ccitcp. This overrides any default CCI protocol specified in the Fileshare Client configuration file (see Line 3).

Line 6:
/f \accounts\payroll.dat

Specifies that the file \accounts\payroll.dat is a local file on the Fileshare Client machine. The Fileshare Client accesses this file using a local copy of the Callable File Handler.

Line 7:
/f \transport\delivery\*

Specifies that any files with a filename beginning with the string \transport\delivery\ are local files.
Line 8:
/f \returns\* /r module1!userfh1

Specifies that the customer file handler userfh1 in module1 should be used for all accesses to files with a name beginning with the string "\returns\".

Note that module1 specifies the library containing a custom file handler and that usedrfh1 is the name of the custom file's entry point.

This option only applies if the environment variable DYNREDIR is set to DYNCONFIG.
Parent topic: Configuring Your Fileshare Client
Related information
Fileshare Client Configuration Options


Using the File Handling Redirector Module

There are three ways of forcing your program to pass file I/O requests to the File Handling Redirector module:

  • If your program uses COBOL I/O syntax, you must compile it with the CALLFH"FHREDIR" Compiler directive so that the File Handling Redirector module processes any I/O requests that your program makes.
  • If your program uses the Micro Focus file handler API, you need to change the program so that it calls "FHREDIR" and not "EXTFH". (The call interface to the File Handling Redirector module is exactly the same as the call interface to the Callable File Handler (ExtFH).)

    For example:

    call "FHREDIR" using operation-code, fcd
  • Set the File Handler configuration option FHREDIR=ON.
    Note:

    Take care with this option. If it is in effect when Fileshare itself is running, Fileshare will attempt to redirect file I/O requests to itself, and this will cause a timeout failure.

When you have performed any of these actions, you have created a Fileshare Client but your program works in exactly the same way as it did before because the File Handling Redirector module simply forwards I/O requests to a local copy of the Micro Focus File Handler.

Parent topic: Fileshare Client
Related information
Specifying the Fileshare Server
Specifying the Communications Protocol
Configuring Your Fileshare Client
FHREDIR Return Codes


FHREDIR Return Codes

Each call to FHREDIR returns a status code in fcd-file-status in the FCD. Most codes returned are the usual file handling codes. The following codes specific to Fileshare might also be returned:

Code | Meaning
-128 | Fileshare Security is enabled and the user name specified by the caller is not found in the password file on the server.
-127 | The named file is not currently open by the fileshare server. This does not mean that the file does not exist on the disk.
-126 | Fileshare Security is enabled and the password given is incorrect.
-125 | The requested data is larger than the buffer provided to contain it. Increase the size of your buffer.
Parent topic: Fileshare Client
Related information
Specifying the Fileshare Server
Specifying the Communications Protocol
Configuring Your Fileshare Client
Using the File Handling Redirector Module


Fileshare Server

Before a Fileshare Server is invoked, you need to configure the Fileshare Server to specify:

  • The Fileshare Server name to use on the network
  • The communications protocols that it can use
  • Configuring the Fileshare Server
  • Starting the Fileshare Server
  • Stopping the Fileshare Server
Parent topic: Standard Operation
Related information
Fileshare Client


Configuring the Fileshare Server

You can specify these Fileshare Server configuration options in one of two ways:

  • On the command line (separated by spaces)
  • In a Fileshare Server configuration file (a text file which you can create using any text editor).

    The Fileshare Server identifies the configuration file to use by checking the FS environment variable:

    • If set, the Fileshare Server uses the configuration file specified by this variable
    • If not set, the Fileshare Server uses the default configuration file fs.cfg either in the current working directory of the Fileshare Server or on the path specified by the COBDIR environment variable
  • Specifying a Fileshare Server Name
  • Specifying the Communications Protocol
  • Fileshare Server Configuration Options
Parent topic: Fileshare Server
Related information
Starting the Fileshare Server
Stopping the Fileshare Server


Specifying a Fileshare Server Name

Each Fileshare Server is identified on the network by a unique name. This name is specified using the /s option, for example, the command line:

fs /s server1

registers the name of the Fileshare Server as server1.

Note:

The Fileshare Server cannot be initialized unless it registers a name on the network. The server-name can be up to 16 characters in length, depending on the CCI protocol you are using.

Parent topic: Configuring the Fileshare Server
Related information
Specifying the Communications Protocol
Fileshare Server Configuration Options


Specifying the Communications Protocol

By default the Fileshare Server uses CCITCP to communicate with Fileshare Clients using the TCP/IP protocol. You need to specify any other protocol you want Fileshare to use by specifying the /cm option, for example:

/cm cciipx

This entry in the Fileshare Server configuration file enables the Fileshare Server to communicate with Fileshare Clients using the Novell IPX (CCIIPX) protocol.

Parent topic: Configuring the Fileshare Server
Related information
Specifying a Fileshare Server Name
Fileshare Server Configuration Options


Fileshare Server Configuration Options

This section describes all of the available Fileshare Server configuration options. The /s option that defines the server-name is compulsory. All other options are optional or have default values that are specified below.

Note:
  • UNIX: Filenames are shown using the Windows naming convention. On UNIX, use the UNIX file-naming conventions.
Server Configuration Options Specifying
/s server-name
 The name that the Fileshare Server registers on the network. This must be a character string up to 16 characters in length, depending on the CCI protocol that you are using. The name specified must be unique. If a Fileshare Server with the same name is already registered on the network, an error is returned.
/d database-reference-file
 The name of the database reference file that the Fileshare Server is to use. The database reference file is used to determine which additional Fileshare features you want to use.
/t timeout-period
 Setting the record lock timeout period after which the Fileshare Server releases all record locks held by a Fileshare Client and rolls back any outstanding transactions. The timeout period is specified in seconds. The default value is 60 seconds. Specifying a value of zero disables the timeout and record locks are only released under the control of your application program. Valid values are 0 thru 99999. The timeout only occurs if one Fileshare Client requests a record currently locked by another Fileshare Client.

Setting a value of zero in conjunction with setting the environment variable ES_RLS_FILE_SUPPORT=Y ensures that no information is returned to the record area following a READ operation on a locked record.

/m record-size
 The maximum record size that can be processed by the Fileshare Server. Setting a value lower than the default value reduces the amount of memory that the Fileshare Server needs to run. The record size is specified in kilobytes. Valid values are 16 thru 64. If you specify a value less than 16, the Fileshare Server uses a buffer size of 16K. If you specify a value greater than 64, the Fileshare Server uses a buffer size of 64K.
/cm cci-protocol
 The CCI protocols that the Fileshare Server can use. Repeat this option for every communications protocol that you want to use to contact this Fileshare Server. Valid values for cci-protocol are:

ccinetb ccitcp cciipx

/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
/pt time
 Writes to fsscreen.lst details of processes that take longer than the time specified to complete. Time can be specified in 10ths of a second.
  • Example Server Configuration File
Parent topic: Configuring the Fileshare Server
Related information
Specifying a Fileshare Server Name
Specifying the Communications Protocol
Database Reference File Maintenance
Automatic Record Lock Timeout
Security
Monitoring Fileshare
Fileshare on UNIX


Example Server Configuration File

This example shows a typical Fileshare Server configuration file.

/s mainsrv
/cm cciipx
/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 cciipx

Specifies that cciipx is one of the communications protocols that a Fileshare Client can use to contact this Fileshare Server.

Line 3:
/d dbase1.ref

Specifies that the database reference file the Fileshare Server is to use is named dbase1.ref.

Line 4:
/t 120

Specifies that the automatic record lock timeout period is 120 seconds.

Line 5:
/pf \pass\passwd.fil

Specifies that the Fileshare Password Security feature is enabled and that the password file is \pass\passwd.fil containing valid user-IDs and passwords.

Parent topic: Fileshare Server Configuration Options


Starting the Fileshare Server

You must start the Fileshare Server running before Fileshare Clients can connect to it.

To start the Fileshare Server use the following command line:

fs
Parent topic: Fileshare Server
Related information
Configuring the Fileshare Server
Stopping the Fileshare Server


Stopping the Fileshare Server

Once started, a Fileshare Server runs as an active process until you explicitly stop it. You must stop the Fileshare Server when you no longer need it. To do this, press the Escape key. Fileshare displays:

FS097-I Are you sure that you wish to close down the Fileshare Server?

Enter Y to confirm that you want Fileshare to terminate. Any other entry causes the Fileshare Server to continue running.

If any data files are still open, the following warning is displayed:

FS111-I Warning - files are still open
        Continue to close down the Fileshare Server (Y/N) ?

Enter Y to confirm that you want Fileshare to terminate. Fileshare automatically closes all data files and rolls back any outstanding transactions. Any other entry causes the Fileshare Server to continue running. This warning indicates one of the following:

  • Fileshare Clients are still active, with open data files
  • A user program terminated abnormally without closing the data files it had open

If you are using the CCITCP protocol and the Fileshare Server terminates abnormally, you can restart the Fileshare Server using the same server-name. However, Fileshare displays the warning message:

FS153-I The Fileshare Server name has been reregistered on the network.
Parent topic: Fileshare Server
Related information
Configuring the Fileshare Server
Starting the Fileshare Server


Configuring CCI Communications for Fileshare

This section describe how to configure the communications between Fileshare Client(s) and Fileshare Server(s). Fileshare clients and servers communicate using the Common Communications Interface (CCI).

  • About Fileshare Communications
  • Specifying the Communications Protocol
  • Using CCITCP
  • About CCISMEM
  • Using CCISMEM
  • Using UNIX named pipes: ccinampu
  • Logging Fileshare Messsages: CCI Trace
  • Using Multiple Protocols with Test Programs
  • Configuring the CCI Timeout
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Database Integrity
Security
Advanced Operation
Fileshare on UNIX
Error Handling
Fileshare Server Messages


About Fileshare Communications

A Fileshare Server communicates with a Fileshare Client using the Common Communications Interface (CCI). A Fileshare Server can use several communication protocols concurrently, enabling it to communicate with a number of Fileshare Clients that do not all use the same protocol.

When you invoke a Fileshare Server, you need to specify the communications protocols it supports, using the /cm option in the Fileshare configuration file. Valid values for /cm are:

Windows platform:

  • TCP IP

    Setting: /ccitcp

  • CCISMEM

    Setting: /ccism

UNIX platform:

  • TCP IP

    Setting: -ccitcp

  • UNIX named pipes (FIFO pipes)

    -ccinampu

Parent topic: Configuring CCI Communications for Fileshare
Related information
Specifying the Communications Protocol
Using CCITCP
About CCISMEM
Using CCISMEM
Using UNIX named pipes: ccinampu
Logging Fileshare Messsages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Using CCITCP

Fileshare defaults to the TCP/IP (CCITCP) protocol. When using CCITCP, you can use either CCITCP Direct or the following process:

  • Both the Fileshare Client and the Fileshare Server must have access to a registration process. Depending upon the product that has been installed there are two versions of the registration server called ccitcp2 or mfds the Micro Focus Directory Server.
  • The registration process helps the Fileshare Client to locate the Fileshare Server.
  • The registration process can be running on any machine that the Fileshare Client and Fileshare Server can contact. It does not have to be running on the same machine as either Fileshare Server or Fileshare Client.
  • You must set the environment variable CCITCP2 to the host name of the machine where the ccitcp2 process is running.

    If you do not set the environment variable, CCITCP assumes that ccitcp2 is running on the local machine. The Fileshare Client and the Fileshare Server must register with the same ccitcp2 process in order to communicate with each other.

    For example, consider the situation where the Fileshare Server and the Fileshare Client are running on different machines and the ccitcp2 process is running on the same machine as the Fileshare Server. The environment variable CCITCP2 does not have to be set on the machine running the Fileshare Server. However, it must be set (on the machine running the Fileshare Client) to the TCP/IP host name of the machine where the Fileshare Server (and the ccitcp2 process) is running.

  • By default both ccitcp2 and mfds will start on TCP (mfds only) and UDP port 86. Both registration processes may be started on different ports. If this has been done then you must set the environment variable CCITCP2_PORT to the decimal number of the port that is being used for the registration process.

    For example, consider the situation where mfds has been started with CCITCP2_PORT set to 2023, or using the -p 2023 option. You must set CCITCP2_PORT to 2023 on both the Fileshare Client and the Fileshare Server.

Many configuration options exist for CCITCP, details of these can be found in the comments within the CCI.INI configuration file.

Parent topic: Configuring CCI Communications for Fileshare
Related information
About Fileshare Communications
Specifying the Communications Protocol
About CCISMEM
Using CCISMEM
Using UNIX named pipes: ccinampu
Logging Fileshare Messsages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


About CCISMEM

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

To also use clients are located on other systems, you must configure Fileshare Server to use CCITCP as well as CCISM. To do this, in cci.in 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 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 CCI.INI.

Parent topic: Configuring CCI Communications for Fileshare
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
Using CCISMEM
Using UNIX named pipes: ccinampu
Logging Fileshare Messsages: 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 method that utilises shared memory.

Shared Memory transfers are usually faster than using TCP/IP between two processes.

To configure Fileshare Server to use CCISMEM you must use the following option:

fs -cm ccism

Provided that you do not intend to run Fileshare server in synchronous mode you can combined multiple communications methods as follows:

fs -cm ccism –cm ccitcp

To configure Fileshare Client to use CCISMEM you must use the following line in FHREDIR.CFG:

/CM ccism

Note: When using CCISMEM the /MA parameter in FHREDIR.CFG has no effect.

Many configuration options exist for CCISMEM, details of these can be found in the comments within the CCI.INI configuration file.

Parent topic: Configuring CCI Communications for Fileshare
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
About CCISMEM
Using UNIX named pipes: ccinampu
Logging Fileshare Messsages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Using UNIX named pipes: ccinampu

Using UNIX named pipes (FIFO pipes)

Parent topic: Configuring CCI Communications for Fileshare
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
About CCISMEM
Using CCISMEM
Logging Fileshare Messsages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Logging Fileshare Messsages: CCI Trace

CCI Trace enables all the messages sent by CCI to be logged to a file. This can help in tracking down and debugging problems related to communications. To activate CCI Trace, add the following to the Fileshare Server configuration file:

/tr cci

To prevent unauthorized access to the CCI Trace information, you are prompted for the supervisor password when you invoke a Fileshare Server with CCI Trace enabled. If the password is accepted, CCI Trace is enabled and a second prompt asks if CCI Trace should be activated immediately or not.

Note:
  • The supervisor password is that specified for the user-ID FSVIEW in the password file, so you must specify the appropriate password file when you start the Fileshare Server.
  • CCI Trace can be toggled on and off using the F3 key.
  • The CCI trace options are specified via the CCITRACE environment variable.
Parent topic: Configuring CCI Communications for Fileshare
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
About CCISMEM
Using CCISMEM
Using UNIX named pipes: ccinampu
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Using Multiple Protocols with Test Programs

Switching between CCITCP protocol and CCISMEM protocol can affect test program timings.

Access to the driver levels usually results in the context switching out of the sending process quite soon after the send attempt has begun. Typically the peer process uses the CPU before the context switches back to the original process.

As a result, with CCITCP, more processing time is required at the driver level than with CCISMEM which has no driver application to call. When CCITCP moves to the drivers to execute the extra data moves, the context is switched out the parent process. On the other hand, using CCISMEM with the same send operation, no context switch occurs. The CCI caller manages when to switch to its peers.

When the configuration is set to async mode (the default) File Share polls CCI to determine if data is present to read. As a result, much more time in CPU processing is spent at the user level, waiting for the next buffer to process. The application and File Share do not context switch to the conversation peer until the end of a full time-slice. That is, the CPU cannot process the next chunk of data and to respond to the original sender until the end of a full time-slice.

This can often cause quite dramatic effects on heavily loaded single CPU systems, or dual/quad core systems, when using test application created with polling loops that have scrolling screen displays.

Highlighting windows and de-selecting them alters the time spent in clients and servers because it changes their system priorities and hence the amount of time that is spent polling around not yielding to let partner processes do their work.

In these cases the fastest route is always to not high-light either client or server, then they both get the same amount of CPU with the smallest time slice. Its a case of the processes running with too much CPU not too little.

The fastest design is of course to not loop at all, then you'll be in the right place to receive the in-bound data when it arrives, and to respond quickly without wasting any CPU cycles in redundant polling.

File share can be configured to avoid the polling loop.

Parent topic: Configuring CCI Communications for Fileshare
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
About CCISMEM
Using CCISMEM
Using UNIX named pipes: ccinampu
Logging Fileshare Messsages: CCI Trace
Configuring the CCI Timeout


Configuring the CCI Timeout

By default, CCI waits 120 seconds for a network request to complete before it times it out and returns an error. If a network request has not completed in a period much shorter than this, it can usually be assumed that it is unnecessary to wait any longer. For example, if a Fileshare Server with the correct server-name is not active when a Fileshare Client attempts its first open, the application appears to hang for 120 seconds before a 9/124 status is returned because the server cannot be contacted. See the section Communications Errors in the chapter Error Handling for more details.

You can configure the Fileshare Client to use a shorter timeout period by using the /ct option in the client configuration file, fhredir.cfg. The timeout period is specified in 1/10th seconds.

For example:

/ct 300

This instructs the Fileshare Client to specify that CCI waits for 30 seconds for network requests to complete. After this time it returns a 9/124 status to the application program.

Parent topic: Configuring CCI Communications for Fileshare
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
About CCISMEM
Using CCISMEM
Using UNIX named pipes: ccinampu
Logging Fileshare Messsages: 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
  • Rollforward recovery
  • Database sequence numbering
  • Automatic database backup
  • Database reference file maintenance
  • Transaction Processing
  • Rollforward Recovery Logging
  • Rollforward Recovery Utility
  • Database Sequence Numbering
  • Automatic Database Backup and Rollforward Recovery
  • Database Reference File Maintenance
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Security
Advanced Operation
Fileshare on UNIX
Error Handling
Fileshare Server Messages


Transaction Processing

Transaction processing enables you to group a set of data file updates together into one logical unit of work, known as a transaction. The changes you make as part of a transaction can be:

  • Permanently reflected in the data files by committing the work
  • Removed from the data files by rolling back the work. When a transaction is rolled back, the Fileshare Server returns the data files to the state they were in before the transaction started.

A transaction can include multiple updates to multiple data files on multiple Fileshare Servers.

A transaction starts when your program performs the first update operation (WRITE, REWRITE or DELETE) on a file which has the WITH ROLLBACK clause defined in its SELECT statement after:

  • The file is opened
  • A COMMIT or ROLLBACK statement is executed

A transaction terminates when:

  • A COMMIT verb is executed
  • A ROLLBACK verb is executed
  • The transaction is timed out. See the section Automatic Record Lock Timeout for further information.
Notes:

  • The COMMIT and ROLLBACK verbs release all the record locks held by a program on every data file. This does not depend on whether or not you specified the WITH ROLLBACK clause for a particular file.
  • The time taken to process a COMMIT or ROLLBACK operation is directly proportional to the number of updates performed in that transaction.
  • If you try to CLOSE a file that is participating in an active transaction, a 9/100 error status is returned and the file remains open. A COMMIT or ROLLBACK needs to be issued before the CLOSE can be executed.
  • When you use the WITH ROLLBACK clause, multiple record locking is implicitly defined on the file.

Before using transaction processing you are strongly advised to do the following to ensure the highest level of integrity for your data:

  • Include any file on which transaction processing is to be performed in the database reference file of the Fileshare Server that services the I/O requests for that file. See the section Database Reference File Maintenance for further information.
  • Specify a rollforward recovery log file in the database reference file. See the section Rollforward Recovery Logging for further information.

Record locks are implicitly obtained on every record that is updated in a transaction. If a transaction is temporarily suspended, for example, if your program requests input and the user is not responding, record locks can remain in the file for a considerable length of time. If another Fileshare Client tries to access the locked records, and a specified length of time has passed, the Fileshare Server aborts (rolls back) the transaction. When this happens, the transaction is said to be timed out by the Fileshare Server. See the section Automatic Record Lock Timeout for further information.

Note:

By keeping the number of updates performed in a transaction to a minimum, the number of record locks obtained is also kept to a minimum. This reduces the number of record locking conflicts between Fileshare Clients sharing the data, and increases the speed of any subsequent COMMIT or ROLLBACK operations.

  • Automatic Record Lock Timeout
  • Transaction Processing - Fileshare Client
  • Transaction Processing - Fileshare Server
Parent topic: Database Integrity
Related information
Rollforward Recovery Logging
Rollforward Recovery Utility
Database Sequence Numbering
Automatic Database Backup and Rollforward Recovery
Database Reference File Maintenance
Automatic Record Lock Timeout
Database Reference File Maintenance
Rollforward Recovery Logging


Automatic Record Lock Timeout

In a multi-user environment where files are being shared, programs use record locks to control concurrent access to individual records. In addition, Fileshare automatically obtains a record lock on any record that it updates within a transaction. The larger the number of record locks being held, however, the less concurrent access to data is possible. It is beneficial, therefore, for any one program to keep the number of record locks that it holds at any one time to a minimum.

If a Fileshare Client obtains a lock on a record (either explicitly or because it updated the record within a transaction) and a second Fileshare Client tries to read the locked record, the Fileshare Server checks to see how long it is since the Fileshare Client holding the record lock last contacted the Fileshare Server. If this period is:

  • Greater than the timeout period, the Fileshare Server:
    • Automatically rolls back any pending transaction being carried out by the first Fileshare Client
    • Releases all the record locks held by the first Fileshare Client
    • Returns error 9/068 "record locked" to the Client trying to read the record. Retrying the operation succeeds in gaining access to the record because the lock has now been released.
  • Less than the timeout period, the Fileshare Server returns error 9/068 "record locked" to the Fileshare Client trying to read the record

The default timeout period is 60 seconds. You can change this value using the /t option in the Fileshare Server configuration file. Specifying a value of zero disables the automatic record lock timeout such that record locks are only released under application program control.

A program that is timed out receives error 9/125 on its next I/O operation. You should treat this as a warning message and repeat the operation on which the error was returned. The Fileshare Server rolls back any active transaction and releases all the record locks held by the program that timed out.

Parent topic: Transaction Processing
Related information
Transaction Processing - Fileshare Client
Transaction Processing - Fileshare Server


Transaction Processing - Fileshare Client

For each data file on which you want transaction processing active, use the WITH ROLLBACK clause when you define the data file using the SELECT statement in your COBOL program.

For example:

select test-file assign to "test.dat"
   organization indexed
   record key prime-key
   lock mode manual with rollback
   ...

This sample code specifies that transaction processing is active on the file test.dat.

In your program, use the COMMIT verb to make the updates in a transaction permanent. Use the ROLLBACK verb to remove the updates in a transaction from the data files.

The COMMIT and ROLLBACK verbs work on all data files involved in a transaction. This means that you cannot check the status of the COMMIT or ROLLBACK operation using the file status of any one data file. Instead, you must call the File Handling Redirector module to check the status of the COMMIT or ROLLBACK. The entry point to call in the the File Handling Redirector module module is fs_status. The format of the call is:

call "fs_status" returning t-status
end-call

where t-status is defined as:

01 t-status  pic x(2) comp-x.

A non-zero value returned in t-status indicates that the COMMIT or ROLLBACK operation failed.

For example:

1   SELECT test-file ASSIGN TO "test.dat"
2      LOCK MODE MANUAL WITH ROLLBACK
3   ...
4   OPEN I-O test-file
5   ...
6   move 1 to prime-key
7   WRITE test-file-record
8   ...
9   COMMIT
10   call "fs_status"
11      returning t-status
12   end-call
13   if t-status < > 0
14      display "Warning - Commit operation failed"
15   end-if
16   move 2 to prime-key
17   WRITE test-file-record
18   ...
19   ROLLBACK
20   call "fs_status"
21      returning t-status
22   end-call
23   if t-status < > 0
24      display "Warning - Rollback operation failed"
25   end-if
26   WRITE test-file-record
27   ...

where:

Lines 1 - 2:
SELECT test-file ASSIGN TO "test.dat"
   LOCK MODE MANUAL WITH ROLLBACK

Specifies transaction processing for this data file.
Line 7:
WRITE test-file-record

Starts a new transaction.
Line 9:
COMMIT

Makes the updates to test-file permanent and terminates the transaction.
Lines 10 - 15:
call "fs_status"
   returning t-status
end-call
if t-status < > 0
   display "Warning - Commit operation failed"
end-if

Checks the status of the COMMIT operation.
Line 17:
WRITE test-file-record

Starts a new transaction.
Line 19:
ROLLBACK

Removes the updates made to test-file and terminates the transaction.
Lines 20 - 25:
call "fs_status"
   returning t-status
end-call
if t-status < > 0
   display "Warning - Rollback operation failed"
end-if

Checks the status of the ROLLBACK operation.
Line 26:
WRITE test-file-record

Starts a new transaction.

You do not need to change the configuration of the Fileshare Client to enable transaction processing.

Parent topic: Transaction Processing
Related information
Automatic Record Lock Timeout
Transaction Processing - Fileshare Server


Transaction Processing - Fileshare Server

You do not need to change the configuration of the Fileshare Server to enable transaction processing. However, if you recover a data file using the Rollforward Recovery Utility, any outstanding transactions at the end of the recovery process are implicitly rolled back. See the section Rollforward Recovery Utility for further information.

Parent topic: Transaction Processing
Related information
Automatic Record Lock Timeout
Transaction Processing - Fileshare Client
Rollforward Recovery Utility


Rollforward Recovery Logging

A system failure can result in loss of data in either of the following circumstances:

  • The Fileshare Server's cache or operating system's cache is not written to disk
  • The system failed while updating a file. In this case, the integrity of the files cannot be guaranteed

Rollforward recovery logging is the method used by Fileshare to store all the updates made to your data files in one or more log files. If your system fails, resulting in loss of data, the Rollforward Recovery Utility together with the log file(s) can be used to re-apply the updates to a back-up copy of the original data files. When the recovery is complete, the files contain the data they contained at the time of the system failure (with any outstanding transactions rolled back).

You do not need to make any changes to the Fileshare Client in order to use rollforward recovery logging.

  • Rollforward Recovery Logging - Fileshare Server
Parent topic: Database Integrity
Related information
Transaction Processing
Rollforward Recovery Utility
Database Sequence Numbering
Automatic Database Backup and Rollforward Recovery
Database Reference File Maintenance


Rollforward Recovery Logging - Fileshare Server

To log updates to one or more files you need to create a database reference file containing the name of the file(s) for which updates are to be logged, and the name of the log file. See the section Database Reference File Maintenance below for details on creating database reference files.

You do not need to include an extension when you specify the log file name as this is generated automatically by the Fileshare Server. If you do specify an extension, the following message is displayed:

FS180-W The log filename specified has an extension. The name of the
log file has been changed to "filename".

During the logging process the Fileshare Server creates one or more recovery log files. The first recovery log file is called a starter log file, and subsequent log files are called continuation log files. The Fileshare Server creates a continuation log file whenever the current log file is backed up.

The current recovery log file always has an extension beginning with the character "L". A recovery log file that has been backed up has an extension beginning with the character "B". Following either of these letters is a two digit number indicating the recovery log file number, starting at 01. These automatically generated extensions indicate the order in which the log files were written, and hence the order in which they should be applied if a rollforward recovery is performed. For example, suppose you specify a log file called recover. When the Fileshare Server starts up it creates a log file called recover.L01 and logs updates in this file. If the recovery log file is backed up, the Fileshare Server renames the current log file recover.B01 and creates a new one called recover.L02. If the Fileshare Server is shut down, there would be two recovery log files: recover.B01 is called the starter log file and recover.L02 is a continuation log file. There is only ever one starter log file, but there can be any number of continuation log files.

When performing a recovery operation, the Rollforward Recovery Utility processes the starter log file first and then the continuation log files in the order in which they were created.

Updates to data files with entries in the database reference file are logged unless you explicitly turn logging off:

  • To add a data file entry to the database reference file, use the /f option of the Database Reference File Maintenance Utility
  • To turn logging off for a particular data file, use the "/o l" (omit logging) option when you add the filename entry to the database reference file

Because of the caching used by some operating systems, not all of the information written to the log file is physically written to disk. The Fileshare Server periodically calls the operating system to force the log file updates to be written. By default, the log file is flushed after every 100 records are written to the log file. You can configure this interval using the /lc (log count) option when you add the log file name to the database reference file. If you specify a log count of zero, the Fileshare Server does not make any calls to the operating system to flush the updates to disk. Instead, the operating system controls the flushing of the log file to disk.

The log file updates are also flushed to disk after every COMMIT operation.

If a transaction was pending at the time of a system failure, the Rollforward Recovery Utility implicitly rolls back the transaction when the files are recovered.

Rollforward recovery logging can severely affect performance. You can use the "/o l" option in the database reference file to switch logging off for those files for which this feature is not essential. Alternatively, you can omit entries for these files from the database reference file altogether.

The recommended method of using recovery logging is:

  1. Each time you want to take a backup of your data files (preferably every day), shut down the Fileshare Server. The Rollforward Recovery Log file(s) contains information about every update made to your database files since the Fileshare Server was started.
  2. Now take a backup of your data files. Once you have backed up your data files, the log file(s) is obsolete (because you only need to log the updates since your last backup) and can be deleted.
  3. Restart the Fileshare Server. It creates a new log file, and any further updates to the files in the database are logged in this new file. In the event of data loss due to a system failure, you can restore your latest database backup and re-apply the updates recorded in the log file(s) using the Rollforward Recovery Utility.
Note:

You can have the Fileshare Server automatically perform this sequence of operations for you by specifying a backup directory in the database reference file. See the section Automatic Database Backup and Rollforward Recovery.

If you have a large number of updates being logged, the log file can grow very large. If the disk where the log file resides were to become full, the ability to write records to the log file could be lost. This would result in an incomplete log file forcing the Fileshare Server to close down. A warning is displayed when the amount of free disk space for the log file drops below a certain percentage of the total disk. You can configure this percentage using the /p database reference file option. When you see this warning, close down the Fileshare Server and take a new backup of your data files. This enables you to discard the log file and continue with a new one when the Fileshare Server is restarted.

If you ignore the warning message and the log file continues to grow larger, the Fileshare Server suspends operation when the free disk space available for the log file drops below 200,000 bytes. It displays error message FS030 and waits for the old log file to be backed-up remotely or removed manually before continuing with a new log file.

Parent topic: Rollforward Recovery Logging
Related information
Database Reference File Maintenance
Automatic Database Backup and Rollforward Recovery


Rollforward Recovery Utility

The Rollforward Recovery Utility enables you to recover updates to data files after a system failure.

Note:

The Rollforward Recovery Utility can only be used to recover a database if the updates were logged to a recovery log file. See the section Rollforward Recovery Logging for further details.

Before attempting the rollforward recovery process:

  • All of the recovery log files created while the Fileshare Server was active should be in the recovery log file directory (or the log file backup directory if one is specified in the database reference file)
  • The original data files (the back-up versions taken before the Fileshare Server was started) should be restored to their correct directories

Use the /r (recover) option to invoke the Rollforward Recovery Utility. You must specify a database reference file when invoking the Rollforward Recovery Utility, for example:

fs /r dbase.ref [options]

Here dbase.ref is the name of the database reference file used by the Rollforward Recovery Utility. This must be the same as the database reference file used by the Fileshare Server while it was running. The Rollforward Recovery Utility reads the database reference file to determine the location and name of the rollforward recovery log file(s) and the name(s) of the data file(s) to recover.

Note:

You can select the data files you want to restore by erasing other entries from the database reference file using the Database Reference File Maintenance Utility (/e option) before invoking the Rollforward Recovery Utility.

You can use the Rollforward Recovery Utility to specify the following options:

  • /dt date-time

    Specifies that the Rollforward Recovery Utility restores the updates made to the data files up to the time specified. The format of date-time is YYMMDDHHMMSS (year, month, day, hour, minutes, seconds) specified numerically. When you do not specify this option, the Rollforward Recovery Utility applies all of the updates that are stored in the rollforward recovery log file.

    For example:

    fs /r dbase.ref /dt 931231235959

    invokes the Rollforward Recovery Utility using the database reference file dbase.ref. Only those updates that were made up to the end of 31 December 1993 are restored.

  • /v

    Causes the Rollforward Recovery Utility to display additional information about which recovery log files it is searching for and in which directories.

Updates can be recorded in multiple log files (see the section Rollforward Recovery Logging for further details). The Rollforward Recovery Utility scans the log file directory for the starter log file. If none is found, the directory is scanned for a backed-up starter log file. If a starter log file still cannot be found the same procedure is repeated with the searches being performed in the backup directory if one is specified in the database reference file. If the Rollforward Recovery Utility is able to locate the starter log file then the recovery procedure commences; if not an error is displayed and the recovery does not start.

Once the starter log file has been processed, the Rollforward Recovery Utility searches for a continuation log file. If no backup of the recovery log file was performed, there is no continuation log file and the recovery process terminates. The Rollforward Recovery Utility searches for the continuation log file in the log file directory and then in the log file backup directory. The recovery process continues using the continuation log file(s) until all of the updates have been recovered and applied to the data files.

If transactions were in progress when the server terminated, then these transactions will be recorded but not committed. In addition, if the server was forced to terminate, then all open files will record a close, even if they were in mid transaction. A rollforward recovery will not be able to commit these transactions and a subsequent normal close would be illegal. When this situation occurs, the user will be informed with the message:

FS290-W Uncommitted transaction recorded - cannot complete transaction.

followed by the name of the file that cannot complete the transaction.

Parent topic: Database Integrity
Related information
Transaction Processing
Rollforward Recovery Logging
Database Sequence Numbering
Automatic Database Backup and Rollforward Recovery
Database Reference File Maintenance
Rollforward Recovery Logging


Database Sequence Numbering

Database sequence numbering provides a method of linking groups of data files so that they and their corresponding log file can be kept in step.

A sequence number, contained in the log file, is automatically stored in the header of each data file for which you have specified sequence numbering. Fileshare increments these sequence numbers every time you invoke the Fileshare Server. In order for the Rollforward Recovery Utility to work, all data files must have sequence numbers that match the log file. If the sequence numbers in the data files do not match, the Fileshare Server fails to start after displaying this message:

FS038-S A matching sequence number not found in <filename>

The possible causes for this error are:

  • A data file has been replaced by a file that does not contain the same sequence number as all the other data files listed in the database reference file. To recover, you need to install the correct file(s) on the system.
  • A power failure prevented proper shutdown of the Fileshare Server when it was last running. To recover the database files, use rollforward recovery. See the section Rollforward Recovery Utility for further information.

All data files listed in the database reference file have sequence number checking active by default. You can turn off sequence number checking using the database reference file option "/o s" (omit sequence numbering). If sequence number checking is not used on a file, your system administrator must make sure that the correct version of the file is installed in the Fileshare System.

Sequence numbering is only available on data files with a variable length record file header. The following file organizations do not contain headers and so sequence number checking is not possible:

  • Line sequential files
  • Non-data-compressed fixed length record sequential files
  • C-ISAM files
  • Non-data-compressed fixed length record relative files

If you have fixed length record data files that you want to use sequence numbering on, create them as variable length record data files. You can do this by changing the file definition in your COBOL program before creating the file.

Example

Data file definition specifying fixed length records:

 FD account-file.
 01 account-file-record.
    03 account-file-prime pic x(4).

Equivalent data file definition specifying variable length records:

 FD account-file recording mode is variable.
 01 account-file-record.
    03 account-file-prime pic x(4).

You do not have to change the configuration of the Fileshare Client or your program to make use of database sequence numbers.

  • Database Sequence Numbers - Fileshare Server
Parent topic: Database Integrity
Related information
Transaction Processing
Rollforward Recovery Logging
Rollforward Recovery Utility
Automatic Database Backup and Rollforward Recovery
Database Reference File Maintenance
Rollforward Recovery Utility


Database Sequence Numbers - Fileshare Server

For data files that you entered in the database reference file, sequence number checking is on by default. If you do not need sequence number checking for a particular data file, you can disable the feature by using the /o s (omit sequence numbers) option for that data file's entry in the database reference file.

Example

fs /d dbase.ref /l \logdir\log.dat
fs /d dbase.ref /f test1.dat
fs /d dbase.ref /f test2.dat /o l
fs /d dbase.ref /f test3.dat /o s

This example specifies:

  • The database reference file is named dbase.ref
  • The log file is named log.dat in the logdir directory
  • Updates to the data file test1.dat are logged in the log file. By default, sequence number checking is on for any data file in the database reference file, and hence for this file
  • Updates to the data file test2.dat are not logged in the log file. The "/o l" option specifies that logging is omitted. However, sequence number checking is still active for this file.
  • Updates to the data file test3.dat are logged in the log file. However, sequence number checking is not activated for this data file. The "/o s" option specifies that sequence number checking is not used on this data file.
Parent topic: Database Sequence Numbering


Automatic Database Backup and Rollforward Recovery

The recommended method of using Fileshare's update logging for rollforward recovery is:

  1. Periodically to shut down the Fileshare Server
  2. Take a backup of all your database files
  3. Re-start the Fileshare Server with a fresh recovery log file

See the section Rollforward Recovery Logging for further details.

You can get Fileshare to do this for you automatically by specifying a backup directory-name in the database reference file using the /backup option. For example, the command:

fs /d dbase.ref /backup	c:\backdir

adds an entry to the database reference file called dbase.ref which specifies the backup directory as c:\backdir. A full path can be specified for the backup directory, otherwise paths which are not fully qualified are taken to be relative to the current directory of the Fileshare Server.

Setting a backup directory in this way causes the Fileshare Server to copy all the data files specified in the database reference file to the directory c:\backdir or /backdir on startup. The Fileshare Server also deletes any recovery log file(s) that it finds since this data is obsolete once the database files have been backed up.

While the Fileshare Server is active, all updates to files which have logging switched on for them are recorded in the log file as normal. The next time the Fileshare Server is restarted, it backs up the database files again and discards any log file(s). However, if it detects that the previous Fileshare Server session did not shut down successfully and a valid terminating record had not been written to the log file (for example, as a result of a system crash), then Fileshare automatically triggers the Rollforward Recovery Utility. This automatically restores the previous backup of the database files and recovers all updates to them as recorded in the log file(s). If the recovery completes succesfully, the Fileshare Server starts up as normal.

It is still possible to run the Rollforward Recovery Utility manually before starting up the Fileshare Server when a backup directory is specified in the database reference file. The Rollforward Recovery Utility automatically restores the previous backup before initiating the recovery.

Note:

The purpose of the automatic database backup facility is to help database administrators follow the recommended steps for rollforward recovery, thus ensuring that the latest Fileshare log file contains only the updates made since the last database backup. If database files are added or replaced manually, Fileshare may not detect this and could backup or restore the incorrect version of a file, compromising the integrity of your data. We recommend, therefore, that you do not attempt to replace any of the database files manually and only ever use Fileshare operations such as closing down the server to back up the entire database.

If you have enabled automatic database backup by specifying a backup directory, you cannot use the "/o l" option to switch logging off for any of the data files declared in the database reference file. By having logging active for every file specified in the database reference file, Fileshare can guarantee that it can recover updates to them all when it copies backed-up versions from the backup directory. If there are some files for which you do not require automatic backup, omit them from the database reference file.

If you need to back up your Fileshare files, for example as part of a system-wide backup overnight, you can use a Fileshare Manager API function to request Fileshare to shut down, back up all the database files and then restart with a fresh log file. Having done this, we recommend that you then make a permanent hard copy of the Fileshare backup directory. See the section Fileshare Manager in the chapter Advanced Operation for more information.

Example

fs /d dbase.ref /l logfile
fs /d dbase.ref /backup c:\backdir
fs /d dbase.ref /f c:\accounts\customer.dat
fs /d dbase.ref /f c:\finance\history.dat

These commands perform the following:

  • Create a database reference file called
          dbase.ref

    •

  • Specify the recovery log file as
          logfile so that the first log file that the Fileshare Server creates is called
          logfile.L01

    •

  • Specify that any updates to the files
          c:\accounts\customer.dat and
          c:\finance\history.dat are logged

    •

  • Specify
          c:\backdir as the backup directory

    •

On startup, the Fileshare Server automatically backs up these data files in the directory
        c:\backdir or
        /backdir. If the log file is backed-up while the Fileshare Server is active, backup files are also placed in this directory. If the Rollforward Recovery Utility is invoked, the backup files in
        c:\backdir or
        /backdir are restored to their original directories and any updates recorded in the log file(s) are re-applied.
Parent topic: Database Integrity
Related information
Transaction Processing
Rollforward Recovery Logging
Rollforward Recovery Utility
Database Sequence Numbering
Database Reference File Maintenance
Rollforward Recovery Logging
Fileshare Manager


Database Reference File Maintenance

The database reference file contains information that the Fileshare Server uses to determine which Fileshare features you want to use on which files. This section explains how to create and update a database reference file in order to make use of the features described earlier in this chapter.

Note:
  • You should only create or change a database reference file using the Database Reference File Maintenance Utility. This is because the file contains information that is stored in a special format.

The Database Reference File Maintenance Utility is invoked using the /d (database) option, for example:

fs /d dbase.ref [options]

where the parameters are:

dbase.ref | Name of the database reference file. If the database reference file does not exist, it is created.
options | These specify the operation to be carried out on the database reference file. Each initiation of the Database Reference File Maintenance Utility adds a record to or removes a record from the database reference file specified.

You can add several types of record to the database reference file.

  • Recovery Log File Records
  • Filename Record
  • File String Record
  • Backup Folder Record
Parent topic: Database Integrity
Related information
Transaction Processing
Rollforward Recovery Logging
Rollforward Recovery Utility
Database Sequence Numbering
Automatic Database Backup and Rollforward Recovery


Recovery Log File Records

You specify the name of the recovery log file using the /l option, for example:

fs /d dbase.ref /l logfilename

You can only have one recovery log file record in a database reference file.

You can specify the following for a recovery log file record:

  • The point at which the Fileshare Server displays a warning when the drive containing the log file is becoming full (use the /p option)
  • How often the log file is flushed to disk (use the /lc option)
  • Deletion of the record (use the /e option)
  • Disk Space Warning (/p)
  • Flushing the Log File (/lc)
  • Erasing a Log File Record (/e)
  • Example
Parent topic: Database Reference File Maintenance
Related information
Filename Record
File String Record
Backup Folder Record


Disk Space Warning (/p)

You can specify the point at which the Fileshare Server displays a warning when the drive containing the log file is becoming full using the /p option:

fs /d dbase.ref /l logfilename /p nnn

where nnn specifies the percentage disk space remaining, below which the Fileshare Server displays a warning message. The default value is 5, that is, the Fileshare Server displays the warning message when the drive containing the log file contains less than 5% free space.

Parent topic: Recovery Log File Records
Related information
Flushing the Log File (/lc)
Erasing a Log File Record (/e)
Example


Flushing the Log File (/lc)

You can specify how often the log file is flushed to disk using the /lc option:

fs /d dbase.ref /l logfilename /lc nnn

where nnn specifies the number of records that are written to the log file before the Fileshare Server calls the operating system to flush the log file buffers to disk. The default value is 100, that is, the Fileshare Server flushes the log file to disk after each set of 100 records are written to it. In addition, the Fileshare Server automatically flushes the log file after every successful COMMIT operation.

The Fileshare Server is unable to flush a log file if the log file is not on the machine where the Fileshare Server is running or if the operating system does not allow Fileshare to force the log file to be flushed. In this situation, the "/lc 1" option forces the Fileshare Server to specify writethrough when opening the log file. The log file is then written to disk if the operating system supports writethrough on files.

Parent topic: Recovery Log File Records
Related information
Disk Space Warning (/p)
Erasing a Log File Record (/e)
Example


Erasing a Log File Record (/e)

You can erase a recovery log file record using the /e option:

fs /d dbase.ref /l logfilename /e

This is the only way to remove a record once you have created the database reference file.

Parent topic: Recovery Log File Records
Related information
Disk Space Warning (/p)
Flushing the Log File (/lc)
Example


Example

fs /d dbase.ref /l \log\log.dat /p 10 /lc 200

Specifies the log file as log.dat in the directory log. Any data files that are specified in this database reference file have all updates recorded in this log file, unless logging is explicitly disabled for a data file. The /p option specifies that the Fileshare Server displays a warning message when less than 10 percent of the disk space remains free on the drive where the log file resides. The /lc option specifies that the Fileshare Server flushes the log file to disk after every 200 records are written to it.

Parent topic: Recovery Log File Records
Related information
Disk Space Warning (/p)
Flushing the Log File (/lc)
Erasing a Log File Record (/e)


Filename Record

You specify a filename record using the /f option, for example:

fs /d dbase.ref /f filename

specifies a data file that you want to include in the database reference file.

Any file that you specify in the database reference file has logging and, for those file organizations that support it, database sequence numbering, enabled by default.

You can specify the following for a filename record:

  • An alternative filename (use the /af option)
  • A virtual file handler (use the /ap option)
  • Data and key compression (use the /k option)
  • That logging is disabled for this file (use the "/o l" option)
  • That database sequence numbering is disabled for this file (use the "/o s" option)
  • That transaction processing is disabled for this file (use the "/o t" option)
  • Deletion of the record
  • Alternative Filename (/af)
  • Virtual File Handler (/ap)
  • Data and Key Compression (/k)
  • Disable Logging (/o l)
  • Disable Database Sequence Numbering (/o s)
  • Disable Transaction Processing (/o t)
  • Erasing a Filename Record
  • Examples
Parent topic: Database Reference File Maintenance
Related information
Recovery Log File Records
File String Record
Backup Folder Record


Alternative Filename (/af)

You can specify an alternative filename for a filename record using the /af option:

fs /d dbase.ref /f filename /af alternate-filename

such that whenever the Fileshare Server is asked to access the data file filename, it accesses alternate-filename instead.

Parent topic: Filename Record
Related information
Virtual File Handler (/ap)
Data and Key Compression (/k)
Disable Logging (/o l)
Disable Database Sequence Numbering (/o s)
Disable Transaction Processing (/o t)
Erasing a Filename Record
Examples


Virtual File Handler (/ap)

You can specify a virtual file handler for a filename record using the /ap option:

fs /d dbase.ref /f filename /ap program-name

where program-name specifies the virtual file handler that the Fileshare Server calls to process all I/O requests on the data file. See the section Virtual File Handler in the chapter, Advanced Operation.

The filename definition in the /f entry (corresponding to an /ap entry) can include a trailing wildcard to specify that groups of files are to have their requests passed to the specified virtual file handler.

Parent topic: Filename Record
Related information
Alternative Filename (/af)
Data and Key Compression (/k)
Disable Logging (/o l)
Disable Database Sequence Numbering (/o s)
Disable Transaction Processing (/o t)
Erasing a Filename Record
Examples


Data and Key Compression (/k)

You can specify data and key compression for a filename record using the /k option, for example:

fs -d dbase.ref /f filename /k DnnnIx

where nnn specifies the data compression routine number and x specifies the key compression number. Valid values for nnn and x are the same as those that can be specified for the Compiler directives DATACOMPRESS and KEYCOMPRESS.

Parent topic: Filename Record
Related information
Alternative Filename (/af)
Virtual File Handler (/ap)
Disable Logging (/o l)
Disable Database Sequence Numbering (/o s)
Disable Transaction Processing (/o t)
Erasing a Filename Record
Examples


Disable Logging (/o l)

You can disable logging for a file using the "/o l" option:

fs /d dbase.ref /f filename /o l

disables logging for filename.

Note:

You cannot disable logging for a file if you have enabled automatic database backup by specifying a backup directory record.

Parent topic: Filename Record
Related information
Alternative Filename (/af)
Virtual File Handler (/ap)
Data and Key Compression (/k)
Disable Database Sequence Numbering (/o s)
Disable Transaction Processing (/o t)
Erasing a Filename Record
Examples


Disable Database Sequence Numbering (/o s)

You can disable database sequence numbering for a file using the "/o s" option:

fs /d dbase.ref /f filename /o s
disables database sequence numbering for filename.
Note:

You should be aware that even with database sequence checking turned off, Fileshare will still update the sequence number in the header of the data file and thus also the timestamp. This is to ensure that if sequencing is turned back on, the sequence numbers will be in sync with other files.

Parent topic: Filename Record
Related information
Alternative Filename (/af)
Virtual File Handler (/ap)
Data and Key Compression (/k)
Disable Logging (/o l)
Disable Transaction Processing (/o t)
Erasing a Filename Record
Examples


Disable Transaction Processing (/o t)

You can disable transaction processing for a file using the "/o t" option:

fs /d dbase.ref /f filename /o t

disables transaction processing for filename. The WITH ROLLBACK clause in a SELECT statement for this data file is ignored. This option in the database reference file overrides any transaction processing specified in your program.

Parent topic: Filename Record
Related information
Alternative Filename (/af)
Virtual File Handler (/ap)
Data and Key Compression (/k)
Disable Logging (/o l)
Disable Database Sequence Numbering (/o s)
Erasing a Filename Record
Examples


Erasing a Filename Record

You can erase a filename record using the /e option, for example:

fs /d dbase.ref /f filename /e

erases the record from the database reference file. This is the only way to remove a record once the database reference file has been created.

Parent topic: Filename Record
Related information
Alternative Filename (/af)
Virtual File Handler (/ap)
Data and Key Compression (/k)
Disable Logging (/o l)
Disable Database Sequence Numbering (/o s)
Disable Transaction Processing (/o t)
Examples


Examples

fs /d dbase.ref /f \accounts\nomlgr.dat /k d001i7

specifies that the data file nomlgr.dat in the directory accounts has data compression and key compression activated if it is created by the Fileshare Server. The d001 option specifies the data compression routine you want to use is the same as if you compiled your program with the DATACOMPRESS"1" Compiler directive. The i7 option specifies the key compression to use is the same as if you compiled your program with the KEYCOMPRESS"7" Compiler directive. This overrides any data or key compression specified in the program.

fs /d dbase.ref /f \accounts\salesday.dat /o tl

specifies that any transaction processing specified in your program for the data file salesday.dat in the directory accounts is ignored. Also, logging is disabled for this file.

fs /d dbase.ref /f \ref\clients.dat /af \oldref\oldclnts.dat /o s

specifies that all I/O requests for the data file clients.dat in the directory ref are redirected to the data file oldclnts.dat in the directory oldref. In addition, database sequence numbering is disabled for this file.

fs /d dbase.ref /f \accounts\saleslgr.dat

enables logging and database sequence numbering for the data file saleslgr.dat in the directory accounts. By default, logging and database sequence numbering are enabled for every data file listed in the database reference file.

fs /d dbase.ref /f \orders\week10.dat

enables logging and database sequence numbering for the data file week10.dat in the directory orders. By default, logging and database sequence numbering are enabled for every data file listed in the database reference file.

Parent topic: Filename Record
Related information
Alternative Filename (/af)
Virtual File Handler (/ap)
Data and Key Compression (/k)
Disable Logging (/o l)
Disable Database Sequence Numbering (/o s)
Disable Transaction Processing (/o t)
Erasing a Filename Record


File String Record

You specify a file string record using the /fs option, for example:

fs /d dbase.ref /fs string1 /af string2

specifies that for any data file with a filename starting with string1, string1 is replaced by the character string string2.

  • Erasing a File String Record
  • Example
Parent topic: Database Reference File Maintenance
Related information
Recovery Log File Records
Filename Record
Backup Folder Record


Erasing a File String Record

You can erase a file string record using the /e option:

fs /d dbase.ref /fs string /e

erases the record from the database reference file. This is the only way to remove a record once the database reference file has been created.

Parent topic: File String Record
Related information
Example


Example

fs /d dbase.ref /fs c:\accounts\ /af c:\lastyear\accounts\

specifies that the character string c:\accounts\ at the front of any filename is replaced by the character string c:\lastyear\accounts\. Note that the string specified by the /fs option is not expanded relative to the Fileshare Server's current directory.

Parent topic: File String Record
Related information
Erasing a File String Record


Backup Folder Record

You specify an automatic backup directory using the /backup option, for example:

fs /d dbase.ref /backup c:\backup

specifies that on startup the Fileshare Server automatically copies all of the files named in the database reference file into the directory c:\backup.

Parent topic: Database Reference File Maintenance
Related information
Recovery Log File Records
Filename Record
File String Record


Security

Fileshare provides security features which enable you to restrict access to a Fileshare Server.

You can also restrict access to specific data files under the control of a Fileshare Server. These restrictions are implemented via:
  • The Fileshare Password System
  • The Logon Validation module
  • The File Access Validation module
  • Password System
  • Logon Validation Module
    To validate a request to log on from a Fileshare Client, the Fileshare Server calls the module FSSecLog (the Fileshare Security at Logon Validation module) to validate the user-ID and password. You can replace FSSecLog with your own module in order to use your own criteria for validating the log on request. Your new module must comply with the FSSecLog interface described below.
  • File Access Validation Module
    To validate an open request from a Fileshare Client, the Fileshare Server calls the Fileshare Security at Open Validation module (FSSecOpn).
  • Password File Maintenance
  • User-ID Groups
  • Supervisor Mode
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Advanced Operation
Fileshare on UNIX
Error Handling
Fileshare Server Messages


Password System

If you invoke the Fileshare Server with the Password System enabled, all Fileshare Clients must supply a valid user-ID and password before they can connect to the Fileshare Server. By default, the Fileshare Password System is not enabled when you invoke the Fileshare Server.

If you want to use the Fileshare Password System you must code your program to pass a user-ID and password to the File Handling Redirector module and you must create a password file on the Fileshare Server machine which contains the user-ID and password that your program will use.

Then, to enable the Fileshare Password System, you must use the /pf option to specify the name of the password file to the Fileshare Server.

With the Fileshare Password System enabled, the sequence of steps that your program and Fileshare follow is (see the figure below):

  1. Your program registers its user-ID and password with the Fileshare Client by calling the File Handling Redirector password module (FHRdrPwd)
  2. Your program performs the first I/O operation
  3. The File Handling Redirector module obtains the user-ID and password registered in step 1 by calling the File Handling Redirector password module (FHRdrPwd)
  4. File Handling Redirector module passes the user-ID and password to the Fileshare Server
    Figure 1. Fileshare Password System
    Fileshare Password System
  5. The Fileshare Server validates the user-ID and password using the password file.
  6. If the Fileshare Server allows the logon, a connection is established between the Fileshare Client and the Fileshare Server. If the Fileshare Server does not allow logon, it returns a file status of 9/037 ("access denied") to the Fileshare Client.

Each of these steps is explained in more detail in the topics that follow.

  • Fileshare Client
  • Fileshare Server
  • Writing Your Own FHRdrPwd Module
Parent topic: Security
Related information
Logon Validation Module
File Access Validation Module
Password File Maintenance
User-ID Groups
Supervisor Mode


Fileshare Client

When Fileshare security is active, your program must supply a user-ID and a password before the first I/O operation is performed.

Even if you have not activated security, your program can still supply the Fileshare Client with a user-ID and password. This enables your program to run unchanged on Fileshare whether or not security is activated.

To register a user-ID and password, your program must call the module FHRdrPwd as follows:

call "fhrdrpwd" using function-code,
                      user-ID,
                      user-password
end-call

where the parameters are:

01 function-code       pic x comp-x.
01 user-ID             pic x(20).
01 user-password       pic x(20).

The function code to register a user-ID and password is 1.

The following example shows how to register a user-ID and password:

working-storage section.
01 function-code    pic x comp-x.
01 user-name        pic x(20).
01 user-password    pic x(20).
...
procedure division.
...
    move 1 to function-code
    move "UserID" to user-name
    move "Password" to user-password
    call "fhrdrpwd" using function-code,
                        user-name,
                        user-password
    end-call
    ...
    open output testfile
    ...

You can substitute the FHRdrPwd module supplied with the Fileshare System with your own. This enables you to retrieve the user-ID and password from somewhere other than the application program. See the section Writing Your Own FHRdrPwd Module for further details.

Parent topic: Password System
Related information
Fileshare Server
Writing Your Own FHRdrPwd Module
Writing Your Own FHRdrPwd Module


Fileshare Server

By default, the Fileshare Password System is not active when you invoke the Fileshare Server. If you want password security activated, use the /pf (Password File) option in the Fileshare Server configuration file, for example:

Windows:

/pf password.fil /s server1

UNIX:

-pf password.fil -s server1

specifies that for the Fileshare Server, server1, Fileshare Password Security is enabled and the password file is password.fil. The Fileshare Server uses this file to determine whether a Fileshare Client is allowed to connect to this Fileshare Server.

The Password File Maintenance Utility is used to create the password file and add user-ID and password entries. See the section Password File Maintenance for further information on this utility.

Parent topic: Password System
Related information
Fileshare Client
Writing Your Own FHRdrPwd Module
Password File Maintenance


Writing Your Own FHRdrPwd Module

To register a user-ID and password, your program must call the File Handling Redirector password module supplying a user-ID and password. If you do not want to hard-code this call into your program, you can replace the supplied File Handling Redirector password module with one that obtains the user-ID and password using a different method (for example, via a screen prompt). Your new module must still conform to the File Handling Redirector password module interface, that is:

Function Code | Action
= 1: | Register the supplied user-ID and password
= 0: | Return the user-ID and password. The File Handling Redirector module uses this call to obtain the user-ID and password when it is about to connect to the Fileshare Server.

Once you have written your own File Handling Redirector password module:

  • Create a cobfhrdrpwd.dll containing your module and ensure it is on the search path, PATH (you can do that by copying the file on the search path).

You can create an object module and link it into any application executable as required.

Parent topic: Password System
Related information
Fileshare Client
Fileshare Server


Logon Validation Module

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.

Introduction

If you have not activated the Fileshare Password System, the Fileshare Server validates requests to log on by calling the Fileshare Security Logon validation module (FSSecLog).

The FSSecLog module supplied with Fileshare allows any Fileshare Client to log on to a Fileshare Server. If you need to restrict the Fileshare Clients that can log on to a Fileshare Server, you must provide your own, alternative, FSSecLog module for the Fileshare Server to call.

For example, your own module can enable integration with the native operating system security, if this is needed.

The sequence of steps that your program and Fileshare follow is (see Figure 5-2):

  1. Your program registers a user-ID and password by calling the File Handling Redirector password module (FHRdrPwd)
  2. Your program performs the first I/O operation
  3. The File Handling Redirector module obtains the user-ID and password registered in step 1 by calling its password module (FHRdrPwd)
  4. The File Handling Redirector module passes the user-ID and password to the Fileshare Server
  5. The Fileshare Server calls the FSSecLog module passing the user-ID and password
  6. If the FSSecLog module allows logging on, a connection is established between the Fileshare Client and the Fileshare Server. If the FSSecLog module does not allow logging on, a status 9/037 "access denied" is returned to the Fileshare Client.

Logon Validation Module

Syntax:

call "fsseclog" using user-ID
                      password
                      return-status

Parameters:

user-ID | pic x(20).
password | pic x(20).
return-status | pic x comp-x.

On Entry:

user-ID | The Fileshare Client's user-ID
password | The Fileshare Client's password

On Exit:

user-ID | Unchanged
password | Unchanged
return-status | Set to 0 if the Fileshare Client is allowed to log onto the Fileshare Server. Any other status indicates the Fileshare Client is not allowed to log on and an error is returned to the Fileshare Client.

Comments:

Windows:

To use your own fsseclog module, create and link it into cobfssecurity.dll and place it on the search path, PATH. Fileshare will notify you that it has loaded the user security modules.

UNIX:

To use your own fsseclog module, create and link it into a cobfssecurity shared object and place it on the search path, LD_LIBRARY_PATH (or SHLIB_PATH, or LIBPATH on different UNIX platforms). Fileshare will notify you that it has loaded the user security modules.

Parent topic: Security
Related information
Password System
File Access Validation Module
Password File Maintenance
User-ID Groups
Supervisor Mode


File Access Validation Module

To validate an open request from a Fileshare Client, the Fileshare Server calls the Fileshare Security at Open Validation module (FSSecOpn).

Whenever a Fileshare Server receives an open request on a file from a Fileshare Client, the Fileshare Server calls the Fileshare Security at Open validation module (FSSecOpn).

The Fileshare Security at Open Validation module supplied with Fileshare allows any Fileshare Client to access a data file. If you need to restrict access to specific files, you must provide your own, alternative, Fileshare Security at Open Validation module for the Fileshare Server to call.

If the Fileshare Security at Open Validation module allows the file access, the operation is allowed to complete. If the module does not allow the file access, a file status of 9/037 "access denied" is returned to the Fileshare Client and the operation is not allowed to complete.

Note: This file access security check is entirely independent of the Fileshare Password System and the User Supplied Logon Validation Module.

The sequence of steps that your program and Fileshare follow are:

  1. Your program registers its user-ID and password with the File Handling Redirector password module. This information is used when the Fileshare Client first logs onto the Fileshare Server.
  2. When your program subsequently performs an I/O operation on a file that it does not have open (such as an Open or Delete file operation), the Fileshare Server calls the Fileshare Security at Open Validation module (FSSecOpn)

You can replace the supplied Fileshare Security at Open Validation module with one of your own in order to use your own criteria for validating the open request. Your new module must comply with the Fileshare Security at Open Validation module's interface described below

Syntax:

call "fssecopn" using filename
                      filename-length
                      operation-code
                      user-ID
                      return-status

Parameters:

filename | pic x(n).
filename-length | pic x(2) comp-x.
operation-code | pic x(2) comp-x.
user-ID | pic x(20).
return-status | pic x comp-x.

On Entry:

filename | The name of the data file that the Fileshare Client wants to open
filename-length | The length of filename
operation-code | The operation code specifying the I/O operation. These codes are those used by the Callable File Handler. See your online help for details on the Callable File Handler.
user-ID | The user-ID of the Fileshare Client making the open request

On Exit:

return-status Set to 0 if the open request is allowed. Any other status indicates that the Fileshare Client is not allowed to open the data file and an error status is returned.

Comments:

Windows:

You can create your own fssecopn module, link it into the cobfssecurity.dll and place it on the search path, PATH. Fileshare will notify you that it has loaded the user security modules.

UNIX:

You can create your own fssecopn module, link it into a cobfssecurity shared object and place it on the search path, LD_LIBRARY_PATH (or SHLIB_PATH, or LIBPATH on different UNIX platforms). Fileshare will notify you that it has loaded the user security modules.

Parent topic: Security
Related information
Password System
Logon Validation Module
Password File Maintenance
User-ID Groups
Supervisor Mode


Password File Maintenance

The password file contains details of user-IDs and passwords that the Fileshare Server uses when Fileshare Password Security is enabled. Because the information in the password file is encrypted for security reasons, you can only add records to and remove records from the password file using the Password File Maintenance Utility.

Use the /pf (password file) option to add or remove entries in the password file, for example:

fs /pf pass.dat [options]

This invokes password file maintenance and appends the specified options to the password file pass.dat. If this file does not exist, it is created.

The following options are available:

  • /u user-ID
    /pw password

    These add the specified user-ID and password to the password file. Both user-ID and password are case-sensitive and can be up to 20 characters in length.

  • [/e]

    This erases the record from the password file and is the only way to remove a record once the password file has been created.

Example

fs /pf pass.dat /u pkel /pw fishwife

This example invokes password file maintenance, creates or updates a password file called pass.dat and adds a user-ID of pkel and password of fishwife.

Parent topic: Security
Related information
Password System
Logon Validation Module
File Access Validation Module
User-ID Groups
Supervisor Mode


User-ID Groups

You can group user-IDs by using the # character. If the # character is present in a user-ID, Fileshare registers the full passed user-ID but only performs logon validation on the portion of the user-ID prior to the # character.

When adding entries to the password file, you should create them as exclusive up to the # character. See the section Password File Maintenance for further information.

If you use view a user with a utility such as FSVIEW, the user information returned will show the full user-ID supplied by the client. Note that any reference to a user must be made using the full user-ID.

Example

fs /pf pass.dat /u pkel#1 /pw fishwife

This example invokes password file maintenance, creates or updates a password file called pass.dat and adds a user-ID of pkel#1 and password of fishwife.

Parent topic: Security
Related information
Password System
Logon Validation Module
File Access Validation Module
Password File Maintenance
Supervisor Mode
Password File Maintenance


Supervisor Mode

In order to use the password-restricted functions of Fileshare Manager, a supervisor password must be defined (see the section Fileshare Manager in the chapter Advanced Operation).

To define a supervisor password, an entry must be made in the password file using the reserved user-ID, FSVIEW. Note that the user-ID FSVIEW must be entered in upper case.

If you are already using Fileshare Password Security, simply add the FSVIEW entry to your existing file.

If you are not using Fileshare Password Security, you can create a password file that contains a single entry, the FSVIEW user-ID. This defines a supervisor password without enabling Fileshare Password Security.

Example

The following example defines a supervisor password of "abracadabra" in the password file password.fil. If the file does not exist, it is created.

fs /pf password.fil /u FSVIEW /pw abracadabra

Once you have defined a supervisor password, you must specify the password file, either in the Fileshare Server configuration file, or on the command line when the Fileshare Server is started.

Note:

If FSVIEW is the only entry in the password file, the Fileshare Server displays a message indicating that Fileshare Password Security is disabled, even though a password file has been specified.

Parent topic: Security
Related information
Password System
Logon Validation Module
File Access Validation Module
Password File Maintenance
User-ID Groups
Fileshare Manager


Advanced Operation

This chapter describes the advanced features that are available with Fileshare.

  • Single User Mode
  • Filename Mapping
  • Data and Key Compression
  • Virtual File Handler Interface
  • Monitoring Fileshare
  • Fileshare Manager
  • Fileshare Manager Configuration
  • Linking Fileshare Manager Applications
  • Byte-stream I/O Calls
  • Running Fileshare as a Windows Service
  • Fileshare Server Configuration
  • Performance Considerations
  • Large File Support with Fileshare
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Fileshare on UNIX
Error Handling
Fileshare Server Messages


Single User Mode

You can configure Fileshare to run in single user mode. All network communication is bypassed and the Fileshare Client makes direct calls to the Fileshare Server module. The Fileshare Server does not run as a separate process in this mode of operation.

This is useful when:

  • You want to develop Fileshare applications without using a network or multiple sessions
  • A single-user application makes use of one of Fileshare's advanced features, such as transaction processing

To run Fileshare in single user mode, set the FSCOMMS environment variable to $local, for example:

set FSCOMMS=$local /s servername

Even when you are running in single user mode, you must still inform the Fileshare Client which Fileshare Server to use, either by specifying the Fileshare Server name as part of the filename in your program or by using a Fileshare Client configuration file.

The Fileshare Server is configured in the normal way using a Fileshare Server configuration file. At the minimum, you must define a Fileshare Server name in this file.

Note:

The Fileshare Server does not have control over the screen when it is running in single user mode. It directs all screen output to the file fsscreen.lst in the current Fileshare Client directory. If your program fails, check this file for messages.

The FSSERVER environment variable must be unset.

Parent topic: Advanced Operation
Related information
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Running Fileshare as a Windows Service
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare


Filename Mapping

Filename mapping enables I/O requests made against one data file to be mapped to a different data file when your program is executed. For example, you can use filename mapping to enable applications that use DOS file naming conventions to access data files under the control of a Fileshare Server running on an operating system that uses different file naming conventions.

You do not need to change the configuration of the Fileshare Client to use filename mapping.

  • Fileshare Server
Parent topic: Advanced Operation
Related information
Single User Mode
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Running Fileshare as a Windows Service
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare


Fileshare Server

To enable filename mapping, use the /af (alternate filename) option with the /f option in the database reference file.

The /fs (filename string) option used in conjunction with the /af option enables you to substitute characters at the start of a filename. This is particularly useful for mapping pathnames.

For example:

fs /d dbase.ref /f old.dat /af new.dat
fs /d dbase.ref /fs c: /af e:

adds entries to the database reference file dbase.ref which specify that:

  • All requests to the data file old.dat are redirected to the data file new.dat
  • All accesses to data files starting with c: are directed to drive e:

If the Fileshare Server finds an entry specifying an alternate filename, any character string substitution specified by a /fs option is applied to the new filename.

After processing any string substitution specified by an /fs option, the Fileshare Server does not search the database reference file for any matching /f option using the new filename.

Fileshare processes all filenames as relative to the Fileshare Server's current directory if you have not given a fully qualified filename after the /f option or a fully qualified filename is not passed from the Fileshare Client.

All filenames and paths are forced to upper case by Fileshare Servers 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 information
Single User Mode
Filename Mapping
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Running Fileshare as a Windows Service
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare


Data and Key Compression - Fileshare Server

To enable data or key compression for a data file, use the /k option in the database reference file. In conjunction with the /k option, use the d option to specify data compression and the i option to specify key compression.

Values that you specify after the d and i options are the same values that you would specify using the Compiler directives DATACOMPRESS and KEYCOMPRESS.

Data and key compression specifications in the database reference file are effective only if the Fileshare Server creates the data files. They do not affect existing data files. For existing files, the data and key compression information is retrieved from the data file header. Any settings in your program or the database reference file are ignored.

Example:

fs /d dbase.ref /f file1.dat /k d001
fs /d dbase.ref /f file2.dat /k d001i7

This example tells the Fileshare Server to create the file file1.dat with data compression and the file file2.dat with both data and key compression.

Parent topic: Data and Key Compression


Virtual File Handler Interface

The Fileshare Server can pass I/O requests to a program specified by you, rather than by the Micro Focus File Handler, as long as the program that you specify conforms to the call interface used by the File Handler.

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 information
Single User Mode
Filename Mapping
Data and Key Compression
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Running Fileshare as a Windows Service
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare


Fileshare Server

To specify a virtual file handler, use the /ap (application program) option with the /f option in the database reference file to specify the program to which I/O requests for a particular data file are passed by the Fileshare Server.

Example:

fs /d dbase.ref /f user1.dat /ap myprog

This adds entries to the database reference file, dbase.ref which specify that the Fileshare Server should pass all I/O requests for the data file user1.dat to the program myprog.

Windows:

On Windows, your program should be compiled to intermediate or generated code, or to a dynamic link library, and must be callable from the Fileshare process.

Parent topic: Virtual File Handler Interface


Monitoring Fileshare

When the Fileshare Server is active, you can toggle the trace option on and off using the F2 key. If the trace option is on, the Fileshare Server displays the file access requests on the console as they happen. Each line of trace provides:

  • Input:
    • The user-ID assigned, in the order that the Fileshare Clients logged onto the Fileshare Server
    • The operation code, indicating the I/O operation requested (see the online help on the Micro Focus File Handler for further information about operation codes)
    • The name of the file being accessed
  • Output:
    • The status returned to the Fileshare Client, indicating the result of the operation
Note:

The trace option can degrade performance. You should only use it as a diagnostic aid in problem investigation.

You can activate the trace option when the Fileshare Server is started using the "/tr f" option. This causes the trace to be written to the file fsscreen.lst, as well as being displayed on the screen. Note, however, that this severely impacts the Fileshare Server performance if tracing is switched on. If, however, tracing is switched off, only information messages are written to the screen and to the file. This is a useful method of keeping a permanent record of Fileshare messages on disk.

If you are using Fileshare in single user mode (see the section Single User Mode), the trace display, together with all other output normally displayed on the Fileshare Server console screen, is written to the file fsscreen.lst in the Fileshare Server's current directory .

Parent topic: Advanced Operation
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Running Fileshare as a Windows Service
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare
Single User Mode


Fileshare Manager

You can use the Fileshare Manager (fsmgr) to automate some of Fileshare's supervisor mode functions by writing a COBOL program to call it. The Fileshare Manager can be called to instruct a Fileshare server to:

  • Perform an automatic backup of its recovery log file
  • Close all of its currently open data files. Any client application accessing these files is returned a file status, indicating that the file is no longer open. This is particularly useful in the event of a system crash or power failure, either of which could cause a Fileshare client program to terminate without disconnecting properly from Fileshare. If this happens, and data files are left open on the Fileshare server, it can prevent automatic disk backups from running and possibly prevent other clients from accessing the files.
  • Log off any clients currently connected to it, close any open files and roll back any incomplete transactions belonging to these clients.Any subsequent access attempts by these client applications result in an error status (9/125).
  • Close down completely. Any open files are closed and any incomplete transactions rolled back
  • Close down completely and then re-start. If a backup directory has been specified in the database reference file, Fileshare copies all the files named in the database reference file to the backup directory, deletes the recovery log file(s) and re-starts with a new recovery log file.
Note: Any Fileshare Clients connected to the Fileshare Server when this instruction is issued will be logged off and any files which they had open will be closed.

The Fileshare Manager program (fsmgr) is called from a COBOL program as follows:

Syntax:

call "fsmgr" using parameter-block

Parameters:

parameter-block
A group item defined as:
function-code
pic xx comp-x.
error-status
pic xx comp-x.
fileshare-name
pic x(16).
supervisor-passwd
pic x(20).
reserved
pic x(24).

On Entry:

function-code
The Fileshare Manager program function required:
1 | Backup recovery log file
2 | Close all open data files
3 | Log off all connected clients
4 | Shut down Fileshare
5 | Shut down and re-start Fileshare
fileshare-name
The name of the Fileshare server (this is the name that was used when Fileshare was started)
supervisor-passwd
The supervisor password. See the section Supervisor Mode in the chapter Security for more information
reserved
Reserved for future use. Must contain binary zeros.

On Exit:

error-status
Reflects the success, or failure, of the call. Possible values of error-status are shown below.
Value | Meaning
0 | Function completed successfully
1 Communications error. A Fileshare server of the name specified in fileshare-name could not be contacted on the network using the specified communications protocol. This error is also returned if a network failure occurs during the execution of the function but after the initial connection was made.

Check that fileshare-name is specified correctly and that the Fileshare Handling Redirection module (FHRedir) is configured to use the correct communications protocol.

2 File error during initial connection.

To connect to Fileshare, the Fileshare Manager opens a file called fsmgr.ctl. This file should not already exist and the Fileshare Manager does not actually create it. If it does exist, this status is returned if there is a subsequent error in closing the file.

3 Invalid password specified in supervisor-password.

Ensure that Fileshare is running with a password file and that the contents of supervisor-password match the supervisor password entry in the password file. Note that Fileshare passwords are case sensitive.

See Supervisor Mode in the chapter Security for more information.

4 | Invalid value specified in function-code - must be within the range one to five
5 No Fileshare log file.

You have attempted to backup the log file on a Fileshare server that is running without a recovery log file.

6 Function 2 or 3 could not complete.

While attempting to log off all Fileshare's clients (function 3), it is possible for other clients to log on before the logging off operation completes. For example, the Fileshare Manager has to send a "logoff client n" request four times if there are four clients logged on. If, however, a new client logs on before all four original clients have been logged off, the Fileshare Manager retries the "logoff client n" request in order to log off the new client. It retries 10 times and if new clients are still logging on, it returns error 6. A similar situation can occur during processing of a function 2 (close all data files) if new files are continuously being opened at the same time.

10 | Other error
Parent topic: Advanced Operation
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Running Fileshare as a Windows Service
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare
Supervisor Mode


Fileshare Manager Configuration

Fileshare Manager, like other Fileshare Client applications, accesses a Fileshare server via the Fileshare Handling Redirection module (FHRedir) and so needs to be configured to use the correct communications protocol. See the section Client Configuration in the chapter Configuration for more information.

Parent topic: Advanced Operation
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Running Fileshare as a Windows Service
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare
Client Configuration


Linking Fileshare Manager Applications

On Windows, if your program calls the Fileshare Manager, you need to link in the Fileshare manager object file (fsmgr.obj when you create an executable file.

Parent topic: Advanced Operation
Related information
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
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare


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 information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Running Fileshare as a Windows Service
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare


FS_LOCATE_FILE

The functionality provided by FS_LOCATE_FILE is the same as CBL_LOCATE_FILE except:

  • You cannot use FS_LOCATE_FILE to search for files in libraries on remote Fileshare Servers
  • You can use CBL_LOCATE_FILE to search for files along each path specified in an environment variable. You can then use the returned actual-file-spec as the filename when opening the file.

    If you have specified a $$server-name prefix in user-file-spec, actual-file-spec must contain the same $$server-name prefix for an OPEN using actual-file-spec to be re-directed automatically. By default, Fileshare only returns the filename in actual-file-spec to your program. To return the $$server-name in actual-file-spec, set the most significant bit of user-mode before making the call to FS_LOCATE_FILE.

  • When a remote file is found, using an environment variable containing many paths, FS_LOCATE_FILE returns actual-file-spec including the full path where the file is located

When a call to FS_LOCATE_FILE is directed to a custom file handler by configurable DYNREDIR, the customer file handler is called with op-code FAF8 plus fcd(3:1) and uses the value 5 to specifiy it as an FS_LOCATE_FILE call.

On Entry Fields

On entry, the following fields are set:

fcd-name-ptr | Pointer to the user file
fcd-open-mode | User mode
fcd-optional | Path flag
fcd-name-length | Length of filename

On entry, the length of the fcd-name-length field is the same as the length of the filename pointed to by the field fcd-name-ptr.

On exit, you need to set the following fields:

fcd-record-ptr | Pointer to the actual file spec
fcd-access-mode | Exist flag
fcd-file-status | File status
Parent topic: Byte-stream I/O Calls
Related information
FS_SPLIT_FILENAME and FS_JOIN_FILENAME


FS_SPLIT_FILENAME and FS_JOIN_FILENAME

The functionality provided by FS_SPLIT_FILENAME and FS_JOIN_FILENAME is the same as that provided by the corresponding CBL_routines. In addition, using FS_SPLIT_FILENAME and FS_JOIN_FILENAME you can process filenames that specify Fileshare Server names using the $$server-name prefix at the front of the filename. When processing such filenames, the $$server-name prefix characters are included as part of the pathname parameter.

If you have included the callable sort, and receive error 173 after switching to release build, you need to include fhrsub.obj in your project.

Parent topic: Byte-stream I/O Calls
Related information
FS_LOCATE_FILE


Running Fileshare as a Windows Service

You can use the Fileshare Server so that it runs as a Windows service, using the following commands:

fsservice -i [service-name [configuration-options] ]
fsservice -u [service-name]
fsservice -v [service-name]

Where:

-i
Install the service.
-v
Display the status of the service.
-u
Uninstall the service.
service-name
A unique name for the service. The service is called "Micro Focus Fileshare Service:name", where :name is included only if a name is specified. service-name is optional unless you specify configuration-options, in which case it is mandatory.
configuration-options
Options used to start the Fileshare service. See Fileshare Server Configuration .

To start the Fileshare service as a background process and to stop it:

  1. Make sure the License Manager service is started.
  2. Click Control Panel > Services.
  3. Select Micro Focus Fileshare Service[: service-name] from the list of displayed services.
  4. Click Start or Stop as appropriate.

    You can also choose to start the service automatically whenever Windows starts.

Notes:
  • When you stop the service from the Services window, as above, Fileshare closes down as normal. Any connected Fileshare clients are logged off and their data files closed (with any incomplete transactions rolled back).
  • When you shut down Windows, Fileshare is similarly shut down.
  • If you choose it to start the service automatically and you have logging switched on for any data files, we recommend that you specify a Fileshare backup directory in your database reference file.

For example, the following command installs a service called "Micro Focus Fileshare Service: My Service", which will execute in the c:\mydir directory and use a Fileshare server name of myserver:

fsservice -i "My Service" /wd c:\mydir /s myserver
Parent topic: Advanced Operation
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Fileshare Server Configuration
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: Advanced Operation
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Running Fileshare as a Windows Service
Performance Considerations
Large File Support with Fileshare


Performance Considerations

Although Fileshare reduces the number of requests made across the network for COBOL I/O, some types of data file access benefit more than others. The following areas affect Fileshare's ability to improve the speed of accessing remote data:

  • File organization

    A single request to an indexed data file can involve many accesses to the physical data file itself such as reading the header and updating the integrity marker. Complex key structures also increase the number of accesses needed to update the index structure in the file. Using the normal COBOL file handling system, each of these accesses generates a request that is sent across the network. Using Fileshare, only one request is sent across the network. The simpler data file organizations (relative and sequential files) involve a smaller processing overhead.

    Any speed improvements using Fileshare are therefore more apparent when processing indexed data files.

  • I/O request

    The number of accesses to a data file needed to process a WRITE, DELETE or REWRITE operation is generally larger than the number needed to process a READ or START operation. Using the normal COBOL file handling system, each of these accesses generates a request that is sent across the network. Using Fileshare, only one request is sent across the network.

    Any speed improvements using Fileshare are therefore more apparent when performing WRITE, DELETE or REWRITE operations.

  • Concurrent use of data files

    If your program opens a data file exclusively, the normal COBOL file handling system uses caching. This means that it does not have to check to see if the file has been updated on every I/O operation. The number of requests sent across the network, therefore, is significantly less if the data file is opened exclusively.

    Fileshare provides a greater improvement in performance, therefore, when a large number of users require concurrent access to data files than when files are opened exclusively. This is because access and caching are controlled by the Fileshare Server and so the additional requests needed when accessing a shared data file via the normal COBOL file handling system are not needed.

Any speed improvements are therefore very specific to individual applications and become more pronounced as more Fileshare Clients concurrently access the same data files.

We recommend you always use the synchronous mode of operation for best performance with Fileshare. Async-mode should be considered as being for development purposes only, and production installations should always use synchronous operation.

Parent topic: Advanced Operation
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Running Fileshare as a Windows Service
Fileshare Server Configuration
Large File Support with Fileshare


Large File Support with Fileshare

Fileshare, by default, supports files that can be up to 32 Terabytes in size.

An alternative technology, file striping, was introduced in previous releases as an interim solution to overcome limitations on the maximum allowed file size some operating systems permit. It enables you to specify that a single data file is to be stored in multiple physical files (or stripes) on disk.

Because of the complications involved with configuring striping together with Fileshare (these issues are discussed below), we recommend that you keep your large files non-striped and instead, configure the file handler to use its standard large file support.

To configure large file support under Fileshare, you should consider the following:

  • Location of the extfh.cfg file

    The extfh.cfg file must be located in the same directory as the Fileshare Server or, if the EXTFH environment variable has been set to point to the extfh.cfg file, it must have been set in the Fileshare Server session.

  • Switching on large file support

    Makes sure the value of FILEMAXSIZE specified in the extfh.cfg file is 8. This is the default value.

The following information explains how to configure striped files under Fileshare control if your operating system does not support large files:

  • Expanded filenames in the extfh.cfg file

    You must use the fully qualified name of the base file in the extfh.cfg configuration file. This name includes the pathnames that you can see if you press F2 at the Fileshare Server to switch tracing on.

    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 information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Running Fileshare as a Windows Service
Fileshare Server Configuration
Performance Considerations


Fileshare on UNIX

This chapter describes Fileshare on UNIX.

  • Running Fileshare as a Background Process
  • The NFILES Setting
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
Error Handling
Fileshare Server Messages


Running Fileshare as a Background Process

The Fileshare Server uses the Enhanced Accept/Display syntax (Adis module) for its screen displays and keyboard handling. Consequently, the Fileshare Server uses much more processor time if you start it as a background UNIX process. To avoid this overhead, you should configure the Fileshare Server using the -b option. This disables all Fileshare displays and keyboard reading.

Since Fileshare does not read the keyboard in background mode, you cannot close it down in the normal manner using the Esc key sequence.

CAUTION:

Do not kill the Fileshare process because this results in the corruption of any data files which are open.

Instead, write a program which calls Fileshare Manager. Alternatively, you can run the supplied utility cobfsclose as follows:

cobfsclose

The cobfsclose utility calls Fileshare Manager itself and prompts you for the name of the Fileshare Server you want to close down and the CCI protocol.

Because you can only shut down the Fileshare Server remotely, the Fileshare Server must have been configured to use a password file. See the section Password File Maintenance in the chapter Security for details.

The Fileshare Server does not start in background mode unless you start it with a password file.

In background mode, any messages the Fileshare Server would normally display on the screen are written to the file fsscreen.lst in the Fileshare Server's current directory.

An example configuration file follows.

-s server-1
-pf password.fil
-cm ccitcp

This configuration file specifies:

  • Fileshare Server name is server-1
  • Password file is password.fil
  • Communications protocol to use is CCITCP
  • -b option invokes running in background mode

On UNIX, you can now start the Fileshare Server in background mode by entering:

fs -b > server-1.log 2>&1 &

On some UNIX systems, output can be sent to the terminal after it has been disconnected. When this happens the entire session terminates. Consequently, you need to redirect the output from the command.

Parent topic: Fileshare on UNIX
Related information
The NFILES Setting
Password File Maintenance


The NFILES Setting

On UNIX systems, the NFILES setting defines how many separate file descriptors can be used in the File Handler config file. This can be set for individual accounts and for the system as a whole. You must ensure that the number of separate file descriptors is set sufficiently high for Fileshare which uses them as follows:

  • One file descriptor is used for every file opened on disk. So, two file descriptors are used for each indexed file opened. Note that two users sharing the same file only require the file to be opened once on disk.
  • CCITCP uses one file descriptor for every connected Fileshare client
  • CCITCP uses one file descriptor for every outstanding Fileshare request (normally this is a maximum of two)

For the user account that the Fileshare session uses, NFILES must be set to accommodate the maximum number of open files and the maximum number of Fileshare clients. In addition, the system setting of NFILES may need to be increased.

Parent topic: Fileshare on UNIX
Related information
Running Fileshare as a Background Process


Error Handling

Fileshare error messages are listed in the chapter Fileshare Server Messages .

This chapter details:
  • Fileshare-specific causes of run-time status codes returned by the COBOL system
  • Communications errors generated by CCI
  • Transaction processing errors
  • COBOL Run-time Errors
  • Communications Errors
  • Transaction Processing Errors
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
Fileshare on UNIX
Fileshare Server Messages
Fileshare Server Messages


COBOL Run-time Errors

Status Code | Meaning
9/037 Access is denied. In addition to the normal situations where this error occurs, Fileshare generates this error when:
  • An invalid user-ID and/or password is passed to a Fileshare Server and Fileshare Password Security is active
  • A Fileshare Client attempts to access a particular data file and access is denied

See the chapter Security for more information.
9/100 | A CLOSE operation is tried on a data file that is participating in an active transaction. See the section Transaction Processing in the chapter Database Integrity for more information.
9/124 | A communications error occurred between the Fileshare Client and the Fileshare Server. You can call fs_status to determine the cause of the error. For details of this call see the section Communications Errors.
9/125 Caused by one of these conditions:
  • A transaction or record lock timed out. (See the section Automatic Record Lock Timeout in the chapter Database Integrity.)
  • The Fileshare Client has been forced to log off from the Fileshare Server
  • If you are using the Micro Focus File Handler interface, an invalid Fileshare session ID was passed on the call to the File Handling Redirector module. Check that the six bytes of the FCD from offset 79 have not been changed.
  • A previous access to this open file returned a 9/124 status, so further operations cannot be made
9/126 | The record size used on the I/O operation is too large to be handled by the Fileshare Server. See the description of the /m option in the section Server Configuration in the chapter Configuration.
9/173 | When using the virtual file interface, the program-name specified in the database reference file is not found. See the section Virtual File Handler Interface in the chapter Advanced Operation.
Parent topic: Error Handling
Related information
Communications Errors
Transaction Processing Errors
Security
Transaction Processing
Communications Errors
Automatic Record Lock Timeout
Server Configuration
Virtual File Handler Interface


Communications Errors

Error status 9/124 on an I/O operation indicates that a communications error has occurred between the Fileshare Client and the Fileshare Server.

The most common time for error 9/124 to occur is on the very first I/O request that your program makes. It is then that the Fileshare Client tries to contact the Fileshare Server. If the Fileshare Client is unable to do this, it returns error 9/124. If you receive this error, examine the configuration of Fileshare and check that:

  • The Fileshare Server is started and operational
  • You have specified the correct Fileshare Server name. The name that you specify must exactly match the name specified when the Fileshare Server was started.
  • The Fileshare Client and Fileshare Server are configured to use the same CCI communications protocol
  • You have a working network connection between the Fileshare Client and the Fileshare Server and the correct network driver and software is loaded

Once you have made a successful connection and the Fileshare Server is servicing the request from the Fileshare Client, the request is visible if trace is active at the Fileshare Server. See the section Monitoring Fileshare in the chapter Advanced Operation for more information. Any further communications errors are returned to the program using the error code 9/124. This is a fatal error and the Fileshare Client drops the connection to the Server. To determine the cause of the error, call the entry point fs_status in the the File Handling Redirector module. The format of the call is:

call "fs_status" returning cci-status

where the parameter is defined as:

01 cci-status   pic x(2) comp-x.

On return, cci-status contains the CCI error code returned to the File Handling Redirector module from the CCI module. For details of CCI error codes, please refer to your book, Configuring CCI.

You can make an additional call after error 9/124 to obtain an extended error message. This message is in the form of a text string that indicates a CCI-specific error as well as some additional information. The format of the call is:

call "fs_commserr" using by reference buffer
                         by value maxlen
                         by reference actual-len

where the parameters are defined as:

01 buffer       pic x(n).
01 maxlen       pic x(4) comp-5 value length of buffer.
01 actual-len   pic x(4) comp-5.

On return, buffer contains the extended error message and actual-len contains the length of this message. The additional information in the returned message includes:

  • The date and time that the last error 9/124 was returned
  • Last return code from the CCI module (a 4-digit number)
  • Message code (for the File Handling Redirector module's internal use, a 2-digit number)
  • The CCI error message text

In addition, the File Handling Redirector module automatically logs communications errors in a local file called fhneterr.log. Each entry in the log file has the same format as the buffer returned from the fs_commserr call.

If you do not have a call to fs_commserr in your application, you can check this file for more detailed information following a 9/124 error.

This log file is not deleted by the Fileshare Client. You can, however, delete it if its contents are of no interest.

Parent topic: Error Handling
Related information
COBOL Run-time Errors
Transaction Processing Errors
Monitoring Fileshare


Transaction Processing Errors

The COMMIT and ROLLBACK operations work across many data files. You cannot check the file status of any one data file to see if the COMMIT or ROLLBACK operation was successful. Instead, call the entry point fs_status to determine the status of the COMMIT or ROLLBACK operation.

The format of the call is:

call "fs_status" returning t-status

where the parameter is defined as:

01 t-status   pic x(2) comp-x.

A non-zero status indicates that the COMMIT or ROLLBACK operation failed. Fileshare cannot provide definitive information on transaction processing errors because of the complexity of multiple file transactions across networks.

Parent topic: Error Handling
Related information
COBOL Run-time Errors
Communications Errors


Fileshare Server Messages

There are three levels of messages that can be produced by the Fileshare Server.

These are of varying levels of severity:

  • Severe

    Severe level messages indicate that a problem has occurred that has prevented the Fileshare Server carrying out the requested operation. The cause of the error should be rectified and then the operation tried again.

  • Warning

    Warning level messages indicate that a situation was encountered that the Fileshare Server was not expecting, but was able to continue.

  • Informational

    Informational level messages provide information about the operations that the Fileshare Server is performing.

The format of each message is as follows:

FSnnn-x text

where:

Parameter | Description
FS | Fileshare Server message
nnn | Message number
x | Indicates the severity of the message ("S", "W" or "I")
text | Text of the message

For more information on the messages, see the links below.

  • Messages from FS001-S to FS050-W
  • Messages from FS051-W to FS099-W
  • Messages from FS101-I to FS149-I
  • Messages from FS151-I to FS200-W
  • Messages from FS201-S to FS252-S
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
Fileshare on UNIX
Error Handling


Messages from FS001-S to FS050-W

  • FS001-S The parameter "text " is not recognized as a valid parameter.
    This error status is displayed when the Fileshare Server parses the specified parameters and finds one which it does not recognize.
  • FS004-S The parameter "text " specifies a time-out value that is invalid.
    The /t parameter has been specified in a configuration file, but the characters following do not conform to a valid specification of a time-out value.
  • FS005-S The parameter "text " is too long or invalid.
    The parameter indicated could not be processed correctly. This can be for one of the following reasons:
  • FS006-S The parameter "text " has already been specified.
    A duplicate parameter has been specified and duplicates are not permitted for this parameter.
  • FS007-S Invalid parameter combination.
    Fileshare has processed the specified parameters and is unable to process the information given.
  • FS008-S Communications Initialization Failure.
    An error has occurred when the Fileshare Server initialized CCI or the Fileshare Server was unable to perform the CCI call because the required operating system and/or Micro Focus communication support modules are not available. This error can also indicate a problem with the network setup on the machine (for example, the required drivers have not been loaded).
  • FS009-S The required communications module cannot be found.
    The Fileshare Server tried to load the CCI module required for the protocol specified, but was unable to do so. This implies that the CCI module (or required support modules) cannot be found or they cannot be loaded.
  • FS011-W Communications send failure.
    The Fileshare Server encountered a communications error when it tried to return the result of an I-O operation to a Fileshare Client. This can imply that there is a problem with the network or that the Fileshare Client process terminated abnormally.
  • FS012-W Communications disconnect failure.
    The Fileshare Server tried to drop the connection with the Fileshare Client, but the communications system returned an error. The Fileshare Server tries to disconnect from Fileshare Clients when:
  • FS013-W Communications receive error.
    An unexpected error occurred while receiving information from the communications system. This error implies a problem with the network software or hardware because a message has been received but could not be processed correctly.
  • FS014-W Communications data length not as expected.
    The information sent from the Fileshare Client to the Fileshare Server includes a check on the amount of information that is being sent. This error occurs when the amount of data received by the Fileshare Server is not the same as the amount sent by the Fileshare Client.
  • FS015-W Request from unknown user - request rejected.
    The information received by the Fileshare Server is not recognized as being from a Fileshare Client that is currently logged onto this Fileshare Server.
  • FS016-S The parameter "text " is invalid.
    The parameter has been recognized as a valid parameter, but the option specified for that parameter is not valid. For example, the /o (omit) parameter has been specified, but the option is not t (transaction processing), l (rollforward recovery logging) or s (sequence number checking).
  • FS017-S Unable to open the file : filename.
    The Fileshare Server is unable to create the file specified.
  • FS018-S Log file corrupt - unrecognizable record in file.
    Each record written to the recovery log file has a marker informing the Rollforward Recovery Utility of the type of data contained in the record.
  • FS019-S Log file corrupt - can't read header.
    Each record written to the recovery log file has a marker indicating the type of data contained in the record. This error indicates that the required header record at the beginning of the log file was not found. This implies that the log file has become corrupt, which can happen, for example, if the system crashed while records were being written to the recovery log file.
  • FS020-S The log file does not match the database sequence numbers - recovery aborted.
    Each index file (not C-ISAM) and all variable length record files have (by default) a sequence number stored in the header of the file. A corresponding sequence number is stored in the log file. Checks are made between the sequence numbers in the file headers and the log file to help ensure that the recovery process proceeds successfully.
  • FS021-S There is no log filename specified in the database reference file.
    You have tried to erase a log file entry from the database reference file but there is no log filename specified in the database reference file. The operation therefore cannot be completed successfully.
  • FS022-S The log filename given cannot be found in the database reference file.
    You have failed to erase a log file entry from the database reference file because the log filename specified is not the same as the log filename in the database reference file.
  • FS024-S Failed to open log file : filename.
    The Fileshare Server encountered an error while trying to open or create the rollforward recovery log file. Common causes of this error are:
  • FS025-S Write failure to the log file, Fileshare Server is closing down.
    The Fileshare Server encountered an error while writing a record to the recovery log file. Because the integrity of the log file cannot be guaranteed, the Fileshare Server shuts down so that the updates performed up to the point of failure are not lost.
  • FS026-W Failed to close the log file.
    The Fileshare Server encountered an error while closing the current log file.
  • FS027-S A second log file parameter has been found.
    While processing the database reference file, a second log file parameter was found. There should only ever be one log file specified in the database reference file and this error indicates that the database reference file is corrupt or has been changed without using the Database Reference File Maintenance Utility.
  • FS028-W The log file shows the last session was not shut down successfully.
    When the Fileshare Server shuts down successfully, the last record written to the recovery log file is a special record that marks the end of the recovery log file. This message indicates that the Fileshare Server could not find the special, last record when it opened the log file, suggesting that the log file was not closed in a controlled manner, probably due to a system crash. The log file could have been opened either to append to or read from in order to perform a rollforward recovery.
  • FS029-S The log filename is already specified in the database reference file.
    You have tried to add the name of the recovery log file to the database reference file. However a log filename already exists in the database reference file. A database reference file can only contain one log filename.
  • FS030-S Insufficient disk space to continue logging to log file.
    The amount of space remaining on the disk where the log file is being written has less than 200K bytes of free space remaining. This is not adequate to ensure that the recovery log file can continue to be successfully written.
  • FS031-I Record lock time-out failure on user : user.
    A record lock time-out has occurred on the user indicated. This is due to the user holding a lock on a record for a period of time longer than the record lock time-out period, when another user is trying to access that locked record.
  • FS034-S A filename or log file parameter must be specified.
    The Database Reference File Maintenance Utility has been invoked using the /d option, however a valid parameter for the utility has not been given
  • FS035-S A database reference file must be specified.
    The Database Reference File Maintenance Utility has been invoked, however the name of the database reference file to use has not been specified using the /d parameter. For example, the parameter /f (filename), /l (log filename), /fs (file string) or /backup (backup directory) has been used to invoke the Database Reference File Maintenance Utility but a /d option has not been specified to supply the name of the database reference file.
  • FS037-I The file filename does not have a file header record. Sequence checking is switched off for this file.
    The Fileshare Server has determined that the file indicated does not have a Micro Focus format file header. It is not possible to have sequence numbering on files that do not contain file headers. However, the configuration of the database reference file specifies that sequence number checking should be applied to this file.
  • FS038-S A matching sequence number not found in filename.
    This error message is displayed when the sequence number in the header of the named file does not match the sequence number in the rollforward recovery log file. See the section Database Sequence Numbering in the chapter Database Integrity for full details of database sequence numbering works.
  • FS039-S Improperly closed file - filename.
    The Fileshare Server has found that the file indicated has been marked as corrupt because it was not closed correctly. This implies that the file was not closed in a controlled manner and that the Fileshare Server last accessing the file terminated abnormally.
  • FS040-S Unable to read the file header record in the file filename.
    The Fileshare Server was able to open the file specified, but was not able to read the file header. The file header consists of the first 128 bytes of the file.
  • FS041-S Unable to update the sequence number in the file filename.
    The Fileshare Server was unable to update the sequence number in the header of the file specified. The sequence number in the header of this file cannot be relied on and hence messages relating to incorrect sequence numbers can be ignored. However, careful checks should be made to ensure that the correct version of the file are in place when starting the Fileshare Server or performing a rollforward recovery.
  • FS042-S Unable to open the database reference file: filename.
    The Fileshare Server was unable to open the database reference file indicated
  • FS043-S The database reference file contains an invalid entry.
    The Fileshare Server has found data in the database reference file which is not as expected. This implies that the database reference file has been changed without using the Database Reference File Maintenance Utility or that the database reference file is corrupt in some way.
  • FS044-S Error reading the database reference file.
    An error was encountered when reading the database reference file. The file was successfully opened by the Fileshare Server. This message implies that the file is corrupt or that a disk I/O error occurred. Alternatively, if the database reference file is on a remote drive, a network error could have occurred.
  • FS045-W Duplicate filename specified in the database reference file.
    A duplicate filename was found when the Fileshare Server processed the database reference file. This message implies that the database reference file has been modified, but not using the Database Reference File Maintenance Utility. A given filename should appear only once in the database reference file.
  • FS050-W A log file is not specified in the database reference file.
    The Fileshare Server processed the database reference file but could not find a rollforward recovery log filename. The database reference file should have a recovery log file specified in order that recovery logging can be performed.
Parent topic: Fileshare Server Messages
Related information
Messages from FS051-W to FS099-W
Messages from FS101-I to FS149-I
Messages from FS151-I to FS200-W
Messages from FS201-S to FS252-S


FS001-S The parameter "text " is not recognized as a valid parameter.

This error status is displayed when the Fileshare Server parses the specified parameters and finds one which it does not recognize.

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

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 indicated could not be processed correctly. This can be for one of the following reasons:

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

A duplicate parameter has been specified and duplicates are not permitted for this parameter.

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.

Fileshare has processed the specified parameters and is unable to process the information given.

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.

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

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.

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.

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.

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.

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.

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:

  • It receives a request from an unknown Fileshare Client
  • The CCI protocol indicated that the Fileshare Client application terminated abnormally

Resolution:

If the error persists, there could be a problem with the network that is being used. Also, ensure that users are closing down Fileshare Client applications correctly and not turning the workstation machines off or using utilities to terminate the Fileshare applications abnormally.

Parent topic: Messages from FS001-S to FS050-W


FS013-W Communications receive error.

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.

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.

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.

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 information received by the Fileshare Server is not recognized as being from a Fileshare Client that is currently logged onto this Fileshare Server.

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.

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

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 Fileshare Server is unable to create the file specified.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 encountered an error while trying to open or create the rollforward recovery log file. Common causes of this error are:

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

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.

The Fileshare Server encountered an error while closing the current 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.

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.

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.

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.

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.

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.

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

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.

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.

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.

The Database Reference File Maintenance Utility has been invoked using the /d option, however a valid parameter for the utility has not been given

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

The Fileshare Server was unable to open the database reference file indicated

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.

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.

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.

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.

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.

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.

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.

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.

Resolution:

If rollforward recovery logging is required, add an entry to the database reference file specifying a rollforward recovery log filename. See the section Database Reference File Maintenance in the chapter Database Integrity for more details.

Parent topic: Messages from FS001-S to FS050-W
Related information
Database Reference File Maintenance


Messages from FS051-W to FS099-W

  • FS051-W Failure to allocate a larger buffer, the I-O request failed.
    When using compression on the communication buffers, this message indicates that there was not enough memory available to the Fileshare Server to enable it to decompress the buffer. The I/O request has failed and the Fileshare Client was returned a 9/105 (out of memory) error.
  • FS052-S Failure to allocate required memory. The Fileshare Server is closing down.
    You see this message when the Fileshare Server is initializing and cannot allocate enough memory for the required internal tables
  • FS055-S The parameter "text " specifies a configuration file that does not exist.
    The Fileshare Server is unable to locate or open the configuration file indicated
  • FS056-S The parameter "text " specifies a data compression value that is not within the range 0-255.
    You have tried to add an entry to the database reference file. This entry specifies a value for the data compression outside of the permitted limits. The data compression option must specify a value within the range 0 through 255. To use the routine CBLDC001 as the compression method on records in the file, specify a compression value of 1.
  • FS057-S The parameter "text " specifies a key compression value that is not within the range 0-7.
    You have tried to add an entry to the database reference file which specifies a value for the key compression outside of the permitted limits.
  • FS058-S Failure to allocate memory for the decompression of the log file.
    The Rollforward Recovery Utility has been invoked but is unable to allocate the required memory so that it can process the recovery log file. This error is displayed during the initialization of the recovery process and indicates a shortage of available memory.
  • FS059-S Failure to allocate the memory required for processing the database reference file.
    When reading in a database reference file (either when the Fileshare Server or the Rollforward Recovery Utility is starting) this message indicates that the Fileshare Server was not able to allocate the required memory to be able to process all of the information in the database reference file
  • FS062-S Failure creating the password file filename.
    The Fileshare Server was unable to create the password file indicated
  • FS063-S Failure opening the password file filename.
    The Fileshare Server was unable to open the password file indicated
  • FS064-S Failure reading the password file filename.
    The Fileshare Server encountered an error reading the information from the password file. This implies that an I/O error occurred, the password file has become corrupted in some way or that a network error occurred if the password file is located on a remote machine.
  • FS065-S The password file is not of a recognized format.
    The first record in the password file is a special record which indicates to the Fileshare Server that the file is a password file. This record also contains information regarding the version of the password file being used.
  • FS066-S The specified user name already exists in the password file.
    You see this message when using the Password File Maintenance Utility and you have tried to add a user name to the password file when the user name already exists in the password file
  • FS068-I The password file is now empty and has been deleted.
    You see this message when you have used /e (erase) option with the Password File Maintenance Utility to remove the last entry from the password file. As the password file is now empty, it has been deleted. If a new password file is required it is created automatically when you add an entry using the Password File Maintenance Utility.
  • FS069-S The specified entry could not be found in the password file.
    This message indicates that you have used /e (erase) option with the Password File Maintenance Utility to remove an entry, but the entry specified does not exist in the password file.
  • FS070-S Failure writing to the password file.
    The Password Maintenance Utility encountered an error when it tried to write information to the password file. This implies that an I/O error occurred (possibly a full disk) or a network error was encountered (if the password file is on a remote machine). The integrity of the password file cannot be guaranteed.
  • FS071-W Unable to load the module FHXSCOMP to decompress the data area.
    This message indicates that the Fileshare Server has received a compressed communications buffer. However, it is unable to load the decompression module FHXSCOMP in order to perform the necessary decompression. There may not be enough memory to load the module or the module may not be found.
  • FS072-S The parameter "text " contains a wild card which is not allowed with this parameter.
    A parameter containing a wild card symbol was specified when invoking the Database Reference File Maintenance Utility but the parameter does not support wild cards.
  • FS073-S Failure to allocate memory to process the password file.
    When reading in a password file (when either the Fileshare Server or the Password File Maintenance Utility is starting), this message indicates that the Fileshare Server was not able to allocate the required memory to be able to process all of the information in the password file.
  • FS074-S The Fileshare Server (NLM) failed to log on to NetWare with the login id specified.
    NLM: This message is only applicable to the Fileshare NLM.
  • FS075-W Unable to load the module FSSECLOG - LOGON has been denied.
    This message indicates that the Fileshare Server failed to call the module FSSECLOG because:
  • FS076-W Unable to load the module FSSECOPN - OPEN has been denied.
    This message indicates that the Fileshare Server failed to call the module FSSECLOG because:
  • FS077-S A Fileshare Server of the same name has already been defined - the Fileshare Server is closing down.
    When the Fileshare Server starts up, it registers its name on the network so that Fileshare Clients can connect to it. This message indicates that the Fileshare Server is trying to register with a name that is already in use by another Fileshare Server on the network.
  • FS079-S A supervisor password entry must exist for the use of background mode.
  • FS080-S No password file has been specified for the use of the synchronous communications mode.
    You have tried to start the Fileshare Server using synchronous communications (as opposed to asynchronous communications which is the default). To enable the use of synchronous communications, you must specify a password file which contains a supervisor-ID of FSVIEW. This enables the Fileshare Server to be closed down remotely using FSVIEW or FSMgr. This is necessary because in this communications mode, the Fileshare Server only checks for keyboard input very occasionally.
  • FS081-S A supervisor password must be specified in the password file for the synchronous communications mode.
    You have tried to start the Fileshare Server using synchronous communications (as opposed to asynchronous communications which is the default). To enable the use of synchronous communications, you must specify a password file which contains a user-ID of FSVIEW. This enables the Fileshare Server to be closed down remotely using FSVIEW or FSMGR. This is necessary because in this communications mode, the Fileshare Server only checks for keyboard input very occasionally.
  • FS082-S The Netbios communications protocol is not responding. Ensure the requester software is loaded and functional.
    You have tried to start the Fileshare Server using the Netbios protocol (CCINETB) but the required network software is not loaded or is not operational. The Fileshare Server is trying to use the NETBIOS software but is receiving invalid data.
  • FS083-S Incompatible CCIIPX.NLM version.
    The Fileshare NLM Server has detected that the version of cciipx.nlm being used is not a compatible version. You are probably trying to use an old version of the CCIIPX NLM with this version of the Fileshare NLM.
  • FS084-I Fileshare Server is starting.
    This message indicates that the Fileshare Server is in the process of initializing. The configuration, database reference and password files (if specified) are being processed and the communications software is being loaded and initialized.
  • FS085-I Fileshare Server is active.
    This message indicates that the Fileshare Server has completed its initialization processing and is now ready to accept incoming requests from Fileshare Clients. At this stage all of the configuration, database reference and password files have been processed and the communications software has been successfully initialized and is operational.
  • FS086-I Fileshare Server is closing down.
    This message indicates that the Fileshare Server has started the process of closing down and will shortly terminate. This can be invoked by the following:
  • FS087-I Fileshare Server has closed down.
    This message indicates that the Fileshare Server has completed all of its termination processing. All communications have stopped, all files closed, all transactions rolled back and any rollforward recovery log file shut. The Fileshare Server can now be restarted when necessary.
  • FS089-I Database Reference File Maintenance Utility.
    The Database Reference File Maintenance Utility has been invoked using the parameters specified on the command line or in the Fileshare Server configuration file. The Database Reference File Maintenance Utility will try to process the remaining parameters specified as options to this utility.
  • FS090-I Database Reference File installation completed successfully.
    The Database Reference File Maintenance Utility has been invoked successfully and the required change made to the database reference file has been made.
  • FS091-I Rollforward Recovery Utility
    The Rollforward Recovery Utility has been invoked using the parameters specified on the command line or in the Fileshare Server configuration file.
  • FS092-I Rollforward Recovery has completed.
    The recovery process is now complete: the files contain the updates recorded in the log file when the Fileshare Server was in use.
  • FS094-I Password File Maintenance Utility.
    The Password File Maintenance Utility has been invoked using the parameters specified on the command line or in the Fileshare Server configuration file.
  • FS096-I Password File installation has completed.
    The Password File Maintenance Utility has successfully updated the password file using the options specified when the Password File Maintenance Utility was invoked.
  • FS097-I Are you sure that you wish to close down the Fileshare Server ? (Y/N)
    You have used the Esc key sequence to close down the Fileshare Server. This message is an additional prompt to avoid closing down the Fileshare Server in error.
  • FS099-W File I/O status was not as expected. Returned status: status Expected status: status Action code: text File: filename.
    This error occurs when a file is being recovered using the Rollforward Recovery Utility. When the log file is written during the normal operation of the Fileshare Server, a record is made in the log file of the status of each I/O operation performed. At the time of recovery, the status returned during the recovery process is compared with that stored in the recovery log file.
Parent topic: Fileshare Server Messages
Related information
Messages from FS001-S to FS050-W
Messages from FS101-I to FS149-I
Messages from FS151-I to FS200-W
Messages from FS201-S to FS252-S


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.

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.

You see this message when the Fileshare Server is initializing and cannot allocate enough memory for the required internal tables

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.

The Fileshare Server is unable to locate or open the configuration file indicated

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.

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.

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.

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.

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.

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.

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.

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

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.

The Fileshare Server was unable to create the password file indicated

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.

The Fileshare Server was unable to open the password file indicated

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

NLM: This message is only applicable to the Fileshare NLM.

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.

This message indicates that the Fileshare Server failed to call the module FSSECLOG because:

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

This message indicates that the Fileshare Server failed to call the module FSSECLOG because:

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

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.

Alternatively, this message can indicate that a Fileshare Server that was using this name terminated abnormally and did not de-register its name from the network.

Resolution:

Ensure that the Fileshare Server name is unique for this server. This is the name that the Fileshare Server is configured to register on the network. If a Fileshare Server that was using this name terminated abnormally, it may be necessary to re-initialize the network software on the machine where that Fileshare Server was running to ensure that its name is no longer registered (what action is required in this situation depends on the communications protocol that is being used).

Parent topic: Messages from FS051-W to FS099-W


FS079-S A supervisor password entry must exist for the use of background mode.

UNIX:

This message is applicable to Fileshare Servers on UNIX only.

It is possible to configure the Fileshare Server to run as a daemon process in the background on UNIX where no information is accepted from the keyboard nor displayed on the screen. When configuring the Fileshare Server to run in this mode, a password file must be used which should contain an FSVIEW (supervisor) user-ID and password. This enables the Fileshare Server to be closed down remotely using FSMgr, FSView or COBFSCLOSE.

This message indicates that you have tried to run the Fileshare Server in background mode but the password file that you specified does not contain an FSVIEW (supervisor) user-ID or password.

Resolution:

Add a user-ID of FSVIEW and password to the password file specified using the Password File Maintenance Utility.

See the section Password File Maintenance in the chapter Security for more information.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS080-S No password file has been specified for the use of the synchronous communications mode.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


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.

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.

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:

  • The Fileshare Server encountered an error when starting up, for example an error was found in a configuration, database reference or password file. Alternatively the communications support could not be started.
  • The user has requested to shut down the Fileshare Server (either by the Esc key sequence or a remote request from FSView or FSMgr)
  • The Fileshare Server has encountered an unrecoverable error during its operation. For example, the remaining disk space where the rollforward recovery log file resides is below the acceptable limits for logging to continue.
  • The Fileshare Server process was terminated by an event external to the Fileshare Server

The Fileshare Server is closing all outstanding connections with Fileshare Clients, rolling back any outstanding transactions, closing all open files and shutting down the communication support.

Depending on the communications protocol that is in use, the Fileshare Client applications may appear to suspend if they are still trying to send requests to this Fileshare Server.

Resolution:

No action is required

Parent topic: Messages from FS051-W to FS099-W


FS087-I Fileshare Server has closed down.

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.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


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.

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 Maintenance Utility has been invoked successfully and the required change made to the database reference file has been made.

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

The Rollforward Recovery Utility has been invoked using the parameters specified on the command line or in the Fileshare Server configuration file.

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.

The recovery process is now complete: the files contain the updates recorded in the log file when the Fileshare Server was in use.

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.

The Password File Maintenance Utility has been invoked using the parameters specified on the command line or in the Fileshare Server configuration file.

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.

The Password File Maintenance Utility has successfully updated the password file using the options specified when the Password File Maintenance Utility was invoked.

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)

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.

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

This message indicates that the status returned during the recovery process was not the same as that when the operation was performed during the normal Fileshare Server processing when the log file was written.

The Returned status is the status that the Rollforward Recovery Utility encountered when trying to apply the updates from the recovery log file to the data files.

The Expected Status is the status that was returned when this operation was originally performed by the Fileshare Server (and when the log file was being written).

The Action code is the operation code that is being performed.

The name of the file is included in the message.

This error indicates one of the following:

  • The files to which the recovery log file is being applied are not the ones that were in use at the time that the Fileshare Server was started and the log file was created
  • The recovery log file or the files being rolled forward are corrupt
  • A situation has arisen which did not occur when the rollforward recovery file was created during normal Fileshare Server operation

Resolution:

Note the expected and returned error codes and take appropriate action. Also ensure that the correct version of the data files are in place and try to re-run the rollforward recovery.

Parent topic: Messages from FS051-W to FS099-W


Messages from FS101-I to FS149-I

  • FS101-I text -- parameter has been accepted.
    The indicated parameter (and value if required) has been accepted by the Fileshare Server
  • FS103-I The log filename has been added to the database reference file.
    The Database Reference File Maintenance Utility has been invoked to add a recovery log filename to the database reference file and the operation has completed successfully. The database reference file now contains the name of the recovery log file specified.
  • FS104-I The log file cannot be found, creating a new recovery log file.
    The Fileshare Server on starting up has processed the database reference file and determined the name of the rollforward recovery log file to use. The recovery log file does not exist and so the Fileshare Server has created a new one.
  • FS105-W The disk free space for the log file is below acceptable limits.
    The Fileshare Server has detected that the amount of disk space remaining on the drive where the recovery log file is being written is below a certain level.
  • FS106-I filename - added to database reference file.
    This message indicates that the Database Reference File Maintenance Utility has successfully added the filename indicated to the database reference file.
  • FS107-I filename - removed from the database reference file.
    This message indicates that the Database Reference File Maintenance Utility has successfully removed the filename indicated from the database reference file.
  • FS108-I Processing the files specified in the database reference file.
    This message indicates that the Fileshare Server has opened the database reference file and is now scanning through it, processing each filename listed. The type of processing that it performs depends on the utility being used:
  • FS109-W The file filename does not exist.
    You see this message when the filenames listed in the database reference file are being processed and indicates that the file indicated cannot be located physically on disk.
  • FS110-I filename - OK.
    The Fileshare system has successfully processed the entry indicated in the database reference file and the file has been physically located on disk.
  • FS111-W Files are still open. Continue to close down the Fileshare Server (Y/N) ?
    You have selected to close down the Fileshare Server using the Esc key sequence. This message indicates that Fileshare Clients are still connected to this Fileshare Server with files open, or at least one Fileshare Client application program has terminated abnormally leaving one or more files open. You are asked to confirm that you do want to shut down the Fileshare Server even though there are files open.
  • FS114-W Waiting for the old log file to be removed.
    The drive where the rollforward recovery log file is being written has become full and the Fileshare Server is no longer able to continue writing to the rollforward recovery log file. The Fileshare Server is waiting for the old log file to be backed up and then deleted so that it can continue writing to the directory where the log file resides.
  • FS118-I The database sequence number matches the sequence number in the log file, no recovery is needed.
    For files formats with file headers (all index files and variable length record relative and sequential files), the Fileshare Server stores a sequence number in the header. This sequence number is also placed in the recovery log file. The sequence numbers can be checked by the Fileshare Server in certain situations to ensure that the correct files are in use.
  • FS122-I Communications too busy on CCI SEND - retrying.
    The Fileshare Server tried to send a reply back to the Fileshare Client performing an I/O request. CCI returned a Too Busy error (error 10) to the Fileshare Server.
  • FS123-I Communications too busy on CCI RECEIVE - retrying.
    The Fileshare Server tried to receive information from the network but CCI returned a Too Busy error (error 10) to the Fileshare Server
  • FS124-I Checking the validity of the log file, please wait.
    You see this message when the Rollforward Recovery Utility has been invoked and it has not found a valid record as the last record in the recovery log file. The Rollforward Recovery Utility scans through the log file to find the last sequence number that was in use to validate the integrity of the recovery log file.
  • FS125-I Recovery possible to last valid recovery log file record.
    You see this message when the Rollforward Recovery Utility has been invoked. This message indicates that the recovery log file has been validated up to the point of the last complete record in the recovery log file. It is therefore possible to apply the updates stored in the recovery log file up to this point.
  • FS126-I Performing recovery, please wait.
    The Rollforward Recovery Utility has been invoked and has initialized successfully, processed the database reference file, checked the sequence numbers in the file listed in the database reference file and validated the recovery log file.
  • FS127-S Invalid name mapping command.
    You see this message when the Fileshare Server or Rollforward Recovery Utility is processing the command line or entries in the database reference file. An /fs (file string replacement) option has been specified without a corresponding /af option specifying the new string value. The /fs option must be used in conjunction with the /af option.
  • FS128-W Fileshare Server closedown invoked by Stop Run processing.
    This message indicates that the Fileshare Server has entered its termination routine not under the control of an administrator (that is, the Esc key sequence or FSView or FSMgr are not being used to shut down the Fileshare Server).
  • FS129-I The Fileshare Server is still active.
    The response to the prompt as to whether the Fileshare Server should be closed down (see messages FS097 and FS111) indicated that the Fileshare Server should not be shut down.
  • FS130-I Reading database reference file, please wait.
    The Fileshare Server, Database File Maintenance Utility or the Rollforward Recovery Utility is reading the information stored in the database reference file. The utility will try to open the database reference file and process the information held in it.
  • FS131-W Invalid communications mode - parameter ignored.
    You see this message when the Fileshare Server is processing a /cm (communications) option. The value specified for this parameter is not valid and the parameter has been ignored. See the chapters Communications and Configuration for details of valid communications modes.
  • FS132-I The Fileshare Server is running with the following communication protocol(s):
    This message gives a list of the communication protocols that the Fileshare Server is using, after it has performed all of its initialization processing.
  • FS133-I Processing the password file, please wait.
    You see this message displayed by the Fileshare Server when it is starting or by the Password File Maintenance Utility when the password file is being updated.
  • FS134-I The password file cannot be found - creating a new password file.
    The Password File Maintenance Utility displays this message when it cannot locate the password file specified with the /pf option.
  • FS135-I Fileshare Server security is active.
    Fileshare Server security is active and all Fileshare Client applications that try to access this Fileshare Server should supply a valid user-ID and password that are in the password file. If you do not provide a valid user-ID or password, access will be denied and a 9/037 error returned to the application.
  • FS136-I Fileshare Server security is not active.
    A password file has been specified, however the only user-ID specified in the file is the FSVIEW (supervisor) id. Because this is the only ID, Fileshare Server security is not active and Fileshare Client applications that try to access the Fileshare Server do not have to supply a valid user-ID or password.
  • FS138-W The log file has been backed up and a new one has been created.
    You see this message when the Fileshare Server is starting up and a recovery log file already exists. The Fileshare Server has determined that it is unable to append to the recovery log file because the last record in the log file indicates that it was not shut in a controlled manner.
  • FS139-I A matching date and time entry has been found in the log file.
    The Rollforward Recovery Utility displays this message when the /dt option has been used to recover updates to a certain point in time. The Rollforward Recovery Utility has performed the recovery using the recovery log file and has applied the updates up to the date and time specified. This message implies that there were additional records stored in the recovery log file which were not processed as they were written after the time specified.
  • FS140-I No matching date and time entry has been found in the log file.
    You see this message displayed by the Rollforward Recovery Utility when the /dt option has been used to recover updates to a certain point in time. The Rollforward Recovery Utility has performed the recovery using the recovery log file and reached the end of the log file before a record could be found that was written at the date and time specified. This implies that the date and time specified when performing the recovery is later than the date and time that the last record was written to the recovery log file. All the updates stored in the recovery log file have been applied to the data files.
  • FS142-W The Operating System does not permit the log file to be flushed to disk.
    You see this message when the Fileshare Server is using a recovery log file to store updates made to files. At certain points during its operation the Fileshare Server makes a call to the operating system to force it to flush the contents of the recovery log file to disk. This ensures that any data that has been written to the recovery log file is physically stored on disk and can be read in again after a system failure. The Fileshare Server performs this flush operation after every COMMIT operation is performed and at regular intervals (the default being after every 100 records have been written to the recovery log file, which can be changed using a /lc entry in the database reference file).
  • FS143-W The Operating System does not allow free disk space information to be obtained.
    When writing a recovery log file, it is important that there is enough disk space available. Consequently, the Fileshare Server makes periodic checks to see whether sufficient disk space remains.
  • FS144-W More than one communications protocol has been specified - synchronous communications mode not active.
    You have tried to start the Fileshare Server using the synchronous communications mode (as opposed to the asynchronous communications mode which is the default) using the /sc option.
  • FS145-W Fileshare Client disconnected, cannot contact user: text.
    The CCI has returned an error to the Fileshare Server indicating that a Fileshare Client has been disconnected. This message indicates that there may be a problem with the network or that the Fileshare Client application program is no longer functioning.
  • FS146-W Unexpected action code, action-code - discarded.
    You see this message when performing a rollforward recovery. The Rollforward Recovery Utility has read a record from the recovery log file which contains information not relating to any file currently being recovered. The information in the record cannot be processed and the Rollforward Recovery Utility has moved onto the next record in the recovery log file.
  • FS147-I A duplicate network message was received and discarded.
    This message only occurs when you are using the CCIIPX protocol and indicates that you are using an old version of the CCIIPX modules. The buffer sent between the Fileshare Client and Fileshare Server for each I/O request contains additional information which enables the Fileshare Server to check on the validity of the request. This message indicates that the Fileshare Server has received (in error) a duplicate of the previous buffer received from the communications system. This duplicate buffer has been discarded as it is not a valid I/O request.
  • FS148-I CCI return-code (function func) = code.
    You see this message when the Fileshare Server receives an unexpected error status from a CCI module. It is normally displayed in conjunction with a Fileshare Server message indicating the circumstances in which the error occurred.
  • FS149-I CCI SEND not complete, status will be checked later.
    A request sent back to a client application from the Fileshare Server has not completed within the expected time period. This message indicates that the Fileshare Server will continue processing requests from other client applications normally and will check the status of this request at a later time.
Parent topic: Fileshare Server Messages
Related information
Messages from FS001-S to FS050-W
Messages from FS051-W to FS099-W
Messages from FS151-I to FS200-W
Messages from FS201-S to FS252-S


FS101-I text -- parameter has been accepted.

The indicated parameter (and value if required) has been accepted by the Fileshare Server

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.

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.

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.

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.

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

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.

This message indicates that the Database Reference File Maintenance Utility has successfully added the filename indicated to the 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.

This message indicates that the Database Reference File Maintenance Utility has successfully removed the filename indicated 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.

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:

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

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.

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.

The Fileshare system has successfully processed the entry indicated in the database reference file and the file has been physically located on disk.

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

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.

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.

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.

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.

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.

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

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 tried to receive information from the network but CCI returned a Too Busy error (error 10) to the Fileshare Server

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.

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.

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.

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.

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

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.

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.

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

This message should not be displayed under normal circumstances. Possible causes for this error are:

  • Closing the Fileshare Session on Windows. Such methods of closing the Fileshare Server should not be used as it can lead to files being corrupted and the recovery log file not being written to disk correctly.
  • The Fileshare Server has encountered an internal processing error which has caused the closedown code in the run-time system to be invoked. In this situation you should contact our technical support department to try and ascertain the cause of this error.

The Fileshare Server terminates by closing all files, rolling back any outstanding transactions, clearing all communication links with Fileshare Clients and closing the recovery log file (if in use).

Resolution:

You should try to ascertain why the Fileshare Server closed in this manner.

Parent topic: Messages from FS101-I to FS149-I


FS129-I The Fileshare Server is still active.

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.

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

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.

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.

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

This message gives a list of the communication protocols that the Fileshare Server is using, after it has performed all of its initialization processing.

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.

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.

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 displays this message when it cannot locate the password file specified with the /pf option.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Message FS228 is displayed when it is determined that the request eventually either completed or failed.

If you see this message frequently, it may be due to large record sizes taking longer to process than expected on slower network connections.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
FS228


Messages from FS151-I to FS200-W

  • FS151-I CCI message size received = text. Indicated send message size = text
    You see this message in conjunction with message FS014.
  • FS153-I The Fileshare Server name has been reregistered on the network.
    The Fileshare Server tried to register its name on the network so that Fileshare Clients can contact it. An error status was returned indicating that the Fileshare Server name was already registered on the network by a Fileshare Server which terminated abnormally. As this name is not being used by an active Fileshare Server, the name has been reregistered on the network by the Fileshare Server being started.
  • FS154-I Please enter the FSVIEW supervisor password to enable the use of CCI Trace.
    The Fileshare Server is being started and is configured to use the CCI Trace option. This option can only be used by a supervisor because it can cause a large amount of disk space to be used for storing the CCI Trace file. When starting the Fileshare Server a password file should be specified that contains a user-ID of FSVIEW.
  • FS155-I Password accepted - CCI Trace is enabled. Do you want CCI Trace active immediately? (Y/N)
    You see this message displayed after the supervisor has entered the supervisor password to enable the use of CCI Trace. The Fileshare Server has confirmed that the password entered is correct and it is now possible to use CCI Trace.
  • FS156-W Incorrect password - CCI Trace is disabled.
    You see this message after the FSVIEW supervisor has entered the supervisor password to enable the use of CCI Trace.
  • FS158-I CCI Trace activated.
    This message indicates that the Fileshare Server has enabled the CCI Trace option and all requests made to CCI are being logged in the CCI Trace file.
  • FS159-I CCI Trace switched off.
    This message indicates that the Fileshare Server has turned off the CCI Trace option and all requests made to CCI are no longer being logged in the CCI Trace file. You see this message when the CCI Trace is either:
  • FS160-I Fileshare trace activated.
    You see this message displayed by the Fileshare Server when the trace option has been activated using the F2 key. All requests received by the Fileshare Server will be shown, with the operation code being requested, the name of the user performing the request and some additional information depending on the operation being performed. The result of the operation (including the file status) that is returned to the Fileshare Client is also shown.
  • FS161-I Fileshare trace switched off.
    You see this message displayed by the Fileshare Server when the trace option has been toggled off using the F2 key. The Fileshare Server no longer displays requests received or information about the data being returned to the Fileshare Clients. The Fileshare Server also is no longer writing to the trace file fsscreen.lst if the trace file option was specified when the Fileshare Server was started.
  • FS163-I Input useropcode [filename-1] [ filename-2].
    You see this message when the Fileshare Server trace option is activated and a request has been received by the Fileshare Server. The information displayed is as follows:
  • FS170-I Input- Logon.
    You see this message when the Fileshare Server trace option is activated and a logon request has been received by the Fileshare Server. The Fileshare Server will process the logon request and the result of the request will also be displayed. A logon request is always the first operation performed by a new Fileshare Client connecting to this Fileshare Server.
  • FS171-I Input- Logoff user.
    You see this message when the Fileshare Server trace option is activated and a log off request has been received by the Fileshare Server. If the Fileshare Client supplied a user name when it logged onto this Fileshare Server, the user name is displayed here if Fileshare Security is active. If no user name was supplied, then the user number is displayed.
  • FS172-I Input- Find File userfilename.
    You see this message when the trace option is activated and a Find File request has been received by the Fileshare Server from a Fileshare Client when a program tries to open a file. The Fileshare Server that should process the file has not been explicitly defined and more than one default Fileshare Server is configured.
  • FS173-I Output- userstatus.
    You see this message when the Fileshare Server trace option is activated and a request has been processed by the Fileshare Server and the result sent back to the Fileshare Client
  • FS176-W There is no backup directory specified in the database reference file.
    You tried to erase a backup directory entry from the database reference file but the database reference file does not contain a backup directory entry
  • FS177-S The backup directory specified cannot be found in the database reference file.
    You tried unsuccessfully to erase a backup directory-name from the database reference file. This is because the backup directory-name specified is not the same as the backup directory-name in the database reference file.
  • FS178-I The backup directory has been added to the database reference file.
    The Database Reference File Maintenance Utility has been invoked to add a backup directory-name to the database reference file and the operation has completed successfully. The database reference file now contains the name of the backup directory specified.
  • FS179-S A backup directory is already specified in the database reference file.
    You tried to add the name of the backup directory to the database reference file. However such an entry already exists in the database reference file which can only contain one recovery log file backup directory-name.
  • FS180-W The log filename specified has an extension. The name of the log file has been changed to "filename".
    The Database Reference File Maintenance Utility has been invoked to add the name of the recovery log file to the database reference file. The name of the log file specified contained an extension and this has been removed. The extension is removed to enable the Fileshare Server to automatically backup the recovery log file when necessary. The name of the log file added to the database reference file is shown.
  • FS182-W Output- Access Denied
    You see this message when the Fileshare Server trace option is activated and a logon request was received by the Fileshare Server from the Fileshare Client. This logon request has been denied, either because:
  • FS188-W Fileshare Server database reference file installation completed with errors.
    The Database Reference File Maintenance Utility has been used to update the contents of the database reference file. However, an error was found when parsing the command line passed to the utility or when processing the information stored in the database reference file.
  • FS189-W The backup directory does not exist.
    The Database Reference File Maintenance Utility has been invoked to add the name of a backup directory to the database reference file.
  • FS190-W The backup directory specifies the name of an existing file.
    The Database Reference File Maintenance Utility has been invoked to add the name of a backup directory to the database reference file.
  • FS191-W An error occurred accessing the backup directory.
    The Database Reference File Maintenance Utility has been invoked to add the name of a backup directory to the database reference file.
  • FS192-S More than one log file exists in the log file directory.
    You see this message when the Fileshare Server is starting up. The Fileshare Server has searched the directory where the recovery log file is to be written and has determined that more than one recovery log file exists in the directory. The Fileshare Server is unable to determine which of these recovery log files is a valid one and hence which one it can append data to.
  • FS193-S Unable to open the log file.
    The Fileshare Server has determined that a recovery log file exists in the directory where the recovery log file is specified but an error was returned when the Fileshare Server tried to open it.
  • FS194-I The log file "filename-1" has been backed up successfully to "filename-2".
    This message indicates that the Fileshare Server has successfully backed up the recovery log file. The backup operation was performed either as a request from FSVIEW or FSMGR or because the current recovery log file cannot be appended to and has been automatically backed up when the Fileshare Server has started. filename-1 is the name of the log file that has been backed up. filename-2 is the name of the file that the log file has been backed up to.
  • FS195-I The Fileshare Server is using the log file "filename".
    The Fileshare Server has successfully opened (and created if necessary) the recovery log file indicated and is writing recovery records to this log file.
  • FS196-W Unable to create the log file "filename".
    The Fileshare Server tried to create the recovery log file indicated, but was unable to do so.
  • FS197-S Unable to create the log file "filename".
    The Fileshare Server tried to create the recovery log file indicated, but was unable to do so.
  • FS198-W The attempt to backup the log file failed because the backup file "filename" already exists.
    The Fileshare Server was unable to backup the recovery log file to the directory and name specified because a file of that name already exists.
  • FS199-S The attempt to backup the log file failed because the backup file "filename" already exists.
    The Fileshare Server was unable to backup the recovery log file to the directory and name specified because a file of that name already exists.
  • FS200-W The attempt to backup the log file to "filename" failed.
    The Fileshare Server tried to copy the recovery log file to the directory and name specified but encountered an error when doing so. Possible causes are that the directory is full or that a disk I/O error occurred during the copying process.
Parent topic: Fileshare Server Messages
Related information
Messages from FS001-S to FS050-W
Messages from FS051-W to FS099-W
Messages from FS101-I to FS149-I
Messages from FS201-S to FS252-S


FS151-I CCI message size received = text. Indicated send message size = text

You see this message in conjunction with message FS014.

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.

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.

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.

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.

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)

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.

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.

You see this message after the FSVIEW supervisor has entered the supervisor password to enable the use of CCI Trace.

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.

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.

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.

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:

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

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.

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.

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.

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

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:

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.

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.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


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.

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.

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.

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.

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

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.

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

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.

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.

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.

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.

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.

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.

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

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.

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

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:

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

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.

The Database Reference File Maintenance Utility has been invoked to add the name of a backup directory to the database reference file.

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.

The Database Reference File Maintenance Utility has been invoked to add the name of a backup directory to the database reference 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.

The Database Reference File Maintenance Utility has been invoked to add the name of a backup directory to the database reference file.

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.

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.

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.

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.

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

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.

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

The Fileshare Server has successfully opened (and created if necessary) the recovery log file indicated and is writing recovery records to this log file.

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 tried to create the recovery log file indicated, but was unable to do so.

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 tried to create the recovery log file indicated, but was unable to do so.

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 recovery log file to the directory and name specified because a file of that name 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 backup the recovery log file to the directory and name specified because a file of that name 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 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.

The Fileshare Server was unable to back up the log file that is currently in use. As the Fileshare Server is already operational, it cannot close down. The Fileshare Server will try to re-open the old recovery log file and continue to write recovery records to that. This message indicates that overall, the backing up of the recovery log file failed. The Fileshare Server is still operational.

Resolution:

Ensure that the filename and directory of the backup file are correct. Also ensure that there is enough disk space in the backup directory for the recovery log file to be copied.

If you are trying to start the Fileshare Server, this message can indicate that you are not following the correct sequence of backing up data files and removing recovery log files. See the section Rollforward Recovery Logging in the chapter Database Integrity for more details.

Parent topic: Messages from FS151-I to FS200-W
Related information
Rollforward Recovery Logging


Messages from FS201-S to FS252-S

  • FS201-S The attempt to backup the log file to "filename" failed.
    The Fileshare Server failed to copy the recovery log file to the directory and name specified. Possible causes are that the directory is full or that a disk I/O error occurred during the copying process.
  • FS202-I The Fileshare Server will continue logging to the log file "filename".
    The Fileshare Server failed to backup the recovery log file as part of an FSView or FSMgr operation and is trying to continue logging to the old recovery log file specified.
  • FS203-I The Fileshare Server is appending to the log file "filename".
    The Fileshare Server has found a valid recovery log file to which it is able to append data.
  • FS204-W The Fileshare Server is unable to log to the log file "filename". Rollforward recovery logging is disabled.
    The Fileshare Server has failed to back up the recovery log file as part of an FSView or FSMgr operation. Consequently, the Fileshare Server does not have a valid recovery log file into which it can write records.
  • FS205-W Unable to remove the old recovery log file "filename".
    The Fileshare Server has successfully backed-up the recovery log file as part of an FSView or FSMgr operation. However, deleting the old recovery log file returned an unexpected error. The Fileshare Server tries to create the new recovery log file.
  • FS206-S There is more than one starter log file. The Recovery Utility is unable to determine which one to use.
    You see this message when the Rollforward Recovery Utility has determined that there is more than one starter recovery log file. When the Fileshare Server starts, it creates a starter recovery log file and a new log file.
  • FS207-I There is no starter log file in the log file directory.
    The Rollforward Recovery Utility has been invoked and has scanned all of the recovery log files in the current directory. It has not found a starter log file, so the recovery cannot start using a log file in the recovery log file directory.
  • FS208-S There is no starter log file in the backup directory.
    The Rollforward Recovery Utility has been invoked and has scanned all of the recovery log files in the backup directory. No starter log file was found and so the recovery cannot commence.
  • FS209-I A starter log file has been located in the backup directory.
    The Rollforward Recovery Utility has not found a starter log file in the recovery log file folder, but one was located in the backup folder. The Rollforward Recovery Utility can start the rollforward recovery.
  • FS210-S There is more than one starter log file in the backup directory.
    The Rollforward Recovery Utility has scanned through all of the recovery log files that are in the backup directory and has determined that there is more than one starter recovery log file.
  • FS211-S An error occurred checking the header on the log file "filename".
    The Rollforward Recovery Utility found the log file indicated but was unable to open it. This message can also indicate that the file was opened successfully but the Rollforward Recovery Utility could not read the first record in the file.
  • FS212-I The Rollforward Recovery Utility is processing the log file "filename".
    The Rollforward Recovery Utility has successfully opened the starter or continuation recovery log file indicated and is processing the update information contained in it
  • FS213-W Unable to locate the continuation log file "filename" in the log file directory.
    The Rollforward Recovery Utility has processed the first recovery log file.
  • FS214-I Searching for a backed up log file in the log file directory.
    The Rollforward Recovery Utility cannot find the required recovery log file in the current log file directory. It is now searching for a backed-up copy of the required recovery log file in the log file directory.
  • FS215-I Searching for a backed up log file in the backup directory.
    The Rollforward Recovery Utility cannot find the required recovery log file in the current log file directory. It is now searching for a backed-up copy of the required recovery log file in the backup directory
  • FS216-I No backed up starter log file can be found in the log file directory.
    The Rollforward Recovery Utility has searched unsuccessfully for a backed-up starter recovery log file in the log file current directory
  • FS217-I No backed up starter log file can be found in the backup directory.
    The Rollforward Recovery Utility has searched unsuccessfully for a backed-up starter recovery log file in the backup directory
  • FS218-I No backed up continuation log file can be found in the log file directory.
    The Rollforward Recovery Utility has searched unsuccessfully for a backed-up continuation recovery log file in the current log file directory
  • FS219-I No backed up continuation log file can be found in the backup directory.
    The Rollforward Recovery Utility has searched unsuccessfully for a backed-up continuation recovery log file in the backup folder
  • FS220-I A backed up starter log file has been found in the log file directory.
    The Rollforward Recovery Utility has found a backed-up starter log file in the current log file recovery directory.
  • FS221-I A backed up starter log file has been found in the backup directory.
    The Rollforward Recovery Utility has found a backed-up starter log file in the backup directory.
  • FS222-I A backed up continuation log file has been found in the log file directory.
    The Rollforward Recovery Utility has found a backed-up continuation log file in the current recovery log file directory.
  • FS223-I A backed up continuation log file has been found in the backup directory.
    The Rollforward Recovery Utility has found a backed-up continuation log file in the backup directory.
  • FS224-S The log file directory contains more than one backed up starter log file.
    The current log file directory contains more than one backed-up starter log file and so the Rollforward Recovery Utility is unable to determine which one is the correct one to use.
  • FS225-S The backup directory contains more than one backed up starter log file.
    The Rollforward Recovery Utility has searched the backup directory for a backed-up starter log file. The backup directory contains more than one backed-up starter log file and so cannot determine which one is the correct one to use.
  • FS227-W Failure to set Fileshare Server's access rights.
    You only see this message displayed by the Fileshare NLM.
  • FS228-I CCI SEND status checked.
    A request sent back from the Fileshare Server to a client application, which previously had not completed within the expected time period, has now either failed or completed successfully.
  • FS229-I Unrecognized CCI session ID - could not disconnect user.
    The Fileshare Server tried to disconnect a Fileshare Client. However, the CCI session ID is invalid which means that the Fileshare Server cannot find details of this Fileshare Client.
  • FS230-I User : user-IDuser-name
    You see this message when the Fileshare Server has received an error from a CCI module following a communications request. The error message indicates a problem has occurred in contacting a specific Fileshare Client.
  • FS231-S The parameter "nnn" is not numeric.
    You see this message when the Fileshare Server is parsing the information supplied on the command line or in the Fileshare Server configuration file. The option specified requires a value which is numeric, however the value specified is not numeric and so that parameter cannot be processed.
  • FS232-I Date : date.
    This information is written to a Fileshare Server trace file (if one is in use) when the Fileshare Server starts up. It is also written to the Fileshare Server trace file when the date of the previous message written to the trace file is different to the current date and a new message is being written to the trace file.
  • FS233-W Unable to set the maximum amount of dynamic memory to the limit specified.
    This message is only displayed by the Fileshare NLM.
  • FS234-W The parameter "text " specifies a memory limit below the minimum of 6 Mbytes allowed.
    This message is only displayed by the Fileshare NLM.
  • FS235-W Failure to allocate memory for incomplete CCI SEND processing.
    The Fileshare Server has tried to allocate some memory in order to process CCI requests to multiple Fileshare Client sessions simultaneously, but there is insufficient free memory available. Consequently, the Fileshare Server may not be able to process communications requests correctly.
  • FS236-I The log file name has been removed from the database reference file.
    This message indicates that the Database Reference File Maintenance Utility has successfully removed the log file name from the database reference file
  • FS237-S The next log file to use filename already exists, unable to back up current log file.
    The Fileshare Server was unable to create the recovery log file because a file of the same name already exists
  • FS237-W The next log file to use filename already exists, unable to back up current log file.
    The Fileshare Server has tried to back up the current log file but was unable to create a new recovery log file because a file of that name already exists. The Fileshare Server will try to re-open the old log file and continue to write records to it.
  • FS238-I Terminating communications with this user.
    You see this message, together with FS015-W, when the network connection with an unknown Fileshare Client terminates
  • FS239-I Output - user Record locked. Retry operation.
    You see this message when tracing is enabled and an I/O operation returns a status of record locked. The user application making the request is compiled with the RETRYLOCK directive which specifies that the request is automatically retried when a status of record locked is returned. The Fileshare Server sends this message to the Fileshare Client requesting that it retries the operation.
  • FS240-I Output - user File locked. Retry operation.
    You see this message when tracing is enabled and an I/O operation returns a status of file locked. The user application making the request has the Callable File Handler RETRYOPEN option set which specifies that the open request is automatically retried when a status of file locked is returned. The Fileshare Server sends this message to the Fileshare Client requesting that it retries the operation.
  • FS241-I Output - user Insufficient log file disk space. Retry operation.
    You see this message when tracing is enabled and the amount of free disk space available to the Fileshare Server to log updates in the log file is below 200 Kbytes. See the messages FS030-S and FS114-W for further information.
  • FS243-S Failure backing up the file filename1 to filename2.
    During an automatic backup of the data files, an error has occurred while copying the file specified by filename1 to the destination specified by filename2
  • FS244-S Failure restoring the backed up file filename1 to filename2.
    An error has occurred while copying the file specified by filename1 to the destination specified by filename2 during an automatic restoration of the data files before running the Recovery Utility
  • FS245-S Failure deleting the log file filename.
    A failure occurred when Fileshare tried to delete the redundant log file, filename.
  • FS246-I Backing up database files to directory backup directory. Please wait.
    The data files listed in the database reference file are being copied to the directory specified by the /backup option
  • FS247-I Restoring database files from directory backup directory. Please wait.
    The data files listed in the database reference file are being copied from the directory specified by the /backup option to their correct locations in preparation for a Fileshare Recovery
  • FS248-I Commencing automatic Fileshare Recovery.
    This message indicates that the Fileshare Recovery Utility has been automatically invoked because the Fileshare Server has detected that the previous server session did not close down successfully
  • FS249-I Restarting Fileshare Server.
    This message indicates that the automatic Fileshare Recovery has completed successfully and that the Fileshare Server is restarting
  • FS250-I Deleting all unwanted log files.
    This message indicates that Fileshare is deleting redundant log files before re-starting the Fileshare Server when a new log file is created
  • FS251-S Logging must be activated for all files when specifying a backup directory.
    You have specified that update logging is to be switched off for one of the files named in the database reference file but have also specified a backup directory-name. You cannot do this because Fileshare automatically backs up (and restores where necessary) all the files listed in the database reference file, in order to keep them synchronized with the log file, when a backup directory is specified. If logging is not active for all files, Fileshare cannot guarantee that it can restore and recover the correct versions of these files.
  • FS252-S Failure deleting the file filename.
    An error occurred while deleting the file filename during an automatic backup or restoration of the data files
Parent topic: Fileshare Server Messages
Related information
Messages from FS001-S to FS050-W
Messages from FS051-W to FS099-W
Messages from FS101-I to FS149-I
Messages from FS151-I to FS200-W


FS201-S The attempt to backup the log file to "filename" failed.

The Fileshare Server 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.

The Fileshare Server is unable to append to the current recovery log file and is also unable to back it up and so will not start. You should rectify the problem before trying to re-start the Fileshare Server.

Resolution:

Ensure that the filename and directory of the backup file are correct. Also ensure that there is enough disk space in the backup directory for the recovery log file to be copied.

If you are trying to start the Fileshare Server, this message can indicate that you are not following the correct sequence of backing up data files and removing recovery log files. See the section Rollforward Recovery Logging in the chapter Database Integrity for more details.

Parent topic: Messages from FS201-S to FS252-S
Related information
Rollforward Recovery Logging


FS202-I The Fileshare Server will continue logging to the log file "filename".

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.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS203-I The Fileshare Server is appending to the log file "filename".

The Fileshare Server has found a valid recovery log file to which it is able to append data.

This message indicates that you are not following the recommended sequence of backing up data and removing recovery log files. A recovery log file already existed when the Fileshare Server started.

See the section Rollforward Recovery Logging in the chapter Database Integrity for more details.

Resolution:

No action is required

Parent topic: Messages from FS201-S to FS252-S
Related information
Rollforward Recovery Logging


FS204-W The Fileshare Server is unable to log to the log file "filename". Rollforward recovery logging is disabled.

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.

Rollforward recovery logging has been suspended.

Resolution:

Terminate the Fileshare Client applications and shut down the Fileshare Server. Then back up the data files, remove the recovery log file and restart the Fileshare Server to create a new recovery log file.

Parent topic: Messages from FS201-S to FS252-S


FS205-W Unable to remove the old recovery log file "filename".

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.

Resolution:

Ensure that the Fileshare Server has the correct permissions to enable it to delete the old recovery log file. Remove the old recovery log file manually if the backup operation has succeeded. This releases more disk space for recovery logging to take place.

Parent topic: Messages from FS201-S to FS252-S


FS206-S There is more than one starter log file. The Recovery Utility is unable to determine which one to use.

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.

Thus, if the Fileshare Server:

  • Starts and there is no recovery log file available, it creates one
  • Automatically backs up the recovery log file, it backs up the starter recovery log file and creates a continuation recovery log file
  • Performs another back up, it backs up the continuation recovery log file and creates another continuation recovery log file

A rollforward recovery can only proceed when there is only one starter recovery log file to use.

Resolution:

Ensure that the correct recovery log files are in place and then try to re-run the rollforward recovery process.

This message indicates that you are not following the correct sequence of backing up data files and removing recovery log files. See the section Rollforward Recovery Logging in the chapter Database Integrity for more details.

Parent topic: Messages from FS201-S to FS252-S
Related information
Rollforward Recovery Logging


FS207-I There is no starter log file in the log file directory.

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

The Fileshare Server now searches for a starter recovery log file that has been backed up to the recovery log file backup directory.

Resolution:

If no starter recovery log file is found in the recovery log file backup directory, it is not possible for the rollforward recovery to be performed. Place the correct starter recovery log file in the recovery log file directory and try to re-run the rollforward recovery.

Parent topic: Messages from FS201-S to FS252-S


FS208-S There is no starter log file in the backup directory.

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.

Resolution:

Place the correct starter recovery log file in the recovery log file directory and invoke the Rollforward Recovery Utility again to perform rollforward recovery.

Parent topic: Messages from FS201-S to FS252-S


FS209-I A starter log file has been located in the backup directory.

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.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS210-S There is more than one starter log file in the backup directory.

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.

A rollforward recovery can only start when there is only one starter recovery log file to use.

See the section Rollforward Recovery Logging in the chapter Database Integrity for more information.

Resolution:

Ensure that the correct recovery log files are in place and then re-try the rollforward recovery process.

This message indicates that you are not following the recommended sequence of backing up data files and removing recovery log files.

Parent topic: Messages from FS201-S to FS252-S
Related information
Rollforward Recovery Logging


FS211-S An error occurred checking the header on the log file "filename".

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.

Resolution:

Ensure that the Rollforward Recovery Utility has read and write access to the file indicated. Also ensure that the utility is able to open the file exclusively and that it is not currently in use by another process.

Parent topic: Messages from FS201-S to FS252-S


FS212-I The Rollforward Recovery Utility is processing the log file "filename".

The Rollforward Recovery Utility has successfully opened the starter or continuation recovery log file indicated and is processing the update information contained in it

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS213-W Unable to locate the continuation log file "filename" in the log file directory.

The Rollforward Recovery Utility has processed the first recovery log file.

The marker at the end of the recovery log file indicates that there is an additional recovery log file to be processed. This message indicates that the Rollforward Recovery Utility cannot find the next recovery log file in the same directory as the previous recovery log file.

The Rollforward Recovery Utility tries to find the next recovery log file in the backup directory if one has been specified.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS214-I Searching for a backed up log file in the log file directory.

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.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS215-I Searching for a backed up log file in the backup directory.

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

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS216-I No backed up starter log file can be found in the log file directory.

The Rollforward Recovery Utility has searched unsuccessfully for a backed-up starter recovery log file in the log file current directory

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS217-I No backed up starter log file can be found in the backup directory.

The Rollforward Recovery Utility has searched unsuccessfully for a backed-up starter recovery log file in the backup directory

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS218-I No backed up continuation log file can be found in the log file directory.

The Rollforward Recovery Utility has searched unsuccessfully for a backed-up continuation recovery log file in the current log file directory

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS219-I No backed up continuation log file can be found in the backup directory.

The Rollforward Recovery Utility has searched unsuccessfully for a backed-up continuation recovery log file in the backup folder

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS220-I A backed up starter log file has been found in the log file directory.

The Rollforward Recovery Utility has found a backed-up starter log file in the current log file recovery directory.

The Rollforward Recovery Utility will open and try to process the recovery log file that it has located.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS221-I A backed up starter log file has been found in the backup directory.

The Rollforward Recovery Utility has found a backed-up starter log file in the backup directory.

The Rollforward Recovery Utility will open and try to process the recovery log file which it has located

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS222-I A backed up continuation log file has been found in the log file directory.

The Rollforward Recovery Utility has found a backed-up continuation log file in the current recovery log file directory.

The Rollforward Recovery Utility will open and try to process the recovery log file which it has located.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS223-I A backed up continuation log file has been found in the backup directory.

The Rollforward Recovery Utility has found a backed-up continuation log file in the backup directory.

The Rollforward Recovery Utility will open and try to process the recovery log file which it has located.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS224-S The log file directory contains more than one backed up starter log file.

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.

It is not possible to start the rollforward recovery process.

This message indicates that you have not followed the recommended sequence of backing up data files and removing unneeded recovery log files. See the section Rollforward Recovery Logging in the chapter Database Integrity for more information.

Resolution:

Ensure that only the correct backed-up starter recovery log file is in the log file directory. Then re-start the rollforward recovery process.

Parent topic: Messages from FS201-S to FS252-S
Related information
Rollforward Recovery Logging


FS225-S The backup directory contains more than one backed up starter log file.

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.

It is not possible to start the rollforward recovery process.

This message indicates that you are not following the correct sequence of backing up data files and removing unneeded recovery log file. See the section Rollforward Recovery Logging in the chapter Database Integrity for more information.

Resolution:

Ensure that only the correct backed-up starter recovery log file is in the backup directory. Then re-start the rollforward recovery process.

Parent topic: Messages from FS201-S to FS252-S
Related information
Rollforward Recovery Logging


FS227-W Failure to set Fileshare Server's access rights.

You only see this message displayed by the Fileshare NLM.

The Fileshare NLM encountered an error when trying to set the Fileshare Server's access rights on the NetWare operating system.

This operation is performed after an I/O operation has been carried out for a Fileshare Client. Because this operation has failed, the Fileshare Server has assumed the access rights of that Fileshare Client.

This message indicates that the Fileshare Server's connection to the NetWare operating system is no longer valid. The Fileshare Server will try to connect with supervisor access rights to the NetWare operating system.

Resolution:

If this error persists you should contact our technical support department.

Parent topic: Messages from FS201-S to FS252-S


FS228-I CCI SEND status checked.

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.

See also the message FS149.

A second message following this one indicates the outcome of the request in question. If this suggests frequent communications errors, there may be errors on the network or client applications may be terminating abnormally. The request completed normally if no message follows.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S
Related information
FS149


FS229-I Unrecognized CCI session ID - could not disconnect user.

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.

A possible cause of this error is that CCI indicated that a Fileshare Client application program terminated abnormally, but the Fileshare Server is unable to locate details about the Fileshare Client which has terminated.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS230-I User : user-IDuser-name

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.

This message provides information regarding the user-ID and the user-name (if available) of the Fileshare Client that the Fileshare Server tried to contact.

Resolution:

No action is required.

Use details contained in other messages displayed by the Fileshare Server to determine the cause of the error.

Parent topic: Messages from FS201-S to FS252-S


FS231-S The parameter "nnn" is not numeric.

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.

Resolution:

Correct the Fileshare Server command line option or the Fileshare Server configuration file entry so that the value for the parameter indicated is numeric. Then try to re-start the Fileshare Server with the new command line or configuration file.

Parent topic: Messages from FS201-S to FS252-S


FS232-I Date : date.

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.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS233-W Unable to set the maximum amount of dynamic memory to the limit specified.

This message is only displayed by the Fileshare NLM.

This message indicates that the Fileshare NLM is configured to use a maximum amount of dynamically-allocated memory (using the /mm option).

The Fileshare Server was unable to set the limit of the amount of dynamically-allocated memory and therefore tries to allocate memory as required, with no upper limit.

Resolution:

The message indicates an internal Fileshare NLM failure. Please contact our technical support department.

Parent topic: Messages from FS201-S to FS252-S


FS234-W The parameter "text " specifies a memory limit below the minimum of 6 Mbytes allowed.

This message is only displayed by the Fileshare NLM.

This message indicates that the Fileshare NLM is configured to use a maximum amount of dynamically-allocated memory (using the /mm option).

However, the amount of memory that it is configured to use is below the minimum of 6 Mbytes in which the Fileshare NLM can successfully operate. The Fileshare NLM has set the amount of dynamically-allocated memory it can use up to six megabytes.

Resolution:

Specify a different value for the /mm option so that the amount of dynamically-allocated memory that it can use is at least six megabytes

Parent topic: Messages from FS201-S to FS252-S


FS235-W Failure to allocate memory for incomplete CCI SEND processing.

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.

Making more memory available to the Fileshare Server session after this message has been displayed will not rectify the problem with this particular request, although it might enable the Fileshare Server to allocate memory if it needs to in the future. However, the Fileshare Server process is near the limit of memory available to it which could adversely affect its operation.

See also the message FS149.

Resolution:

Make more memory available by closing other active applications on the machine where the Fileshare Server is running in order to avoid Fileshare Server memory problems in general.

Parent topic: Messages from FS201-S to FS252-S
Related information
FS149


FS236-I The log file name has been removed from the database reference file.

This message indicates that the Database Reference File Maintenance Utility has successfully removed the log file name from the database reference file

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS237-S The next log file to use filename already exists, unable to back up current log file.

The Fileshare Server was unable to create the recovery log file because a file of the same name already exists

Resolution:

The Fileshare Server has not started. Ensure that no file already exists with the same name as that which the Fileshare Server is trying to use for the next recovery log file. Then re-start the Fileshare Server.

Parent topic: Messages from FS201-S to FS252-S


FS237-W The next log file to use filename already exists, unable to back up current log file.

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.

Resolution:

The Fileshare Server continues to run but the back up of the recovery log file has failed. Ensure that no file already exists with the same name as that which the Fileshare Server is trying to use for the next recovery log file.

Parent topic: Messages from FS201-S to FS252-S


FS238-I Terminating communications with this user.

You see this message, together with FS015-W, when the network connection with an unknown Fileshare Client terminates

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S
Related information
FS015-W


FS239-I Output - user Record locked. Retry operation.

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.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


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.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS241-I Output - user Insufficient log file disk space. Retry operation.

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.

Resolution:

Because the Fileshare Server can no longer guarantee that it can store updates in the log file, it has suspended operations and is waiting for the log file to be removed in order to create more disk space. While operations are suspended any requests from Fileshare Clients are rejected. Refer to messages FS030-S and FS114-W

Parent topic: Messages from FS201-S to FS252-S
Related information
FS030-S
FS114-W


FS243-S Failure backing up the file filename1 to filename2.

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

Resolution:

Ensure that no other process is currently accessing either filename1 or filename2 and that the Fileshare Server has sufficient access permissions to carry out this operation.

Parent topic: Messages from FS201-S to FS252-S


FS244-S Failure restoring the backed up file filename1 to filename2.

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

Resolution:

Ensure that no other process is currently accessing either filename1 or filename2 and that the Fileshare Server has sufficient access permissions to carry out this operation. Then re-start the Recovery Utility. If this was invoked automatically during the Fileshare Server start-up, you also need to re-start the server manually once the recovery has completed successfully.

Parent topic: Messages from FS201-S to FS252-S


FS245-S Failure deleting the log file filename.

A failure occurred when Fileshare tried to delete the redundant log file, filename.

Resolution:

Ensure that no other process is accessing the file and that the Fileshare Server has sufficient permissions to delete the log file. Fileshare cannot start up and log updates to the correct log file until the redundant log file is deleted. Once the problem is rectified you need to restart the Fileshare Server.

Parent topic: Messages from FS201-S to FS252-S


FS246-I Backing up database files to directory backup directory. Please wait.

The data files listed in the database reference file are being copied to the directory specified by the /backup option

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS247-I Restoring database files from directory backup directory. Please wait.

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

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


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

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS249-I Restarting Fileshare Server.

This message indicates that the automatic Fileshare Recovery has completed successfully and that the Fileshare Server is restarting

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


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

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS251-S Logging must be activated for all files when specifying a backup directory.

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.

Resolution:

If you are adding the name of a data file to the database reference file, you must add it without specifying the /o l option.

If you are adding a backup directory-name using the /backup option, you should first remove any database reference file entries for files which have logging switched off

Parent topic: Messages from FS201-S to FS252-S


FS252-S Failure deleting the file filename.

An error occurred while deleting the file filename during an automatic backup or restoration of the data files

Resolution:

Ensure that no other process is accessing the file and that the Fileshare Server has sufficient permissions to delete it. You will then need to re-start the Fileshare Server or the Fileshare Recovery Utility (depending on which you were trying when the error occured).

Parent topic: Messages from FS201-S to FS252-S


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.
  • Multi-threaded Programming
  • WCF and COBOL
    Provides information about the WCF support in COBOL.
Parent topic: Programming


Managed COBOL Programming

  • Background to .NET
  • 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.
  • 64-Bit Applications in the .NET Environment
    .NET COBOL applications running on a 64-bit platform can use either the 32-bit or the 64-bit Common Language Runtime (CLR).
  • Multiple User COBOL Applications in .NET
    In a multiple user environment, COBOL applications must use multiple run units, with each instance of the application running in its own run unit.
  • Code Page Conflicts in .NET Managed COBOL
    Code page conflicts can occur when interacting with rich code page support of the .NET framework.
Parent topic: Managed COBOL Programming


Background to .NET

The Microsoft .NET Framework is a language-independent programming model that simplifies the process of building distributed applications. Any programs written for .NET can interact with one another, regardless of the programming language in which the programs were written.

.NET has two core components:

  • The Common Language Runtime (CLR). The CLR is responsible for run-time code management, undertaking such tasks as memory and thread management, and security enforcement. Programs that are written to make use of the CLR are known as managed code. Programs that do not make use of the CLR are known as unmanaged code.
  • .NET Framework class library. The class library is an object-oriented collection of types that are closely integrated with the CLR. By inheriting functionality defined in the .NET Framework class library, you can reduce the amount of code you need to write.

To create an application for .NET, you use Microsoft Visual Studio, a development environment that enables you to develop applications that work with .NET regardless of the programming language in which they are written.

For more information on .NET, go to the Microsoft .NET Web site:

Microsoft .NET

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 on the .NET platform compiles to Microsoft Intermediate Language (IL) , and native COBOL compiles to machine code. This means that native COBOL has to be compiled for the operating system on which it is going to run, whereas compiled managed COBOL can run on any Windows platform.

For .NET managed code, the management services are provided by the Microsoft Common Language Runtime (CLR). 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 are:

  • The .NET CLR, which provides automatic memory management.
  • The .NET framework, which provides a large library of building blocks to simplify many application programming tasks. It provides APIs for everything from dates and times to thread management. These features are less useful for procedural COBOL programs, but once you have migrated them to managed code, you can use them to add new features.
  • Seamless interoperation of COBOL programs with programs in other managed languages.
  • The ability to write object-oriented COBOL.

What Is .NET Managed Code?

.NET managed code compiles to Microsoft Intermediate Language (IL). The IL is stored in an assembly, along with meta data that describes the classes, methods, and attributes (such as security requirements) of the code you've created. This assembly is relatively easy to deploy and often involves only copying the assembly to the server where your run-time system is.

.NET managed code runs in the Microsoft Common Language Runtime (CLR). The CLR does Just In Time (JIT) compilation. That is, when you load an assembly, the CLR JITs the assembly code the first time it is executed. There is a small performance penalty as an application loads, but because the CLR compiles your code, it doesn't do it again (until next time you restart it).

The CLR is responsible for managing your application code at run time, and provides security, memory management and so on.

Building Native and Managed COBOL Applications

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

You can deploy and further debug the application under the run-time system provided by COBOL Server. .NET COBOL applications are deployed to Windows platforms running the .NET Framework.

Parent topic: Managed COBOL Programming
Related information
Visual Studio and COBOL
IDE Differences Between Micro Focus IDEs


64-Bit Applications in the .NET Environment

.NET COBOL applications running on a 64-bit platform can use either the 32-bit or the 64-bit Common Language Runtime (CLR).

The 64-bit CLR is used by default. This corresponds to setting the project property Platform Target to AnyCPU. To use the 32-bit CLR, you set the Platform Target to a 32-bit platform.

Note: When compiling for .NET using SQL(DBMAN=ODBC), set the Platform Target to specify the appropriate platform.

Most COBOL programs can run on 64-bit systems without recompilation. However, there are some cases where you need to ensure that COBOL pointer items in your application are allocated as 64 bits in size rather than the default of 32 bits. To do this you set the project property Generate 64-bit Pointers.

You need to generate 64-bit pointers when:

  • The combined data of all the programs in your application requires more than a 32-bit address space
  • Your managed COBOL is calling native COBOL on the 64-bit CLR and the managed COBOL is passing parameters that contain structures with pointers

If your application uses native COBOL code, and you need to execute that code on a 64-bit CLR, you need to ensure it is recompiled to target the appropriate 64-bit processor.

Parent topic: Managed COBOL Programming
Related reference
COBOL Properties


Multiple User COBOL Applications in .NET

In a multiple user environment, COBOL applications must use multiple run units, with each instance of the application running in its own run unit.

  • Background to Multiple Run Units and .NET
  • Developing an Application for Multiple Run Units in .NET
  • To call managed COBOL in a multiple user environment
Parent topic: Managed COBOL Programming
Related reference
TRACELEVEL


Background to Multiple Run Units and .NET

.NET server applications, such as ASP.NET and .NET remoting, 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 .NET, server applications are executed and controlled by application domains. Each application domain can execute multiple instances of an application at the same time.

By default, when a procedural COBOL application runs in an application domain, 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 instantiated.
  • Call the COBOL class (or program) within its own run unit. To do this, the calling program creates a run unit and creates an instance of the COBOL class. 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 MicroFocus.COBOL.RuntimeServices assembly.

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


Developing an Application for Multiple Run Units in .NET

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

You can use any existing COBOL program in a multiple user environment in .NET. Do this as follows:

  1. Create a COBOL class library project and add your procedural COBOL program to that project.
  2. Rebuild the project.

    The COBOL program is now represented as a class that can be instantiated. It is packaged as a library (.dll); it is not compiled as an executable that can be run directly.

Whether the COBOL program to be called is procedural or OO COBOL, you need a program to call it, and this program can be in any .NET language, such as C# or COBOL. You need to:

  1. Create a project for the calling program, which can be more or less any project type, and add a reference to the:
    • MicroFocus.COBOL.RuntimeServices assembly.
    • MicroFocus.COBOL.Runtime assembly. You need this only if the calling program is in a .NET language other than COBOL.
    • Project containing the COBOL class library that you want to call.
  2. In the calling program, create a run unit using the MicroFocus.COBOL.RuntimeServices.RunUnit constructor.

    Use the Try ... Finally syntax to ensure that the program destroys the run unit if the program fails.

    Either use the RunUnit.Call() method to call the COBOL class, or:

    • Make sure that any parameters use .NET standard data types, and make sure that the called COBOL can receive these .NET standard 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.

    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 System.ApplicationException is thrown.
  • In OO COBOL programs in a mixed language environment, be careful how you use static methods and data. Use static methods and data only where they need to be shared by all run units. In addition, ensure that data access is synchronized (as the run units will be executing in different threads).

For details of the RunUnit class in the MicroFocus.COBOL.RuntimeServices assembly, see: RunUnit Class.

Parent topic: Multiple User COBOL Applications in .NET
Related information
MicroFocus.COBOL.RuntimeServices


To call managed COBOL in a multiple user environment

  1. If the COBOL to be called is procedural, create a COBOL class library project and add your procedural COBOL to that project.
  2. Create a project for the calling program and add a reference to the:
    • MicroFocus.COBOL.RuntimeServices assembly.
    • MicroFocus.COBOL.Runtime assembly. You need this only if the calling program is in a .NET language other than COBOL.
    • Project containing the COBOL class library that you want to call.
  3. Write a program that calls the COBOL class within its own run unit. To do this, you create a run unit using the MicroFocus.COBOL.RuntimeServices.RunUnit class. Then you instantiate the COBOL class and invoke this instance within the new run unit.

See the MultiRunUnits example, which is with the Visual Studio examples in the examples folder in the installation of your COBOL development system.

Parent topic: Multiple User COBOL Applications in .NET
Related information
MicroFocus.COBOL.RuntimeServices
Developing an Application for Multiple Run Units in .NET


Code Page Conflicts in .NET Managed COBOL

Code page conflicts can occur when interacting with rich code page support of the .NET framework.

  • Avoiding Code Page Conflicts in .NET Managed COBOL
  • Example of Code Page Conflicts in .NET Managed COBOL
  • To Avoid Code Page Conflicts in .NET Managed COBOL
Parent topic: Managed COBOL Programming


Avoiding Code Page Conflicts in .NET Managed COBOL

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

Code pages are not often a consideration for traditional COBOL application development. However, they require attention in the advanced system Visual COBOL, which interacts with the rich code page support of the Microsoft .NET framework.

Visual COBOL follows the default behavior of Visual Studio by creating all auto-generated code files as UTF-8. The Compiler automatically compensates for this by detecting if the source code can be read as UTF-7/ASCII. If it cannot, all the files in a solution are saved as the appropriate code page, thereby avoiding corruption of PICTURE clause data items.

Code page conflicts can impact WPF and WCF projects, where by default:

  • Visual Studio auto-generates code in UTF-8 encoding. The code page of the auto-generated COBOL matches the code page of the source XML code.
  • Existing or new programmer-generated COBOL have the code page of the platform locale.
Parent topic: Code Page Conflicts in .NET Managed COBOL


Example of Code Page Conflicts in .NET Managed COBOL

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

Visual Studio creates partial classes in COBOL to give programmatic access to WPF and WCF user interfaces. These partial classes are auto-generated and can then be updated by you or Visual Studio.

In the following example:

  • Window1.xaml.cbl is the source code of a WPF (or WCF) user inteface.
  • CodePageStuff.Window1 is the partial class generated from the above source. Because this file is auto-generated, it is encoded using the UTF-8 code page by default.
  • PicLen.cbl is in the same project. This files stores the source code for a simple COBOL program for assessing the content length of c PIC X(1024) field which is space filled.

If PicLen.cbl is previously existing code or is a new hand-entered source file, it is not encoded using the platform default code page. For example, in the United Kingdom this is code page 1252, or on a Japanese locale machine, it is most likely the Shift-JIS code page 932.

When PicLen is called from WindowStuff, as follows, one code page calls another:
       call "PicLen" using stuff lStuff

Calling one code page from another is not supported directly. The COBOL run-time system generates an error when the application is run. The following source code for Window1 shows the code that handles this and displays the exception:

try
           set stuff to self::textBox1::Text
           call "PicLen" using stuff lStuff
           move lStuff to nStuff
           set self::textBox2::Text to nStuff::ToString()
       catch ex
           set self::textBox3::Text to ex::Message
       end-try

When PicLen and Window1 are encoded in different code pages, the application produces the following exception:

198 Load failure [Program has an incompatible codepage dependency
CodePageStuff.StrLen is using codepage Western European (Windows)
but the first program CodePageStuff.Window1 is using Unicode (UTF-8)]
Parent topic: Code Page Conflicts in .NET Managed COBOL


To Avoid Code Page Conflicts in .NET Managed COBOL

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

To avoid code page conflicts, save all the auto-generated developer-editable .cbl files using the platform locale that matches the developer-generated of previously existing files, as follows:

  1. Ensure the source code from the file is displayed in the editor.
  2. Click File > Advanced Save Options.

    The advanced save dialog is displayed indicating the current code page for the file it UTF-8.

  3. Change the encoding to the platform default.
  4. Repeat the above for each auto-generated .cbl file.
  5. Save all the .cbl files under the same locale.
  6. Rebuild the solution.
Parent topic: Code Page Conflicts in .NET 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.

  • Overview of Interoperability
    Broadly, there are three Microsoft techniques for calling between native COBOL and managed code: CCW, RCW and Platform Invoke.
  • 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.
  • Calling a .NET Class from Native COBOL, Using CCW
    The COM-callable-wrapper (CCW) is a .NET technique for COM interoperability. CCW wraps managed code as a COM object so that native code can call it like any other COM object.
  • Calling a Native COBOL COM Object, Using RCW
    The runtime-callable-wrapper (RCW) is a .NET technique for COM interoperability. RCW wraps a COM object so that the .NET runtime system can call it. It effectively exposes a COM interface so that managed code can call it.
  • Platform Invoke and Calling Native COBOL
    Platform Invoke is a .NET technique that enables managed code to call unmanaged functions implemented in dynamic link libraries (.dlls).
  • PInvoke Example
    The supplied PInvoke sample demonstrates Platform Invoke.
  • Callable Attribute in .NET COBOL Interoperation
    To call methods from COBOL safely, you need to set the MicroFocus.COBOL.RuntimeServices.CallableAttribute attribute on the non-COBOL methods and on the class and assembly containing them
  • Mixed Language Programming with Native COBOL
    This section covers parameters, return codes and call conventions for mixed language development with native COBOL.
Parent topic: Managed COBOL Programming


Overview of Interoperability

Broadly, there are three Microsoft techniques for calling between native COBOL and managed code: CCW, RCW and Platform Invoke.

Microsoft provides the technology for interoperability between native and managed code. They have published much excellent documentation, which explains the options and gives advice on the strategies you can adopt.

Broadly, there are three techniques for calling between native COBOL and managed code (whether managed COBOL or other managed languages):

  • CCW for calling a .NET component or managed code from native COBOL. CCW wraps the managed code in a COM Callable Wrapper, which you can call from native COBOL.

    To do this, you register the managed class for COM interop. When you build the project, the class is registered and thereby made available to native COBOL.

  • RCW for calling native COBOL as a COM object from .NET managed code. RCW wraps the native COBOL in a Runtime Callable Wrapper, which you can call from managed code.

    To do this, first you package the native COBOL as a COM object and register it. Then you add the COM object as a reference in your project. When you build the project, the RCW is generated, thereby exposing the COM class as a managed proxy class.

  • Platform Invoke for calling native API functions from managed code. Platform Invoke enables you to call any function in any managed language.

    To do this, first you first you package the native COBOL as a .dll, with the appropriate entry points. Then you add the .dll and the COBOL run-time system support as a reference in your project. The managed code can now call into you must redeclare the function's signature in the managed source code.

For native COBOL and managed COBOL to interoperate, you don't need to worry about data type conversion. Native types are understood and converted to the appropriate managed types when the COBOL is compiled.

However, for native 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. For example, for integers (such as PIC S9(9) comp-5), you might use the predefined type binary-long, which corresponds to int in both C# and Java.

COM Support from Micro Focus

COM is a feature of Microsoft Windows which enables one application to load and send messages to any application registered with the operating system as a COM Automation server.

Micro Focus COM support enables you to send messages to COM objects from COBOL programs and classes (where this COBOL is behaving as a COM client). You can also create COM objects, enabling you to manipulate a COBOL class through COM Automation.

The terminology used to describe COM components - servers, classes, clients, and objects - can be confusing. In this documentation, we use these terms as follows:

  • COM class - COBOL class that you write based on existing COBOL programs
  • COM server or COM Automation server - an application created using COM classes
  • COM client - any program that accesses a COM server application
  • COM object or component - an instance of a COM server application received by a client

COM objects are built using Microsoft's Component Object Model (COM). There are two main differences between COM and a language such as native OO COBOL:

  • COM does not support inheritance. When you write a new COM class, you can't inherit functionality from any of your existing COM or non-COM classes.
  • COM does not support class methods and class data.

Microsoft also support a distributed version of COM, which works across a network, called DCOM. DCOM enables you to send messages to an object residing on a different machine.

Parent topic: Interoperability


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.
  • Examples of Compatible Types for Native and Managed COBOL
    The InterfacingWithStdCOBOL.sln solution contains six projects. There are three pairs of projects, where each pair comprises a C# client console project and a COBOL project. Each client C# project makes a reference to its corresponding COBOL project so that it can use the implicit or explicit COBOL methods that are exposed.
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.

The Microsoft Common Language Specification (CLS) defines a set of basic language features, including the rules for the common type system. In theory, your COBOL must use CLS-compliant types. However, in practice, you can use .NET types that are not CLS-compliant, providing the non-COBOL language supports them. This is true of many C# types.

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 or a java.lang.String.
  • 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 that are not CLS-compliant, 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?
Compatible Types Example in .NET COBOL Interoperation
Group Items Example in .NET COBOL Interoperation
Occurs Clause Example in .NET COBOL Interoperation
Type Compatibility of Managed COBOL with Other Managed Languages


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

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 members of the class. For example:

    lnkBDetails.lnkBStockno

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

In summary, to expose group items:

  • Compile the COBOL with ILSMARTLINKAGE and optionally with ILCUTPREFIX
  • In the non-COBOL project, add a reference to the COBOL project and the MicroFocus.Runtime.Assembly

Example:

The following COBOL program is compiled with ILSMARTLINKAGE, 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).
       procedure division using by value lnk-function
                                by reference lnk-b-details.

In C#, you can access the data in BookLegacy program in .NET managed 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.Stockno = "6666";
       myDetails.Title = "Managed COBOL";
       myDetails.Author = "Mike Focus";
       myDetails.Type = "Reference";
       myDetails.Retail = 15.50M;
       myDetails.Onhand = 20;
       myDetails.Sold = 5;
       myBook.BookLegacy("2", myDetails);
         // calls the BookLegacy method with myDetails,
         // which corresponds to the group item lnk-b-details

See the C# WinBook demonstration in the Visual COBOL samples for more.

Parent topic: Data Marshaling and Type Conversion for Managed Code Interoperation
Related information
Type Compatibility in Interoperation with Managed Code
Interfacing with C Programs
COBOL and .NET Managed Type Compatibility
Type Mappings from Native COBOL to Managed Code
ILCUTPREFIX
ILSMARTLINKAGE


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.

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
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 S9(n) where 4 < n <= 9 | uint | int | binary-long unsigned
PIC 9(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 | ScaledInteger | decimal
PIC 9(n)V9(m) | decimal | ScaledInteger | 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
Types and Type Conversion
Type Compatibility of Managed COBOL with Other Managed Languages
Data Types - in COBOL and C#


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 IL, which exposes the module and its entry points as instance methods. Your managed code can then use the CobLoad method of the Interop class in MicroFocus.COBOL.RuntimeServices to 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 IL (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


Examples of Compatible Types for Native and Managed COBOL

The InterfacingWithStdCOBOL.sln solution contains six projects. There are three pairs of projects, where each pair comprises a C# client console project and a COBOL project. Each client C# project makes a reference to its corresponding COBOL project so that it can use the implicit or explicit COBOL methods that are exposed.

The InterfacingWithStdCOBOL.sln solution is supplied with the samples that are installed under %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples 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\<product name>\Samples.

  • Compatible Types Example in .NET COBOL Interoperation
    The first pair of projects, StdCbl01.*, shows a COBOL program using types that are compatible with C# types.
  • Group Items Example in .NET COBOL Interoperation
    The second pair of projects, StdCbl02*, shows a COBOL program using group items.
  • Occurs Clause Example in .NET COBOL Interoperation
    The third pair of projects, StdCbl03*, shows a COBOL program using occurs clauses.
Parent topic: Data Marshaling and Type Conversion for Managed Code Interoperation


Compatible Types Example in .NET COBOL Interoperation

The first pair of projects, StdCbl01.*, shows a COBOL program using types that are compatible with C# types.

In the InterfacingWithStdCOBOL.sln solution, the first pair of projects, StdCbl01.*, shows a COBOL program using types that are compatible with C# types. Although this works, it is a somewhat fictitious example, as COBOL modules usually use other data types and more complex structures that don't correspond to .NET types.

The StdCbl01 projects include the following programs:

  • StdCbl01.cbl. This program uses types that are directly compatible with C# types. This means that you can invoke the COBOL from the C# client, without changing the COBOL. For example:

    Lines 21-31

    LINKAGE SECTION.
...
01  F-SBYTE-COMP5 PIC S9(02) COMP-5. *>   map to C# sbyte
01  F-SHORT-COMP5 PIC S9(04) COMP-5. *>   map to C# short
01  F-INT-COMP5   PIC S9(09) COMP-5. *>   map to C# int
01  F-LONG-COMP5  PIC S9(18) COMP-5. *>   map to C# long
01  F-COMP1                  COMP-1. *>   map to C# float
01  F-COMP2                  COMP-2. *>   map to C# double

    This program is procedural COBOL. When you compile it to managed code, you create a class and an instance method is implicitly exposed. The Class and method names are derived from the PROGRAM-ID, StdCbl01. In this way, the program is exposed as a method so that any managed code can use it directly. For example:

    Line 12:

    PROGRAM-ID. StdCbl01. *> PROGRAM-ID is used both as class name
                      *> and as the only INSTANCE method available
    By default, the COBOL language translates all names and identifiers to upper case. If you want to maintain and expose a name in its original case, you must use the keyword AS. For example the following would expose the class and method as StdCbl01 in a C# program.
    PROGRAM-ID. StdCbl01 AS “StdCbl01”
  • StdCbl01Client.cs. This is the C# client, which passes data to the COBOL, and receives data back. This C# code invokes the COBOL program by fetching the COBOL program instance and then invoking the method in the same way that it would invoke any other managed code method, as follows:

    Line 37:

    STDCBL01 stdCbl01 = (STDCBL01)Interop.CobLoad("StdCbl01");
COBOLrc = stdcbl01.STDCBL01(ref CSsbyte, ref CSshort,
                                 ref CSint, ref CSlong,
                                 ref CSfloat, ref CSdouble);
Parent topic: Examples of Compatible Types for Native and Managed COBOL
Related information
Type Compatibility in Interoperation with Managed Code


Group Items Example in .NET COBOL Interoperation

The second pair of projects, StdCbl02*, shows a COBOL program using group items.

In the InterfacingWithStdCOBOL.sln solution, the second pair of projects, StdCbl02*, shows a COBOL program using group items. This is more representative of real COBOL than the StdCbl01 program. C# doesn't have the concept of group items, so we write a proxy class to manipulate the data and act as an interface between the COBOL and the C#.

The StdCbl02 projects contain the following programs:

  • StdCbl02.cbl. This program is procedural COBOL. It is compiled to managed code without any changes.
  • StdCbl02.cpy. This copybook defines group items, which contain the parameters passed to and from StdCbl02.cbl, as follows:

    Lines 06-09:

    01 INPUT-FIELDS.
   03 IN-FIELD01     PIC  X(01).
   03 IN-FIELD02     PIC  9(03).
   03 IN-FIELD03     PIC S9(05)V99    COMP-3.
  • ooiStdCbl02.cbl. This program acts as an interface (a proxy) between the C# and the unchanged COBOL StdCbl02.cbl. It manipulates the group items as follows:
    • Defines object properties to contain the data passed to and from the client C# program, as follows:

      Lines 33-35

01 InField01  Object Reference StringClass  property AS "InField01".
01 InField02  Binary-Short                  property AS "InField02".
01 InField03  Object reference DecimalClass property AS "InField03".
    • Takes the input data from the object properties set in the C# client program and puts this data into the COBOL fields defined in the copybook, as follows:

      Lines 52-54:

      Set IN-FIELD01              to InField01
Set IN-FIELD02              to InField02
Set IN-FIELD03              to InField03
  • StdCbl02Client.cs. This is the client program, written in C#. It does the following:
    • Sets the object properties of the class OOiStdCbl02

      Lines 25-27

objStdCbl02.InField01  = "A";
objStdCbl02.InField02  = 999;
objStdCbl02.InField03  = 12345.67M;
    • Invokes the method ExecStdCbl02 in the newly written proxy class, as follows:

      Line 31:

      objStdCbl02.ExecStdCbl02();
Parent topic: Examples of Compatible Types for Native and Managed COBOL
Related information
Type Compatibility in Interoperation with Managed Code


Occurs Clause Example in .NET COBOL Interoperation

The third pair of projects, StdCbl03*, shows a COBOL program using occurs clauses.

In the InterfacingWithStdCOBOL.sln solution, the third pair of projects, StdCbl03*, shows a COBOL program using occurs clauses. In the same way as the StdCbl02 projects, this project uses a proxy class to manipulate the COBOL data to and from object properties, so that these properties are exposed to the C# client.

The StdCbl03 projects contain the following programs:

  • StdCbl03.cbl. This uses two occurs clauses (defined in the copybook). One of these occurs clauses is as follows:

    Lines 11-16:

    01 INOUT-FIELDS.
  03 INOUT-FIELD01                PIC  9(02)       COMP.
  03 INOUT-FIELD02                PIC  X(26).
  03 INOUT-TABLE          OCCURS 3.
    05 INOUT-TABLE-FIELD01        PIC  X(15).
    05 INOUT-TABLE-FIELD02        PIC    S9(09)V9(5)  COMP-3.

    We can view this occurs group as if it had three occurrences of two fields or an array of size three where each position in the array has two fields or properties. If each occurrence is an object with two properties, you can code it neatly as a .NET ArrayList.

  • OOiInoutfields.cbl. This program defines a COBOL class that exposes the input/output fields as object properties. This class is instantiated by StdCbl03Client.cs and each object created is saved in an ArrayList item. This ArrayList is then passed to OOiStdCbl03.Cbl. For example:

    Lines 7-33

        *> OO COBOL class for OUT-TABLE table
 class-id. OOiOutFields.
 working-storage section.
    *> using native .NET Type and/or classes
 01 OutTableField01      type System.Double property.
 01 OutTableField02      type System.Double property.

 end class.
  • OOiOutfields.cbl. Similar to the above program, this program defines a COBOL class that exposes the output fields as object properties for use in StdCbl03Client.cs as ArrayList items.
  • OOiStdCbl03.cbl. This is the newly-written proxy COBOL program that manipulates the occurs groups, as follows:
    • Uses the arrays that are passed to and from the .NET managed client.

      Line 31 in the Working Storage section of the method ExecStdCbl03:

      01 obj-InoutFieldsItem    type OOiInoutFields

      Line 59 in the Linkage section:

      01 obj-InoutFieldsArray   Object Reference ArrayListClass.

      Line 36:

      procedure division using obj-InoutFieldsArray as type System.Collections.ArrayList
                         obj-OutFieldsArray   as type System.Collections.ArrayList.
    • For each occurrence in each ArrayList, take the object's properties and populate the original occurs group (defined in the copybook).

      Lines 47-51:

      Move 1 to Idx
Perform varying obj-InoutFieldsItem through obj-InoutFieldsArray
             Set INOUT-TABLE-FIELD01(Idx) to
                       obj-InoutFieldsItem::"InOutTableField01"
    Move obj-InoutFieldsItem::"InOutTableField02" to
                       INOUT-TABLE-FIELD02(Idx)
             Add 1 to Idx
    End-Perform

      The ArrayList now contains three objects each with two properties. It contains the equivalent of three occurrences of two fields in an occurs group.

    • Call the existing COBOL module from the proxy COBOL class, passing the original data structure with its occurs group. See the program OOiStdCbl03.cbl

      Line 53:

      Call "StdCbl03"
         using INPUT-FIELDS INOUT-FIELDS OUTPUT-FIELDS
  • StdCbl03Client.cs. This is the client program, written in C#. It does the following:
    • Creates a NET ArrayList (or more precisely System.Collections.ArrayList), as follows:

      Lines 31:

      ArrayList InOutArray = new ArrayList(3);
    • Sets the object properties of the ArrayList items, as follows:

      Lines 36-39:

      OOiInoutFields inOutFieldsItem0 = new OOiInoutFields();
inOutFieldsItem0.InOutTableField01 = "Item #1";
inOutFieldsItem0.InOutTableField02 = 111.111;
InOutArray.Add(inOutFieldsItem0);
    • Invokes the method ExecStdCbl03 in the newly written proxy class, as follows:

      Line 55:

      objStdCbl03.ExecStdCbl03(ref InOutArray, ref OutArray );

The result is a .NET ArrayList (or more precisely System.Collections.ArrayList) that you can pass to and from C# or any .NET managed code. You can work with it in many ways, including binding it to a DataGrid.

Parent topic: Examples of Compatible Types for Native and Managed COBOL
Related information
Type Compatibility in Interoperation with Managed Code


Calling a .NET Class from Native COBOL, Using CCW

The COM-callable-wrapper (CCW) is a .NET technique for COM interoperability. CCW wraps managed code as a COM object so that native code can call it like any other COM object.

The COM-callable-wrapper (CCW) is a .NET technique for COM interoperability. CCW wraps managed code as a COM object so that native code can call it like any other COM object. It effectively exposes a .NET managed class in any language as a COM interface. For more background, see the Visual Studio Help topic COM Callable Wrapper.

To expose a .NET class as a COM object, you configure the project so that the class is registered for COM interop. When you build the project, the class is registered and thereby made available to native COBOL.

All public methods defined and implemented in the .NET class are exposed as a COM interface. Your COM client application can then invoke those methods as if they were methods of a COM object.

To call a .NET class from native COBOL

  1. In Visual Studio, open the project containing the .NET class to expose, by clicking File > Open > Project and browsing to the project.
  2. Click Project > myProject Properties.
  3. On the COBOL tab, click Advanced, and check Register for COM interop.

    The native client can now invoke methods in the .NET class as if it was any other COM object, by using the COM programmatic ID of the .NET class. This ID is defined as DefaultNamespace.Class. Where the default namespace, DefaultNamespace, is defined on the Application tab in the project properties and is by default set to the name of the project.

    For example, a native COBOL client can invoke the .NET class called ManagedCOM, as follows:

    class ManagedCOM as "$OLE$COMDemo.ManagedCOM"

To call the exposed .NET class from native COBOL

The native COBOL calls the .NET class as if it were a COM object, by including the following elements of code:

  1. Set the Checker directive OOCTRL(+P) in your program:
    $SET OOCTRL(+P)

    This checker directive enables the run-time system to map from COBOL data types to COM data types.

  2. Map each COM class to an OO COBOL proxy class in the CLASS-CONTROL paragraph. Give the COM class an OO COBOL class-name, and specify that it is in the COM domain, using a statement of the form:
    class-name IS CLASS "$OLE$windows-registry-name"

    where windows-registry-name is one of the following:

    • the ProgID for the server
    • the CLSID for the server

    The ProgID and CLSID are defined in the Windows registry.

  3. Create an instance of the OO COBOL COM class.

    Send the message "new" to the OO COBOL proxy class. This starts the COM server if it is not already running. You are returned an OO COBOL handle which you can use to send messages to the COM server.

  4. Send messages to the COM server.
  5. To access properties, prefix the property name with "Set" to set a property or "Get" to retrieve a property.

    When setting a property, pass a single parameter. When getting a property the value is returned as the RETURNING parameter.

Parent topic: Interoperability
Related information
To use CCW to expose a .NET class to native COBOL


Calling a Native COBOL COM Object, Using RCW

The runtime-callable-wrapper (RCW) is a .NET technique for COM interoperability. RCW wraps a COM object so that the .NET runtime system can call it. It effectively exposes a COM interface so that managed code can call it.

The runtime-callable-wrapper (RCW) is a .NET technique for COM interoperability. RCW wraps a COM object so that the .NET runtime system can call it. It effectively exposes a COM interface so that managed code can call it. For more background, see the Visual Studio Help topic Runtime Callable Wrapper.

RCW enables the COBOL CALL statement to call native COBOL that is packaged as a COM object.

Note: The COM object must have a type library for it to be usable in the .NET environment.

To call a native COBOL from managed code, first you package the COBOL as a COM object and then you register it. You then add the COM object as a reference in your project. When you build the project, the RCW is generated, thereby exposing the COM class as a managed proxy class. When you run the application, the managed code accesses the COBOL COM object running as a COM automation server.

The benefit of using RCW is that your managed program just sees the COM object as a managed class (and you get the benefit of IntelliSense). The .NET run-time system manages the data type manipulation to convert .NET types to COM types for you.

To call a native COBOL COM object

  1. Package the native COBOL as a COM object.

    Note that in .NET, COM objects must have a type library.

  2. Register the COM object using the command:
    regsvr32 myCOMObject.dll
  3. Add the COM object to your Visual COBOL project as a reference. To do this:
    1. Right-click References in Solution Explorer.
    2. Click Add reference.
    3. Browse to your COM object and select it.
  4. In your managed code, invoke the COM object in the same way as any other managed object. The following example invokes the Calculate method on the object theLoanCalculator:
    invoke theLoanCalculator::"Calculate"
Parent topic: Interoperability
Related information
To use RCW to call native COBOL


Platform Invoke and Calling Native COBOL

Platform Invoke is a .NET technique that enables managed code to call unmanaged functions implemented in dynamic link libraries (.dlls).

For more information on Platform Invoke see the Visual Studio Help topic Consuming Unmanaged Code.

Platform invoke is similar to an API call. It enables managed COBOL to use the COBOL CALL statement to call native COBOL that is built as a .dll.

If you have existing COBOL that you want to call from managed code, you must first build it as a native .dll with the entry points that you need to call. You then add the .dll as a reference to your .NET project.

In your .NET project, you write a managed COBOL program and use CALL statements to call functions in the .dll. These CALL statements generate a platform invoke call if the CALL matches an entry in the native .dll.

To use Platform Invoke to call native COBOL

  1. Package your native COBOL as a .dll with the necessary entry points into the code.
  2. Add the .dll and the COBOL run-time system support to your COBOL project as references, as follows:
    1. Right-click References in the solution view on the right.
    2. Click Add reference.
    3. Browse to MicroFocus.COBOL.Runtime and select it.
    4. On the Projects tab, browse to your .dll and select it.
  3. Write some .NET managed COBOL to call your .dll, using the standard COBOL CALL statement, such as:
    CALL myNativeLibrary USING myParams
  4. Now non-COBOL managed code can invoke the above managed COBOL, which in turn calls the native COBOL .dll.
Parent topic: Interoperability
Related information
To use Platform Invoke to call native COBOL
PInvoke Example


PInvoke Example

The supplied PInvoke sample demonstrates Platform Invoke.

See the Pinvoke example, which is with the examples. See Start > All Programs > Micro Focus Visual COBOL > Samples. This example contains the following of interest:

  • Pinvoke.cbl. This program is managed COBOL. It uses the standard COBOL CALL statement to call the sub program and to send it the message buffer to display, as follows:
           call "SUB" using messageBuffer
  • sub.dll. This program is existing native COBOL.

    The built sub.dll is included as a reference in the project, whereas the source file sub.cbl is not included, because it is native code and not compiled as part of the project. You can view the source file by opening it from the File menu.

To run the example:

  1. Build the solution by clicking Build > Build pinvoke.
  2. Step through the program, using Debug > Step into.
Parent topic: Interoperability
Related information
To use Platform Invoke to call native COBOL
Platform Invoke and Calling Native COBOL


Callable Attribute in .NET COBOL Interoperation

To call methods from COBOL safely, you need to set the MicroFocus.COBOL.RuntimeServices.CallableAttribute attribute on the non-COBOL methods and on the class and assembly containing them

Because both COBOL-enabled methods and .NET Framework methods can have the same name and signature, you might get unexpected results when using the COBOL CALL verb.

Set the MicroFocus.COBOL.RuntimeServices.CallableAttribute attribute on the non-COBOL methods and on the class and assembly containing them in order to call the methods from COBOL safely.

Parent topic: Interoperability
Related information
The CALL Statement
CallableAttribute Class


Multi-threaded Programming

  • Introduction to Multi-threading
  • Synchronizing Execution and Resolving Contention
  • Writing Multi-threaded Applications
  • Multi-threading Compiler Directives
Parent topic: Managed COBOL 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.

To run a .NET managed multi-threaded application, you can run the executable like any .NET application, that is, without a trigger program.

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
  • Considerations When Creating Reentrant Programs
  • Multi-threading Library Routines
  • Manipulating Threads
  • Canceling Called Programs
  • Optimizations and Programming Tips
  • Multi-threading in the .NET Framework
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 .

Parent topic: Writing Multi-threaded Applications


Run-time System for Multi-threaded Applications

The run-time system for multi-threaded applications needs to handle both multi-threaded and single-threaded applications. As a result, the multi-threaded run-time system incurs many of the synchronization costs that a standard multi-threaded COBOL application would. Further, most of these costs are incurred regardless of whether the application is multi-threaded or single-threaded. Because of this, and in order to enable single-threaded applications to run at maximum speed, Micro Focus provides two separate run-time systems: a multi-threaded run-time system that supports all applications, and a single-threaded run-time system that supports only single-threaded applications. You can choose between these run-time systems either when you run your application or when you link your application.

The files you need to ship with an application will depend in some cases on whether your application has been linked to the single-threaded or multi-threaded run-time system.

Parent topic: Writing Multi-threaded Applications


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. For managed applications using the .NET Framework, these routines are deprecated. See Multi-threading in the .NET Framework.
  • 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. For managed applications using the .NET Framework, this routine is deprecated. See Multi-threading in the .NET Framework.
  • Call cobtidy() to indicate that the COBOL run-time system will not be needed again in this application run.For managed applications using the .NET Framework, this routine is deprecated. See Multi-threading in the .NET Framework.
  • Call cobexit() to terminate the run unit. For managed applications using the .NET Framework, this routine is deprecated. See Multi-threading in the .NET Framework.
  • 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 a an externally visible routine written in another language, such as C. It must not be a nested program, 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.
  • 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.

CAUTION:
For managed applications in the .NET Framework, Microsoft mandates that you "do not use the System.Threading.Thread.Suspend and System.Threading.Thread.Resume methods to synchronize the activities of threads. You have no way of knowing what code a thread is executing when you suspend it. If you suspend a thread while it holds locks during a security permission evaluation, other threads in the System.AppDomain might be blocked. If you suspend a thread while it is executing a class constructor, other threads in the System.AppDomain that attempt to use that class are blocked. Deadlocks can occur very easily."

You can use the Compiler directive WARNINGS(2) to issue warnings when suspend and resume are being used.

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.
  • 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. For managed applications using the .NET Framework, these routines are deprecated. See Multi-threading in the .NET Framework.
  • 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. For managed applications using the .NET Framework, these routines are deprecated. See Multi-threading in the .NET Framework.
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:

  • 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 in the .NET Framework

Multi-threading is fully supported in managed code under the .NET Framework.

If your application uses Windows forms, you can use the threading support. However if you are using COBOL in a ThreadPool, do not use the threading support. Instead, you should invoke COBOL using the multipel run units. See MicroFocus.COBOL.RuntimeServices.

Note the following with regard to multi-threading in managed code:

  • If your application uses Windows forms, you can use the threading support. However you need to understand ThreadPools to do this. See the ThreadPool class in the .Net Framework Help. An alternative is to invoke COBOL using multiple run units. See MicroFocus.COBOL.RuntimeServices.
  • The CBL_THREAD_SUSPEND and CBL_THREAD_RESUME routines are deprecated in managed code and their use is bound by Microsoft restrictions.
    CAUTION:

    For managed applications in the .NET Framework, the CBL_THREAD_SUSPEND and CBL_THREAD_RESUME routines are provided but are implemented using obsolete APIs (Thread.Suspend/Thread.Resume) and as such their use is bound by restrictions imposed by the .NET Framework.

    Microsoft mandates that you "do not use the System.Threading.Thread.Suspend and System.Threading.Thread.Resume methods to synchronize the activities of threads. You have no way of knowing what code a thread is executing when you suspend it. If you suspend a thread while it holds locks during a security permission evaluation, other threads in the System.AppDomain might be blocked. If you suspend a thread while it is executing a class constructor, other threads in the System.AppDomain that attempt to use that class are blocked. Deadlocks can occur very easily."

    You can use the Compiler directive WARNINGS(2) to issue warnings when suspend and resume are being used.

  • cobthreadtidy(), cobtidy(), and cobexit() routines are are deprecated in managed code. Their work is done automatically.
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


WCF and COBOL

Provides information about the WCF support in COBOL.

Windows Communication Foundation (WCF) is part of Microsoft's .NET Framework that enables you to build service-oriented applications. WCF services consist of a number of operations which you can expose to client applications through different endpoints.

With Visual COBOL you can create and access WCF COBOL services for versions of the .NET Framework version 3.0 or greater. Note: This replaces the ASMX Web reference clients which is the only option when you target .NET Framework v. 2.0.

Restriction: The WCF project types are not available in the Visual Studio 2010 Shell but adding a service reference for client applications is supported.

The following is a brief overview of the process of creating and consuming a WCF service:

  1. Create a new project, a WCF Service Library.
  2. Specify the service contract.

    A contract is an interface that includes the operations that a service endpoint exposes to the client applications.

    • You create the contract as an interface and specify the System.ServiceModel.ServiceContract() attribute on it.
    • The service operations to expose to client applications are the methods in the interface. You need to set the System.ServiceModel.OperationContract() attribute on these methods.

    Note: WCF Services use mostly the members that are part of the System.ServiceModel and System.Runtime.Serialization namespaces.

  3. Create the WCF service.

    You can define this as a COBOL class that implements the interface and the methods that represent the service operations.

  4. Configure the service.

    You specify the details for accessing the WCF service (the host and the endpoint details) in the App.config file in your project. You can use the WCF configuration editor to edit the App.config file - right-click the file and select Edit WCF Configuration.

  5. Host and run the service.

    You need to specify the service endpoints through which the service functionality is exposed, and enable metadata exchange for the service. The general details, or so called ABC, of an endpoint are: the address of the service, its binding and the service contract which is exposed. The WCF Service Library template has preconfigured endpoint and metadata exchange details which you might need to modify.

    Visual Studio provides a WCF Host Application and a WCF Test Client to enable you to host and test your services without a client application.

  6. Create a WCF client application.

    This is the application that accesses and consumes your service. The client connects to the WCF service through one of its endpoints and uses the service operations that are exposed.

    You can create the client application as a new project in your WCF solution and add a service reference to the WCF service project. From the context menu for the project invoke the Add Service Reference dialog and use it to discover and select the services in the solution.

  7. Configure the client to access the service through one of its endpoints.

    You specify the endpoint details for accessing the WCF service (the service address , the binding, the service name and contract) in an app.config file for the project for the client application.

  8. Use the client to access the service operations that are exposed.

    When the WCF service project is part of the solution that contains the client application, the service is usually hosted automatically when you start debugging. You can configure this in the project properties for the WCF service project.

For more, check Tutorial: Creating and Accessing WCF COBOL Services and the WCF Book Service and Client demonstration in the Samples.

Parent topic: Managed COBOL Programming


Problem Determination and Diagnostic Tools

  • Protection Violations
  • FaultFinder
  • Introduction to the Consolidated Tracing Facility
  • Profiler
Parent topic: Programming


Protection Violations

  • Overview - Protection 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) 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.

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


FaultFinder

FaultFinder is an aid to debugging production applications. It enables you to obtain a text-based report on the state of an application at the time of any abnormal application termination. The report is a snapshot of the application at the time of failure and identifies items such as open files, file buffers, loaded programs, and so on.

  • FaultFinder Tunables
    FaultFinder is controlled by tunables.
  • FaultFinder Report
    The FaultFinder report shows the state of an application at the time of any abnormal application termination
  • FaultFinder Listing Generator
    To help you analyze a FaultFinder report, you can take a snapshot of a program's source code, and its compiled characteristics, before shipping the program to your end-users.
Parent topic: Problem Determination and Diagnostic Tools


FaultFinder Tunables

FaultFinder is controlled by tunables.

To turn on FaultFinder set the run-time tunable faultfind_level to a positive value. Then, if the application terminates abnormally, the run-time-system automatically invokes FaultFinder which in turn generates the report.

The following run-time tunables control the operation and output of FaultFinder:

faultfind_config=n Controls the inclusion of program memory data in the output file, where value indicates the action to perform and the type of memory as follows:

0 = Include all types of memory (default)

1 = Exclude working storage

2 = Exclude thread-local storage

4 = Exclude dynamically allocated memory

These values can be combined to suppress combinations of types of memory, for example, a value of 5 will exclude working storage and dynamically allocated memory.

faultfind_level=n | Turns on FaultFinder and enables tracing of events. n can be any positive value less than or equal to 1024 and enables the last n events to be dumped. The default value is 0.
faultfind_outfile="filename" The file to which the analysis is written. The default filename is fltfnd.out in the current working directory. If, for some reason, the specified file cannot be opened, output is directed to the screen.

You can specify the filename as follows:

"fault%option.log"

Where option can be:

d = replaced with the date of the fault in the format <yyyymmdd>

p = replaced with the process ID of the faulting process

t = replaced with the time of the fault in the format <hhmmss>

faultfind_recsize="record_size" | A numerecord_sizeric value, in bytes, that specifies the amount of extra data that is to be kept for each trace operation. record_size can be any non-negative value less than or equal to 1024. The default value is 64.

Example:

set faultfind_config=5
set faultfind_level=5
set faultfind_outfile="applflt.log"
set faultfind_recsize=1024

FaultFinder Performance

Enabling FaultFinder event tracing (that is, setting faultfind_level to a value greater than 0) does have a performance impact, although it should not be noticeable in most cases. The number of events traced does not significantly impact performance; tracing one event is not significantly faster than tracing 1000. The most expensive operations to trace are file operations; the worst case for FaultFinder is a file handling benchmark. Even if this is the case, you would expect no more than a 5% performance degradation. Most applications which perform a mixture of operations should see minimal impact on performance.

FaultFinder Listing Generator

To help you analyze a FaultFinder report, you can take a snapshot of a program's source code, and its compiled characteristics, before shipping the program to your end users. You can create a snapshot using the FaultFinder Listing Generator.

Parent topic: FaultFinder
Related reference
faultfind_config
faultfind_level
faultfind_outfile
faultfind_recsize
Related information
FaultFinder Report
FaultFinder Listing Generator


FaultFinder Report

The FaultFinder report shows the state of an application at the time of any abnormal application termination

This information is contained in titled sections in the report. You can search for sections in the report by their titles.

For threaded programs (run with the multi-threading run-time system), additional information is output; this is discussed in the relevant sections.

Note:
  • On most systems only one process can have debug control over a target. If your target process is already being debugged by the Debugger, you might not be able to obtain a FaultFinder report.
  • It takes a finite amount of time to obtain the information used by FaultFinder. During this time, the target process is stopped and unable to respond to any user input.
  • FaultFinder Report - Environment
  • FaultFinder Report - Call Stack
  • FaultFinder Report - Loaded Programs
  • FaultFinder Report - Logically Canceled Programs
  • FaultFinder Report - Open Files
  • FaultFinder Report - Trace Back
Parent topic: FaultFinder
Related information
FaultFinder


FaultFinder Report - Environment

The Environment section of the report describes:

  • The application command line
  • The run-time system error (both number and message) that caused the problem
  • The date and time at which the dump was taken
  • For threaded applications, the identifier of the failing thread
  • The settings of all current environment variables
  • The settings of all the run-time tunables
Parent topic: FaultFinder Report


FaultFinder Report - Call Stack

The Call Stack section of the report contains, for each thread running at the time of failure, a call stack traceback. Programs are listed with full pathname and extension (where available). Entry points are not listed. The information for each thread is listed in a reverse calling hierarchy, so that:

  • The last program running (the program executing at time of termination) is listed first
  • Any programs that called the program that terminated, and any programs that called these programs are then listed
  • Finally, the initial program in the call hierarchy is listed

If the program contains Local-Storage and/or Linkage Sections, these sections are dumped with the corresponding call stack instance. For these sections, the following information is dumped:

  • Local-storage. The starting address is given followed by the contents. This information is dumped in hexadecimal and ASCII. Duplicate lines are not repeated but replaced by a single asterisk (*).
  • Linkage:
    • Addresses of Using parameters (in USING order)
    • Addresses of Linkage pointers (in Linkage Section order)

For .int files, the current program-counter is also dumped.

Parent topic: FaultFinder Report


FaultFinder Report - Loaded Programs

The Loaded Programs section of the report contains all currently loaded ("live") programs, with their reentrant and non-reentrant data areas. The non-reentrant data area has separate areas for working-storage and each instance of user-allocated data (using CBL_ALLOC_MEM, flag=0). A separate reentrant data area exists for each thread executing that program and has separate areas for thread-local storage and thread-local allocated data (using CBL_ALLOC_MEM, flag=8). Each chunk of data states the hexadecimal address of the data item and the dump (in hexadecimal and ASCII with duplicate lines not repeated but replaced by a single vertical bar (|)) of the data.

Note: The working-storage section includes all of the non-user program specific data areas, as in the file-control and file sections, as well as system needed non-reentrant space. To better define the start of the program's actual working-storage section, it is recommended that you insert a special data item as the first item in working-storage and give it a value that can easily be searched for.
Parent topic: FaultFinder Report


FaultFinder Report - Logically Canceled Programs

This section of the report contains a list of logically canceled programs, with full pathname and filename extensions.

Files that have been logically canceled are still known to the run-time system, so can be loaded and run directly without having to be loaded from disk. Files that are physically canceled release all their memory and no longer exist to the run-time system.

No other information is available in this section of the report.

Parent topic: FaultFinder Report


FaultFinder Report - Open Files

This section of the report contains information about all opened files, both local (non-external) and externally opened files. For each file the information listed is:

  • The filename
  • The exit status of a file operation
  • The record length
  • The organization
  • The open mode
  • For local files, which program it was opened by
  • The last record
  • The file control descriptor
  • The last operations performed on this file

The entire last record and the file control descriptor (FCD) are both dumped (with address) in hexadecimal and ASCII.

The operation trace records the basic operation (READ, WRITE, OPEN and so on) as well as the:

  • Exact operation code
  • Return status for that operation
  • Thread performing the operation
  • Dump of record data for the file operation

The last two items are only recorded when applicable.

Parent topic: FaultFinder Report


FaultFinder Report - Trace Back

The Trace Back section of the report lists the last n events for each thread, where n is defined by the run-time tunable faultfind_level. For each thread, the operations traced are:

  • CBL_ALLOC_MEM
  • CBL_ALLOC_DYN_MEM
  • CBL_ALLOC_SHMEM
  • CBL_ALLOC_THREAD_MEM
  • All file operations.

This section is broken down by thread; it records all operations for thread 1, followed by all operations recorded for thread 2, and so on. There are typically two events per operation: one as the operation begins, and another as it finishes.

Parent topic: FaultFinder Report


FaultFinder Listing Generator

To help you analyze a FaultFinder report, you can take a snapshot of a program's source code, and its compiled characteristics, before shipping the program to your end-users.

  • Using the FaultFinder Listing Generator
  • The FaultFinder Source Listing
Parent topic: FaultFinder


Using the FaultFinder Listing Generator

You can create a snapshot using the FaultFinder Listing Generator, which provides information in the form of a detailed listing file.

To create a listing file:

  1. Compile the program for debug
  2. Run the fflst command

To run the FaultFinder Listing Generator, use the command:

fflst options filename [listfile]

where the parameters are:

options
Specifies the level of detail in the FaultFinder listing. options can be any combination of:

If you specify no options, the Listing Generator produces the full source, data map, procedure map and cross-reference listing. For details of these listings, see below.

s | Suppresses the source listing
d | Suppresses the data map listing
-p | Suppresses the procedure map listing
-x | Suppresses the cross reference listing
-ln | Specifies a page size of n lines. The default is 66 lines
-v | Verbose output with version information
filename
The name of the .idy file to be processed. You do not have to specify the .idy file extension as this is the default file type.
listfile
The name of the file to which the listing is saved. If you do not specify this parameter, the listing is directed to the screen.
Note: The FaultFinder Listing Generator always uses the .idy file, not the COBOL source file.

For example, if you have a program appsource.cbl, the following command generates a full listing minus any cross-reference information in the listing file appsource.ffl:

cobol appsource.cbl anim;
fflst -x appsource.idy appsource.ffl
Parent topic: FaultFinder Listing Generator


The FaultFinder Source Listing

The FaultFinder listing is composed of several parts.

The examples of output in the topics describing these parts were generated using the following program:

 program-id. 'funbar'.
 working-storage section.
 01 ws-var-1    pic x(255).

 thread-local-storage section.
 01 tls-var-1   pic x(1021).

 local-storage section.
 01 ls-var-1    pic x(511).

 linkage section.
 01 lnks-var-1  pic x(2011).
 01 lnks-var-1r pic a(1024) redefines lnks-var-1.
 01 lnks-var-2  pic x(3096).

 procedure division using lnks-var-1 lnks-var-2.
     move tls-var-1 to ws-var-1
     if ws-var-1 = lnks-var-1
         display ls-var-1
     end-if
     stop run.

This program was compiled to generated code, and the FaultFinder listing generated using the commands:

cobol fun.cbl;
cbllink fun.obj
fflst –l19 fun.idy fun.lst
  • FaultFinder Source Listing - Header
  • FaultFinder Source Listing - Source
  • FaultFinder Source Listing - Map
  • FaultFinder Source Listing - Xref
Parent topic: FaultFinder Listing Generator


FaultFinder Source Listing - Header

The header to the listing provides useful information on the compilation of the program. An example header appears below, with additional notes describing the information presented below:

* * * * * * * * * * * * * COMPILATION SUMMARY * * * * * * * * * * *

        Micro Focus Net Express        V1.1 revision 000

        Product ID   : HXCTG/AA0/00000
        Compiler ref : GNR-071060000AD

        Date compiled: 05-Oct-99
        Time Compiled: 18:20

        Source File: fun.cbl
        .idy File  : fun.id   y
        Program ID : funbar
        Compiled to: Gnt/object with xref information

- - - - - - - - - - - - - - - - Sizes  - - - - - - - - - - - - - - -

 INT Code Proc:   000059  Data: 0001C4  Local: 000200 Thread: 0003FE
 GNT Code User:   000178  Full:   0002C8

- - - - - - - - - - - - -  02 Linkage Item(s) - - - - - - - - - - - -

 LNKS-VAR-1                 :   2011 bytes (h"000007DB")
 LNKS-VAR-1R                :   1024 bytes (h"00000400") (redef)
 LNKS-VAR-2                 :   3096 bytes (h"00000C18")

- - - - - - - - - - - -  Key Compilation Directives - - - - - - - - -

 noP64 INTLEVEL(3) noREENTRANT  CHARSET(ASCII)
 MF    noOSVS      noVSC2       CHECKDIV        PERFORM-TYPE(MF)
 noBOUND         TRUNC(ANSI)
 noSPZERO        noIBMCOMP

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

Information section

The first section of the listing provides information on the Compiler and the sources compiled. For the Compiler, the product name, product version, product ID and compiler reference number are given. These values are often useful to Micro Focus support representatives. For the source code, the files compiled, the resulting .idy file, the main entry point of the program and target mode of the compilation are given.

Sizes

The Sizes section of the report shows the sizes of the various segments defined in the program, in particular:

  • Intermediate code created during the syntax-check phase
  • Machine code generated during the generate phase
  • The Working-Storage Section, Local-Storage Section and the Thread-Local-Storage Section.

In the example listing above:

  • The syntax-check phase generated h"59" bytes of intermediate code
  • The generate phase created h"178" bytes of machine code as a result of user application code, and h"2C8" bytes of machine code in total
  • The Working-Storage Section is h"1C4" bytes long
  • The Local-Storage Section is h"200" bytes long
  • The Thread-Local-Storage Section is h"3FE" bytes long

Linkage items

The Linkage Item(s) section of the report lists the Linkage Section data items defined in this program, and their sizes. As these sizes are significant in interprogram communication, they warrant their own section. In the example above, the item LNKS-VAR-1R is a redefinition of LNKS-VAR-1, so there are effectively only two distinct linkage items.

Key Compilation Directives

The Key Compilation Directives section of the report lists the Compiler directives that affect run-time behavior.

Parent topic: The FaultFinder Source Listing


FaultFinder Source Listing - Source

There are two kinds of source listings that appear in the output, the Data Division listing and Procedure Division listing.

Data Division Listing

The Data Division listing looks like this:

fun.cbl, line 1
Line    Loc   :Size  ----+-*A-1-B--+----2----+----3----+----4----+---...-8
000001                        program-id. 'funbar'.
000002                        working-storage section.
000003  000050:0000FF         01 ws-var-1     pic x(255).
000004  000005                thread-local-storage section.
000006  000000:0003FD         01  tls-var-1   pic x(1021).
000007  000008                local-storage section.
000009  000000:0001FF         01  ls-var-1    pic x(511).
000010  000011                linkage section.
000012  000000:0007DB         01  lnks-var-1  pic x(2011).
000013  000000:000400         01  lnks-var-1r pic a(1024) redefines lnks-var-1.
000014  000000:000C18         01  lnks-var-2  pic x(3096).
000015  000016               procedure division using lnks-var-1 lnks-var-2.

The listing contains a page header, not shown in the example above, that gives product and compilation information. This is followed by the name of the source module that the first line of page originates from and its sequence number relative to that module. For example, the first line of page 1 in the example source listing originates from the module fun.cbl and is line 1 in that module.

After the line showing the module is a column scale; this indicates the COBOL areas of the source line (that is, Area A, Area B, and so on). In the example above, this scale is compressed to allow notations. In this scale line, there is also a header for the sequence line of the source lines being displayed.

Following the column scale is the Data Division code. The first 80 characters of each source line that was compiled are displayed in the body of the source listing. If a source line exceeds 80 characters, the excess characters are not shown.

The header indicates that the location (Loc) and size (Size) of each data item definition is displayed (in hexadecimal) immediately before the actual source line that defines the data item. For example, on line 3, the data item ws-var-1 is defined and it has an offset from the start of statically allocated data of h"50" and a size of h"ff" (decimal 255). Similarly, at line 6 the variable tls-var-1 has an offset of h"00" and a size of h"3FD" (decimal 1021).

Procedure Division Listing

The Procedure Division Listing looks like this:

fun.cbl, line 17
IntAddr:GntAddr----+-*A-1-B--+----2----+----3----+----4----+--- ... -8   Xref
000017  00002e                 sec1 section.                          =000017
000018  000030                 par1.                                  =000018
000019  000031:00000CC             move tls-var-1 to ws-var-1          000006 >000003
000020  000039:00000F4             if ws-var-1 = lnks-var-1           ?000003 ?000012
000021  000042:0000160                display ls-var-1                 000009
000022  000049                     end-if
000023  00004B:000016C         stop run.
000024

The listing contains a page header, not shown in the example above, that gives product and compilation information. This is followed by the name of the source module that the first line of the page originates from and its sequence number relative to that module. For example, the first line of page 2 in the listing originates from the module fun.cbl and is line 17.

After the line showing the module is a column scale that indicates the COBOL areas of the source line (that is, Area A, Area B, and so on). In the example listing above, this scale is compressed to allow notations. In the scale line there is also a header for the sequence line of the source lines being displayed.

The column scale contains the headers IntAddr and GntAddr, under which are shown the intermediate code address and the generated/object code address relative to the start of the module, of the actual source line from which the generated code was created. For example, for the syntax at line 19, the intermediate code address is h"31" and the generated/object code address is h"CC". The column scale aslo contains the header Xref, under which is shown the definition line of the data items that are manipulated in the statement, and any operations performed on the data items in the statement. The type of operations is indicated by a character:

= | Definition
> | Modification
? | Test

For example, on line 18 of the listing above, par1 is defined; on line 19, there is a reference to tls-var-1 which is defined on line 6 and there is a modification to ws-var-1 which is defined on line 3. On line 20, there is a test of ws-var-1, which is defined on line 3, and of lnks-var-1, which is defined on line 12.

Parent topic: The FaultFinder Source Listing


FaultFinder Source Listing - Map

There are two map listings, one for data items and one for procedural items.

Data Item Map Listing

The data item map listing looks like this:

* Data Map Listing
* Line   Name                           Addr   Size   Sec  Usage   Picture string
  000003 WS-VAR-1                       000050 0000FF WS   Alnum   PIC X(255)
  000006 TLS-VAR-1.                     000000 0003FD TS   Alnum   PIC X(1021)
  000009 LS-VAR-1                       000000 0001FF Lcl  Alnum   PIC X(511)
  000012 LNKS-VAR-1                     000000 0007DB Lnk  Alnum   PIC X(2011)
  000013 LNKS-VAR-1R.                   000000 000400 Lnk  Alpha   PIC A(1024)
  000014 LNKS-VAR-2                     000000 000C18 Lnk  Alnum   PIC X(3096)
  000000 RETURN-CODE                    000150 000002 WS   Comp    PIC S9(4) COMP
  000000 SORT-RETURN                    000154 000002 WS   Comp    PIC S9(4) COMP

This listing shows:

  • The line at which the data item was defined
  • The hexadecimal address and size of the data item
  • The section in which the data item was defined, identified by:
    WS | Working-Storage Section
    FS | File Section
    TS | Thread-Local Storage Section
    Lcl | Local Storage Section
    Lnk | Linkage Section
    Obj | Object-Storage Section
    SRg | Compiler Special Register
  • The usage defined for the data item, such as alphanumeric, alphabetic or computational
  • The picture of the data item

Procedural Item Map Listing

The procedural item map listing looks like this:

*  Procedure Map Listing
*  Line   Name                           Seg IntAddr  GntAddr  Sec/Par
   000017 SEC1                               000002E           Sec
   000018 PAR1
   0000030                                   00000CC           Par

This listing shows:

  • The line at which the procedural item was defined
  • The address in the intermediate and/or generated code at which the procedural item was defined
  • Whether the procedural item is a section or paragraph
Parent topic: The FaultFinder Source Listing


FaultFinder Source Listing - Xref

The Xref listing provides a sorted list of data names. It looks like this:

*  Xref Map Listing
*  Def'd  Name                    References, ?Tests, >Modifications
   000012 LNKS-VAR-1              0000013 0000016 ?0000020
   000013 LNKS-VAR-1R.
   000014 LNKS-VAR-2              0000016
   000009 LS-VAR-1                0000021
   000018 PAR1
   000017 SEC1
   000006 TLS-VAR-1               0000019
   000003 WS-VAR-1                >0000019 ?0000020
   000016 funbar*
   000001 funbar@

For each data item, the listing shows:

  • The line at which the data item was defined
  • The lines at which the data item is used
  • The operations performed on the data item on particular lines

The header to the third column, References, ?Tests, >Modifications, shows the type of operations that are recognized, and the indicators for these operations. For example, lnks-var-1 is defined at line 12, referenced at lines 13 and 16, and tested at line 20, while ws-var-1 is defined at line 3, modified at line 19 and tested at line 20.

A name suffixed with an asterisk (*) indicates the line at which that program's Procedure Division begins, while a name suffixed with the at sign (@) indicates the line at which that program's program id is defined.

Parent topic: The FaultFinder Source Listing


Introduction to the Consolidated Tracing Facility

The Consolidated Tracing Facility (CTF) is a tracing infrastructure that enables you to quickly and easily produce diagnostic information detailing the operation of Micro Focus software components 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.

Note:

CTF can also produce tracing information for applications running on Microsoft Azure or the Azure compute emulator. For more information on this see the documentation supplied with the Visual COBOL for Visual Studio 2010 Azure AddPack.

  • To enable CTF tracing
  • CTF Viewer
  • Components Traced by CTF
  • Configuration File for CTF
  • Emitter List
  • Tracing Examples
Parent topic: Problem Determination and Diagnostic Tools


To enable CTF tracing

  1. Set the MFTRACE_CONFIG environment variable to point to the configuration file, before you invoke the application. For example:
    set MFTRACE_CONFIG=c:\ctf\ctf.cfg
  2. Specify the format of CTF trace files you require by adding the appropriate lines in the configuration file ctf.cfg, or, if developing .NET managed code, a configuration file app.cfg located in the same folder as the associated app.exe file, such as:
    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
  3. Set the MFTRACE_LOGS environment variable to specify the location in which to create the CTF log files. If MFTRACE_LOGS is not set, the current folder is used. Your COBOL development system's command prompt sets MFTRACE_LOGS to the base\mftrace\logs directory.
  4. Run the application from the environment you set up.
  5. If you are using the .NET environment, instead of setting the MFTRACE_CONFIG variable you can configure CTF tracing in an app.config file in the same folder as its associated app.exe file. The configuration statements must be inserted in an <mftrace_config> section in the <configSections> as CDATA. For example:
    <?xml version ="1.0"?>
  <configuration>
    <configSections>
      <sectionGroup name="MicroFocus.COBOL.Tracing">
        <section name="mftrace_config"
         type="MicroFocus.COBOL.Runtime.CdataSectionHandler,
         MicroFocus.COBOL.Runtime.Win32,Version=4.0.0.0,Culture=neutral,
         PublicKeyToken=0412c5e0b2aaa8f0" />
      </sectionGroup>
    </configSections>
    <MicroFocus.COBOL.Tracing>
      <mftrace_config>
        <![CDATA[>
mftrace.dest                           = binfile
mftrace.emitter.binfile#location       = c:\logs
mftrace.level.mf.rts                   = info
mftrace.comp.mf.rts#pgm                = true
mftrace.comp.mf.rts#pgmload            = true
mftrace.comp.mf.rts#syspgm             = true
        <]]>
      </mftrace_config>
    </MicroFocus.COBOL.Tracing>
  </configuration>
    Note: If the MFTRACE_CONFIG variable is set, CTF will use it in preference to an app.config file.
Parent topic: Introduction to the Consolidated Tracing Facility


CTF Viewer

The Consolidated Tracing Facility (CTF) viewer is a tool for viewing binary format trace files that were created using the CTF binfile emitter..

The CTF viewer enables you to:

  • Navigate a trace file using the usual arrow and navigation keys
  • Display annotations for trace events to give them meaningful descriptions
  • Display more details of the selected event in the Properties view
  • Open more than one trace file at a time, with each trace file being opened in a separate editor tab
  • Set CTF preferences to control annotation file locations, and automatic switching to the CTF perspective
  • Use bookmarks for quick navigation
  • Perform text searches

To use the CTF viewer, you need to create trace files in binary format and to set up your environment and CTF configuration file appropriately.

  • Annotation Files for CTF Events
  • Bookmarks in the CTF viewer
  • To create and load a binary trace file into the CTF Viewer
  • To search in the CTF viewer
  • To enable your annotation files in the CTF viewer
Parent topic: Introduction to the Consolidated Tracing Facility
Related information
CTF Trace File Formats
Example CTF Configuration Files


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 base\MFTRACE\Annotations directory. There is one annotations file for each supported component.

Parent topic: CTF Viewer


Bookmarks in the CTF viewer

You can set bookmarks on events in a trace file, when you are using the CTF viewer. Bookmarks enable you to navigate quickly. Bookmarks behave as follows:

  • You can add a bookmark to an event, by right-clicking the event and clicking Add Bookmark.
  • Bookmarked events are shown in the main CTF View by a blue bookmark icon in column one of the event. They are also displayed in the Bookmarks view.
  • Double-click a bookmark in the Bookmarks view to jump to the bookmarked event in the Viewer. If the bookmarked event is in a file that isn't open, the file is automatically opened.
  • You can select multiple events in the main CTF view and set bookmarks on them all. You can also select multiple bookmarked events and remove their bookmarks.
  • Bookmarks persist between IDE sessions.
  • 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
Related information
CTF Trace File Formats
Example CTF Configuration Files


To create and load a binary trace file into the CTF Viewer

  1. Enable CTF tracing.
  2. Configure CTF to generate a binary trace file when the application is run, by adding the following lines to the configuration file ctf.cfg:
    mftrace.dest                     = binfile
mftrace.emitter.binfile#location = <directory in which to write the trace file>
  3. Run the application.
  4. Click File > Open File, and then double-click the trace file you want.

    Alternatively you can create a project containing the trace files.

    1. Create a new project of the General type.
    2. Follow the wizard, and when it asks for the location of your files, specify the directory containing your trace files. We recommend that you specify the trace file location defined in the mftrace.emitter.binfile#location entry in your CTF configuration file.
    3. In the COBOL Explorer view, double-click a trace file to load it into the viewer.
Parent topic: CTF Viewer


To search in the CTF viewer

  1. Right-click in the CTF viewer.
  2. Click Find.
  3. Enter your search string in the Find field, using the normal search features.
  4. Click Find.
Note:
  • You can use only Find capabilities and not Replace ones, since the trace file is loaded as a read-only file.
  • When you search for a text string, each row in the viewer is treated as a single text string, with each column in a row separated by a single space character. For example, a row with the following information is treated as a single text string for searching purposes:
    12:17:35.630 COBOL Runtime System 504 Library Load 0 0 C:\nx50\Base\BIN\UTILS.lbr
  • You can also use Find from the Edit menu.
  • You can use keys for Find next (Ctrl+K) and Find previous (Shift+Ctrl+K).
Parent topic: CTF Viewer
Related information
CTF Trace File Formats


To enable your annotation files in the CTF viewer

  1. Click Window > Preferences > Micro Focus COBOL > CTF > Annotation Files.

    Initially, the Location field is populated with the location of the trace files. This location is defined in the MFTRACE_ANNOTATIONS environment variable, which is set automatically in the Visual COBOL command environment from which you start Eclipse.

  2. Set the location to point to where your trace files are. You can add multiple locations and retain or remove the default location.
  3. Set the order of the trace file locations, so that the first location is used if trace files are found there.

The locations are preserved between Eclipse IDE sessions

Parent topic: CTF Viewer
Related information
CTF Trace File Formats
Example CTF Configuration Files


Components Traced by CTF

The Consolidated Tracing Facility (CTF) can produce tracing information for the components listed below:

  • mf.esmq Properties
    MQSeries XA switch module
  • mf.ide Properties
    Integrated Development Environment (IDE).
  • mf.mffh.fs Properties
    Fileshare
  • mf.mffh.xfh Properties
    File Handler system
  • mf.mffh.xsm Properties
    Sort
  • mf.mvs.casspool Properties
    JCL workload management
  • mf.mvs.mvscatio Properties
    JES system catalog
  • mf.rts Properties
    Run-time system
  • mf.mvs.le37 Properties
    Language environment services
Parent topic: Introduction to the Consolidated Tracing Facility
Related information
Introduction to the Consolidated Tracing Facility


mf.esmq Properties

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

The properties of the mf.esmq component provide information about the calls to the MQSeries XA switch module.

Property | Property Description | Level | Event Id | Event Description
ALL | Enables all of the tracing properties | - | - | -
MQLOAD | Switch load file events | DEBUG | 3 | Switch load file loaded
START | Start of work units | DEBUG | 3 | Unit of work started
END | End of work units | DEBUG | 3 | Unit of work finished
OPEN | Opening of MQI channels | DEBUG | 3 | MQI channel to the server queue manager opened
CLOSE | Closing of MQI channels | DEBUG | 3 | MQI channel to the server queue manager closed
COMMIT | Commit decisions | DEBUG | 3 | Decision made to commit the unit of work
ROLLBACK | Rollback decisions | DEBUG | 3 | Decision made to rollback the unit of work
PREPARE | Commit preparation | DEBUG | 3 | Preparation to commit the unit of work started
Parent topic: Components Traced by CTF


mf.ide Properties

Integrated Development Environment (IDE).

The following table lists the properties of the mf.ide component and shows the event information that can be included in the trace for each property.

The properties of the mf.ide component provide information about the behavior of the integrated development environment (IDE).

Property | Property Description | Level | Event Id | Event Description
DEBUG | Debugging of enterprise server SEPs. | DEBUG | 3 | Text strings indicating the status of various debugging operations.
EDIT | Editor functions. | DEBUG | 3 | Text strings indicating the status of editing-related operations that span more than one section of the IDE.
IDELOAD | IDE loading. | DEBUG | 3 | Text strings indicating the progress of loading, finishing when the IDE is loaded and initialized.
IDEVCS | Source code control system support. | DEBUG | 3 | Text strings indicating interaction with source code control systems.
SPFEDIT | SPF edit functions and all SPF line commands and the lines upon which they are operating. | DEBUG | 3 | Text strings indicating line commands, the line upon which the operation is occurring, and the results of processing.
VSXPRJ | Calls to Micro Focus Common Client (MFCC). The IDE uses the MFCC infrastructure to determine which enterprise servers to interact with. | DEBUG | 3 | Progress through MFCC calls and returned values along with an indication of logic flow.
 |  | ERROR | 3 | Text string indicating an enterprise server repository that has been found to be corrupt.
VSXREST 1 | VSXREST functions. | DEBUG | 3 | Text strings indicating different trace points in the VSXREST section of the IDE.
Parent topic: Components Traced by CTF
Related information
Introduction to the Consolidated Tracing Facility
Components Traced by CTF
1 VSXREST is the part of the IDE responsible for editing and debugging.


mf.mffh.fs Properties

Fileshare

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.

The properties of the mf.mffh.fs component provide information about the behavior of Fileshare.

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

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

Sort

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.

The properties of the mf.mffh.xsm component provide information about the behavior of Sort.

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

JCL workload management

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.

The properties of the mf.mvs.casspool component provide information about JCL workload management, such as job submission, dispatch, printing and held SYSOUT.

Property | Property Description | Level | Event Id | Event Description
ACTIVE | Movement of a job into active status. The job is given to the batch initiator for execution and upon completion of the job the batch initiator signals that it is ready for more work. | DEBUG | 4 | Compiled JCL has been executed.
COMP | Submission of JCL by Enterprise Server to be syntax checked. | DEBUG | 2 | A JCL file has been submitted for syntax scanning.
DELETE Removal of a job from the input, output, held, printing or active queues. DEBUG 7 A job has been removed from one of these quese. This could have occurred for the following reasons:
  • an active job has been killed
  • output has been requeued
  • a purge has taken place
DISP | Movement of a job from the input queue so that it can be executed by a batch initiator. | DEBUG | 3 | The next available compiled JCL for a given class and priority has been requested for scheduling in an available batch initiator.
OPEN | Opening and closing of the casspool.dat file. | DEBUG | 10 | casspool.dat is accessed when starting and stopping an initiator, initializing and terminating an enterprise server, and restarting a generic SEP.
OUTPUT | Movement of a job that has completed from the active queue to the output queue and performing of any associated cleanup tasks. | DEBUG | 5 | Compiled JCL has finished executing.
PRINT | Routing of a job to a batch printer or a batch printer exit. | DEBUG | 9 | This routing occurs upon job completion for active batch printers or when a SYSOUT is driven to the printer by requeuing.
REPL Replacement of a job that has either been made active or had been requested for execution into either the input or output queues. DEBUG 6 A job bas been replaced. This could have happened for the following reasons:
  • the job was previously active and canceled
  • a protection violation occurred in the batch initiator
  • a protection violation occurred in one of your programs
  • job was canceled by the operator

If the job was previously active it is moved to the output queue for review. If it was never made active then it is replaced in the input queue.

RETRIEVE | Requests to retrieve information about a job or SYSOUT DDs that are associated with a job. | DEBUG | 8 | These requests typically occur because of an interaction with ESMAC or when the casout utility needs to retrieve SYSOUT information.
Parent topic: Components Traced by CTF
Related information
Introduction to the Consolidated Tracing Facility
Components Traced by CTF


mf.mvs.mvscatio Properties

JES system catalog

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.

The properties of the mf.mvs.mvscatio component provide information about the JES system catalog, which maintains the relationship between the native file system and the MVS/VSE form of data set names.

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

Run-time system

This topic lists the properties of the mf.rts component and shows the event information that can be included in the trace for each property.

The properties of the mf.rts component provide information about the behavior of the run-time system.

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 | 48 | Insufficient low-memory available for PL/I. This property is for native COBOL only.
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

Language environment services

This topic lists the properties of the mf.mvs.le37 component and shows the event information that can be included in the trace for each property.

The properties of the mf.rts component provide information about the language environment services.

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.

A sample CTF configuration file ctf.cfg is supplied in your COBOL development system ...\examples directory.

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.
  • Example CTF Configuration Files
Parent topic: Introduction to the Consolidated Tracing Facility


mftrace.application

Restricts tracing to a specific application.

Syntax:

mftrace.application=executable-name

Parameters:

executable-name
The name of the executable for the application for which tracing is to be performed. This can be either a fully-qualified or unqualified name. Enclosing the executable name within parentheses indicates that the application is being run under a trigger program (such as run ), and that the second program of the command line is to be used as the real executable name.

Default:

All applications are traceable if you do not set mftrace.application.

Comments:

Use mftrace.application to restrict tracing to a specific application. If the name of the application's executable does not match executable-name, all preceding configuration entries are ignored and the remainder of the configuration file is not processed.

Examples:

To restrict tracing to the myapp executable:

...
mftrace.application=myapp
...

To restrict tracing to the otherapp executable being run under a trigger program:

...
mftrace.application=(otherapp)
...
Parent topic: Configuration File for CTF


mftrace.comp.component-name#property

Sets a component's property.

Syntax:

mftrace.comp.component-name#property-name=property-value

Parameters:

component-name
The name of the component for which the property is to be set. See Component List for a list of available components.
property-name
The name of the component property to set.
property-value
The value of the component property to be set.
If any of the following well-known property case-insensitive values are used, they are held in two forms: the string as given, and a corresponding numeric value. A component can then use CBL_CTF_COMP_PROPERTY_GET to retrieve the numeric value of the property directly without needing to perform its own string conversion.
String Value | Maps to
ON | 1
OFF | 0
YES | 1
Y | 1
NO | 0
N | 0
TRUE | 1
FALSE | 0
ENABLED | 1
DISABLED | 0
numeric-string | n

Component names and property names are case insensitive.

Default:

The properties and their associated values depend on the component.

Comments:

Use mftrace.comp.component-name#property to set the property with the given name and value for the given component. You can set any property name and value, regardless of whether the component actually makes use of it.

You can specify multiple mftrace.comp.component-name#property entries in the configuration file, but an entry that specifies a property for a component that has previously been set overrides the previous property value.

Properties are intended to be used for defining the areas of tracing that are required for the component.

Examples:

To set the Memory and PgmLoad properties for the mf.rts component:

...
mftrace.comp.mf.rts#memory=on
mftrace.comp.mf.rts#pgmload=enabled
...
Parent topic: Configuration File for CTF
Related information
Components Traced by CTF
mf.rts Component Properties
To enable CTF tracing
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
Related information
Emitter List
To enable CTF tracing
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
Related information
Emitter List
To enable CTF tracing
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
Related information
Emitter List
To enable CTF tracing
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
Related information
To enable CTF tracing
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
Related information
Components Traced by CTF
To enable CTF tracing
mftrace.application
mftrace.comp.component-name#property
mftrace.emitter.emitter-name#property
mftrace.level


Example CTF Configuration Files

Example ctf.cfg file 1

This configuration file traces the COBOL programs' loads, entries, exits and cancels, and creates a text file:

mftrace.emitter.textfile#Format = $(TIME) $(THREAD) $(COMPONENT) $(EVENT) $(LEVEL) :$(DATA)
mftrace.level.mf.rts              = info
mftrace.comp.mf.rts#pgm           = true
mftrace.comp.mf.rts#pgmload       = true
mftrace.comp.mf.rts#syspgm        = true

Example ctf.cfg file 2

This configuration file traces the COBOL programs' loads, entries, exits and cancels, and creates a text file:

mftrace.dest                      = binfile
mftrace.emitter.binfile#location  = c:\logs
mftrace.level.mf.rts              = info
mftrace.comp.mf.rts#pgm           = true
mftrace.comp.mf.rts#pgmload       = true
mftrace.comp.mf.rts#syspgm        = true

where:

  • c:\logs is the location where the trace files for the application is created.
  • binfile indicates that a binary trace file is to be generated

Example app.config file

(For .NET environment only.) This configuration file traces the COBOL programs' loads, entries, exits and cancels, and creates a text file:

<?xml version ="1.0"?>
  <configuration>
    <configSections>
      <sectionGroup name="MicroFocus.COBOL.Tracing">
        <section name="mftrace_config"
         type="MicroFocus.COBOL.Runtime.CdataSectionHandler,
         MicroFocus.COBOL.Runtime.Win32,Version=4.0.0.0,Culture=neutral,
         PublicKeyToken=0412c5e0b2aaa8f0" />
        </sectionGroup>
    </configSections>
    <MicroFocus.COBOL.Tracing>
      <mftrace_config>
        <![CDATA[>
mftrace.dest                           = binfile
mftrace.emitter.binfile#location       = c:\logs
mftrace.level.mf.rts                   = info
mftrace.comp.mf.rts#pgm                = true
mftrace.comp.mf.rts#pgmload            = true
mftrace.comp.mf.rts#syspgm             = true
        <]]>
      </mftrace_config>
    </MicroFocus.COBOL.Tracing>
  </configuration>
Parent topic: Configuration File for CTF


Emitter List

The Consolidated Tracing Facility can output its trace information using any of the emitters listed below:

  • CTF Trace File Formats
  • BINFILE Emitter Properties
    Writes to a binary file
  • IDEDBG Emitter Properties
    Writes to a debugger that is attached to the running process
  • TEXTFILE Emitter Properties
    Writes to a text file.
  • WINEVENT Emitter Properties
Parent topic: Introduction to the Consolidated Tracing Facility


CTF Trace File Formats

CTF is a diagnostic tool that traces running applications and creates trace files in one of two formats: text (the default) or binary.

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: Emitter List
Related information
Example CTF Configuration Files
Introduction to the CTF Viewer


BINFILE Emitter Properties

Writes to a binary file

You can view the trace files output by the BINFILE emitter using the CTFViewer utility that is supplied with your development system. The format of the trace files is platform independent.

To enable the BINFILE emitter, specify the following statement in the Consolidated Tracing Facility configuration file:

mftrace.dest = BINFILE

The following list shows the properties you can set to control the behavior of the BINFILE emitter:

Property | Description | Default
FILE The name of the trace file to be written. You can use the following pseudo-variables for the construction of the trace file name:
$(APPNAME)
The basename of the executable invoked to start the current process. For example, if run.exeis invoked, $(APPNAME) has the value "run".
$(EMITTER)
Always "BINFILE" for this emitter.
$(GEN)
The generation of the file, starting from 1.
$(PID)
The operating system identifier for the current process
$(APPNAME).$(EMITTER).$(PID).ctb, or $(APPNAME).$(EMITTER).$(PID).ctb_$(GEN) if the MAXGENERATION property has been specified. For example:
  • If the BINFILE emitter is being used to output trace events for run.exe executing as process-id 3456 and the MAXGENERATION property has not been specified, the trace file created will be called run.binfile.3456.ctb .
  • If the binfile emitter is being used to output trace events for myapp.exe executing as process-id 1975 and the MAXGENERATION property has been set to 3, the trace files created will be called myapp.binfile.1975.ctb_1, myapp.binfile.1975.ctb_2, and myapp.binfile.1975.ctb_3.
FLUSHEVERY | The number of trace records that will be output before the file is flushed. 0 indicates that the file will never be explicitly flushed. | 1
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.

Your COBOL development system command prompt implicitly sets MFTRACE_LOGS to the base\mftrace\logs directory in your COBOL development system installation.

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. | FALSE, indicating that the configured trace file includes only events from the current process
Parent topic: Emitter List


IDEDBG Emitter Properties

Writes to a debugger that is attached to the 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:

DELIMCHAR
The character used in the output file to delimit trace data parts for a trace event.
Default = 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.nnn.
Default = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
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
Default = 3
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
Default = 8
QUOTESTRING
Whether or not string trace data is to be output enclosed in double-quote characters.
Default = TRUE
Parent topic: Emitter List
Related information
Emitter List


TEXTFILE Emitter Properties

Writes to a text file.

The following list shows the properties you can set to control the behavior of the TEXTFILE emitter:

DELIMCHAR
The character used in the output file to delimit trace data parts for a trace event.
Default = 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.exe is invoked, $(APPNAME) has the value "run".
$(EMITTER)
Always "TEXTFILE" for this emitter.
$(GEN)
The generation of the file, starting from 1.
$(PID)
The operating system identifier for the current process.
Default = $(APPNAME).$(EMITTER).$(PID).log, or $(APPNAME).$(EMITTER).$(PID).log_$(GEN) if the MAXGENERATION property has been specified. For example:
  • If the TEXTFILE emitter is being used to output trace events for run.exe executing as process-id 3456 and the MAXGENERATION property has not been specified, the trace file created will be called run.textfile.3456.log .
  • If the TEXTFILE emitter is being used to output trace events for myapp.exe executing as process-id 1975 and the MAXGENERATION property has been set to 3, the trace files created will be called myapp.textfile.1975.log_1, myapp.textfile.1975.log_2, and myapp.textfile.1975.log_3.
FLUSHEVERY
The number of trace records that will be output before the file is flushed. 0 indicates that the file will never be explicitly flushed.
Default = 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).
$(THREAD)
The current operating system thread identifier.
$(TIME)
The current time, output as hh:mm:ss
Default = $(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
LOCATION
The folder where the trace files are to be written, that is
the folder specified by the MFTRACE_LOGS environment variable. If MFTRACE_LOGS is not set, the current folder is used. Your COBOL development system command prompt implicitly sets MFTRACE_LOGS to the base\mftrace\logs directory in your COBOL development system installation.

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.

Default = 8
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.
Default = 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.
Default = 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.

Default=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.
Default = TRUE
Parent topic: Emitter List


WINEVENT Emitter Properties

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:

DELIMCHAR
The character used in the output file to delimit trace data parts for a trace event. The default is 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: information
  • 2: warning
  • 3: error
  • 4: fatal
$(THREAD) | The current operating system thread identifier.
$(TIME) | The current time, output as hh:mm:ss.nnn.
The default is $(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
The default is 8.
LEVEL
The trace level below which this emitter will not output trace records. The default is 3.
QUOTESTRING
Whether or not string trace data is to be output enclosed in double-quote characters. The default is TRUE.
Parent topic: Emitter List


Tracing Examples

By default, tracing is disabled for all components, so the absolute minimum you need to do to enable run-time system tracing is to specify an mftrace.level or mftrace.level.mf.rts entry in the configuration file. For example, if you have set the MFTRACE_CONFIG environment variable set as follows:

set MFTRACE_CONFIG=e:\mydir\ctf.cfg

and e:\mydir\ctf.cfg contains only the following entry:

mftrace.level=error

a trace file with an entry for event id 255 would be created by any process that generated a run-time system error. Note that you do not have to specify any properties for the mf.rts component for this event to be emitted; having the trace level set to error is enough.

In the examples that follow, the application mymain is used. This application comprises two programs: mymain.cbl and mysub.cbl that include the following code:

mymain.cbl:

 identification division.
 program-id. mymain.
 environment division.
 data division.
 working-storage section.
 01 my-var pic 9(9) external.
 procedure division.
     move 1 to my-var

     perform 5 times
         call 'mysub'
         add 1 to my-var
     end-perform

     cancel 'mysub'

     call 'myprog'
     goback.

mysub.cbl:

 identification division.
 program-id. mysub.
 environment division.
 data division.
 working-storage section.
 01 my-var pic 9(9) external.
 procedure division.
     display my-var
     goback.

When mymain is executed, run-time system error 173 (“Called program file not found in drive/directory”) occurs because of the call to myprog. The contents of a trace file generated using the configuration above look similar to the following:

1>   # -MFTRACE Text Emitter-
2>   # CommandLine      = mymain
3>   # ProcessId        = 2404
4>   # Date             = 2004/12/14
5>   # Time             = 11:54:42.875
6>   # Operating System = Windows XP Service Pack 1 (Build 2600)
7>   # Computer Name    = PC-NAME
8>   # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
9>   11:54:42.875 MF.RTS 255 3 173 1 "myprog"
The entries marked 1> through 8> are header records output by the TEXTFILE emitter giving information about the application being traced. 8> indicates the format of the subsequent trace entries (this example is using the default trace entry format), so the fields in entry 9> can be interpreted as follows:
Information in Trace File | Pseudo-variable | Description
11:54:42.875 | $(TIME) | The time the trace entry was output.
MF.RTS | $(COMPONENT) | The name of the component outputting the trace entry. MF.RTS indicates the run-time system.
255 | $(EVENT) | The event identifier. Event identifier 255 for the mf.rts component indicates a run-time system error.
3 $(LEVEL) The level of the error, based on the following values:
  • 0 = debug
  • 1 = info
  • 2 = warning
  • 3 = error
  • 4 = fatal
173 1 "myprog" | $(DATA) | Event-specific data.

If you now rerun mymain after changing the statement in the configuration file to specify a trace level of INFO, as follows:

mftrace.level=info

the trace file created contains entries for the run-time system initialization and de-initialization events in addition to the run-time system error event. The trace file looks similar to the following:

    # -MFTRACE Text Emitter-
    # CommandLine      = mymain
    # ProcessId        = 2820
    # Date             = 2004/12/14
    # Time             = 12:27:04.317
    # Operating System = Windows XP Service Pack 1 (Build 2600)
    # Computer Name    = PC-NAME
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    12:27:04.317 MF.RTS 128 1
    12:27:04.327 MF.RTS 129 1
    12:27:04.337 MF.RTS 255 3 173 1 "myprog"
    12:27:04.367 MF.RTS 130 1
    12:27:04.367 MF.RTS 131 1

To see which programs the application has invoked before the run-time system error occurred you need to set the PGM property. If you want to see where the programs have been loaded from and when they are canceled, you also need to set the PGMLOAD property, as follows:

mftrace.level=info
mftrace.comp.mf.rts#pgm=true
mftrace.comp.mf.rts#pgmload=true

When you rerun mymain, the trace file created contains additional entries for program load, entry, exit, and cancel events. The trace file looks similar to the following:

    # -MFTRACE Text Emitter-
    # CommandLine      = mymain
    # ProcessId        = 4092
    # Date             = 2004/12/14
    # Time             = 13:44:30.868
    # Operating System = Windows XP Service Pack 1 (Build 2600)
    # Computer Name    = PC-NAME
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    13:44:30.868 MF.RTS 128 1
    13:44:30.888 MF.RTS 129 1
    13:44:30.888 MF.RTS 19 1 0 0 "mymain" "" ""
    13:44:30.888 MF.RTS 6 1 17 0 "mymain"
    13:44:31.008 MF.RTS 19 1 0 0 "mysub" "gnt" "E:\myprogs"
    13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.008 MF.RTS 20 1 0 0 "mysub"
1>  13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.139 MF.RTS 255 3 173 1 "myprog"
    13:44:31.199 MF.RTS 130 1
    13:44:31.199 MF.RTS 20 1 0 0 "mymain"
2>  13:44:31.199 MF.RTS 6 1 17 0 "mymain"
    13:44:31.199 MF.RTS 7 1
    13:44:31.199 MF.RTS 131 1

The entries marked 1> and 2> show event type 6 and 7 entries (program entry and exit) for a program immediately after an event type 20 entry (logical cancel) for the same program. This is because the Compiler embeds a cancel routine in all programs to close any files that the program may have opened. These cancel routines are implicitly invoked by the run-time system as part of a logical cancel operation.

To enable the tracing of all run-time system events with the exception of the memory management ones, you use the following configuration file entries:

mftrace.level = info
mftrace.comp.mf.rts#all=true
mftrace.comp.mf.rts#memory=false

When you rerun mymain, the trace file created contains additional entries for external data items. If you have compiled the programs with the AMODE directive, there would also be entries for each of the Mainframe Pointer Manager events. The trace file looks similar to the following:

    # -MFTRACE Text Emitter-
    # CommandLine      = mymain
    # ProcessId        = 2716
    # Date             = 2004/12/14
    # Time             = 14:33:22.704
    # Operating System = Windows XP Service Pack 1 (Build 2600)
    # Computer Name    = PC-NAME
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    14:33:22.704 MF.RTS 128 1
    14:33:22.714 MF.RTS 129 1
    14:33:22.714 MF.RTS 19 1 0 0 "mymain" "" ""
    14:33:22.714 MF.RTS 6 1 17 0 "mymain"
1>  14:33:22.714 MF.RTS 26 1 "MY_VAR" 9
    14:33:22.714 MF.RTS 19 1 0 0 "mysub" "gnt" "E:\myprogs"
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 20 1 0 0 "mysub"
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 255 3 173 1 "myprog"
    14:33:22.764 MF.RTS 130 1
    14:33:22.764 MF.RTS 20 1 0 0 "mymain"
    14:33:22.764 MF.RTS 6 1 17 0 "mymain"
    14:33:22.764 MF.RTS 7 1
2>  14:33:22.764 MF.RTS 27 1 "MY_VAR"
    14:33:22.764 MF.RTS 131 1

The entries marked 1> and 2> show the additional entries for external data items.

Parent topic: Introduction to the Consolidated Tracing Facility
Related information
To enable CTF tracing


Profiler

  • Introduction to Profiler
  • Running Profiler
  • Profiler Output
  • Time Spent in Called Programs
  • Directives for Profiler
Parent topic: Problem Determination and Diagnostic Tools


Introduction to Profiler

Note: This facility is supported in native COBOL only.

Profiler is a facility that enables you to obtain detailed statistics on the run-time performance of a COBOL program.

When you compile a program you can specify the PROFILE compiler directive. This causes the compiler to include code in your program that produces performance statistics about each paragraph of the program each time you run the compiled program. If your program contains no paragraphs, this report is not produced.

The performance statistics produced using the PROFILE compiler directive for that run of the program are contained in a file called program-name.ipf where program-name is the name of the program that was run. If an executable file is produced, then program-name is the first entry point name in the executable file.

These performance statistics are in compact form and first must be converted to a readable format, using Profiler.

By default, this file is created in the current working directory, but you can change this using the COBPRFDIR environment variable to specify an alternative directory. For example:

SET COBPRFDIR=C:\myipfdir
Parent topic: Profiler
Related information
PROFILE


Running Profiler

Note: This facility is supported in native COBOL only.

To start Profiler from the Visual COBOL command prompt, use the following command:

profiler filenames directives

where the parameters are:

filenames
One or more files containing compact Profiler output. Profiler always searches for a file with the filename extension .ipf; if you specify any other extension, it is ignored.
directives
One or more of the directives that control the operation of Profiler. To specify a directive to Profiler, you must precede it with a plus sign (+). You can precede each directive with a plus sign; alternatively, you can specify one at the start of a list of directives.

Directives must be separated by one or more spaces. Where a Profiler directive takes a parameter, you can enclose the parameter either in quotation marks or in parentheses. If you use either of these, however, you must escape them using the backslash character ( \).

Profiler creates a file with the extension .prf, with the same basename as the .ipf file. If you profile more than one program at one time, Profiler output for all programs is appended to the output file for the first program, that is filename1 .prf.

Parent topic: Profiler


Profiler Output

When you run Profiler, the following banner is displayed:

* Micro Focus COBOL Profiler Vv.r
* name-1
.
.
.
* name-n

where name is one of the files listed in filenames in the command line.

For example, if you compile the program prog1 with the PROFILE directive set, run the program, and then enter:

profiler prog1 +LIST

the following output is produced on the console:

* Micro Focus COBOL Profiler Vv.r
* prog1
 Total time: 172 milliseconds. Module called once.

%time   time    entries  ms/entry    paragraph
-----------------------------------------------------------------
64.53   111     21       5           TEST-ROUTINE
17.44   30      1        30          PARA1
16.28   28      15       2           NAME-ENTRY
1.74    3       1        3           END-SECTION
0.00    0       1        0           INITIAL(UNNAMED) PARAGRAPH

The Profiler output gives the total execution time (in milliseconds) for the program run and then breaks this down for each section and paragraph in the program:

Output | Description
%time | Total percentage of execution time spent in the named section or paragraph
time | Total time (in milliseconds) spent in the named section or paragraph
entries | Number of times the named section or paragraph was entered
ms/entry | Average time (in milliseconds) per entry to the section or paragraph
paragraph | Section or paragraph to which performance statistics apply. The initial (unnamed) paragraph listed is the initialization code executed before the user part of the program is entered.

The product of the ms/entry and the number of entries should equal the total time spent in the section or paragraph; however, because all three values are truncated, there can be a slight discrepancy.

Note: Profiler reports can include unnamed paragraphs that appear if a program has sections without subsequent paragraphs, or in-line PERFORM and EVALUATE statements.
Parent topic: Profiler


Time Spent in Called Programs

How the run-time system treats the time spent in a called COBOL program that has been compiled with the PROFILE directive (a profiled program) depends on the value of the profile_behavior run-time tunable. You specify this tunable when you run the program that you want to be profiled.

If the profile_behavior run-time tunable is set to 0 (the default), then time spent in a profiled called program is recorded both in the called program and in the calling program.

If the profile_behavior run-time tunable is set to1, then time spent in a profiled called program is recorded only in the called program.

For example, suppose program prog_a calls program prog_c. prog_a is a profiled COBOL program. Then:

  • If prog_c is not COBOL, time spent in prog_c is recorded in prog_a
  • If prog_c is COBOL but is not profiled, time spent in prog_c is recorded in prog_a
  • If prog_c is COBOL and profiled, time spent in prog_c is recorded in prog_c, and not in prog_a

If prog_a actually calls prog_b, which calls prog_c, and prog_b is not a profiled COBOL program, then time in prog_b is always recorded in prog_a, while time in prog_c is recorded as explained above.

Parent topic: Profiler


Directives for Profiler

You can use the following directives to control the behavior of the COBOL Profiler.

ALL
Outputs a full performance profile. If you do not set the ALL directive, no statistics are produced for sections or paragraphs that are not entered or PERFORMed
ALPHA
Outputs performance statistics in alphabetical order by paragraph name. If you do not specify ALPHA, statistics are output in descending order of the total percentage time spent in each paragraph.
FORM"integer"
Specifies the page size in lines for the listing file. The minimum value you should specify is 6. The default size is 60 lines.
LIST["destination"]
Specifies where the listing is to be produced.
If destination is specified, the output is written to that file.
If destination is not specified, then the output is sent to the console, with page headings and page throws omitted. The VERBOSE Profiler directive is also set automatically.
If you do not set the LIST Profiler directive, then by default the output is produced in a file called filename.prf, where filename is the first name in the files listed on the command line.
[NO]VERBOSE
Displays on the screen messages output by Profiler. The default setting is NOVERBOSE, unless the LIST directive is set without a specified parameter, in which case VERBOSE is set automatically.
WIDE
Allows lines in the Profiler output to be up to 131 characters wide. If the WIDE directive is not set, lines are truncated to 79 characters.
Parent topic: Profiler
Related information
PROFILE


Hints and Tips

  • Performance Programming
  • Programming Tips
Parent topic: Programming


Performance Programming

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 use a number of simple operations rather than one complex operation.

  • Optimizing Data Definitions
    Defining data items appropriately and aligning them to give the best performance.
  • Optimizing Arithmetic Statements
    Arithmetic statements, for which simple two-operand statements are the most efficient.
  • Optimizing COMPUTE Statements
    COMPUTE statements, which are for floating-point calculations.
  • Decimal Point Alignment
    Decimal point alignment. For operations on non-integer numbers, make the decimal point alignment of the operands match.
  • Optimizing Exponential Operations
    Exponential operations, some of which are optimized. For others, use MULTIPLY and DIVIDE.
  • Initializing Data Items
    Data item initialization. By default, COBOL initializes all data items in the Working-Storage Section to spaces if no VALUE clause is specified.
  • Optimizing Data Manipulation and Reference Modification
    Data manipulation and reference modification, and how to use the MOVE, INITIALIZE, STRING and UNSTRING statements.
  • Optimizing Table Handling
    Handling tables. For example, make each subscript a COMP-5 item 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. These are, if possible, optimized to produce in-line code.
  • Optimizing PERFORM Statements
    PERFORM statements. These are generally very efficient, although you can increase their performance in a number of ways.
  • Optimizing CALL Statements
    CALL statements. For example, to use these efficiently, call the program using a literal rather than a data-name, limit the number of CALL statements, and so on.
  • Optimizing Parameter Handling
    Passing parameters. For example. avoid making many references to linkage items.
  • Optimizing File Sorting
    Sorting files.
  • Aligning Bit Data Items
    Aligning bit data.
  • Compiler Directives for Optimizing Code
  • Examples
Parent topic: Hints and Tips


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.

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: Performance Programming


Speed of Processing of Different Data Types

The following list shows the order of speed of processing data of different types. This applies to any size of numeric data item. On this COBOL system this applies to integer data items. The list is ordered fastest to slowest.

  • COMP-5
  • COMP-X
  • COMP
  • COMP-3
  • DISPLAY

If the ON SIZE ERROR clause is used, or if the data item is non-integer, the above ordering does not apply. For example, arithmetic on such items uses packed decimal registers inside the In this non-optimized mode the order is:

  • COMP-3
  • DISPLAY
  • COMP
  • COMP-X
  • COMP-5

However, individual cases might behave differently.

  • 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", the default. See the COBOL On-line Reference for details.

Parent topic: Speed of Processing of Different Data Types


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. Arithmetic on COMP-3 data items is slower than DISPLAY items in intermediate code.

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

Align items on even-byte boundaries. Align numeric items greater than two bytes on four-byte boundaries. Use the ALIGN"4" Compiler directive to ensure that level-01 items are always aligned on such boundaries. Use ALIGN"8" for compatibility with 64-bit systems.

To ensure that all items in a table are correctly aligned, check that the size of an occurrence in the table (the of the table) is a multiple of two or four bytes as required. Pad the table as necessary. For example:

 01 a OCCURS 10.
     03 b PIC X(4) COMP-5
     03 c PIC X.
     03 filler PIC X(3).

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.

You can use the REF Compiler directive to find out how data items are aligned.

Parent topic: Optimizing Data Definitions


Optimizing Arithmetic Statements

Arithmetic statements, for which simple two-operand statements are the most efficient.

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.

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

Provided that 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: Performance Programming


Optimizing COMPUTE Statements

COMPUTE statements, which are for floating-point calculations.

Only use COMPUTE statements to perform calculations that involve floating-point data. For floating-point data, COMPUTE is the most efficient statement.

COMPUTE is defined 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 operations to be slower. The temporary field is stored in the target field with any necessary truncation. This also applies to IF statements involving expressions. 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: Performance Programming
Related information
Decimal Point Alignment
Exponential Operations
Initializing Data Items


Decimal Point Alignment

Decimal point alignment. For operations on non-integer numbers, make the decimal point alignment of the operands match.

Operations are fastest on integers. Operations on non-integer numbers are most efficient if 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 fastest if the source and target have the same decimal alignment.
  • MULTIPLY operations are fastest if the decimal alignment of the target is the sum of the alignments of the sources.
  • DIVIDE operations are fastest if the divisor has no fractional part and if the dividend and the target have the same decimal alignment.
Parent topic: Performance Programming
Related information
COMPUTE Statements
Exponential Operations
Initializing Data Items


Optimizing Exponential Operations

Exponential operations, some of which are optimized. For others, use MULTIPLY and DIVIDE.

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 for them. Where integer powers are involved, use MULTIPLY and DIVIDE operations instead.

Parent topic: Performance Programming
Related information
COMPUTE Statements
Decimal Point Alignment
Initializing Data Items


Initializing Data Items

Data item initialization. By default, COBOL initializes all data items in the Working-Storage Section to spaces if no VALUE clause is specified.

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.

Parent topic: Performance Programming
Related information
COMPUTE Statements
Decimal Point Alignment


Optimizing Data Manipulation and Reference Modification

Data manipulation and reference modification, and how to use 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 verb.

Do not use the INITIALIZE verb.

The STRING or UNSTRING verbs can create a large amount of code. To manipulate filenames 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: Performance Programming
Related information
The MOVE Statement
The INITIALIZE Statement
The USAGE Clause
The STRING Statement
The UNSTRING Statement
CBL_SPLIT_FILENAME
CBL_JOIN_FILENAME


Optimizing Table Handling

Handling tables. For example, make each subscript a COMP-5 item of the smallest optimum size for the values involved, and use the BOUND directive only when debugging.

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 samestride 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: Performance Programming
Related information
Example of Optimized Subscripts to Table Elements
Example of Optimizing USAGE DISPLAY Subscripts
BOUNDOPT
BOUND


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 information
The IF Statement
The EVALUATE Statement
The GO TO Statement


Optimizing Logical Operations

Logical operations, such as AND, OR and XOR. These are, if possible, optimized to produce in-line code.

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: Performance Programming
Related information
Logic Routines for Bit Manipulation


Optimizing PERFORM Statements

PERFORM statements. These are generally very efficient, although you can increase their performance in a number of ways.

Using PERFORM is generally very efficient, and 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.

    If your program does not trickle, you can compile it with the directive NOTRICKLE which causes the Compiler to produce more efficient code since PERFORM is implemented as a machine code CALL instruction with a corresponding RET at the end of the perform range. If NOTRICKLE is used where two perform ranges overlap, results are unpredictable.

    For example, do not use code in the following form:

  • 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.
Parent topic: Performance Programming
Related information
Example of Inefficient Use of the PERFORM Statement
TRICKLE


Optimizing CALL Statements

CALL statements. For example, to use these efficiently, call the program using a literal rather than a data-name, limit the number of CALL statements, and so on.

You can optimise 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 unmanaged 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.
Parent topic: Performance Programming
Related information
Parameter Handling
Call Conventions for Interfacing with Mixed Languages
Logical Operations
Logic Routines for Bit Manipulation
Overview - Mixed Language Programming
Overview - Calling COBOL Programs
DEFAULTCALLS


Optimizing Parameter Handling

Passing parameters. For example. avoid making many references to linkage items.

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 referred to in the Procedure Division header appear after those that do.

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 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. This construct is considered poor programming practice.

Parent topic: Performance Programming
Related information
CALL Statements
Linkage Section
CBL_ALLOC_MEM


Optimizing File Sorting

Sorting files.

If you use input and output procedures with a file sort in your program, it is important that you write them efficiently as they are executed once for each record that you are sorting. Inefficient input and output procedures can make the sort process appear to be very slow.

Parent topic: Performance Programming
Related information
The File Control Entry
The I-O-Control Paragraph
The SORT Statement


Aligning Bit Data Items

Aligning bit data.

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: Performance Programming


Compiler Directives for Optimizing Code

A number of Compiler directives can be used to optimize the native code for a program. Some of these directives must be used with care. Ensure that their expected behavior is acceptable for your application.

In general, always use the following directives when compiling your programs to native code:

  • NOALTER
  • ALIGN"4"
  • COMP
  • NOBOUND
  • NOCHECKDIV
  • NOODOSLIDE
  • NOQUALPROC
  • NOSEG
  • NOTRUNC

Use the REMOVE directive to remove the following reserved words:

  • REMOVE "UNSTRING"
  • REMOVE "STRING"
  • REMOVE "GIVING"
  • REMOVE "ROUNDED"
  • REMOVE "COMPUTE"
  • REMOVE "ERROR"
  • REMOVE "ALTER"
  • REMOVE "INITIALIZE"
  • REMOVE "CORRESPONDING"
  • REMOVE "TALLYING"
  • REMOVE "THRU"
  • REMOVE "THROUGH"

By removing these reserved words, you prevent code that uses these inefficient constructs from being added to the program.

You can use directives to optimize your program for speed.

  • Directives that Optimize for Speed
  • Directives that Optimize for Size
Parent topic: Performance Programming


Directives that Optimize for Speed

There are many Compiler directives that you can use to optimize for speed. In some cases, the defaults for directives are the ones that provide speed optimization. The following directives are those that need to be changed from their default values to provide for speed optimization.

  • ALTER
  • BOUND
  • BOUNDOPT
  • COMP
  • FASTLINK
  • LITLINK
  • OPT
  • SCHEDULER
  • TARGET
  • TRUNC
Parent topic: Compiler Directives for Optimizing Code
Related reference
ALTER
BOUND
BOUNDOPT
COMP
FASTLINK
LITLINK
OPT (Intel x86 platforms)
OPT (Non-Intel x86 platforms)
SCHEDULER
TRUNC


Directives that Optimize for Size

There are many Compiler directives that you can use to optimize for size. In some cases, the defaults for directives are the choices that provide size optimization. The following directives are ones that need to be changed from their default values to provide for size optimization.

  • ALIGN
  • OPT
Parent topic: Compiler Directives for Optimizing Code
Related reference
ALIGN
OPT (Intel x86 platforms)
OPT (Non-Intel x86 platforms)


Examples

  • Example of Inefficient Use of the PERFORM Statement
  • Example of Optimized Subscripts to Table Elements
  • Example of Optimizing USAGE DISPLAY Subscripts
Parent topic: Performance Programming


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


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


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


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: Hints and Tips
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.
display cmds
…

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

A more extensive illustration of recursive routines can be seen in the example program diophant.cbl. This program solves the linear equation Ax + By = 0 for integers x and y.

See Related information for the example program diophant.cbl.

Parent topic: Programming Tips


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

A |  | 0 | 0 | 1 | 1
B |  | 0 | 1 | 0 | 1
CBL_NOT | (not A) | 1 | 1 | 0 | 0
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_IMO | (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


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


Example of Intrinsic Functions

This example program, intrins.cbl, shows some of the ways you can use intrinsic functions in your programs.

Note:

There are three types of intrinsic function: integer, numeric and alpha. The FACTORIAL function used in the sample below is a numeric function. The coding technique shown might not apply for the other function types.

  1$set mf noosvs ans85
  2
  3*************************************************************
  4* Copyright Micro Focus Limited 1991. All Rights Reserved.  *
  5* This demonstration program is provided for use by users   *
  6* of Micro Focus products and may be used, modified and     *
  7* distributed as part of your application provided that you *
  8* properly acknowledge the copyright of Micro Focus in this *
  9* material.                                                 *
 10*************************************************************
 11
 12*************************************************************
 13*                                                           *
 14*                     INTRINS.CBL                           *
 15*                                                           *
 16*    This program demonstrates some of the ways you can     *
 17*    use Intrinsic Functions in your COBOL application.     *
 18*    This program uses the FACTORIAL Intrinsic Function     *
 19*    to illustrate the following capabilities:              *
 20*                                                           *
 21*    1) Data item is assigned the value of a function       *
 22*    2) Function is used as a data item in an EVALUATE      *
 23*           statement                                       *
 24*    3) Function is used as a data item in an IF            *
 25*           statement                                       *
 26*    4) Function uses an array element (fixed index) as     *
 27*           an argument                                     *
 28*    5) Function uses an array element (variable index)     *
 29*           as an argument                                  *
 30*    6) Data item is assigned the value of a function of    *
 31*           a function                                      *
 32*    7) Data item, assigned the value of the function,      *
 33*           is used in a COMPUTE statement                  *
 34*    8) Data item is assigned the value of the sum of       *
 35*           two functions                                   *
 36*    9) Function is used in the UNTIL condition of a        *
 37*           PERFORM ... UNTIL statement                     *
 38*                                                           *
 39*                                                           *
 40*    To familiarize yourself with the Intrinsic function    *
 41*    syntax, try running INTRINS under Debugger.            *
 42*                                                           *
 43*    Compile the program using:                             *
 44*                                                           *
 45*           COBOL INTRINS ANIM;                             *
 46*                                                           *
 47*    then debug the program:                                *
 48*                                                           *
 49*           ANIMATE INTRINS                                 *
 50*                                                           *
 51*                                                           *
 52*                                                           *
 53*                                                           *
 54*                                                           *
 55*************************************************************
 56 working-storage section.
 57 78 fals value 0.
 58 78 tru  value 1.
 59
 60 01 true-or-false               pic 9(1).
 61
 62 01 factor                      pic s9(10).
 63
 64 01 val                         pic s9(10).
 65
 66 01 indx                        pic 9(5) comp-x.
 67
 68 01 arg                         pic 9(2) comp-x  value 5.
 69
 70 01 arr                                         value "40537".
 71     03 elem   occurs 5 times   pic 9.
 72
 73 procedure division.
 74
 75 main-section.
 76
 77************************************************************
 78* Form 1 - Data item is assigned the value of the function *
 79************************************************************
 80
 81     compute factor = function factorial(0)
 82
 83************************************************************
 84* Form 2 - Function is used as a data item in an EVALUATE  *
 85*          statement                                       *
 86************************************************************
 87
 88     evaluate function integer(6.5)
 89      when 6
 90         move tru to true-or-false
 91      when other
 92         move fals to true-or-false
 93     end-evaluate
 94
 95************************************************************
 96* Form 3 - Function is used as a data item in an IF        *
 97*          statement                                       *
 98************************************************************
 99
100     if function integer (function factorial(arg)) = 120 then
101         move tru to true-or-false
102     else
103         move fals to true-or-false
104     end-if
105
106  ************************************************************
107  * Form 4 - Function uses an array element (fixed index) as *
108  *          an argument                                     *
109  ************************************************************
110
111     compute factor = function factorial(elem(4))
112
113  ************************************************************
114  * Form 5 - Function uses an array element (variable index) *
115  *          as an argument                                  *
116  ************************************************************
117
118       move 4 to indx
119       compute factor = function factorial(elem(indx))
120
121  ************************************************************
122  * Form 6 - Data item is assigned the value of a function   *
123  *          of a function                                   *
124  ************************************************************
125
126     compute factor = function factorial(
127                        function factorial(3))
128
129  ************************************************************
130  * Form 7 - Data item, assigned the value of the function,  *
131  *          is used in a COMPUTE statement                  *
132  ************************************************************
133
134     compute val = function factorial(3) + 5
135
136  ************************************************************
137  * Form 8 - Data item is assigned the value of the sum of   *
138  *          two functions                                   *
139  ************************************************************
140
141     compute val = function factorial(3) +
142                   function factorial(5)
143
144  ************************************************************
145  * Form 9 - Function is used in the UNTIL condition of a    *
146  *          PERFORM ... UNTIL statement                     *
147  ************************************************************
148
149     move 1 to indx
150     perform para-1 until function integer (function
151           factorial(indx))  = 120
152     stop run.
153
154 para-1.
155     compute indx = indx + 1.
Note:
  • Line 81
     compute factor = function factorial(0)

    Data item is assigned the value of the function

  • Lines 88-93
     evaluate function integer(6.5)
  when 6
     move tru to true-or-false
  when other
     move fals to true-or-false
 end-evaluate

    Function is used as a data item in an EVALUATE statement

  • Lines 100-104
     if function integer (function factorial(arg)) = 120 then
     move tru to true-or-false
 else
     move fals to true-or-false
 end-if

    Function is used as a data item in an IF statement

    The result of a numeric function is in floating-point format, so it cannot be expected to hold an exact integer value. In this example, the integer function is used to obtain an exact integer value for the IF statement.

  • Line 111
     compute factor = function factorial(elem(4))

    Function uses an array element (fixed index) as an argument

  • Lines 118-119
     move 4 to indx
 compute factor = function factorial(elem(indx))

    Function uses an array element (variable index) as an argument

  • Lines 126-127
     compute factor = function factorial (function factorial(3))

    Data item is assigned the value of a function of a function

  • Line 134
     compute val = function factorial(3) + 5

    Data item, assigned the value of the function, is used in a COMPUTE statement

  • Lines 141-142
     compute val = function factorial(3) + function factorial(5)

    Data item is assigned the value of the sum of two functions

  • Lines 149-155
        move 1 to indx
    perform para-1 until function integer (function
       factorial(indx)) = 120
  stop run.

 para-1.
    compute indx = indx + 1.

    Function is used in the UNTIL condition of a PERFORM ... UNTIL statement

Parent topic: Examples


Example of Bit Manipulation

The sample program logoper.cbl, shown below, illustrates the use of bit manipulation routines. It uses three of the logical call-by-name routines, namely, CBL_OR, CBL_AND, and CBL_XOR.

working-storage section.
01  clr-char            pic x value space.
01  clr-attr            pic x value x"0f".

78  text-start          value 29.
78  text-len            value 23.
78  text-end            value 51.

01  text-scr-pos.
    03  text-row        pic 9(2) comp-x value 12.
    03  text-col        pic 9(2) comp-x value text-start.
01  text-char-buffer    pic x(text-len)
                        value "Text-in-various-colours".
01  text-attr-buffer.
    03  first-word      pic x(4) value all x"0f".
    03  second-word     pic x(4) value all x"2c".
    03  third-word      pic x(7) value all x"14".
    03  third-space     pic x value x"30".
    03  fourth-word     pic x(7) value all x"59".
01  text-length         pic 9(4) comp-x value text-len.

01  char-read           pic x.
01  char-length         pic 9(9) comp-5 value 1.

01  quit-flag           pic 9 comp-x.
    88 not-ready-to-quit    value 0.
    88 ready-to-quit        value 1.

01  csr-pos.
    03  csr-row         pic 9(2) comp-x value 12.
    03  csr-col         pic 9(2) comp-x value 39.
01  csr-attr            pic x.
01  csr-length          pic 9(4) comp-x value 1.

01  blink-mask          pic x value x"80".
01  steady-mask         pic x value x"7f".

01  invert-mask         pic x(text-len) value all x"7f".

78  instr-len           value 41.
01  instr-length        pic 9(4) comp-x value instr-len.
01  instr               pic x(instr-len)
        value "Press (L)eft, (R)ight, (I)nvert or (Q)uit".
01  instr-pos.
    03  instr-row       pic 9(2) comp-x value 8.
    03  instr-col       pic 9(2) comp-x value 19.

procedure division.

main section.
    perform init-screen
    set not-ready-to-quit to true
    perform until ready-to-quit
        perform read-keyboard
        evaluate char-read
            when "L"
                perform csr-move-left
            when "R"
                perform csr-move-right
            when "I"
                perform invert-text
            when "Q"
                set ready-to-quit to true
        end-evaluate
    end-perform
    stop run
    .

init-screen section.
    call "CBL_CLEAR_SCR" using clr-char
                               clr-attr
    call "CBL_WRITE_SCR_CHARS" using instr-pos
                                     instr
                                     instr-length
    call "CBL_WRITE_SCR_CHARS" using text-scr-pos
                                     text-char-buffer
                                     text-length
    perform put-attrs-on-screen
    perform blink-cursor
    .

read-keyboard section.
    call "CBL_READ_KBD_CHAR" using char-read
    call "CBL_TOUPPER" using char-read
                             by value char-length
    .

csr-move-left section.
    perform steady-cursor
    subtract 1 from csr-col
    if csr-col < text-start
        move text-end to csr-col
    end-if
    perform blink-cursor
    .

csr-move-right section.
    perform steady-cursor
    add 1 to csr-col
    if csr-col > text-end
        move text-start to csr-col
    end-if
    perform blink-cursor
    .

blink-cursor section.

*> Turn on the blink bit at the current attribute.

    call "CBL_READ_SCR_ATTRS" using csr-pos
                                    csr-attr
                                    csr-length
    call "CBL_OR" using blink-mask
                        csr-attr
                        by value 1
    call "CBL_WRITE_SCR_ATTRS" using csr-pos
                                     csr-attr
                                     csr-length
    .

steady-cursor section.

*> Turn off the blink bit at the current attribute.

    call "CBL_READ_SCR_ATTRS" using csr-pos
                                    csr-attr
                                    csr-length
    call "CBL_AND" using steady-mask
                         csr-attr
                         by value 1
    call "CBL_WRITE_SCR_ATTRS" using csr-pos
                                     csr-attr
                                     csr-length
    .

invert-text section.

*> invert the bits that set the foreground colour, the background
*> colour, and the intensity bits, but leave the blink bit alone.

    call "CBL_READ_SCR_ATTRS" using text-scr-pos
                                    text-attr-buffer
                                    text-length
    call "CBL_XOR" using invert-mask
                         text-attr-buffer
                         by value text-len
    perform put-attrs-on-screen
    .

put-attrs-on-screen section.
    call "CBL_WRITE_SCR_ATTRS" using text-scr-pos
                                     text-attr-buffer
                                     text-length
    .

In the sample program, the section blink-cursor makes the cursor character (the character the cursor is pointing to) blink by its attributes. To see how you would create code to make the cursor blink, first consider the form of the display attribute. The following table shows the structure of the attribute byte for a personal computer with a monochrome display.

Bit | Attribute
7 | Blink
6-4 | Turns off display or sets reverse video
3 | Intensity
2-0 | Normal or underline select

Thus, for example, setting bit 7 to 1 turns blinking on. In the Working-Storage Section of the program, the mask for the "blink" attribute is defined as:

01 blink-mask pic x value x"80".

This hex value translates to the following bit pattern:

1 0 0 0 0 0 0 0

The CBL_READ_SCR_ATTRS routine reads the current attributes of the screen into an attribute buffer that in this case is one character long.

     call "CBL_READ_SCR_ATTRS" using csr-pos
                                     csr-attr
                                     csr-length

The CBL_OR routine does a logical OR on the current attributes and the blinking mask. This in effect turns on the blinking attribute. Note that the length parameter is 1. This says the OR operation is for one byte.

     call "CBL_OR" using blink-mask csr-attr by value 1

The CBL_WRITE_SCR_ATTRS routine writes the updated attributes buffer to the screen causing the character to "blink".

     call "CBL_OR" using blink-mask
                         csr-attr
                         by value 1
Parent topic: Examples


General Reference

  • C Functions for Calling COBOL
  • COBOL Language Reference
  • Command Line Reference
  • Compiler Directives
  • Environment Variables
  • Error Messages
  • File Handling Reference
  • Integrated Preprocessor Interface
  • Library Routines
  • Managed COBOL
  • Restrictions, Compiler Limits, and System Limits
  • Licensing
  • Run-time System Configuration
Parent topic: Micro Focus Visual COBOL for Visual Studio 2010


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.

  • cobcall
    Calls a COBOL program, subprogram or entry point from C.
  • cobcancel
    Cancels a program previously loaded by the COBOL run-time system.
  • 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.
  • 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.
  • coblines
    Returns the number of lines on the screen.
  • coblongjmp
    With the cobsetjmp function, provides the capability of a non-local GO TO, for use in error or exception handling.
  • cobpostsighandler
    Adds the specified handler to the list of handlers for the specified signal, at the specified priority.
  • 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.
  • cobsetjmp
    With the coblongjmp function, provides the capability of a non-local GO TO, for use in error or exception handling.
  • cobthreadtidy
    Tidies up the thread-local COBOL run-time environment.
  • cobtidy
    Tidies up the global COBOL run-time environment.
Parent topic: General Reference
Related information
Interfacing with C Programs


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 standard COBOL search order and paths.

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


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


cobcols

Returns the number of columns on the screen.

Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobscreen.h"

int cobcols (void);

Parameters:

None.

Comments:

This function returns the width in columns of the screen.

Equivalent COBOL Syntax:

call "CBL_GET_SCR_SIZE" using ...

Example:

To find out and display the width of the screen use:

int width = cobcols();

printf("Width of screen = %d\n", width);
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


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


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


coblines

Returns the number of lines on the screen.

Note: This function is supported for native COBOL only.

Syntax:

#include "cobscreen.h"

int coblines (void);

Parameters:

None.

Comments:

This function returns the depth in lines of the screen.

Equivalent COBOL Syntax:

call "CBL_GET_SCR_SIZE" using ...

Example:

To find out and display the depth of the screen use:

int depth = coblines();

printf("Depth of screen = %d\n", depth);
Parent topic: C Functions for Calling COBOL


coblongjmp

With the cobsetjmp 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 signal handler.

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


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


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


cobsetjmp

With the coblongjmp 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.

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


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


COBOL Language Reference

  • COBOL Language Supported and Copyrights
  • Notations
  • Part 1. Concepts
  • Part 2. Program Definition
  • Part 3. Additional Topics
  • Part 4: Appendices
Parent topic: General Reference
Related reference
Managed COBOL Reference


COBOL Language Supported and Copyrights

This describes the base COBOL language supported by this system: this COBOL language is based on the ANSI COBOL standards X3.23-1985, X3.23a-1989 and X3.23b-1993, and is supported by a number of COBOL systems. In addition, support has been added for some of the features from ISO/IEC 1989:2002, Programming language COBOL.

COBOL is an industry language and is not the property of any company or group of companies, or of any organization or group of organizations.

No warranty, expressed or implied, is made by any contributor or by the CODASYL Programming Language Committee as to the accuracy and functioning of the programming system and language. Moreover, no responsibility is assumed by any contributor, or by the committee, in connection herewith.

The authors and copyright holders of the copyrighted material used herein:

  • FLOW-MATIC Programming for the Univac I and II, Data Automation Systems copyrighted 1958,1959, by Sperry Rand Corporation; IBM Commercial Translator Form No. F28-8013, copyrighted 1959 by IBM; FACT, DSI27A5260-2760, copyrighted 1960 by Minneapolis-Honeywell

have specifically authorized the use of this material in whole or in part, in the COBOL specifications. Such authorization extends to the reproduction and use of COBOL specifications in programming manuals or similar publications.

Parent topic: COBOL Language Reference


Notations

Throughout this book, the following notation is used to describe the format of COBOL statements:

  1. Words printed in capital letters which are underlined must always be present when the functions of which they are a part are used. An error will be reported by your COBOL system if the underlined words are absent or incorrectly spelled. The underlining is not necessary when writing a COBOL source program.
  2. Words printed in capital letters which are not underlined are used in the COBOL source program for readability only. They may be written, or not, as the programmer wishes, but if written, must be correctly spelled.
  3. All words printed in small letters are generic terms representing names which will be devised by the programmer.
  4. When material is enclosed in braces { }, a choice must be made from the options within them.
  5. When material is enclosed in choice indicators { | | }, 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. 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.
  10. 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.

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

    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.

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

  14. 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.
  15. 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 250 single-byte or 125 double-byte characters.

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 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. Nonnumeric literals may be of 1 to 160 characters in length. Whether quotation marks

ISO2002 OSVS VSC2 MF or apostrophes

are used as delimiters, the presence of that delimiter within a nonnumeric 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 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 lietral) by expressing it as: Z"string", where string is a non-numeric 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.
VSC2 MF LENGTH OF data-name-2 2 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 3 S9(4) COMP

XOPEN S9(9) 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 4 | 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. 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.
ENT MF XML-EVENT 5 | 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-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-EVENT6 | 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 nondefault 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 correponds 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 delcaration. | 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 nondefault 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
1 The format of the contents of the CURRENT-DATE special register is sensitive to the CURRENT-DATE directive.
2 The LENGTH OF special register may be followed by an alphanumeric literal when using the Micro Focus dialect.
3 The size of the RETURN-CODE special register is sensitive to the XOPEN and RTNCODE-SIZE directives.
4 For a list of supported exception codes, see the topic XML-CODE Exception Codes.
5 The contents of XML-TEXT and XML-NTEXT vary depending on the contents of XML-EVENT. See Table 2 for additional information.
6 For all events except EXCEPTION, XML-CODE contains zero. Unless stated otherwise, the namespace XML registers (XML-NAMESPACE, XML-NNAMESPACE, XML-NAMESPACE-PREFIX, and XML-NNAMESPACE-PREFIX) are empty and have length zero.


Predefined Object Identifiers

The predefined object identifiers are:

Predefined Object Identifier | Usage
SELF | References the object on which the current method is executing. May be used in the Procedure Division of a method. References the object that was used to invoke the method in which SELF appears. If SELF is specified for a method invocation, the search for the method includes all methods declared for the object.
SELFCLASS | References the object that is the class object of the current object (SELF). If SELF is itself a class object, SELFCLASS is the system class BEHAVIOR. The class object BEHAVIOR terminates this self-reference. (i.e., If SELF is the BEHAVIOR of class, so is SELFCLASS.)
SUPER | References the object on which the current method is executing. May be used in the Procedure Division of a method. May be the object used to invoke a method with the INVOKE statement or inline invocation. References the object that was used to invoke the method in which SELF appears. If SUPER is specified for a method invocation, the search for the method ignores all the methods defined in the same class as the executing method.
NULL | References the null object reference value, which is a unique value that is guaranteed to never reference an object. NULL is implicitly described as class object and category object reference, and is not a universal object reference. NULL must not be specified as a receiving operand.
Parent topic: Language Structure


PICTURE Character-Strings

A PICTURE character-string consists of certain combinations of characters in the COBOL character set, used as symbols. See the topic The PICTURE Clause for the PICTURE character-string and for the rules that govern its use.

Any punctuation character that appears as part of the specification of a PICTURE character-string is not considered to be a punctuation character, but a symbol used in the specification of that PICTURE character-string.

Parent topic: Language Structure
Related information
The PICTURE Clause


Comment-entries

A comment-entry is an entry in the Identification Division that can be any combination of characters from the computer's character set. A comment-entry is for documentary purposes only, may extend over more than one line and is terminated upon encountering a division, section or paragraph name that is a reserved word

OSVS or encountering any character

in area A of a line. The continuation of a comment-entry by the use of the hyphen in the indicator area is not permitted.

Parent topic: Language Structure


Formats and Rules

  • General Format
  • Syntax Rules
  • General Rules
  • Elements
Parent topic: Concepts of the COBOL Language


General Format

A general format is the specific arrangement of the elements of a clause or a statement. Throughout this document a format is shown adjacent to information defining the clause or statement. When more than one specific arrangement is permitted, the general format is separated into numbered formats. Clauses must be written in the sequence given in the general formats. (Clauses that are optional must appear in the sequence shown if they are used.) In certain cases, stated explicitly in the rules associated with a given format, the clauses can appear in sequences other than that shown. Applications, requirements or restrictions are shown as rules.

Parent topic: Formats and Rules


Syntax Rules

Syntax rules are those rules that define or clarify the order in which words or elements are arranged to form larger elements, such as phrases, clauses, or statements. Syntax rules also impose restrictions on individual words or elements.

These rules are used to define or clarify how the statement must be written; that is, the order of the elements of the statement and restrictions on what each element may represent.

Parent topic: Formats and Rules


General Rules

General rules are those rules that define or clarify the meaning or relationship of meanings of an element or set of elements. They are used to define or clarify the semantics of the statement and the effect that it has on either execution or on the way intermediate code is produced.

Parent topic: Formats and Rules


Elements

Elements which make up a clause or a statement consist of upper-case words, lower-case words, level-numbers, brackets, braces, connectives and special characters.

Parent topic: Formats and Rules


Concept of Computer-independent Data Description

To make data as computer-independent as possible, the characteristics or properties of the data are described in relation to a standard data format rather than to an equipment-oriented format. This standard data format is oriented to general data processing applications and uses the decimal system to represent numbers (regardless of the radix used by the computer) and the remaining characters in the COBOL character set to describe nonnumeric data items.

Parent topic: Concepts of the COBOL Language


Concept of Levels

A level concept or hierarchy is inherent in the structure of a logical data record. This concept arises from the need to specify subdivisions of a record for the purpose of data reference. Once a subdivision has been specified, it can be further subdivided to permit more detailed data referral.

The most basic subdivisions of a record, that is, those not further subdivided, are called elementary items; consequently, a record is said to consist of a sequence of elementary items, or the record itself can be an elementary item.

In order to refer to a set of elementary items, the elementary items are combined into groups. Each group consists of a named sequence of one or more elementary items. Groups, in turn, can be combined into groups of two or more groups, and so on. Thus, an elementary item can belong to more than one group.

  • Level-Numbers
Parent topic: Concepts of the COBOL Language


Level-Numbers

A system of level-numbers shows the organization of elementary items and group items. Since records are the most inclusive data items, level-numbers for records start at 01. Less inclusive data items are assigned higher (not necessarily successive) level-numbers not greater in value than 49. A maximum of 49 levels in a record is allowed. There are special level-numbers, 66, 77

MF , 78

and 88 which are exceptions to this rule (see below). Separate entries are written for each level-number used.

A group includes all group and elementary items following it until a level-number less than or equal to the level-number of that group is encountered. All items which are immediately subordinate to a given group item should be described using identical level-numbers greater than the level-number used to describe that group item

OSVS VSC2 ; this rule is not insisted upon

.

Example

Correct OSVS VSC2 MF Incorrect but Permitted
01 A.
  05 C-1.
    10 D PICTURE X.
    10 E PICTURE X.
  05 C-2.

01  A.
  05 C-1.
    10 D PICTURE X.
    10 E PICTURE X.
 04 C-2.

Four types of entries exist for which there is no true concept of level. These are:

  1. Entries that specify elementary items or groups introduced by a RENAMES clause.
  2. Entries that specify noncontiguous working storage and linkage data items.
  3. Entries that specify condition-names.
  4. MF Entries that specify constant-names.

Entries describing items by means of RENAMES clauses for the purpose of regrouping data items have been assigned the special level-number 66.

Entries that specify noncontiguous data items, which are not subdivisions of other items, and are not themselves subdivided, have been assigned the special level-number 77.

Entries that specify condition-names, to be associated with particular values of a conditional variable, have been assigned the special level-number 88.

MF Entries that specify constant-names, to be associated with the value of a particular literal, have been assigned the special level-number 78.

Figure 1. Example of Level-numbers Representing a Data Hierarchy
Example of Level-numbers Representing a Data Hierarchy

Note that indentation of COBOL source code is a readability convention only and is not part of the language.

Elementary items are by definition those items without any subordinate entries (entries without numerically greater level-numbers) following, and must have a storage definition associated with them (see the topics The PICTURE Clause and the The USAGE Clause).

Note that only elementary items (marked with an asterisk, "*", above) and FILLER items (marked with a "#" sign above) have storage explicitly reserved for them (in accordance with the associated PICTURE clause); non-elementary items have implicit storage associated with them of size determined by their subordinate items plus any FILLER bytes needed for synchronization (see the topic The SYNCHRONIZED Clause).

Level-numbers need not be consecutively ascending or descending as shown above for clarity; thus, the next subordinate level after 01 could be 05, and the next level 10, and so on.

The above data descriptions would produce storage allocation in the following manner:

Data Record Storage Allocation

where:

R-E-I | is Record-Entry-Item
M-G-I | is Major-Group-Item
R-G-I | is Regular-Group-Item
S-G | is Sub-Group
EI | is Elementary-Item
NEI | is Noncontiguous Elementary-Item
Parent topic: Concept of Levels
Related information
The PICTURE Clause
The USAGE Clause
The SYNCHRONIZED Clause


Class and Category of Data

Every elementary data item, every literal, and every function has a class and a category. The class and category of a data item are defined by its picture character string, by the BLANK WHEN ZERO clause, or by its usage; the class and category of a literal are defined in the section Literals.

ANS85 and the class and category of an intrinsic function are specified by the definition of that intrinsic function (see the topic Intrinsic Functions).

The category of a group item is alphanumeric.

The following table depicts the relationship of categories to classes of data for elementary items.

Table 1. Category and class relationships for elementary items
Class Category
Alphabetic
  • Alphabetic
Alphanumeric
  • Numeric edited
  • Alphanumeric edited
  • Alphanumeric
  • VSC2 MF DBCS
Index
  • Index
National
  • National
Numeric
  • Numeric
  • OSVS VSC2 MF Internal floating-point
  • OSVS VSC2 MF External floating-point
Object
  • ISO2002 MF Object-reference
Pointer
  • ISO2002 VSC2 MF Pointer
  • MF COB370 Procedure-pointer
  • Algebraic Signs
  • Standard Alignment Rules
  • Item Alignment for Increased Object-code Efficiency
  • Selection of Character Representation and Radix
  • Uniqueness of Reference
  • Explicit and Implicit Specifications
Parent topic: Concepts of the COBOL Language
Related information
Literals
Intrinsic Functions


Algebraic Signs

Algebraic signs fall into two categories:

  1. Operational signs, which are associated with signed numeric data items and signed numeric literals to indicate their algebraic properties.
  2. Editing signs, which appear on edited reports to identify the sign of the item.

The SIGN clause permits you to state explicitly the location of the operational sign. The clause is optional; if it is not used, operational signs are represented as described in the section Selection Of Character Representation And Radix.

Editing signs are inserted into a data item through the use of the sign control symbols of the PICTURE clause.

Parent topic: Class and Category of Data
Related information
Selection Of Character Representation And Radix


Standard Alignment Rules

The standard rules for positioning data within an elementary item depend on the category of the receiving item. These rules are:

  1. If the receiving data item is described as numeric:
    1. The data is aligned by decimal point and is moved to the receiving character positions with zero fill or truncation on either end as required
    2. When an assumed decimal point is not explicitly specified, the data item is treated as if it had an assumed decimal point immediately following its rightmost character and is aligned as in paragraph a. above.
  2. If the receiving data item is a numeric edited data item, the data moved to the edited item is aligned by decimal point with zero fill or truncation at either end as required within the receiving character positions of the data item, except where editing requirements cause replacement of the leading zeros.
  3. If the receiving data item is alphanumeric (other than a numeric edited data item), alphanumeric edited or alphabetic, the sending data is moved to the receiving character position and aligned at the leftmost character position in the data item with space fill or truncation to the right, as required.
  4. OSVS VSC2 MF If the receiving data item is external floating-point, the leftmost non-zero digit, if one exists, is aligned on the leftmost digit position: the exponent is adjusted accordingly.

If the JUSTIFIED clause is specified for the receiving item, these standard rules are modified as described in the section The JUSTIFIED Clause in the chapter Data Division - File and Data Description.

Parent topic: Class and Category of Data
Related information
The JUSTIFIED Clause


Item Alignment for Increased Object-code Efficiency

Some computer memories are organized so that natural addressing boundaries exist in the computer memory (for example, word boundaries, half-word boundaries, byte boundaries). The way in which data is stored need not respect these natural boundaries.

However, certain uses of data (for example, in arithmetic operations or in subscripting) can be facilitated if the data is stored so as to be aligned on these boundaries. Specifically, additional machine operations in the run-time element can be repeated for the accessing and storage of data if portions of two or more data items appear between adjacent natural boundaries, or if certain natural boundaries divide a single data item.

Data items which are aligned on these natural boundaries in such a way as to avoid additional machine operations are defined to be synchronized. A synchronized item is assumed to be introduced and carried in that form; conversion to synchronized form occurs only during the execution of a statement (other than READ or WRITE) which stores data in the item.

Synchronization can be accomplished in two ways:

  1. By use of the SYNCHRONIZED clause
  2. By organizing the data suitably on the appropriate natural boundaries without the use of the SYNCHRONIZED clause.

By use of the SYNCHRONIZED clause, the use of special types of alignment within a group can affect the results of statements in which the group is used as an operand. The effect of the implicit FILLER and the semantics of any statement referencing these groups is described later in this chapter.

Parent topic: Class and Category of Data


Selection of Character Representation and Radix

The value of a numeric item (defined as numeric by its PICTURE, see the topic The PICTURE Clause) can be represented in the computer's storage in either binary or decimal form depending on the USAGE clause of the declaration (see the topic The USAGE Clause). These numeric formats are:

  • DISPLAY
  • COMPUTATIONAL, COMP,

    ANS85 BINARY,

    OSVS VSC2 MF COMPUTATIONAL-4 or COMP-4

  • OSVS VSC2 MF XOPEN COMPUTATIONAL-3, COMP-3 or

    ANS85 PACKED-DECIMAL

  • MF XOPEN OS390 COMPUTATIONAL-5, COMP-5,
  • MF COMPUTATIONAL-X or COMP-X

  • OSVS VSC2 MF COMPUTATIONAL-1, COMPUTATIONAL-2

    ,

    ISO2002 FLOAT-SHORT or FLOAT-LONG

  • VSC2 MF POINTER
  • MF COB370 PROCEDURE-POINTER

ANS85 An alphanumeric function is always represented in the standard data format. Its size is determined by the definition of the function.

The representation of integer and numeric functions is as follows:

  • COMP-2 if the function is trigonometric or if one or more function arguments are COMP-2 and the function is not defined as returning an integer.
  • Otherwise, as PIC SV9(39)ES9(4). The exponent is S9(4) COMP and so has a range of approximately +/-32k.

Integer and numeric functions can be used only in arithmetic expressions, and represent the value resulting from the evaluation of the function without the restriction on composite of operands and/or receiving data items.

When a computer provides more than one means of representing data, the standard data format must be used for data items

ANS85 other than integer and numeric functions,

if not otherwise specified by the data description.

  • DISPLAY Format
  • COMPUTATIONAL, BINARY, or COMPUTATIONAL-4 Format
  • COMPUTATIONAL-1, COMPUTATIONAL-2,FLOAT-SHORT and FLOAT-LONG Formats
  • COMPUTATIONAL-3 or PACKED-DECIMAL Format
  • COMPUTATIONAL-X and COMPUTATIONAL-5 Formats
  • POINTER Format
  • PROCEDURE-POINTER Format
Parent topic: Class and Category of Data
Related information
The PICTURE Clause
The USAGE Clause


DISPLAY Format

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
Related concepts
COMPUTATIONAL-1 Data Items with a PICTURE other than S9(4)


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
Related concepts
COMP-3/COMPUTATIONAL-3 Data


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, there is still a maximum of 18 digits which can be specified (either up to eighteen "9"s or up to eight "x"s in the PICTURE clause). If the compiler directive INTLEVEL(4) is specified, the maximum is 38 digits (either thirty-eight "9"s or sixteen "x"s).
  • 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.

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. Records within a set of records that have duplicate alternate record key values are retrieved in the 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
  • 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

Note: This functionality is not supported in COBOL for JVM.

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.

To use a delegate in COBOL there must be a declaration, instantiation and finally invocation, as follows:

Declaring a delegate

To declare a delegate you must declare a method name and its signature. In COBOL you do this by defining a specialized class with a single method that represents the delegate. A delegate declaration looks very much like a class but is declared using the DELEGATE-ID keyword.

Instantiating a delegate

To make use of an existing delegate, for instance System.EventHandler defined in the framework, you must provide a method implementation with the same signature as the delegate. You can then instantiate a new instance of the delegate class by supplying your method as a parameter to the constructor. Depending upon whether this method is a static or an instance member of a class determines how you specify this parameter in the constructor, as specified below:

Static method:     class name::MethodName
Instance method:   object reference::MethodName
Invoking a delegate

When you declare a DELEGATE-ID, the compiler creates a class that inherits from the System.MulticastDelegate class. All delegates have a method named 'Invoke' whose signature matches the signature of the method in your DELEGATE-ID declaration. Therefore, if you hold an object reference to a delegate instance, you can invoke the INVOKE method on this object which actually invokes the implementation of the method supplied when the delegate was constructed.

We provide a sample program that declares a new delegate class using DELEGATE-ID and then demonstrates how that delegate can be invoked using either static or instance method implementations. However, it's useful to note that in most cases, the delegate pattern is used in a more client/server like role where one software component provides the delegate definition and a separate component provides the implementation e.g. a method to be executed when a button on a form is clicked.

Parent topic: Managed Code Concepts
Related information
The Delegate-ID Paragraph


Enumerations and Enum types

An enumeration represents a list of constant values, such as values for the days of the week. You can declare an enum type that defines the values and symbolic names for them. You can then refer to the values by name.

For example, you could declare an enum type for the days of the week, as follows:

enum-id DaysOfWeek as "DaysOfWeek".
       01 binary-long.
          78 Sunday value 0. *> optional, as 0 is the default
          78 Monday.         *> by default, this is value 1
          78 Tuesday.        *> by default, this is value 2 and so on
          78 Wednesday.
          78 Thursday.
          78 Friday.
          78 Saturday.
       end enum.

You can then refer to the enum type in your code, as follows:

set today to type DaysOfWeek::Monday

Where DaysOfWeek::Monday represents the binary-long value 1.

The Compiler adds a static method called 'values' that returns an array containing the values of the enum. You can use this method together with the PERFORM THROUGH construct to iterate over the values of an enum type.

You declare an enum using the ENUM-ID paragraph. This is followed by a working-storage section consisting of:

  • A single numeric field of one of the predefined types. By default, this is binary-long corresponding to the .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 using the syntax:

self::memberName

The optional SHARING PARENT phrase in the nested class definition enables 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 using the self:: syntax, 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 self::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 cannot access instance members of the containing class with the self:: syntax, but only do it 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 that a class name is expected. For example:

    01 anInteger binary-long.

Predefined Managed Types

Managed COBOL | .NET class | JVM type | C# type | 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 unsigned integer Not CLS-compliant
binary-short unsigned | System.UInt16 |  | ushort | A 16-bit signed 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 |  | decimal | A 96-bit decimal value
type System.IntPtr | System.IntPtr |  |  | A signed integer whose size depends on the underlying platform (a 32-bit value on a 32-bit platform and a 64-bit value on a 64-bit platform)
type System.UIntPtr | System.UIntPtr |  |  | An unsigned integer whose size depends on the underlying platform (a 32- bit value on a 32-bit platform and a 64-bit value on a 64-bit platform) Not CLS-compliant
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

Defining Types with 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.

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 Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET.

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.

In .NET COBOL, to refer to a generic type using the TYPE literal syntax, you enumerate the generic parameters within square brackets. The following example declares myNames as an item of type Dictionary with both generic parameters set to string (System.String):

myNames type System.Collections.Generic.Dictionary[string, string].
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 Comment
Parent topic: Reference Format
Related information
Reference Format Representation


In-line Comment

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

Note: This functionality is not supported in COBOL for JVM.

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
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 operators in managed COBOL, use the following construct:

       class-id MyOperatorExtension static.
       operator-id = extension
       local-storage section.
       procedure division using s1 as string s2 as string
                      returning myReturn as condition-value.
       set myReturn to my code...
       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 may have any 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 a trailing separate character.
  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: This syntax is no longer required and is not recommended. It is supported 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.
    • 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

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 .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 .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. NET JVM Enum-name-1 is the name of an enumeration definition that may be used throughout the scope of the containing Environment Division.
  14. 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.
  15. Function-prototype-name-1 is the name of a function prototype that may be used throughout the scope of the containing Environment Division.
  16. 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.
  17. Intrinsic-function-name-1 may be specified in a function-identifier without being preceded by the word FUNCTION.
  18. 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.
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


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.
  13. ANS85 Character-string must not be a reserved word, a user-defined word that is defined elsewhere, or a literal.

Syntax Rules for Formats 1 and 2 (Record and Line SequentialFiles)

  14. When the ORGANIZATION clause is not specified, sequential organization is assumed.
  15. MF KEYBOARD means console input.
  16. MF DISPLAY means console output.
  17. MF PRINTER specifies the system's main printer.
  18. MF PRINTER-1 specifies the system's second printer.

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

Syntax Rules for Format 5 (Sort-Merge Files)

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

General Rules for Format 2 (Line SequentialFiles)

  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. MF XOPEN The LOCK MODE IS clause is documentary only.

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 elementand the operating system.

General Rules for Format4 (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 describedonly in one of these record description entries. The identical character positionsreferenced by data-name-5

    ISO2002 MF and any data-names referenced by split-key-name-1

    in any one record descriptionentry are implicitly referenced as keys for all other record description entriesof 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-MergeFiles)

  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.

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 LOCAL-STORAGE SECTION header is not permitted in nested programs.
  7. 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 concepts
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.

Note: This functionality is not supported in COBOL for JVM.

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.

    MF These restrictions do not apply.

  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 The EXTERNAL clause must not be specified in the data division of a method, or 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.
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.

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 for Format 1 (All Files)

General Formats for Format 2 (All Files)

Syntax Rules for Format 1 (All Files)

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

Syntax Rules for Format 2 (All Files)

  2. MF Data-name-2 must be in the Working-Storage Section.
  3. MF Literal-2 must be a nonnumeric literal and cannot be a figurative constant.
  4. MF The VALUE OF FILE-ID clause cannot 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).

General Rules for Format 1 (All Files)

  1. MF This clause is documentary only.

General Rules for Format 2 (All Files)

  2. MF The character-string specified in literal-2 or data-name-2 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

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.
  • 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.
    Note: The ANY LENGTH clause is not permitted to be specified in an outermost program. This is because an outermost program can be called with or without a program-prototype format CALL statement. For calls without a program-prototype, the implementation is not able to determine whether an argument corresponds to a formal parameter described with ANY LENGTH.
  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.
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

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 specifed, 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. Data-name-1 must have a fixed location, and must not follow an item that contains an OCCURS DEPENDING ON clause.
  4. 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.

  5. 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.
  6. 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.
  7. 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
  8. 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.
  9. 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.
  10. 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.
  11. 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

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

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". The number of digit positions that can be described by the PICTURE character-string must range from 1 through 18.

    ISO2002 OS390 The PICTURE character-string can contain up to 31 digit positions.

    MF The PICTURE character-string can contain up to 18 digit positions by default or if you set INTLEVEL"2", and up to 38 digit positions if you set INTLEVEL"4".

  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 number of digit positions that can be represented in the PICTURE character-string must range from 1 through 18.

      ISO2002 OS390 The PICTURE character-string can contain up to 31 digit positions.

      MF The PICTURE character-string can contain up to 18 digit positions by default or if you set INTLEVEL"2", and up to 38 digit positions if you set INTLEVEL"4".

    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 (18) 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 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 concepts
PICTURE Character-strings
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 eight bytes inclusive. If it describes an alphanumeric item of size 1, 2, 3, 4, 5, 6, 7, or 8 bytes, then this is equivalent to specifying an integer item with 2, 4, 7, 9, 12, 14, 16 or 18 decimal digit positions respectively

    .

    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. MF An elementary data item whose description contains, 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 or national-edited data item.
  22. 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.
  23. 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.

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

  25. MF The NATIONAL phrase must be specified in a USAGE clause associated with an elementary data item whose explicit or implicit picture character-string contains the symbol 'N'.
  26. NET JVM A USAGE clause with the CONDITION-VALUE phrase must be specified only for an elementary data item with level 1.
  27. 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.

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 programpointer 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.
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 Format 3 can be used only in a constant-name entry.
  14. 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.
  15. MF Any number of arithmetic or logical operators can be used. The result is evaluated using integer arithmetic in strict left to right order. No parentheses can be used. If any intermediate result is less than zero, the final value is undefined. A constant-name may be used in place of integer-1.
  16. MF The logical operations AND and OR act on the binary representation in a bit-wise manner.
  17. 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.
  18. 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.
  19. MF START of identifier-2 or identifier-4 is the offset at which identifier-2 or identifier-4, respectively, begins.
  20. MF For rules 18 and 19, 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.
  21. MF Offsets are not portable across different COBOL implementations and no reliance should be placed on particular values outside this compilation unit.

Table Rules (Format 4)

  22. 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.
  23. 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.
  24. 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.
  25. 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

  26. 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 concepts
Initialization of Working Storage
Related information
Standard Alignment Rules
The SET Statement
The PICTURE Clause
NEXT Phrase of CONSTANT-NAMES


Screen Section

Note: This functionality is not supported in COBOL for JVM.
  • 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.

Note: This functionality is not supported in COBOL for JVM.

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 COLUMN clause specifies the column in which the screen item is to appear on the screen in an ACCEPT or DISPLAY operation.
  2. 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.

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

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

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
      • BELL/BEEP
      • BLANK LINE/SCREEN
      • BLINK
      • FOREGROUND-COLOR/FOREGROUND-COLOUR
      • FULL/LENGTH-CHECK
      • GRID
      • HIGHLIGHT
      • JUSTIFY/JUST
      • LEFTLINE
      • LOWLIGHT
      • OVERLINE
      • PROMPT
      • REQUIRED/EMPTY-CHECK
      • REVERSE-VIDEO
      • SECURE/NO-ECH0
      • UNDERLINE
      • 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.
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 LINE clause specifies the line on which the screen item is to appear on the screen in an ACCEPT or DISPLAY operation.
  2. 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.

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

  4. 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.
  5. If a LINE position that is specified is off the screen, the ACCEPT or DISPLAY is truncated.
  6. 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, the OMITTED phrase may be specified as the corresponding argument; otherwise, the OMITTED phrase must not be specified 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 concepts
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 n3        *> n1 = 6
     if n2 b-and n3 = 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, you must not change the setting of the INTLEVEL compiler directive from its default value of "2". This means that you cannot use some of the newer features, such as numeric pictures with more than 18 total digits, with the TRUNC20 parameter.

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.

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:

Note that the required relational characters "<" , ">", and "=" are not underlined, to avoid confusion with other symbols such as " ? ".

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:

Note that the required relational characters "<" , ">", and "=" are not underlined, to avoid confusion with other symbols such as " ? ".

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:

Note that the required relational characters "<" , ">", and "=" are not underlined, to avoid confusion with other symbols such as " ? ".

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 concepts
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 UPPER-CASE Function | Alph1 or Anum1 MF or Nat1 | Depends upon argument* | All letters in the argument are set to uppercase
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 alphnumeric 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 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. Currently beyond the default codepage only 1208 is supported.

Returned Values

  1. A character string is returned with each national character of argument-1 converted to its corresponding alphanumeric character representation, if any. The correspondence of characters between the alphanumeric character set and the national character set depends on the native environment.
  2. ISO2002 MF If argument-2 is specified, the alphanumeric substitution character is returned for each national character in argument-1 that has no corresponding alphanumeric character representation.
  3. ISO2002 MF If argument-2 is unspecified, each national character in argument-1 that has no corresponding alphanumeric character representation is returned in national external format, with the minimum of control functions necessary for interpretation of the external format characters.
  4. The length of the returned value is the number of character positions of usage display required to hold the returned value; it is dependent on the characters in the argument and on the attributes of the national character set.
Parent topic: Definitions of Functions


The E Function

The E function returns an approximation of e, the base of natural logarithms.

The type of the function is numeric.

General Format

Returned Values

  1. The returned value is:

    2.718281828459045235

Parent topic: Definitions of Functions


The EXP Function

The EXP function returns an approximation of the value of e raised to the power of the argument.

The type of the function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is:

    FUNCTION E ** argument-1

Parent topic: Definitions of Functions


The EXP10 Function

The EXP10 function returns an approximation of the value of 10 raised to the power of the argument.

The type of the function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is:

    10 ** argument-1

Parent topic: Definitions of Functions


The FACTORIAL Function

The FACTORIAL function returns an integer that is the factorial of argument-1. The type of this function is integer.

General Format

Arguments

  1. Argument-1 must be an integer greater than or equal to zero.

Returned Values

  1. If the value of argument-1 is zero, the value 1 is returned.
  2. If the value of argument-1 is positive, its factorial is returned.
  3. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The FRACTION-PART Function

The FRACTION-PART function returns a numeric value that is the fraction portion of the argument.

The type of the function is numeric.

General Format

Arguments

  1. Argument-1 must be of the class numeric.

Returned Values

  1. The returned value is:

    (argument-1 - FUNCTION INTEGER-PART (argument-1))

    where the argument for the INTEGER-PART function is the same as for the FRACTION-PART function itself.

    Note: If the value of argument-1 is +1.5, +0.5 is returned. If the value of argument-1 is -1.5, -0.5 is returned.
Parent topic: Definitions of Functions


The INTEGER Function

The INTEGER function returns the greatest integer value that is less than or equal to the argument. The type of this function is integer.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is the greatest integer less than or equal to the value of argument-1. For example, if the value of argument-1 is -1.5, -2 is returned. If the value of argument-1 is +1.5, +1 is returned.
Parent topic: Definitions of Functions


The INTEGER-OF-BOOLEAN Statement

The INTEGER-OF-BOOLEAN function returns the numeric value of the boolean string in argument-1.

The function type is integer.

General Format

FUNCTION INTEGER-OF-BOOLEAN (argument-1)

Syntax Rules

  1. Argument-1 must be a boolean data item.
Parent topic: Definitions of Functions


The INTEGER-OF-DATE Function

The INTEGER-OF-DATE function converts a date in the Gregorian calendar from standard date form (YYYYMMDD) to integer date form. The type of this function is integer.

General Format

Arguments

  1. Argument-1 must be an integer of the form YYYYMMDD, whose value is obtained from the calculation:

    (YYYY * 10,000) + (MM * 100) + DD.

    1. YYYY represents the year in the Gregorian calendar. It must be an integer greater than 1600.
    2. MM represents a month and must be a positive integer less than 13.
    3. DD represents a day and must be a positive integer less than 32 provided that it is valid for the specified month and year combination.

Returned Values

  1. The returned value is an integer that is the number of days by which the date represented by argument-1 succeeds December 31, 1600, in the Gregorian calendar.
Parent topic: Definitions of Functions


The INTEGER-OF-DAY Function

The INTEGER-OF-DAY function converts a date in the Gregorian calendar from Julian date form (YYYYDDD) to integer date form. The type of this function is integer.

General Format

Arguments

  1. Argument-1 must be an integer of the form YYYYDDD, whose value is obtained from the calculation:

    (YYYY * 1000) + DDD.

    1. YYYY represents the year in the Gregorian calendar. It must be an integer greater than 1600.
    2. DDD represents the day of the year. It must be a positive integer less than 367 provided that it is valid for the year specified.

Returned Values

  1. The returned value is an integer that is the number of days by which the date represented by argument-1 succeeds December 31, 1600, in the Gregorian calendar.
Parent topic: Definitions of Functions


The INTEGER-PART Function

The INTEGER-PART function returns an integer that is the integer portion of argument-1. The type of this function is integer.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. If the value of argument-1 is zero, the returned value is zero.
  2. If the value of argument-1 is positive, the returned value is the greatest integer less than or equal to the value of argument-1. For example, if the value of argument-1 is +1.5, +1 is returned.
  3. If the value of argument-1 is negative, the returned value is the least integer greater than or equal to the value of argument-1. For example, if the value of argument-1 is -1.5, -1 is returned.
Parent topic: Definitions of Functions


The LENGTH Function

The LENGTH function returns an integer equal to the length of the argument in alphanumeric character positions

MF or national character positions, depending on the class of the argument.

The type of this function is integer.

General Format

Arguments

  1. Argument-1 can be a nonnumeric literal or a data item of any class or category.
  2. If argument-1 or any data item subordinate to argument-1 is described with the DEPENDING phrase of the OCCURS clause, the contents of the data item referenced by the data-name specified in the DEPENDING phrase are used at the time the LENGTH function is evaluated.

Returned Values

  1. If argument-1 is an alphanumeric literal or is an elementary data item of class other than national or is a group data item that does not contain a variable occurrence data item, the value returned is an integer equal to the length of argument-1 in alphanumeric character positions.

    MF If argument-1 is an elementary data item of the class national or is a national literal, the returned value is an integer equal to the length of argument-1 in national character positions.

  2. If argument-1 is a group data item containing a variable occurrence data item, the returned value is an integer determined by evaluation of the data item specified in the DEPENDING phrase of the OCCURS clause for that variable occurrence data item. This evaluation is accomplished according to the rules in the OCCURS clause dealing with the data item as a sending data item. See the section The OCCURS Clause in the chapter Data Division - File and Data Description.
  3. The returned value includes implicit FILLER characters, if any.
Parent topic: Definitions of Functions
Related information
The OCCURS Clause


The LENGTH-AN Function

The LENGTH-AN function returns an integer equal to the length of the argument in number of alphnumeric 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 decribed 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.
    2. Otherwise the value returned is an integer equal to the lengthof argument-1 in alphanumeric character positions.
    3. 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 specifes 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. Currently beyond the default codepage only 1208 is supported.

Returned Values

  1. A character string is returned with each alphanumeric character and each national character in argument-1 converted to its corresponding national internal format. Any control functions used for external format representation in argument-1 are recognised only for purposes of distinguishing characters, and are not be considered as separate characters of argument-1.
  2. ISO2002 MF If argument-2 is specified, each character in argument-1 that has no corresponding internal national representation is converted to the substitution character specified by argument-2.

  3. ISO2002 MF If argument-2 is unspecified, each character that has no corresponding internal national representation is converted to a national space.

    .
  4. The length of the returned value is the number of character positions of usage national required to hold the converted argument and depends on the number of characters contained in argument-1.
Parent topic: Definitions of Functions


The NUMVAL Function

The NUMVAL function returns the numeric value represented by the character string specified by argument-1. Leading and trailing spaces are ignored. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be an alphanumeric

    MF or national

    literal or an alphanumeric

    MF or national

    data item whose content has one of the following two formats:

    or

    where space is a string of zero or more spaces and digit is a string of one to 18 digits.

  2. The total number of digits in argument-1 must not exceed 18.
  3. If the DECIMAL POINT IS COMMA clause is specified in the Special-Names paragraph, a comma must be used in argument-1 rather than a decimal point.

Returned Values

  1. The returned value is the numeric value represented by argument-1.
  2. The number of digits returned is 18.
  3. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The NUMVAL-C Function

The NUMVAL-C function returns the numeric value represented by the character string specified by argument-1. Any optional currency string specified by argument-2 and any optional commas preceding the decimal point are ignored. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be an alphanumeric

    MF or national

    literal or an alphanumeric

    MF or national

    data item whose content has one of the following two formats:

    or

    where space is a string of zero or more spaces, cs is the string of one or more characters specified by argument-2 and digit is a string of one or more digits.

  2. If the DECIMAL POINT IS COMMA clause is specified in the Special-Names paragraph, the functions of the comma and decimal point in argument-1 are reversed.
  3. The total number of digits in argument-1 must not exceed 18.
  4. Argument-2, if specified, must be of the same class as argument-1.

    It cannot be a digit, comma, space, plus sign(+), minus sign (-) or decimal point.

  5. If argument-2 is not specified, the character used for cs is the currency string specified for the program when argument-1 is of class alphanumeric

    MF ; or if argument-1 is of class national, the national representation of the currency string specified for the program. The national representation of cs is the value returned from FUNCTION NATIONAL-OF (cs).

Returned Values

  1. The returned value is the numeric value represented by argument-1.
  2. The number of digits returned is 18.
  3. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The ORD Function

The ORD function returns an integer value that is the ordinal position of argument-1 in the collating sequence for the program. The lowest ordinal position is 1. The type of this function is integer.

General Format

Arguments

  1. Argument-1 must be one character in length and must be class alphabetic, alphanumeric

    MF or national.

Returned Values

  1. If the class of argument-1 is alphabetic or alphanumeric, the returned value is the ordinal position of argument-1 in the current alphanumeric collating sequence for the program.
  2. MF If the class of argument-1 is national, the returned value is the ordinal position of argument-1 in the current national program collating sequence.
Parent topic: Definitions of Functions


The ORD-MAX Function

The ORD-MAX function returns a value that is the ordinal number of the argument-1 that contains the maximum value. The type of this function is integer.

General Format

Arguments

  1. If more than one argument-1 is specified, all arguments must be of the same class, except alphabetic and alphanumeric arguments which can be mixed.

Returned Values

  1. The returned value is the ordinal number that corresponds to the position of the argument-1 having the greatest value in the argument-1 series.
  2. The comparisons used to determine the greatest valued argument are made according to the rules for relation conditions. See the topic Relation Condition in the chapter Procedure Division.
  3. If more than one argument-1 has the same greatest value, the number returned corresponds to the position of the leftmost argument-1 having that value.
Parent topic: Definitions of Functions
Related information
Relation Condition


The ORD-MIN Function

The ORD-MIN function returns a value that is the ordinal number of the argument-1 that contains the minimum value. The type of this function is integer.

General Format

Arguments

  1. If more than one argument-1 is specified, all arguments must be of the same class, except alphabetic and alphanumeric arguments which may be mixed.

Returned Values

  1. The returned value is the ordinal number that corresponds to the position of the argument-1 having the lowest value in the argument-1 series.
  2. The comparisons used to determine the lowest valued argument are made according to the rules for relation conditions. See the topic Relation Condition in the chapter Procedure Division.
  3. If more than one argument-1 has the same lowest value, the number returned corresponds to the position of the leftmost argument-1 having that value.
Parent topic: Definitions of Functions
Related information
Relation Condition


The PI Function

The PI function returns a value that is an approximation of the ratio of the circumference of a circle to its diameter.

The type of the function is numeric.

General Format

Returned Values

  1. The returned value is:

    3.141592653589793238

Parent topic: Definitions of Functions


The PRESENT-VALUE Function

The PRESENT-VALUE function returns a value that approximates the present value of a series of future period-end amounts specified by argument-2 at a discount rate specified by argument-1. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 and argument-2 must be of the class numeric.
  2. The value of argument-1 must be greater than -1.

Returned Values

  1. The returned value is an approximation of the summation of a series of calculations with each term in the following form:

    argument-2 / (1+argument-1) ** n

    There is one term for each occurrence of argument-2. The exponent, n, is incremented from one by one for each term in the series.

  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The RANDOM Function

The RANDOM function returns a numeric value that is a pseudo-random number from a rectangular distribution. The type of this function is numeric.

General Format

Arguments

  1. If argument-1 is specified, it must be zero or a positive integer. It is used as the seed value to generate a sequence of pseudo-random numbers.
  2. If a subsequent reference specifies argument-1, a new sequence of pseudo-random numbers is started.
  3. MF If the first reference to this function in the run unit does not specify argument-1, the seed value of zero is used.
  4. In each case, subsequent references without specifying argument-1 return the next number in the current sequence.

Returned Values

  1. The returned value is greater than or equal to zero and less than one.
  2. For a given seed value on a given implementation, the sequence of pseudo-random numbers will always be the same.
  3. The domain of argument-1 values will yield distinct sequences of pseudo-random numbers. This subset includes the values from 0 through at least 32767.
  4. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The RANGE Function

The RANGE function returns a value that is equal to the value of the maximum argument minus the value of the minimum argument. The type of this function depends upon the argument types as follows:

Argument Type | Function Type
All arguments integer | Integer
Numeric | Numeric
(some arguments can be integer) |

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is equal to the greatest value of argument-1 minus the least value of argument-1.
  2. The comparisons used to determine the greatest and least values are made according to the rules for relation conditions. See the topic Relation Condition in the chapter Procedure Division.
  3. If the value of argument-1 is numeric non-integer, results are returned in floating-point format.
Parent topic: Definitions of Functions
Related information
Relation Condition


The REM Function

The REM function returns a numeric value that is the remainder of argument-1 divided by argument-2. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 and argument-2 must be class numeric.
  2. The value of argument-2 must not be zero.

Returned Values

  1. The returned value is the remainder of argument-1 / argument-2. It is defined as the expression:

    argument-1 - (argument-2 * FUNCTION INTEGER-PART (argument-1 / argument-2))

  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The REVERSE Function

The REVERSE function returns a character string whose length and characters are exactly the same as argument-1, except that the characters are in reverse order. The type of this function depends on the argument type as follows:

Argument Type | Function Type
Alphabetic | Alphanumeric
Alphanumeric | Alphanumeric
National | National

General Format

Arguments

  1. Argument-1 must be class alphabetic, alphanumeric

    MF or national

    and must be at least one character in length.

Returned Values

  1. If argument-1 is a character string of length n, the returned value is a character string of length n such that for 1 <j < n, the character in position j of the returned value is the character from position n-j+1 of argument-1.
Parent topic: Definitions of Functions


The SIGN Function

The SIGN function returns +1, 0, or -1 depending on the sign of the argument.

The type of the function is integer.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is:
    1. When the value of argument-1 is positive, 1
    2. When the value of argument-1 is zero, 0
    3. When the value of argument-1 is negative, -1
Parent topic: Definitions of Functions


The SIN Function

The SIN function returns a numeric value that approximates the sine of an angle or arc, expressed in radians, that is specified by argument-1. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.
    Note: Conversion factors from degrees and Gon (grad) to radians are specified in the section Trigonometric Functions.

Returned Values

  1. The returned value is the approximation of the sine of argument-1 and is greater than or equal to -1 and less than or equal to +1.
  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions
Related information
Trigonometric Functions


The SQRT Function

The SQRT function returns a numeric value that approximates the square root of argument-1. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.
  2. The value of argument-1 must be zero or positive.

Returned Values

  1. The returned value is the absolute value of the approximation of the square root of argument-1.
  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The STANDARD-DEVIATION Function

The STANDARD-DEVIATION function returns a numeric value that approximates the standard deviation of its arguments. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is the approximation of the standard deviation of the argument-1 series.
  2. The returned value is calculated as follows:
    1. The difference between each argument-1 value and the arithmetic mean of the argument-1 series is calculated and squared.
    2. The values obtained are added. This quantity is divided by the number of values in the argument-1 series.
    3. The square root of the quotient obtained is calculated. The returned value is the absolute value of this square root.
  3. If the argument-1 series consists of only one value, or if the argument-1 series consists of all variable occurrence data items and the total number of occurrences for all of them is one, the returned value is zero.
  4. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The SUM Function

The SUM function returns a value that is the sum of the arguments. The type of this function depends upon the argument types as follows:

Argument Type | Function Type
All arguments integer | Integer
Numeric | Numeric
(some arguments may be integer) |

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is the sum of the arguments.
  2. If the argument-1 series are all integers, the value returned is an integer.
  3. If the argument-1 series are not all integers, a numeric value is returned in floating-point format.
Parent topic: Definitions of Functions


The TAN Function

The TAN function returns a value that approximates the tangent of an angle or arc, expressed in radians, that is specified by argument-1. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.
    Note: Conversion factors from degrees and Gon (grad) to radians are specified in the section Trigonometric Functions.

Returned Values

  1. The returned value is the approximation of the tangent of argument-1.
  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions
Related information
Trigonometric Functions


The 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 ALTER Statement
    The ALTER statement modifies a predetermined sequence of operations.
  • 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 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 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 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 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 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

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

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.

General Rules for Format 1

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

  3. 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.
  4. 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.)
  5. 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.

  6. MF XOPEN If the mnemonic-name associated with the function-name ENVIRONMENT-VALUE is used then,
    1. 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.
    2. 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.
  7. 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

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

  9. 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.
  10. 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.
  11. 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.
  12. 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.
  13. 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.
  14. 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

  15. MF The value returned from the ACCEPT FROM LINE NUMBER phrase is always numeric. The value is implementation-dependent.
  16. MF The FROM USER NAME option returns spaces.
  17. MF The FROM ESCAPE KEY option returns the two-digit code generated by a termination key.
  18. MF 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.

General Rules for Format 4

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

  20. 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.
  21. MF The AT phrase gives the absolute address on the screen where the ACCEPT operation is to start.
  22. 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.
  23. 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.
  24. 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.
  25. 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

  26. MF The ACCEPT operation starts at line 1, column 1 if no AT phrase is specified.
  27. 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 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.

  28. 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.
  29. 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.
  30. 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.
  31. MF The effect of specifying the PROMPT option is as described in the topic The PROMPT Clause.
  32. 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.
  33. 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.

  34. 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.
  35. 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.)
  36. MF The LEFT-JUSTIFY option is documentary only.
  37. 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.
  38. 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.
  39. 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.)
  40. MF The UPPER option forces input into upper case.
  41. MF The LOWER option forces input into lower case.
  42. 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.
  43. 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.
  44. 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.
  45. 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.
  46. 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.
  47. 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).
  48. 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.

  49. 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.)
  50. MF All references to (NOT) ON EXCEPTION phrases also apply to (NOT) ON ESCAPE phrases.

General Rules for Formats 1 and 5

  51. 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.
Parent topic: Statements
Related concepts
ACCEPT Fields at the Edge of the Screen
Display of Input Data in Concealed ACCEPT Fields
ACCEPT FROM CENTURY-DATE and FROM CENTURY-DAY
Related reference
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

General Formats for Format 2

General Formats for 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 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.

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 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 Formats for Format 1

General Formats for Format 2 (program-prototype)

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 for All Formats

  1. * Identifier-1 must be defined as an alphanumeric

    ISO2002 MF or national

    data item.

  2. * Literal-1

    MF , literal-2

    VSC2 MF , and literal-3

    cannot be a figurative constant and must be an alphanumeric literal

    ISO2002 MF or a national literal.

  3. * Identifier-2 and identifier-4 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 must not be defined in the Working-Storage or File Section of a factory or an instance object.

  4. MF * Neither identifier-5, identifier-6, identifier-7, nor identifier-8 can be a function-identifier.
  5. MF * GIVING and RETURNING are equivalent.
  6. MF Identifier-9 must be defined as a data item in the Linkage Section with a level number of 01 or 77.
  7. MF *Identifier-2, identifier-4, identifier-6 and identifier-8 must not be described with the ANY LENGTH clause.
  8. MF USING and GIVING/RETURNING can be used in either order.

Syntax Rules for Format 1

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

  10. MF * Integer-1 may be signed.
  11. VSC2 MF * Identifier-3 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.

  12. 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
  13. ISO2002 * Identifier-2 must not be a data item of class object or pointer.

Syntax Rules for Format 2

  14. ISO2002 MF The NESTED phrase must be specified only in a program definition.
  15. ISO2002 MF If the NESTED phrase is specified, literal-1 must be specified. Literal-1 must be the same as the program-name specified in the Program-ID paragraph of a common program as specified in the topic Conventions for Program-names in the chapter Concepts of the COBOL Language or of a program that is directly contained in the calling program.
  16. ISO2002 MF Program-prototype-name-1 must be specified in a program-specifier in the Repository paragraph.
  17. ISO2002 MF If the BY CONTENT or BY REFERENCE phrase is specified or implied for an argument, the BY REFERENCE phrase must be specified for the corresponding formal parameter in the PROCEDURE DIVISION header.
  18. ISO2002 MF BY CONTENT must not be omitted when identifier-4 is an identifier that is permitted as a receiving operand, except that BY CONTENT may be omitted when identifier-4 is an object property.
  19. ISO2002 MF If the BY VALUE phrase is specified for an argument, the BY VALUE phrase must be specified for the corresponding formal parameter in the PROCEDURE DIVISION header.
  20. ISO2002 MF Identifier-6 must be of class numeric, object, or pointer.
  21. ISO2002 MF Literal-4 must be a numeric literal.
  22. ISO2002 MF If the OMITTED phrase is specified, the OPTIONAL phrase must be specified for the corresponding formal parameter in the PROCEDURE DIVISION header.
  23. ISO2002 MF The rules for conformance specified in the topic Conformance for Parameters and Returning Items in the chapter Procedure Division apply.

General Rules for All Formats

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

    VSC2 MF If identifier-3 is in the Linkage Section and has 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 cannot be modified by the called subprogram.

    MF If the BY REFERENCE literal-2 phrase is specified or implied then the object program processes literal-2 as described for literal-3.

  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-4 is specified, then both the implied data description of the additional data item and its contents are identical to that of identifier-4. 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-5 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-5.

  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-6 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-6, 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-6. This conversion and representation facilitates calling non-COBOL programs.

    Otherwise, if identifier-6 is specified then the implied data description of the additional data item and its contents are identical to that of identifier-6.

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

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

General Rules for Format 1

  29. 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.
  30. 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.
  31. 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.

General Rules for Format 2

  32. ISO2002 MF If none of identifier-1, literal-1 or procedure-pointer-1 is specified, program-prototype-name-1 determines the externalized program-name of the program being called, according to the rules specified in the topic The Repository Paragraph.
  33. ISO2002 MF If the NESTED phrase is specified, the common or contained program that has literal-1 specified in the Program-ID paragraph is used to determine the characteristics of the called program.
  34. ISO2002 MF If the NESTED phrase is not specified, program-prototype-name-1 is used to determine the characteristics of the called program.
  35. An argument that consists merely of a single identifier or literal is regarded as an identifier or literal rather than an arithmetic expression.
  36. ISO2002 MF If an argument is specified without any of the keywords BY REFERENCE, BY CONTENT, or BY VALUE, the manner used for passing this argument is determined as follows:
    1. When the BY REFERENCE phrase is specified or implied for the corresponding formal parameter:
      1. If the argument meets the requirements of syntax rule 3, BY REFERENCE is assumed.
      2. If the argument does not meet the requirements of syntax rule 3, BY CONTENT is assumed.
    2. When the BY VALUE phrase is specified or implied for the corresponding formal parameter, BY VALUE is assumed.
  37. ISO2002 MF Control is transferred to the called program in a manner consistent with the entry convention specified for the program.
  38. ISO2002 MF If an OMITTED phrase is specified or a trailing argument is omitted, the omitted-argument condition for that parameter evaluates to true in the called program. (See the topic The Omitted-argument Condition in the chapter Procedure Division.)
  39. ISO2002 MF If a parameter for which the omitted-argument condition is true is referenced in a called program, except as an argument or in the omitted-argument condition, you will get runtime error 203.

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 reference
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, then a fatal run-time 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.
  9. The USING phrase must not be used if you have specified the Compiler directive INTLEVEL"1".
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.

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

COMPUTE {identifier-2} ... = boolean-expression-1 [END-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" and "=" are synonymous.

Syntax Rules for Format 2

  3. Identifier-2 must reference an elementary boolean data item.
  4. Boolean-expression-1 must not consist solely of the figurative constant ALL literal.

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-1 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 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 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 or literal-1 must each, if used, reference an alphanumeric data item or a nonnumeric literal respectively. 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-VALUE is used then
    1. 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.
    2. 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 the chapter 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 If the FOREGROUND-COLOR option is specified, then the specified color becomes the default foreground color if and only if the entire screen is cleared by this display. The entire screen is cleared either when the BLANK SCREEN option is specified or when literal-1 is SPACES and the DISPLAY starts at line 1 column 1.
  24. MF If the BACKGROUND-COLOR option is specified, then the specified color becomes the default background color if and only if the entire screen is cleared by this display.
  25. 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

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. 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.
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. CHANGED and NAMED can both be omitted.

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 If the ADDRESS OF clause is not specified, 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-1 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.

General Rules for Format5

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

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 If the ADDRESS OF clause is not specified, 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

General Formats for 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 national or object or pointer.

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

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

  4. If the REPLACING phrase is specified, literal-1 or the data item referenced by identifier-2 is the sending operand.

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

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 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 MF Any identifiers that are not valid receiving operands of a MOVE statement - 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.
    2. Second, an elementary data item is a posible receiving item if either of the following apply:
      1. It is explicitly referenced by identifier-1
      2. It is contained within the group dtat 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

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. 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-9 must be a data item no more than 8 bytes in size that is defined in the File, Working-Storage,

    MF Object-Storage,

    Local-Storage, or Linkage Section.

  16. MF Identifier-10 must be defined as a data item in the Linkage Section with a level number of 01 or 77.
  17. Identifier-3 is both a sending and receiving operand.
  18. 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.
  19. Identifier-9 and identifier-10 are receiving operands.
  20. 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 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, Table 14-1, MOVE Statement Data Categories, 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 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.

      ISO2002 MF When the receiving field is national 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 national 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. The table 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 | DBCS, national or national-edited | Boolean
    Alphabetic | Yes/4c | Yes/4a | No/3a | No/3a | No/4e | No/3f
    Alphanumeric | Yes/4c | Yes/4a | Yes/4b2 | Yes/4b | No/4e | Yes/3e
    Alphanumeric-Edited | Yes/4c | Yes/4a | No/3a | No/3a | No/4e | No/3f
    Numeric Integer | No/3b | Yes/4a | Yes/4b | Yes/4b | No/4e | No/3f
    Numeric Non-Integer | No/3b | No/3c | Yes/4b | Yes/4b | No/4e | No/3f
    Numeric-Edited | No/3b | Yes/4a | Yes/4b | Yes/4b | No/4e | No/3f
    DBCS national or national-edited | No/4e | No/4e | No/4e | No/4e | Yes/4e | No/3f
    Boolean | No/3c | Yes/4a | No/3b | No/3b | No/3g | Yes/4f
    Note: An error is reported if a non-integer alphanumeric literal sending item is used
Parent topic: Statements
Related concepts
Undefined Results of MOVE and Arithmetic Operations
Related reference
MOVE Statement
Related information
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

General Formats for 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.

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

General Formats for Format 2

General Formats for Format 3

General Formats for Format 4

General Formats for Format 5

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. ANS85 If procedure-name-1 is omitted, imperative-statement-1 and the END-PERFORM phrase must be specified; if procedure-name-1 is specified, imperative-statement-1 and the END-PERFORM phrase must not be specified.

    MF When imperative-statement-1 is specified, the END-PERFORM phrase is optional.

    COB370 Procedure-name-1 and imperative-statement-1 may both be omitted.

  2. The words THROUGH and THRU are equivalent.
  3. 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 Formats 2 and 4

  4. Each identifier represents a numeric elementary item described in the Data Division. In Format 2, identifier-1 must be described as a numeric integer.
  5. 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.

Syntax Rules for Format 3

  6. If the TEST phrase is specified, the EXIT phrase must not be specified.

Syntax Rules for Formats 3 and 4

  7. ANS85 If neither the TEST BEFORE nor the TEST AFTER phrase is specified, the TEST BEFORE phrase is assumed.
  8. Condition-1, condition-2, ... , can be any conditional expression. (See the section Conditional Expressions in the chapter Procedure Division)

Syntax Rules for Format 4

  9. ANS85 In Format 4, if procedure-name-1 is omitted, the AFTER phrase must not be specified.

    ISO2002 MF This restriction does not apply.

  10. Each literal represents a numeric literal.
  11. 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.
  12. 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.
  13. The literal in the BY phrase must not be zero.
  14. Two AFTER phrases are permitted in Format 4 of the PERFORM statement.

    ANS85 Six AFTER phrases are permitted in Format 4 of the PERFORM statement.

    MF This limit is raised to fifteen.

Syntax Rules for Format 5

  15. NET JVM Identifier-9 must be an instance of a collection class, i.e. a class that has a GetEnumerator method returning a type that:
    1. contains a public instance method called MoveNext with no parameters;
    2. contains a public instance get property called Current. The type of this property is known as the element type of identifier-9.
    Any class that implements the System.Collections.IEnumerable interface satisfies the above rules and is therefore a collection class. All .NET arrays are such collection classes, as are the various Dictionary and List classes defined in the .NET framework.
  16. 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 All Formats

  1. When procedure-name-1 is specified, the PERFORM statement is referred to as an out-of-line PERFORM statement;

    ANS85 when procedure-name-1 is omitted, the PERFORM statement is referred to as an in-line PERFORM statement.

  2. The statements contained within the range of procedure-name-1 (through procedure-name-2 if specified) for an out-of-line PERFORM statement

    ANS85 or contained in the PERFORM statement itself for an in-line PERFORM statement

    are referred to as the specified set of statements.

  3. 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.)
  4. 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.
  5. 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.
    5. ANS85 If an in-line PERFORM statement is specified, an execution of the PERFORM statement is completed after the last statement contained within it has been executed.
    6. MF An EXIT PERFORM statement can be used to exit an in-line perform before executing all statements within the in-line perform.
  6. 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.
  7. 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.
  8. The PERFORM statements operate as follows:
    1. Format 1 is 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. Format 2 is the PERFORM ... TIMES. 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. Format 3 is the PERFORM ... UNTIL. 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. Format 4 is the PERFORM ... VARYING. This variation of 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 Format 4 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.

    5. NET JVM Format 5 is the PERFORM VARYING ... THROUGH. This variation of the PERFORM statement is used to set the values referenced by identifier-8 to access every element of collection during the execution of a PERFORM statement. The specified set of statements is performed once for each element of the collection referenced by identifier-9. Following the execution of the specified set of statements for each element of the collection, control is transferred to the end of the PERFORM statement. During execution of the PERFORM statement, reference to identifier-8 or identifier-9 cannot alter the number of times the specified set of statements is to be executed from that which was indicated by the initial size of the collection referenced by identifier-9.
  9. 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.
  10. 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.
  11. 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.

  12. 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, one of the following:
    1. Sections and/or paragraphs wholly contained in one or more non-independent segments.
    2. Sections and/or paragraphs wholly contained in a single independent segment.

    OSVS VSC2 These restrictions do not apply.

  13. 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:
    1. Sections and/or paragraphs wholly contained in one or more non-independent segments.
    2. Sections and/or paragraphs wholly contained in the same independent segment as that PERFORM statement.

    OSVS VSC2 These restrictions do not apply.

General Rules for Format 4

  14. The data items referenced by identifier-4 and identifier-7 must not have a zero value.
  15. 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 IndexedFiles)

  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 andIndexed 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 (IndexedFiles)

  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.

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

General Rules for Format 1 (Record Sequential Files)

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

  9. 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.
  10. 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.
  11. MF For files opened for INPUT, the READ, READ WITH LOCK or READ WITH KEPT LOCK statements do not acquire a record lock.
  12. 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.
  13. 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.)
  14. 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)

  15. 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.
  16. 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.
  17. 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 IndexedFiles)

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

  19. 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.
  20. 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.
  21. 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.

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

  23. 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.
  24. 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.
  25. MF The WITH WAIT phrase ensures that a lock is acquired on the record, waiting if necessary.

General Rules for Format 3 (Relative Files)

  26. 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 Format4 (Relative Files)

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

  28. MF The IGNORE LOCK phrase causes the READ to proceed as if the record were not locked.

General Rules for Format 3 (Indexed Files)

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

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

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

General Formats for Format 2 (Record Sequential Files)

General Formats for Format 2 (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 - 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

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

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 (Boolean-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 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.
  5. MF Each FALSE or TRUE phrase applies to the occurrences of condition-name-1 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 6

  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

Syntax Rules for Format 10 (Value of Event-pointer)

  24. MF Event-pointer-1 must be defined as a data item with USAGE EVENT-POINTER.

Syntax Rules for Format 11 (Address of Event-pointer)

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

  26. MF Monitor-pointer-1 must be defined as a data item with USAGE MONITOR-POINTER.
  27. MF If the NOT phrase is specified, then the CONVERTING phrase must not be specified.

Syntax Rules for Format 13 (Address of Monitor-pointer)

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

  29. MF Mutex-pointer-1 must be defined as a data item with USAGE MUTEX-POINTER.

Syntax Rules for Format 15 (Address of Mutex-pointer)

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

  31. MF Semaphore-pointer-1 must be defined as a data item with USAGE SEMAPHORE-POINTER.
  32. MF Identifier-11 must reference an integer.

Syntax Rules for Format 17 (Address of Semaphore-pointer)

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

  34. NET JVM Identifier-12 must be described with a format 3 OCCURS clause.
  35. NET JVM Identifier-13 must describe an integer.
  36. 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)

  37. NET JVM Identifier-14 must be described with a format 3 OCCURS clause as either a one-dimensional array or a rectangular array.
  38. NET JVM Literal-2 must be a valid literal for a VALUE clause describing the subject of the entry.
  39. NET JVM Parentheses may be used within the repetitions of literal-2 to separate the values into subarrays.

Syntax Rules for Format 20 (Boolean setting)

  40. NET JVM Identifier-15 and identifier-16 must have usage CONDITION-VALUE.
  41. NET JVM Condition-name-2 and condition-name-3 must be associated with conditional variables.
  42. NET JVM If condition-name-2 is specified and the TRUE phrase is not specified, the FALSE phrase must be specified in the VALUE clause of the Data Description entry for condition-name-2.

Syntax Rules for Format 21 (.NET-data-setting)

  43. NET JVM Identifier-17 is the receiving item.
  44. NET JVM Identifier-18, 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-17 and identifier-18 are objects of the same class.
    • The class of identifier-18 inherits directly or indirectly from the class of identifier-17.
    • Identifier-17 conforms to an interface and identifier-18 implements that interface.
    • There is an implicit conversion operator for an item with the class of identifier-18 to the class of identifier-17.
    • Identifier-17 is 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 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 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 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 identifer-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.

General Rules for Formats 10 and 11

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

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

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

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

  26. 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
  27. 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.
  28. 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)

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

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

  31. MF The execution of the SET statement sets the value of the mutex referenced by mutex-pointer-1 to ON or OFF.
  32. 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)

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

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

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

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

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

  39. 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 specfied values..

General Rules for Format 20 (Boolean setting)

  40. NET JVM The contents of the data-item referenced by identifier-15 or condition-item-2 is set to the contents of the data item referencesby identifier-16 or condition-name-3 or to TRUE or FALSE.

General Rules for Format 21 (.NET-data-setting)

  41. NET JVM If identifier-17 is 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-17. Note that the ToString method exists for any class since it is implemented in System.Object.
  42. 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

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.
    • 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. MF The COLLATING SEQUENCE phrase is treated as documentary only.
  26. 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)

General Formats for Format 2 (Indexed Files)

General Formats for Format 3 (Threads)

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.

Syntax Rules for Format 1 (Relative Files)

  5. 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 Format2 (Indexed Files)

  6. 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.
  7. MF Split-key-name-1 can reference one or more data items, and is specified as a record key associated with file-name-1.
  8. MF WITH SIZE specifies the number of characters in the key to be used in the positioning process.
  9. MF Identifier-1 must be the name of an elementary integer data item when used with the WITH SIZE phrase.

Syntax Rules for Format 3 (Threads)

  10. MF Literal-1 must be a nonnumeric literal and cannot be a figurative constant.
  11. MF Identifier-1 must be defined as an alphanumeric data item such that its value can be a COBOL or non-COBOL program-name.
  12. 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.
  13. MF Thread-pointer-1 must be defined as USAGE THREAD-POINTER.
  14. 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. 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.
  5. When executed within a thread created with a START statement or the CBL_CREATE_THREAD 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 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

General Formats for Format 2

General Formats for 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

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 System.Exception or a subclass of System.Exception.

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

General Formats for Format 2 (Record Sequential Files)

General Formats for Format 3 (Relative and Indexed Files)

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

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.

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


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.
Parent topic: Statements


Compiler-directing Statements

  • Source Text Manipulation
  • 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

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

  1. 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. See your COBOL system documentation for details of libraries.

    OSVS VSC2 MF This restriction is removed.

  2. The COPY statement must be preceded by a space and terminated by the separator period.
  3. Pseudo-text-1 must not be null, nor can it consist solely of either the character space(s) or comment lines.
  4. Pseudo-text-2 can be null.
  5. 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.)
  6. Word-1 or word-2 can be any single COBOL word.
  7. 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.
  8. 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.

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

  10. OSVS VSC2 MF The SUPPRESS phrase is used to suppress the printing of the contents of the copy member on the source listing.
  11. 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.

  12. OSVS MF External-file-name-literal and library-name-literal, when enclosed in quotation marks, may contain the $, #, and @ characters.
  13. ISO2002 MF Partial-word-1 must consist of one text-word.
  14. ISO2002 MF Partial-word-2 must consist of zero or one text-word.
  15. ISO2002 MF Neither a nonnumeric literal nor a national literal can be specified as partial-word-1 or partial-word-2.
  16. Library text must conform to the rules for COBOL reference format.
  17. ISO2002 MF XOPEN A concatenation expression must not be specified for external-file-name-literal, library-name-literal, literal-1 or literal-2.

General Rules

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

  4. 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.
  5. 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.
  6. 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.
  7. 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.

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

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

  11. 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.
  12. If the unit identifier is not explicitly specified, the default drive is used. (The default is operating system-dependent.)
  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 the next COBOL standard, however, they are not included in the ANSI '85 COBOL standard.

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 topic Example Using ANSI'85 with Special Characters
  • Using the COPY statement with partial word replacement supported by ISO2000 rules. See the topic Example Using ISO2000 and MF Dialects
Parent topic: Source Text Manipulation
Related concepts
Preprocessor Response Codes
Related information
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 concepts
Preprocessor Response Codes
Related information
Reference Format Representation
Reference Format


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. 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.
  2. Within the BASIS mechanism DELETE statement, all subject-sequence and subject-sequence-range numbers must be in ascending numeric order.
  3. Within the edit control file, all subject-sequence and subject-sequence-range numbers must be in ascending numeric order.
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.


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.


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.


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


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


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


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


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


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


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


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


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 HRLHLHWRI0RU906.html#FN4
AR | NEXT PAGE | 1 | 2b | 3a | 4c | 5c | Illegal Combination HRLHLHWRI0RU906.html#FN4
AR |  | 1 | 2a | 3a |  | 5d | Illegal Combination HRLHLHWRI0RU906.html#FN4
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 HRLHLHWRI0RU906.html#FN5
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 HRLHLHWRI0RU043.html#FN4
AR | Relative | 1 | 2 | 3a | 4a |  | Illegal Combination HRLHLHWRI0RU043.html#FN4
AR | NEXT PAGE | 1 | 2 | 3a | 4a |  | Illegal Combination HRLHLHWRI0RU043.html#FN4
AR |  | 1 | 2 | 3a | 4a |  | Illegal Combination HRLHLHWRI0RU043.html#FN4
R | Absolute | 1 | 2 | 3b | 4b | 5 | Illegal Combination HRLHLHWRI0RU043.html#FN4
R | Relative | 1 | 2 | 3b | 4b |  | 4d | 6f
R | NEXT PAGE | 1 | 2 | 3b | 4b |  | Illegal Combination HRLHLHWRI0RU043.html#FN4
R |  | 1 | 2 | 3b | 4b |  | 4d | 6f
NP R | Absolute | 1 | 2 | 3c | 4a | 5 | Illegal Combination HRLHLHWRI0RU043.html#FN4
NP R | Relative | 1 | 2 | 3c | 4a |  | Illegal Combination HRLHLHWRI0RU043.html#FN4
NP R | NEXT PAGE | 1 | 2 | 3c | 4a |  | Illegal Combination HRLHLHWRI0RU043.html#FN4
NP R |  | 1 | 2 | 3c | 4a |  | Illegal Combination HRLHLHWRI0RU043.html#FN4
 |  |  |  |  | 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 CombinationHRLHLHWRI0RU910.html#FN4
R |  | 1b | 2 | 3b |  | 4a | 3b | 4a
NP R |  | 1c | 2 | 3c |  | 4a | Illegal Combination HRLHLHWRI0RU910.html#FN4
 |  |  |  | 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.
  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 concepts
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 for DBCS items are DBCS and KANJI.

MF DBCS and KANJI class tests are not supported.

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. This class test is true if all characters in the data item being tested are valid single-byte Katakana or double-byte characters, or if the data item contains all spaces.

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

  • Data General Interactive COBOL V1.3 Syntax Support
  • DOS/VS COBOL Support
  • Microsoft COBOL V1.0 and V2.0 Syntax Support
  • Ryan McFarland COBOL V2.0 Syntax Support
  • Siemens BS2000 COBOL Syntax Support
  • VS COBOL II Compatibility
Parent topic: Part 3. Additional Topics


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
DG Interactive COBOL Source Programs
Compatibility Directives
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.

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


Ryan McFarland COBOL V2.0 Syntax Support

The syntax listed in this chapter is accepted by your COBOL system purely for compatibility with version 2.0 of Ryan McFarland COBOL. Many features found in Ryan McFarland 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 if you set the RM Compiler directive when you submit your source code to your COBOL system. See the RM/COBOL Language Reference Manual version 2.0 for a full description of the Ryan McFarland syntax.

  • Environment Division
  • Data Division
  • Procedure Division
Parent topic: Additional Dialect Support
Related concepts
RM/COBOL Source Programs
The RM Directive


Environment Division

  • The ASSIGN Clause
  • The ORGANIZATION Clause
Parent topic: Ryan McFarland COBOL V2.0 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 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


Data Division

  • The VALUE OF LABEL Clause
  • Length of Nonnumeric Literals
  • Default Sign Representation
  • The USAGE Clause
Parent topic: Ryan McFarland COBOL V2.0 Syntax Support


The VALUE OF LABEL Clause

General Format

The following clause is accepted in an FD entry:

General Rules

  1. This clause is treated as documentary.
Parent topic: Data Division


Length of Nonnumeric Literals

In the Data Division, nonnumeric literals up to 2047 characters long are allowed if you set the RM Compiler directive when you submit your source code to your COBOL system.

Parent topic: Data Division


Default Sign Representation

The syntax:

is assumed in the SPECIAL-NAMES paragraph 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 when you submit your source code to your COBOL system, this phrase is not assumed.

Parent topic: Data Division


The USAGE Clause

General Format

The following format of the USAGE clause is supported:

Syntax Rules

  1. COMP and COMPUTATIONAL are synonymous.
  2. COMP-1 and COMPUTATIONAL-1 are synonymous.
  3. COMP-6 and COMPUTATIONAL-6 are synonymous.

General Rules

  1. The COBOL system allocates a 2-byte signed binary data item, capable of holding values in the range –32k to +32k, for each data item declared as USAGE COMP-1 in the source program, regardless of its picture string. That is, each USAGE COMP-1 data item is treated as though it had a standard COBOL picture-string of S9(4) COMP.
  2. COMP-6 data items are converted to COBOL COMP format. If, as a result of this, less data space is allocated to each item than would be under the RM/COBOL system, the space is padded with null bytes (that is, bytes containing X"00")..
  3. USAGE IS COMPUTATIONAL is treated the same as USAGE IS DISPLAY.
Parent topic: Data Division


Procedure Division

  • Literals as CALL Parameters
  • The EXIT PROGRAM Statement
  • Bound Checking
  • Size Allocation for Index Data Items
  • The ACCEPT Statement
  • The DISPLAY Statement
  • Non-Standard Operations on Alphanumeric Data Items
  • OPEN and CLOSE on SEQUENTIAL Files
  • The PERFORM Statement
  • Procedure Names
  • REWRITE on LINE SEQUENTIAL Files
  • The STOP RUN Statement
  • I-O Status Codes
  • Locked Records
Parent topic: Ryan McFarland COBOL V2.0 Syntax Support


Literals as CALL Parameters

Literals can be used as parameters to CALL statements.

Parent topic: Procedure Division


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


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


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.

Parent topic: Procedure Division


The ACCEPT Statement

General Format

The following format of the ACCEPT statement is supported:

Syntax Rules

  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

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

General Format

The following format of the DISPLAY statement is supported:

Syntax Rules

  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

  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


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


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


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


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


I-O Status Codes

COBOL I-O status codes are mapped onto their RM equivalents if you specify the RM Compiler directive when you submit your source files to your COBOL system.

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


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 special register RETURN-CODE is also supported, but it has the description PIC S9(8) COMP-5 SYNC.

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

  1. 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 3 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 3 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 3 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 3 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, DATE-TO-YYYYMMDD, DAY-TO-YYYYDDD, and YEAR-TO-YYYY. The ADDR function is described below. The other intrinsic functions are described in the topic Intrinsic Functions.

  • The ADDR 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 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
  • 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 | ... | ... | ... | I2 | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ...
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 | ... | ... | ... | I2 | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | 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 | ... | ...
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-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-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 | ... | ...
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-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 | ... | ... | ... | I2 | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ...
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 | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ...
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 | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ...
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 | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ...
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
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
MF1 | MF"1" | Word reserved in Micro Focus LEVEL II COBOL, LEVEL II COBOL/ET and Professional COBOL
MF2 | MF"2" | As MF1 plus additional features in Micro Focus VS COBOL Workbench V1.2
MF3 | MF"3" | As MF2 plus additional features in Micro Focus VS COBOL Workbench V1.3 and V2.0, Professional COBOL V2.0 and Micro Focus V1.5
MF4 | MF"4" | As MF3 plus additional features in Micro Focus COBOL/2 V1.1, Microsoft COBOL" V3.0 and IBM COBOL V2
MF5 | MF"5" | As MF4 plus additional features in Micro Focus COBOL/2 V1.2 and Micro Focus COBOL/2 Workbench V2.3
MF6 | MF"6" | As MF5 plus additional features in Micro Focus COBOL/2 V2.4 and Micro Focus COBOL/2 Workbench V2.4
MF7 | MF"7" | As MF6 plus additional features in Micro Focus COBOL/2 V2.5 and Micro Focus COBOL/2 Workbench V2.5
MF8 | MF"8" | As MF7 plus additional features in Micro Focus COBOL V3.0 and Micro Focus COBOL Workbench V3.0
MF9 | MF"9" | As MF8 plus additional features in Micro Focus COBOL V3.1 and Micro Focus COBOL Workbench V3.1
MF10 | MF"10" | As MF9 plus additional features in Micro Focus COBOL V3.2 and Micro Focus COBOL Workbench V3.2
MF11 | MF"11" | As MF10 plus additional features in Micro Focus Net Express 3.0
MF12 | MF"12" | As MF11 plus additional features in Micro Focus 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
MF13 | MF"13" | As MF12 plus additional features in Micro Focus Net Express 5.1 WS2 and Server Express 5.1 WS2
MF14 | MF"14" | As MF13 plus additional features in Micro Focus Net Express 6.0 and Server Express 6.0
MF15 | MF"15" | As MF14 plus additional features in Micro Focus Net Express 5.1 WS5 and 6.0 WS2, and Server Express 5.1 WS5 and 6.0 WS2
MF16 | MF"16" | As MF15 plus additional features in versions Micro Focus Visual COBOL R3 and later
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 Ryan-McFarland COBOL V2.0
DVS | DOSVS | Word reserved in DOSVS COBOL
BS | BS2000 | Word reserved in Siemens BS2000 COBOL
MGD | ILGEN or DOTNET | Word reserved in managed COBOL.
Parent topic: Reserved Words
Related concepts
DG Interactive COBOL Source Programs
Compatibility Directives
Reserved Words


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
ATTRIBUTE | SET statement | 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
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 | I2
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
NONE | DEFAULT clause | I2
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


XML-CODE Exception Codes

Your COBOL system supports a subset of the exception codes that are available on the mainframe for the XML-CODE special register. Support is provided for the following exception codes, dependent on the setting of the XMLPARSE compiler directive.

Exception Codes supported when XMLPARSE is set to COMPAT

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 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.
Parent topic: Part 4: Appendices


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.

!

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.

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


Command Line Reference

A range of command line utilities and interfaces are available for creating, building, debugging and running COBOL applications.

  • Setting Directives Outside the IDE
  • Compiling from the Command Line
  • Linking from the Command Line
  • Converting Header Files Using the H2cpy Utility
  • Debugging from the Command Line
  • Running an Application from the Command Line
  • Configuring Enhanced ACCEPT and DISPLAY
    This chapter describes how you configure the enhanced ACCEPT and DISPLAY.
  • Test Coverage
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. However, you can specify them in a number of other ways too, such as on the command line, or in a directives file.

  • Order in which Compiler Directives Are Processed
    Choose the appropriate way to set the Compiler directives to ensure that they are processed in the order you require.
  • System-wide Directives File, cobol.dir
    Use this file if you want to permanently override the default value of a directive.
  • $SET Statements in the Source Code
    Use $SET statements if your program is affected by particular circumstances that none of the other programs in an application needs.
  • User Directives File
    Use this file when you have a set of directives that you always want to use together.
Parent topic: Command Line Reference


Order in which Compiler Directives Are Processed

Choose the appropriate way to set the Compiler directives to ensure that they are processed in the order you require.

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 the directives according to the way you set them. It processes them in the following order:

  1. Project or file properties, set from within the IDE
  2. System-wide directives file cobol.dir
  3. $SET statements in the source code

In addition, you can set directives in a user directives file, which you specify with the USE directive. These directives are then processed when they are encountered.

For example, the above order means that a directive set in a $SET statement would override the setting for that directive in the IDE.

Parent topic: Setting Directives Outside the IDE


System-wide Directives File, cobol.dir

Use this file if you want to permanently override the default value of a directive.

Place the directive that you want to override in the system-wide directives file, cobol.dir. Make sure that the file is in a directory specified by the COBDIR environment variable.

The Compiler automatically process the directives in the system-wide directives file, cobol.dir. It looks for a cobol.dir file first in the current directory, and then in the %COBDIR%\etc directory.

Compilation terminates if the Compiler rejects a directive, if that directive is on the command line or in a directives file specified on the command line. 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


$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


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 directive to pass this user directives 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. 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 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


Compiling from the Command Line

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.

  • 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 information
cbllink


The cobol Command

You can use cobol.exe to compile COBOL source and generate managed code assemblies as well as 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 using the default run-time libraries as specified by the LINKLIB directive.

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 the preceding comma is specified, but no filename is entered, the default is s-file.lst.

If you specify s-list without an extension or trailing period, the system adds the extension .lst to create the filename s-list.lst.

l-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 the preceding comma is specified, but no filename is entered, the default is s-file.grp.

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.
In order to compile for managed code you must include either the -ILGEN or -ILGEN(SUB) directives in this sequence.
;
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
Related concepts
Compiler Directives
Overview - 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


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


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


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


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


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


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 | Indicates an error which the Compiler has attempted to correct
Warning | 4 | 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.

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
Related reference
Key to Syntax Checking Error Messages
INFORETURN


Linking from the Command Line

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
Related reference
cbllink Options
cbllink Examples
Compiling from the Command Line


cbllink Options

The cbllink options affect the link process.

Separate options with a comma or spaces.

  • -d
  • -f[option]
  • -g
  • -isymbol
  • -k
  • -l
  • -mname
  • -oname
  • -roption[v]
  • -s
  • -udir_file
  • -v
  • -xsymbol
Parent topic: Linking from the Command Line
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]

Link 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

Specify that the function or entry-point symbol should be included in the executable file.

Parent topic: cbllink Options


-k

Prevent temporary files created by cbllink from being deleted.

Parent topic: cbllink Options


-l

Create a linker .map output file.

Parent topic: cbllink Options


-mname

Specify 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

Specify 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]

Link 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 the version specified in the registry.

This form of linking should be used on any application that is deployed using COBOL Server.

Parent topic: cbllink Options


-s

Prevent system modules, for example, Adis, Adisinit, Adiskey, Adisdyna, Mffh, from being linked into the executable.

Parent topic: cbllink Options


-udir_file

Specify that the Compiler directives contained in the file dir_file be used during compilation.

Parent topic: cbllink Options


-v

Verbose option. The options passed to the Cblnames utility and to the Linker are displayed.

Parent topic: cbllink Options


-xsymbol

Specify that the function or entry-point symbol should be excluded from the executable file.

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
Related information
cbllink


Converting Header Files Using the H2cpy Utility

The Header-to-copy utility can be run directly from the command line or it can be invoked 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 option or filename, a list of available options is displayed.

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 to be specified 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 specfiy 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__

Groups of macro definitions can be held in the h2cpy.dir file. See the h2cpy option -G option for details.

Parent topic: Command Line Reference
Related reference
PREPROCESS, P


Debugging from the Command Line

  • cobdebugremote
    The cobdebugremote 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


Running an Application from the Command Line

Runnable programs can be linked system executable files, which can be run directly from the command line, or dynamically loadable programs, which can be run without being linked into a system executable file.

  • Command to Run a Linked System Executable Program
Parent topic: 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 environment variable are searched.
parameters
Parameters that are required by the program. Each parameter is a string, separated from adjoining parameters by one or more spaces.
Parent topic: Running an Application from the Command Line


Configuring Enhanced ACCEPT and DISPLAY

This chapter describes how you configure the enhanced ACCEPT and DISPLAY.

  • 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. Configuration changes ADISCTRL, 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 output by Adis in response to errors.
  • Which keys are enabled or disabled.

You can alter any of the configurations held in ADISCTRL using the 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.

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

  • DG ICOBOL Compatibility.

    This is provided to emulate the action of ACCEPT and DISPLAY statements under Data General's ICOBOL.

  • IBM V1.0 Compatibility.

    This is provided to emulate IBM COBOL V1.0. It is not a close emulation, especially in the action of ACCEPT operations into numeric and numeric-edited fields.

  • Microsoft V2 Compatibility.

    This is provided to emulate Microsoft COBOL V2.2. It is not a close emulation, especially in the action of ACCEPT operations into numeric and numeric-edited fields.

See the Compatibility Guide for full details on RM, 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 directory specified by the COBDIR environment variable) 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 directory specified by COBDIR. 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.

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


Test Coverage

Information regarding test coverage is provided on the Micro Focus Web site.

See Test Coverage

Parent topic: Command Line Reference


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
To set project-wide build properties and compiler directives


Language Features

These directives change which language features your Compiler accepts.

  • Language Features - Dialect
  • Language Features - Mainframe Compatibility
  • Language Features - Multi-threading
  • Language Features - Reserved Word Control
  • Language Features - Speed
  • Language Features - Additional Features
Parent topic: Compiler Directives


Language Features - Dialect

  • ACTUAL-PARAMS
    Specifies actual parameters that are substituted for formal parameters in a parameterized class or interface.
  • ACU
    Enables compatibility with ACU COBOL.
  • ACUOPT
    Enables you to set various options specifically for compilation of ACU COBOL applications.
  • ACUSYNC
    Changes the effect of the SYNC clause so that it matches that used in ACU programs.
  • 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.
  • COMS85
    Allows your program to contain syntax introduced in the Communications Module of the ANSI'85 COBOL Standard.
  • 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
    Facilitates 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.
  • 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 Ryan-McFarland COBOL V2.0 are to be regarded as reserved words, and changes the behavior of certain features to be compatible with that COBOL system.
  • 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.

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


ACU

Enables compatibility with ACU COBOL.

Syntax:

>>--.---.--.----.--ACU------><
    +-/-+--+-NO-+

Parameters:

None

Properties:

Default: | NOACU
Phase: | Syntax check
$SET: | Initial

Comments:

Setting ACU enables some ACU extensions to the language and implements changes of behavior for compatibility with ACU COBOL. Refer to the ACU COBOL documentation for more information.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List
Related concepts
ACU Compiler Directive
Related information
ACUCOBOL-GT Syntax Extensions


ACUOPT

Enables you to set various options specifically for compilation of ACU COBOL applications.

Syntax:

>>--.---.--.----.--ACUOPT--(option)----><
    +-/-+

Parameters:

option
The ACU compiler option in the form -Xx or --option.
Refer to the ACU COBOL documentation 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 concepts
Setting 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


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


COMS85

Allows your program to contain syntax introduced in the Communications Module of the ANSI'85 COBOL Standard.

Syntax:

>>-.---.-.----.--COMS85--------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOCOMS85 (Dialect)
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 (Dialect)
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"
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 (Dialect)
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


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 (Dialect)
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: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


ANS85 DIALECT setting

If you set DIALECT"ANS85", the following Compiler directives are set:

NOADV

ALIGN"8"

ALPHASTART"1"

ALTER

ANS85

ARITHMETIC"MF"

NOBS2000

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"ASCII"

CHECKDIV"ANSI"

COMS85

COPYEXT"cbl,CPY,"

COPYLBR

CURRENT-DATE"MMDDYY"

NODBCHECK

NODBCS

NODBCSSOSI

NODBSPACE

DE-EDIT"2"

DEFAULTBYTE"32"

NODG

DPC-IN-SUBSCRIPT

DYNAM

ECHO

NOENTCOBOL

NOEXTINDEX

NOFDCLEAR

NOFLAG

NOFLAGAS

NOFLAGMIG

FLAGSTD"H C2 D2 S2 R O"

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

NOHOSTNUMCOMPARE

NOHOSTNUMMOVE

NOIBM-MS

INFORETURN"U"

INTLEVEL"2"

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"

ALPHASTART"1"

ALTER

NOANS85

ARITHMETIC"MF"

ASSIGN"EXTERNAL"

BS2000

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"EBCDIC"

CHECKDIV"ANSI"

NOCOMS85

COMP5-BYTE-ORDER"NATIVE"

COPYEXT"cbl,CPY,"

NOCOPYLBR

CURRENT-DATE"MMDDYY"

NODBCHECK

NODBCS

NODBCSSOSI

NODBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

DPC-IN-SUBSCRIPT

DYNAM

ECHO

NOENTCOBOL

NOEXTINDEX

NOFDCLEAR

FLAG"BS2000"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

NOHOSTNUMCOMPARE

NOHOSTNUMMOVE

NOIBM-MS

INFORETURN"U"

INTLEVEL"4"

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

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"

ALPHASTART"1"

ALTER

NOANS85

ARITHMETIC"MF"

ASSIGN"EXTERNAL"

BS2000-OFFLOAD

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"ASCII"

CHECKDIV"ANSI"

NOCOMS85

COMP5-BYTE-ORDER"NATIVE"

COPYEXT"cbl,CPY,"

NOCOPYLBR

CURRENT-DATE"MMDDYY"

NODBCHECK

NODBCS

NODBCSSOSI

NODBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

DPC-IN-SUBSCRIPT

NODG

DYNAM

ECHO

NOENTCOBOL

NOEXTINDEX

NOFDCLEAR

FLAG"BS2000"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

NOHOSTNUMCOMPARE

NOHOSTNUMMOVE

NOIBM-MS

INFORETURN"U"

INTLEVEL"4"

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

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


COB370, COB371 and COB372 DIALECT settings

If you set DIALECT"COB370", DIALECT"COB371" or DIALECT"COB372", the following Compiler directives are set:

ADV

ALIGN"8"

ALPHASTART"1"

ALTER

ANS85

APOST

AREACHECK

ARITHMETIC"VSC2"

ASSIGN"EXTERNAL"

NOBOUND

BYTEMODEMOVE

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"EBCDIC"

CHECKDIV"COBOL370"

COBOL370"2" (for DIALECT"COB370")

COBOL370"2" (for DIALECT"COB372")

COBOL370"1" (for DIALECT"COB371")

COBSTATCONV

COMS85

COPYEXT"CPY,CBL"

COPYLBR

CURRENT-DATE"MMDDYY"

DBCHECK

DBCS"3"

DBCSSOSI"14""15"

DBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

NODOSVS

DPC-IN-SUBSCRIPT

NODYNAM

ECHO

NOENTCOBOL

NOEXTINDEX

FDCLEAR

FLAG"COBOL370"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

HOSTNUMCOMPARE"2"

HOSTNUMMOVE"2"

NOIBM-MS

IBMCOMP

INDD

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

MAPNAME

NOMF

NOMFCOMMENT

NOMS

NOODOOSVS

ODOSLIDE

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOPTIONAL-FILE

NOOS390

NOOSVS

OUTDD

NOPANVALET

NOPC1

PERFORM-TYPE"COB370"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

QUOTE

RDW

RECMODE"COB370"

REMAINDER"2"

RESEQ

NORM

RTNCODESIZE"2"

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS"COL"

SOURCEFORMAT"FIXED"

NOSPZERO

STICKY-LINKAGE

NOSTICKY-PERFORM

SYMBSTART"1"

NOTRACE

NOTRUNC

TRUNCCALLNAME"8"

TRUNCCOPY"8"

WARNING"3"

NOXOPEN

NOXREF

ZEROLENGTHFALSE

NOZEROSEQ

ZWB

Parent topic: DIALECT


ENTCOBOL DIALECT setting

If you set DIALECT"ENTCOBOL" the following Compiler directives are set:

ADV

ALIGN"4"

ALPHASTART"1"

ALTER

ANS85

APOST

AREACHECK

ARITHMETIC"ENTCOBOL"

ASSIGN"EXTERNAL"

NOBOUND

BYTEMODEMOVE

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"EBCDIC"

CHECKDIV"ENTCOBOL"

COBSTATCONV

NOCOBOL370

COMS85

COMP5-BYTE-ORDER"NATIVE"

COPYEXT"CPY,CBL"

COPYLBR

COPYLIST

CURRENT-DATE"MMDDYY"

DBCHECK

DBCS"3"

DBCSSOSI"14""15"

DBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

NODOSVS

DPC-IN-SUBSCRIPT

NODYNAM

ECHO

ENTCOBOL

NOEXTINDEX

FDCLEAR

FLAG"ENTCOBOL"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

FORM"60"

FP-ROUNDING"ENTCOBOL"

HOSTNUMCOMPARE"2"

HOSTNUMMOVE"2"

NOIBM-MS

IBMCOMP

INDD

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

MAPNAME

NOMF

NOMFCOMMENT

NOMS

NOMVS

ODOSLIDE

NOODOOSVS

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOPTIONAL-FILE

NOOS390

NOOSVS

OUTDD

NOPANVALET

NOPC1

PERFORM-TYPE"ENTCOBOL"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

RDW

RECMODE"ENTCOBOL"

REMAINDER"2"

RESEQ

NORM

RTNCODESIZE"2"

NOSAA

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS"COL"

SOURCEFORMAT"FIXED"

NOSPZERO

STICKY-LINKAGE"2"

NOSTICKY-PERFORM

SYMBSTART"1"

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"

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

NOFDCLEAR

FLAG"ISO2002"

NOFLAGAS

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

NOHOSTNUMCOMPARE

NOHOSTNUMMOVE

NOIBM-MS

INFORETURN"U"

INTLEVEL"4"

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"

ALPHASTART"1"

ALTER

ANS85

APOST

NOAREACHECK

ARITHMETIC"MF"

ASSIGN"DYNAMIC"

BOUND

NOBYTEMODEMOVE

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"ASCII"

CHECKDIV"ANSI"

NOCOBOL370

NOCOBSTATCONV

COMP5-BYTE-ORDER"NATIVE"

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

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"

ALPHASTART"1"

ALTER

ANS85

APOST

AREACHECK

ARITHMETIC"VSC2"

ASSIGN"EXTERNAL"

NOBOUND

BYTEMODEMOVE

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"EBCDIC"

CHECKDIV"COBOL370"

NOCOBOL370

COBSTATCONV

COMS85

COPYEXT"CPY,CBL"

COPYLBR

COPYLIST

CURRENT-DATE"MMDDYY"

DBCHECK

DBCS"3"

DBCSOSSI"14""15"

DBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

NODOSVS

DPC-IN-SUBSCRIPT

NODYNAM

ECHO

NOENTCOBOL

NOEXTINDEX

FDCLEAR

FLAG"MVS"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

FORM"60"

FP-ROUNDING"VSC2"

HOSTNUMCOMPARE"2"

HOSTNUMMOVE"2"

IBMCOMP

NOIBM-MS

INDD

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

MAPNAME

MVS

NOMF

NOMFCOMMENT

NOMS

NOODOOSVS

ODOSLIDE

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOPTIONAL-FILE

NOOS390

NOOSVS

OUTDD

NOPANVALET

NOPC1

PERFORM-TYPE"MVS"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

RDW

RECMODE"COB370"

REMAINDER"2"

RESEQ

NORM

RTNCODESIZE"2"

NOSAA

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS"COL"

NOSTICKY-PERFORM

SOURCEFORMAT"FIXED"

NOSPZERO

STICKY-LINKAGE"2"

SYMBSTART"1"

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"

ALPHASTART"1"

ALTER

ANS85

APOST

AREACHECK

ARITHMETIC"OS390"

ASSIGN"EXTERNAL"

NOBOUND

BYTEMODEMOVE

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"EBCDIC"

CHECKDIV"OS390"

NOCOBOL370

COBSTATCONV

COMS85

COMP5-BYTE-ORDER"NATIVE"

COPYEXT"CPY,CBL"

COPYLBR

COPYLIST

CURRENT-DATE"MMDDYY"

DBCHECK

DBCS"3"

DBCSOSSI"14""15"

DBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

NODOSVS

DPC-IN-SUBSCRIPT

ECHO

NOENTCOBOL

NOEXTINDEX

FDCLEAR

FLAG"OS390"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

FORM"60"

FP-ROUNDING"OS390"

HOSTFD

HOSTNUMCOMPARE"2"

HOSTNUMMOVE"2"

IBMCOMP

NOIBM-MS

INDD

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

MAPNAME

NODYNAM

NOMF

NOMFCOMMENT

NOMS

NOMVS

NOODOOSVS

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOPTIONAL-FILE

NOOSVS

ODOSLIDE

OUTDD

OS390

NOPANVALET

NOPC1

PERFORM-TYPE"OS390"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

RDW

RECMODE"OS390"

REMAINDER"2"

RESEQ

NORM

RTNCODESIZE"2"

NOSAA

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS"COL"

SOURCEFORMAT"FIXED"

NOSPZERO

STICKY-LINKAGE"2"

NOSTICKY-PERFORM

SYMBSTART"1"

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"

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

CURRENT-DATE"MMDDYY"

NODBCHECK

NODBCS

NODBCSSOSI

NODBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

NODOSVS

DPC-IN-SUBSCRIPT

NODYNAM

ECHO

NOENTCOBOL

NOEXTINDEX

FDCLEAR

FLAG"OSVS"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

FORM"60"

FP-ROUNDING"OSVS"

HOSTNUMCOMPARE"2"

HOSTNUMMOVE"2"

IBMCOMP

NOIBM-MS

INDD

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

MAPNAME

NOMF

NOMFCOMMENT

NOMS

NOMVS

ODOOSVS

ODOSLIDE

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOPTIONAL-FILE

NOOS390

OSVS

OUTDD

NOPANVALET

NOPC1

PERFORM-TYPE"OSVS"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

RDW

RECMODE"OSVS"

REMAINDER"2"

REPORTLINE"132"

RESEQ

NORM

RTNCODESIZE"2"

NOSAA

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS"LINE"

SOURCEFORMAT"FIXED"

NOSPZERO

STICKY-LINKAGE

STICKY-PERFORM

SYMBSTART"1"

TRACE

NOTRUNC

TRUNCCALLNAME"8"

TRUNCCOPY"8"

NOVSC2

WARNING"3"

NOXOPEN

NOXREF

NOZEROLENGTHFALSE

NOZEROSEQ

ZWB

Parent topic: DIALECT


RM DIALECT setting

If you set DIALECT"RM", the following Compiler directives are set:

ALIGN(2)

COMP-6(1)

COPYSEARCH(RM)

PARAMCOUNTCHECK

OLDINDEX

NOOPTIONAL-FILE

RETRYLOCK

SEQUENTIAL"LINE"

NOTRUNC

The following settings are also enabled:
  • The LOCKING clause of the SELECT statement is set to LOCK MODE IS AUTOMATIC for all file types.
  • Numeric data items are defined as SIGN TRAILING SEPARATE.
  • The 1024 calling convention, which is required to run the RM/COBOL standard library routines available in this COBOL system.
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"

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

CURRENT-DATE"MMDDYY"

DBCHECK

DBCS"2"

DBCSSOSI"14""15"

DBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

NODOSVS

DPC-IN-SUBSCRIPT

NODYNAM

ECHO

NOENTCOBOL

NOEXTINDEX

FDCLEAR

FLAG"VSC2"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

FORM"60"

FP-ROUNDING"VSC2"

HOSTNUMCOMPARE"2"

HOSTNUMMOVE"2"

IBMCOMP

NOIBM-MS

INDD

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

MAPNAME

NOMF

NOMFCOMMENT

NOMS

NOMVS

ODOSLIDE

NOODOOSVS

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOPTIONAL-FILE

NOOS390

NOOSVS

OUTDD

NOPANVALET

NOPC1

PERFORM-TYPE"VSC2"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

RDW

RECMODE"OSVS"

REMAINDER"2"

RESEQ

NORM

RTNCODESIZE"2"

NOSAA

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS"COL"

SOURCEFORMAT"FIXED"

NOSPZERO

STICKY-LINKAGE

STICKY-PERFORM

SYMBSTART"1"

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"

ALPHASTART"1"

ALTER

ANS85

APOST

AREACHECK

ARITHMETIC"VSC2"

ASSIGN"EXTERNAL"

NOBOUND

BYTEMODEMOVE

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"EBCDIC"

CHECKDIV"VSC2"

NOCOBOL370

COBSTATCONV

COMS85

COPYEXT"CPY,CBL"

COPYLBR

COPYLIST

CURRENT-DATE"MMDDYY"

DBCHECK

DBCS"2"

DBCSSOSI"14""15"

DBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

NODOSVS

DPC-IN-SUBSCRIPT

NODYNAM

ECHO

NOENTCOBOL

NOEXTINDEX

FDCLEAR

FLAG"VSC2"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

FORM"60"

FP-ROUNDING"VSC2"

HOSTNUMCOMPARE"2"

HOSTNUMMOVE"2"

NOIBM-MS

IBMCOMP

INDD

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

MAPNAME

NOMF

NOMFCOMMENT

NOMS

NOMVS

NOODOOSVS

ODOSLIDE

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOPTIONAL-FILE

NOOS390

NOOSVS

OUTDD

NOPANVALET

NOPC1

PERFORM-TYPE"VSC2"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

RDW

RECMODE"VSC23"

REMAINDER"2"

RESEQ

NORM

RTNCODESIZE"2"

NOSAA

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS"COL"

SOURCEFORMAT"FIXED"

NOSPZERO

STICKY-LINKAGE

NOSTICKY-PERFORM

SYMBSTART"1"

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

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

Properties:

Default: | MF"16" (Dialect)
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 concepts
Reserved Words
Preprocessor Response Codes
Related information
DIALECT
OLDBLANKLINE
OLDNEXTSENTENCE
Language Features - Dialect
Key to Compiler Directives


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


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
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:
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.
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 to use working storage to mean object storage in instances and factory (class) objects.

Properties:

Default: | OOCTRL(+F-G-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(Dialect)
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 (Dialect)
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


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

  • 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.
  • 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.
  • 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.
  • PANVALET
    Allows ++INCLUDE statements in your program.
  • PROGID-COMMENT
    Allows comments following the PROGRAM-ID header in the Program-Id paragraph.
  • 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


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


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


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

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
Language Features - 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


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

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"COB370", 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:
      • 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
Multiple User COBOL Applications in .NET
RunUnit Class


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"-A-----><
    +-/-+

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.

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

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

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---"rsv-word"---------------><
   +-/-+

Parameters:

rsv-word A 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 concepts
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.
  • TRICKLE
    Tells the Compiler that the program contains legal but unstructured perform-ranges, and that certain optimizations cannot, therefore, be made.
Parent topic: Language Features


ALTER

Allows ALTER statements in your program.

Syntax:

>>-.---.-.----.--ALTER---------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | ALTER (Dialect)
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 (Dialect)
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 (Dialect)
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


TRICKLE

Tells the Compiler that the program contains legal but unstructured perform-ranges, and that certain optimizations cannot, therefore, be made.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--TRICKLE-------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | TRICKLE
Phase: | Generate
$SET: | Initial

Comments:

NOTRICKLE tells the Compiler that nowhere in the program could control "trickle" from one perform-range into another. Such a program has structured flow of control: it contains no paragraph or section that is entered both by being performed and by control falling into it from the preceding code, and none that is at the end of the range of one PERFORM and in the middle of the range of another PERFORM.

With NOTRICKLE, the Compiler can generate more efficient code for PERFORM statements.

Parent topic: Language Features - Speed
Parent topic: Compiler Directives - Alphabetical List


Language Features - Additional Features

  • CONSTANT
    Declares a constant for use in the program.
  • DB2
    Causes EXEC SQL statements in your program to be replaced with DB2 LUW API calls.
  • FCDREG
    Makes the Compiler define special registers giving access to File Control Descriptions (FCD) and Key Definition Blocks.
  • PREPROCESS, P
    Makes the Compiler take the source program from a preprocessor instead of a source file.
  • REWRITE-LS
    Allows REWRITE statements on line sequential files.
  • SEQCHK
    Makes the Compiler check the sequence numbers in columns 1 through 6 and identify source lines that are out of sequence.
  • SOURCEFORMAT
    Selects free, fixed, variable, or terminal format for COBOL source.
  • LOCALSOURCEFORMAT
    Specifies that any setting of the SOURCEFORMAT directive in a source file is maintained for that file. This means that if a file with a different SOURCEFORMAT setting is copied into the source file, when processing exits the copied code, the SOURCEFORMAT setting returns to that originally specified in the source file.
  • SQL
    Causes EXEC SQL statements in your program to be replaced by ODBC run-time calls, depending on the options you specify.
  • XMLPARSE
    Determines the behavior of the XML PARSE statement and special registers relating to XML events.
Parent topic: Language Features


CONSTANT

Declares a constant for use in the program.

Syntax:

>>-.---.-CONSTANT-const-name-.-(numeric-lit)--.-><
   +-/-+                     +-"alphanum-lit"-+

Parameters:

const-name | Data-name. The constant's name.
numeric-lit | Numeric literal. The constant's value. Must be zero or a positive integer.
alphanum-lit | Alphanumeric literal. The constant's value.

Properties:

Default: | Not set
Phase: | Syntax check
$SET: | Any

Comments:

The effect is as if the constant const-name had been defined in the program in a level-78. Its value is that given in the parentheses or quotation marks. If parentheses are used, the constant is of category numeric; if quotation marks are used it is of category alphanumeric.

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) csqltype=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 (Dialect)
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

Selects free, fixed, variable, or terminal format for COBOL source.

Syntax:

>>-.---.--SOURCEFORMAT--"format-type"------><
   +-/-+

Parameters:

format-type
The format of COBOL source. One of:
  • FIXED
  • FREE
  • VARIABLE
  • TERMINAL

Properties:

Default: | SOURCEFORMAT"VARIABLE" (Dialect) for managed code and SOURCEFORMAT"FIXED" (Dialect) for native code and from the command line
Phase: | Syntax check
$SET: | Any

Dependencies:

SOURCEFORMAT"FREE" sets NOMFCOMMENT, NORESEQ and NOSEQCHK at end.

SOURCEFORMAT"VARIABLE" is set by DIALECT(ENTCOBOL).

Parent topic: Language Features - Additional Features
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Language Features - Additional Features
MFCOMMENT
RESEQ
SEQCHK
Key to Compiler Directives


LOCALSOURCEFORMAT

Specifies that any setting of the SOURCEFORMAT directive in a source file is maintained for that file. This means that if a file with a different SOURCEFORMAT setting is copied into the source file, when processing exits the copied code, the SOURCEFORMAT setting returns to that originally specified in the source file.

Syntax:

>>-.---.-.----.--LOCALSOURCEFORMAT-------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOLOCALSOURCEFORMAT
Phase: | Check
$SET: | Any
Parent topic: Language Features - Additional Features
Parent topic: Compiler Directives - Alphabetical List
Related information
Key to Compiler Directives
SOURCEFORMAT


SQL

Causes EXEC SQL statements in your program to be replaced by ODBC run-time calls, depending on the options you specify.

Syntax:

>>-.---.-.----SQL-.----------------------.-.><
   +-/-+ |        |   +-----.---.-----+  | |
         |        |   |     +-,-+     |  | |
         |        |   V               |  | |
         |        +-(.-option=setting-.)-+ |
         |           |                |    |
         |           +-NO-option------+    |
         +-NO-SQL--------------------------+

Parameters:

option
One of the SQL options listed in the topic SQL Compiler Directive Options
setting
The setting for the option

Properties:

Default: | NOSQL
Phase: | Syntax check
$SET: | Initial
Parent topic: Language Features - Additional Features
Parent topic: Compiler Directives - Alphabetical List
Related reference
Embedded SQL Statements
Related information
Language Features - Additional Features
Key to Compiler Directives


XMLPARSE

Determines the behavior of the XML PARSE statement and special registers relating to XML events.

Syntax:

>>-.---.-.----.-------XMLPARSE--"version"---><
   +-/-+

Parameters:

version
The version of Enterprise COBOL that the XML PARSE statement emulates.
COMPAT
The operational behaviors and results of XML PARSE statements are compatible with those of Version 3 of Enterprise COBOL.
XMLSS
XML PARSE statements are processed as for Enterprise COBOL version 4. The following XML parsing capabilities are available only when this option is in effect:
  • Enhanced namespace processing
  • ENCODING and RETURNING NATIONAL phrases of the XML PARSE statement
  • Support for the VALIDATING phrase to enable checking against an XML schema in text format.

Properties:

Default: | XMLPARSE(XMLSS)
Phase: | Syntax Check
$SET: | Initial
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.
  • 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.
  • IDYSRCPATH
    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.
  • 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
    Compiles a program for execution in a 64-bit run-time environment.
  • 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 number of space characters by which to expand tab characters in the source code when it is parsed by the checker.
  • 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 (Dialect)
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


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 (Dialect)
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: | Click Project > Properties > Build and fill in Configuration Copybook Paths
Phase | Syntax check
$SET | None

Comments:

You should only use the COPYPATH directive when compiling using the cobol 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 in:

  • IBM's TX Series on WebSphere
Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


IDYSRCPATH

Controls the paths stored in .idy files for main source files.

Note: This directive has been deprecated. It is provided for backward compatibility only and may be removed in later releases.

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

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.

INTLEVEL"7" is the only available setting in this COBOL system. All other levels are deprecated, and INTLEVEL"7" is automatically set where these levels are specified.

Syntax:

>>-.---.-.-------INTLEVEL--"integer"-.-----><
   +-/-+ +-----NOINTLEVEL------------+

Parameters:

integer
The level of portability. Can be 4, 5, 6 or 7 where:
4
Enables long numeric support, that is, PIC clauses greater than PIC 9(18).
5
Reserved.
6
Reserved. Enables UNICODE support.
7
Reserved.

Properties:

Default: | INTLEVEL"7"
Phase: | Syntax check
$SET: | No

Comments:

Full details of intermediate code portability are included with the relevant COBOL systems.

NOINTLEVEL causes intermediate code to be created that is suitable for execution only in this environment.

INTLEVEL"integer" creates intermediate code that can be executed by some versions of Micro Focus products in other environments. For portability between environments, the value of integer used for compilation must be supported by the Micro Focus COBOL system on each environment on which you want to execute the intermediate code.

INTLEVEL"integer" can limit the syntax that can be used in your program.

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.

Parent topic: Compiler Control - Compile/Link 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.

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


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" (with OMF"OBJ")
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 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
Related information
OMF


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
Related concepts
Compiler Directives
Overview - Compiling COBOL Code


P64

Compiles a program for execution in a 64-bit run-time environment.

Syntax:

 >>-.---.-.----.--P64------------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOP64 on 32-bit systems or P64 if the 64-bit check box in the Build Settings dialog box is set.
IDE equivalent: | Click Project > Properties >Configuration Properties > Build > Outputs > Generate 64-Bit Pointers
Phase: | Syntax check
$SET: | Any

Dependencies:

P64 immediately sets: RTNCODE-SIZE"8" and FCD3

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: Compiler Directives - Alphabetical List


PCOMP

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.

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


REPOSITORY

Creates a repository file or requests that the program being compiled is checked against the repository file.

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


SOURCETABSTOP

Sets the number of space characters by which to expand tab characters in the source code when it is parsed by the checker.

Syntax:

>>-.---.--SOURCETABSTOP--"number"------><
   +-/-+

Parameters:

number A number between 1-255

Properties:

Default: | SOURCETABSTOP"4" (Dialect)(IDE default) or SOURCETABSTOP"8" (command line default)
Phase: | Syntax check
$SET: | Initial

Visual Studio inserts tab characters when the tab key is pressed.

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


DIRECTIVES, DIR

Makes the Compiler read directives from a file.

Syntax:

>>-.---.-.-DIRECTIVES-.-"filename"---------><
   +-/-+ +-DIR--------+

Parameters:

filename A full file specification of the directives file. This can be any valid filename except cobol.dir .

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


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 (Dialect)
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 a file that appears in a DIRECTIVES or USE 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"------------------><
   +-/-+

Parameters:

filename A full file specification of the directives file. This can be any valid filename except cobol.dir .

Properties:

Default: | Not set
Phase: | Syntax check
$SET: | Any

Comments:

USE is synonymous with DIRECTIVES. All rules that apply to DIRECTIVES also apply to USE.

Parent topic: Compiler Control - Directives Control
Parent topic: Compiler Directives - Alphabetical List


Compiler Control - Error and Flag Messages

  • BRIEF
    Makes the Compiler 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
    Makes the Compiler ask, each time it gives an error message, whether you want to stop compiling.
  • 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
    Makes the Compiler ask, each time it gives a flagging message, whether you want to stop compiling.
  • 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 the number of a syntax check error message to "hide" so that if the error is encountered it is ignored.
  • IMPLICITSCOPE
    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.
  • 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.
  • QUERY
    Makes the Compiler ask, each time it is unable to find a copybook, what it should do.
  • 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


BRIEF

Makes the Compiler 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


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 Number of message to be changed or ALL meaning all messages.
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"10 S 135 E 100 N"
Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List
Related information
FLAGAS
HIDE-MESSAGE
Compiler Control - Error & Flag Messages
Key to Compiler Directives


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

Makes the Compiler ask, each time it gives an error message, whether you want to stop compiling.

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 (Dialect)
Phase: | Syntax check
$SET: | Any
Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Compiler Control - Error & Flag Messages
Key to Compiler Directives


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

Makes the Compiler ask, each time it gives a flagging message, whether you want to stop compiling.

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 the number of a syntax check 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--"integer"-----.----><
   +-/-+ |                                 |
         +-NO--HIDE-MESSAGE--.-----------.-+
                             +-"integer"-+

Parameters:

integer The number of the syntax check error message to hide.

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"integer" adds integer to a list of syntax check 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 flag with its number in the list 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. Normally, they are always shown, even if their number appears in this list.

NOHIDE-MESSAGE clears the list of numbers so no messages are hidden.

NOHIDE-MESSAGE"integer" removes only the specified message number from the list.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List


IMPLICITSCOPE

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" (Dialect)
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.

Syntax:

>>-.---.-.----.-MOVE-LEN-CHECK--.---------------.--.---><
   +-/-+      +                 +--"parameter"--+  +
              +-NOMOVE-LEN-CHECK-------------------+

Parameters:

parameter ALL or TRUNC

Properties:

Default: | NOMOVE-LEN-CHECK
Phase: | Syntax check
$SET: | Any

Comments:

This directive causes the compiler to check source and target lengths for alphanumeric MOVE operations and issues a warning message (166) if they are different.

If you do not specify a parameter, or if you set parameter to ALL, a warning message (166) is issued if the source and target lengths are different.

If you set parameter to TRUNC, a warning message (1247) is issued when the source length is greater than the target length.

Any warning messages produced by enabling this directive are only visible if WARNINGS"2" or WARNINGS"3" is selected.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List


QUERY

Makes the Compiler ask, each time it is unable to find a copybook, what it should do.

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


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"2" (Dialect) (IDE default) or WARNING"1" (command line default)
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 information
DIALECT
FLAGAS
Compiler Control - Error & Flag Messages
Key to Compiler Directives


Compiler Control - Listing

  • ASM
    Causes the generator to create a .grp file containing an assembly listing of the native code produced.
  • ASMHEX
    Makes the compiler include machine code byte values in the assembler listing.
  • 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.
  • 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 as well as to show all data passed to the Compiler by a preprocessor.
  • 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


ASM

Causes the generator to create a .grp file containing an assembly listing of the native code produced.
Note: This directive is supported for native COBOL only.
Note:

ASMLIST is synonymous with ASM on all but 32 bit x86 systems, on which it has no effect.

Syntax:

>>-.---.-.----.---------ASM----------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOASM
Phase: | Generate
$SET: | Any
Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List
Related information
Compiler Control - Listing
LIST
ANIM
Key to Compiler Directives


ASMHEX

Makes the compiler include machine code byte values in the assembler listing.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--ASMHEX------------------><
   +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | NOASMHEX
Phase: | Generate
$SET: | Any

Comments:

ASMHEX is ignored on 32-bit x86 systems, where byte values are always included.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List
Related information
Key to Compiler Directives
The PICTURE Clause


COPYEXT

Specifies the filename extension of the copybook that the Compiler is to look for if a filename in a COPY statement is specified without an extension.

Syntax:

                             +---------------+
                             V               |
>>-.---.--COPYEXT-"extension--.-------------.--"--><
   +-/-+                      +-,-extension-+

Parameters:

extension A filename extension.

Properties:

Default: | COPYEXT"cbl,CPY"
Phase: | Syntax check
$SET: | Initial

Comments:

Up to eight 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 then the list of possible extensions is tried in turn until a file is sucessfully 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.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


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-----------><
   +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | NODATAMAP
Phase: | Syntax check
$SET: | Initial

Dependencies:

None.

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 they are encountered in your program by the Compiler. The first line is the program-id of the program to which the data items belong. This enables you to see the relevant data items for nested programs, or for the various areas of OO class programs (classes, object methods, and so on). For each data item, the following information is listed:

  • The line number
  • The data name
  • The address of the data item, that is the offset from the beginning of the program's data area
  • 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 information
Compiler Control - Listing
LIST
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 (Dialect)
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 ). 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 as well as to show all data passed to the Compiler by a preprocessor.

Syntax:

>>-.---.-.----.--PREPLIST------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOPREPLIST
Phase: | Syntax check
$SET: | No

Comments:

This directive is provided as a debugging aid to preprocessor writers.

This directive only affects what the listing file, if produced, contains. 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 (Dialect)
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
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 (Dialect)
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: | Generate
$SET: | Initial
Parent topic: Compiler Control - Screen
Parent topic: Compiler Directives - Alphabetical List


ECHO

Makes the Compiler display error lines and error messages on the screen.

Syntax:

>>-.---.-.----.--ECHO----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | ECHO (Dialect)
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.
  • FAULTFIND
    Enables file input and output to be logged by FaultFinder.
  • 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)
Phase: | Both
$SET: | Initial

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: | COBIDY".\bin\Debug\" for managed code, COBIDY".\bin\x86\Debug\" for native code or NOCOBIDY from the command line
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 file.

Parent topic: Compiling for Debugging and Analysis
Parent topic: Compiler Directives - Alphabetical List


FAULTFIND

Enables file input and output to be logged by FaultFinder.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--FAULTFIND------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOFAULTFIND
Phase: | Syntax check
$SET: | Any
Parent topic: Compiling for Debugging and Analysis
Parent topic: Compiler Directives - Alphabetical List


PROFILE

Includes code in your program to produce detailed performance statistics each time you run the program.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--PROFILE-----------><
   +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | NOPROFILE
Phase: | Syntax check
$SET: | No

Comments:

You need to use the Profiler utility to look at 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 information
To use test coverage from the command line for native COBOL
Run-time Behavior - General
Key to Compiler Directives


TRACE

Enables READY TRACE and RESET TRACE statements.

Syntax:

>>-.---.-.----.--TRACE----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOTRACE(Dialect)
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 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 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

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

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
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" (Dialect)
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 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
Enables access and use of Vision, the ACUCOBOL-GT indexed file system. Specify this parameter if you want to access your Vision files.
Note:

Access to the RM/COBOL file handler is available by configuring an add-on to the Vision file handler.

FHREDIR
For use with Fileshare Version 2
fhname
Name of your own file handler

Properties:

Default: | CALLFH"EXTFH" (Dialect)
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 directive.

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.

Use this directive to make your programs call your file handler instead of the standard File Handler.

Parent topic: File Handling
Parent topic: Object Code - External Handlers
Parent topic: Compiler Directives - Alphabetical List
Related concepts
Environment Variables Used to Resolve File Names
Configuring the RM/COBOL File Handler


CALL-RECOVERY

Specifies the behavior when control is returned to a program.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.-------CALL-RECOVERY--"integer"--.-----><
   +-/-+ +.----.-CALL-RECOVERY-------------+
          +-NO-+

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 "2" when compiling a mixture of CICS and non-CICS programs for running in IBM's TX Series on WebSphere.

Properties:

Default: | NOCALL-RECOVERY
Phase: | Syntax check
$SET: | Initial

Comments:

Specifying CALL-RECOVERY with no parameter has the same effect as specifying CALL-RECOVERY "2".

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" (Dialect)
Phase: | Syntax check
$SET: | Initial
Parent topic: File Handling
Parent topic: Object Code - External Handlers
Parent topic: Compiler Directives - Alphabetical List


COBFSTATCONV

Causes the Callable File Handler to use the user-supplied module specified in the COBFSTATCONV environment variable to convert the file status codes if an I/O error is encountered on a file.

Syntax:

>>-.---.-.----.--COBFSTATCONV--------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOCOBFSTATCONV .
Phase: | Syntax check
$SET: | Initial

Comments:

This directive is provided for compatibility with previous versions of Micro Focus COBOL only.

Parent topic: File Handling
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related information
Run-time Behavior - General
Key to Compiler Directives


DATACOMPRESS

Specifies the type of data compression to be done on sequential and indexed files.

Syntax:

>>-.---.-.-----DATACOMPRESS--"integer"-.---><
   +-/-+ +-NO--DATACOMPRESS------------+

Parameters:

integer
Must be one of:
0
Equivalent to NODATACOMPRESS
1
Specifies run-length encoding.
3
Specifies run-length encoding for double-byte (DBCS) characters
128 through 255
User-defined compression routines

Properties:

Default: | DATACOMPRESS"0"
Phase: | Syntax check
$SET: | Any

Comments:

The only values that can be specified for data compression supported by this system are 0, 1 and 3. Values in the range 128 through 255 indicate user-defined compression routines.

You need to specify data compression only when creating the file. Subsequently, the data compression is detected when the file is opened.

To get data compression on an individual file, use $SET statements in your source so that this directive is in effect only for the part of the source containing the file's SELECT statement.

Data compression is supported only by the Callable File Handler. All indexed files are processed by the Callable File Handler. However, if you want to use data compression with sequential files, every program referencing those files must be compiled with the directive CALLFH"EXTFH".

Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List
Related information
CALLFH
File Handling
Key to Compiler Directives


DETECT-LOCK

Makes READ statements detect when a record is locked by another program.

Syntax:

>>-.---.-.----.--DETECT-LOCK---------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | DETECT-LOCK
Phase: | Syntax check
$SET: | Initial

Comments:

The Compiler also accepts the name without a hyphen; that is, DETECTLOCK.

With DETECT-LOCK, if a READ statement reads a record locked by another program, it returns an I/O status of 9/068. With NODETECT-LOCK, it returns 0/000. In both cases it reads the record successfully.

If a READ statement attempts to lock a record (that is, if the statement LOCK MODE IS AUTOMATIC has been specified, or a WITH LOCK phrase is used on the READ statement), and the record is locked by another program, an I/O status of 9/068 is returned. If NODETECT-LOCK is specified, and the READ statement is not attempting to lock a record an I/O status of 0/000 is returned.

When DETECT-LOCK is specified, individual READ statements can be made to ignore locks by using the READ ... IGNORE LOCK syntax.

Parent topic: File Handling
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


FCDCAT

Specifies whether the catalogued file information for a file is used when accessing that file.

Syntax:

>>-.---.--.----.-FCDCAT-----><
   +-/-+  +-NO-+

Parameters:

None

Properties:

Default: | FCDCAT for mainframe dialects; NOFCDCAT for non-mainframe dialects
Phase: | Syntax check
$SET: | Any

Comments:

To enable this behavior for an individual file, use a $SET statement in your source code before the file's SELECT statement.

Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List


FDCLEAR

Specifies that the record buffer for a file should be cleared after every write operation.

Syntax:

>>-.---.-.-------FDCLEAR--"integer"--.-----><
   +-/-+ +.----.-FDCLEAR-------------+
          +-NO-+

Parameters:

integer
Must be one of:
1
Specifies that the record buffer for a file should be cleared after every write operation. The buffer is cleared to the value specified by the DEFAULTBYTE directive.
2
As for 1, but the record buffer is also cleared after the initial OPEN statement.

Properties:

Default: | NOFDCLEAR (Dialect)
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.

This directive is not related in any way to Fileshare Version 2. You must not use this directive when using Fileshare V2.

Syntax:

>>-.---.-.----.--FILESHARE-----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOFILESHARE
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 locking syntax rather than this directive.

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 | System-specific default (for this COBOL system, same as 3).
1 | C-ISAM format.
2 | Micro Focus Level II format.
3 | Micro Focus COBOL format.
4 | An optimized form of the format used by this COBOL system, for fast duplicate key handling.
5 | Reserved
6 | Reserved
7 | Reserved.
8 | Large indexed files.
9-10 | Reserved.
11 | Mainframe print file format.
12-255 | Reserved.

Properties:

Default: | FILETYPE"0"
Phase: | Syntax check
$SET: | Any

Dependencies:

FILETYPE"integer" sets IDXFORMAT"integer" 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.

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.

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

Syntax:

>>-.---.--IDXFORMAT--"integer"-------------><
   +-/-+

Parameters:

integer
An integer representing the type to use.
0
System-specific default (identical to 8).
1
C-ISAM format.
2
Micro Focus Level II format.
3
Micro Focus indexed file format.
4
An optimized form of Micro Focus indexed file format, for fast duplicate key handling.
5
Btrieve with ANSI
6
Btrieve without ANSI
7
RLIO format indexed files.
8
Large indexed.
9
Indexed with single key, non-duplicate, key ordered records.
10
Reserved.
11
Mainframe print file format.
12-13
Reserved.
14
Heap file.
15
ESDS
16-255
Reserved.

Properties:

Default: | IDXFORMAT"0"
Phase: | Syntax check
$SET: | Any

Dependencies:

Set to IDXFORMAT"integer" immediately by FILETYPE"integer".

Comments:

Existing files in any of the given formats are processed correctly without the need for this directive. This directive controls the format used when creating new files.

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


IXNLSKEY

Specifies that the File Handler should sort index file keys according to the local collating sequence rather than the ASCII collating sequence.

Syntax:

>>-.---.-.----.----IXNLSKEY---------------><
   +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | NOIXNLSKEY
Phase: | Syntax check
$SET: | Any

Comments:

If you set IXNLSKEY, then move the index file to a different locale, the index keys will no longer be found.

Parent topic: File Handling
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


IXNUMKEY

Enables true numeric sorting on index keys.

Syntax:

>>-.---.-.----.-IXNUMKEY-------------------><
   +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | NOIXNUMKEY
Phase: | Syntax check
$SET: | Any

Comments:

Index keys are are normally treated as alphanumeric even if they contain numeric data. Therefore, the results of READ NEXT operations might be unexpected. This directive should be used when the true numeric order is required. In general it will only have an effect for keys defined as signed numeric, but some kinds of unsigned data (for instance COMP-5) may also be affected.

For example, say you have a key defined as pic s9(5), and you had four records for which the key values were 1, -2, 3, -4, stored as:

  • 00001+
  • 00002-
  • 00003+
  • 00004-

If these keys are treated as alphanumeric, they will be retrieved in the above order. However if they are treated as numeric (which is the case when IXNUMKEY is specified), they will be stored (and therefore retrieved when using READ NEXT) in numeric order:

  • 00004-
  • 00002-
  • 00001+
  • 00003+
Parent topic: File Handling
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


KEYCOMPRESS

Specifies the type of key compression to be done on indexed files.

Syntax:

>>-.---.-.-----KEYCOMPRESS--"integer"-.----><
   +-/-+ +-NO--KEYCOMPRESS------------+

Parameters:

integer
Must be between 0 and 7, combining the following values
1
Suppress repetitions of duplicate keys.
2
Suppress leading characters that are the same as in the previous key.
4
Suppress trailing spaces.

You can specify any combination of these numbers by adding these values together.

Properties:

Default: | KEYCOMPRESS"0"
Phase: | Syntax check
$SET: | Any

Comments:

KEYCOMPRESS"0" is equivalent to NOKEYCOMPRESS.

You need specify key compression only when creating the file. Subsequently, key compression is detected when the file is opened.

To get key compression on an individual file, use $SET statements in your source code so that this directive is in effect only for the part of the source containing the relevant KEY clause in the file's SELECT statement.

Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List
Related information
File Handling
The File Control Entry
Data Description Entry Skeleton
The OCCURS Clause
The INVALID KEY Condition
The ACCEPT Statement
The DELETE Statement
The MERGE Statement
The READ Statement
The REWRITE Statement
The SORT Statement
The START Statement
The WRITE Statement
XML Syntax - DELETE Statement
XML Syntax - READ Statement
XML Syntax - REWRITE Statement
XML Syntax - START Statement
XML Syntax - WRITE Statement
XML Syntax - SELECT Clause
Index Files - Overview
Key to Compiler Directives


LOCKTYPE

Specifies the type of record locking.

Syntax:

>>-.---.--LOCKTYPE--"integer"--------------><
   +-/-+

Parameters:

integer
The type of locking.
0 | Programs can read locked records, but not access them in other ways. This is the standard method with this COBOL system.
1 | Programs cannot access locked records at all. This is as in languages other than COBOL.
2 | Creates a new file with the same basename as the file being opened but with a .lck extension. Any record locks are recorded in this file. This enables the File Handler to read and write to files up to 4 gigabytes in size regardless of whether the file is shared or locked. You cannot set this value for striped files.

Properties:

Default: | LOCKTYPE"0"
Phase: | Syntax check
$SET: | Initial

Comments:

This directive only has an effect if the CALLFH directive is used.

Parent topic: File Handling
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


OLDREADINTO

Changes the behavior of the READ ... INTO statement.

Syntax:

>>-.---.-.----.--OLDREADINTO---------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOOLDREADINTO (Dialect)
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 (Dialect)
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to OPTIONAL-FILE immediately by NORM. Set to NOOPTIONAL-FILE immediately by RM or RM"ANSI".

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 concepts
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 for managed code and NOPRESERVECASE for native code.
Phase: | Syntax check
$SET: | Any

Comments:

PRESERVECASE preserves the case of those items for which the COBOL name determines a name that is visible externally (such as PROPERTY names specified without the AS clause). The exact case of the COBOL name used in the declaration is the case used for the external name. References to the item from within the same COBOL program can still use any case combination.

The directive also preserves the case of data-names in output from the XML GENERATE statement.

Example:

$set preservecase
01 Fred property binary-long.
*> Sets up a property with external name "Fred"

procedure division.
    Move 999 to fred
*> fred is a normal COBOL data name and can therefore be accessed using any case
Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List


PRINT-EXT

Specifies the extension to be added to the filename associated with the ASSIGN TO PRINTER clause.

Syntax:

>>-.---.-.----PRINT-EXT--"extension"---.-------><
   +-/-+ +-------NOPRINT-EXT-----------+

Parameters:

extension The extension to be added.

Properties:

Default: | NOPRINT-EXT
Phase: | Syntax check
$SET: | Any

Comments:

This directive is ignored unless ASSIGN-PRINTER() is specified with no filename.

Parent topic: File Handling
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


RECMODE

Specifies the default format of files.

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

Properties:

Default: | RECMODE"F" (Dialect)
Phase: | Syntax check
$SET: | Initial

Dependencies:

RECMODE"VSC22" set at end by CMPR2.

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

Set to NORETRYLOCK immediately by NORM.

Comments:

This directive affects a file only if the file has a FILE STATUS item but there is no declarative specifically for that file.

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" (Dialect)
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to SEQUENTIAL"RECORD" immediately by NORM or RM"ANSI".

Set to SEQUENTIAL"LINE" immediately by RM.

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: | DOTNET for managed code and NODOTNET for native code or from the command line
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
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
ILASSEMBLY
ILMAIN
Key to Compiler Directives
ILGEN


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: | ILASSEMBLY"assembly-name" (IDE default) or NOILASSEMBLY (command line default)
IDE equivalent: | Click Project > Properties > Application > Assembly Name

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
ILGEN
ILOUTPUT
ILMAIN
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
ILASSEMBLY
ILMAIN
Key to Compiler Directives


ILMAIN

Specifies the entry method for the executable program being compiled.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.---ILMAIN--"entry-program"--.---><
       +-NOILMAIN------------------+

Parameters:

entry-program
The name of the program containing the main entry point, which is the first static method within that program. For procedural COBOL, the main entry point is denoted by the Procedure Division Using clause.

Properties:

Default: | NOILMAIN
IDE equivalent: | Click Project > Properties > Application and fill in Startup object

Comments:

This directive is comparable to the ILGEN directive: NOILMAIN is equivalent to ILGEN"SUB".

Parent topic: Application Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
ILASSEMBLY
ILGEN
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 > Application > Default Namespace
Parent topic: Application Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
ILASSEMBLY
ILGEN
Key to Compiler Directives


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 > COBOL > Output Path

Comments:

If you need to set the filename of the output assembly file, use the ILASSEMBLY directive.

Parent topic: Application Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
ILASSEMBLY
ILGEN
ILMAIN
Key to Compiler Directives


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.
  • ILNATIVE
    Exposes COBOL 01 level data items as managed primitives where possible.
  • ILOBJECTIFY
    Deprecated functionality. Supported for backward compatibility only.
  • ILSMARTLINKAGE
    Exposes the linkage section and entry points 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.
  • 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.
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.

If you do not need to map any entry points to aliases, avoid using this directive.

Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILNATIVE

Exposes COBOL 01 level data items as managed primitives where possible.
Restriction: This directive is supported for managed COBOL only.

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

When ILNATIVE is specified:

  • 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)
  • COBOL data items other than level-01 items are stored within byte arrays
  • 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

When ILNATIVE is specified, 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.

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 ilgen;
cobol csub ilgen(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 ilgen noilnative;
cobol csub ilgen(sub) noilnative;
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
ILGEN
Key to Compiler Directives


ILOBJECTIFY

Deprecated functionality. 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 reference
ILSTATIC
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILSMARTLINKAGE

Exposes the linkage section and entry points 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

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. Subordinate groups are exposed as strings.

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.

If a namespace is specified, all classes generated as a result of this directive are grouped under that namespace.

Example:

The following COBOL program is compiled with ILSMARTLINKAGE, 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).
       procedure division using by value lnk-function
                                by reference lnk-b-details.

In C#, you can access the data in BookLegacy program in .NET managed 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.Stockno = "6666";
       myDetails.Title = "Managed COBOL";
       myDetails.Author = "Mike Focus";
       myDetails.Type = "Reference";
       myDetails.Retail = 15.50M;
       myDetails.Onhand = 20;
       myDetails.Sold = 5;
       myBook.BookLegacy("2", myDetails);
         // calls the BookLegacy method with myDetails,
         // which corresponds to the group item lnk-b-details

See the C# WinBook demonstration in the Visual COBOL samples for more.

Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related reference
ILSMARTNEST


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

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).
       procedure division using by value lnk-function
                                by reference lnk-b-details.

In C#, you can access the data in BookLegacy program in .NET COBOL as follows:

    BookLegacy myBook = new BookLegacy();
         //creates an object corresponding to the BookLegacy program
    BookLegacy.Details myDetails = new Details();
         //creates an instance corresponding to the group lnk-b-details
    . . .
       myDetails.Stockno = "6666";
       myDetails.Title = "Managed COBOL";
       myDetails.Author = "Mike Focus";
       myDetails.Type = "Reference";
       myDetails.Retail = 15.50M;
       myDetails.Onhand = 20;
       myDetails.Sold = 5;
       myBook.BookLegacy("2", myDetails);
         // calls the BookLegacy method with myDetails,
         // which corresponds to the group item lnk-b-details
See the C# WinBook demonstration in the Visual COBOL samples for more.
Note: The C# program and form needs amending, to refer to BookLegacy.Details, when compiling with the ILSMARTNEST Compiler directive set.
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related reference
ILSMARTLINKAGE


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
Parent topic: Compiler Directives - Alphabetical List
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

Comments:

The main uses of this directive are for performance and for integrating with components that use native platform invokes to access unmanaged code.

Applications compiled with SQL(DBMAN=ODBC) for .NET must be compiled with ILTARGET directive specifying the appropriate platform. You cannot specify ILTARGET(ANYCPU) in this case.

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


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. See the Visual Studio Help topic Calling Native Functions from Managed Code.
  • ILREF
    This directive makes the Visual Studio Framework classes in the specified assembly available to the program being compiled.
  • 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). See the Visual Studio Help topic 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.
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. See the Visual Studio Help topic Calling Native Functions from Managed Code.
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
Parent topic: Reference, Resource and Namespace Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
ILREF
ILRESOURCE
Key to Compiler Directives


ILREF

This directive makes the Visual Studio Framework classes in the specified assembly available to the program being compiled.
Restriction: This directive is supported for managed COBOL only.

Syntax:

>>-----.---ILREF--"parameter"---.--><
       +-NOILREF----------------+

Parameters:

assembly-name
The name of the assembly that contains the required classes

Properties:

Default: | ILREF"assembly-name" (IDE default) or NOILREF (command line default)
IDE equivalent: | Add a reference in the References folder of the solution
Parent topic: Reference, Resource and Namespace Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
ILPINVOKE
ILRESOURCE
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
ILPINVOKE
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 solution

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 information
Managed COBOL Command Line Compiler Directives
ILASSEMBLY
ILREF
ILPINVOKE
ILRESOURCE
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). See the Visual Studio Help topic 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
ILPINVOKE
ILRESOURCE
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: | For the IDE default, see the selected namespaces in the project's properties. Click Project > Properties > Namespaces. 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 > Namespaces and add a namespace in the Imported Namespaces section.
$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 System.DateTime.

Is equivalent to:

$set ilusing"System"
01 d1 type DateTime.

Note that the complete namespace must be specified in an ILUSING directive for it to be effective.

For example:

$set ilusing"System"
01 f1 type System.Windows.Forms.Form.   *> this is OK
01 f2 type Windows.Forms.Form.          *> this does not work

However, this does work:

$set ilusing"System.Windows.Forms"

01 f1 type Form.

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
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


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. See the Visual Studio Help topic Delay Signing for more information.

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. See the Visual Studio Help topic Strong-Name Assemblies (Assembly Signing) for more information.

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
ILDELAYSIGN
ILKEYNAME
ILMAIN
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. See the Visual Studio Help topic Strong-Name Assemblies (Assembly Signing) for more information.

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
ILKEYFILE
ILDELAYSIGN
ILMAIN
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
ILFILEVERSION


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: | ILVERSION"version"
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 - Object File Format
  • 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.
  • CALLMCS
    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.
  • CALLSORT
    Defines the program to be called to handle all SORT and MERGE operations.
Parent topic: Object Code, Size, and Optimization


CALLMCS

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.

Causes all Message Control System operations to be routed through the specified handler.

Syntax:

>>-.---.-.-------CALLMCS--"mcs-name"--.-----><
   +-/-+ +.----.-CALLMCS--------------+
          +-NO-+

Parameters:

mcs-name Root-name of a program to be called to process message control system (MCS) operations.

Properties:

Default: | NOCALLMCS
Phase: | Syntax check
$SET: | Initial

Comments:

If mcs-name is not specified, EXTMCS is assumed.

Parent topic: Object Code - External Handlers
Parent topic: Compiler Directives - Alphabetical List


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.

Properties:

Default: | NOLITLINK
Phase: | Generate
$SET: | Initial

Dependencies:

If OMF"GNT", LITLINK sets OMF"OBJ" at end.

Comments:

This directive only affects object code files.

With LITLINK"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.)

With LITLINK or LITLINK"1", all CALL literal statements generate litlinked calls, regardless of the inclusion of underscores at the start of the literal.

With NOLITLINK, no CALL literal statements generate litlinked calls, regardless of the inclusion of underscores at the start of the literal.

LITLINK"2" is only intended to provide backward compatibility with code written for the 16-bit COBOL system. You should use call-convention 8 for new programs.

Parent topic: Object Code - Interprogram Communication
Parent topic: Compiler Directives - Alphabetical List


LITVAL-SIZE

Specifies the number of bytes to pass if the SIZE clause is omitted when passing numeric literals BY VALUE.

Syntax:

>>-.---.--LITVAL-SIZE--"integer"-----------><
   +-/-+

Parameters:

integer A number up to 4. The number of bytes to pass.

Properties:

Default: | LITVAL-SIZE"4"
Phase: | Syntax check
$SET: | Any
Parent topic: Object Code - Interprogram Communication
Parent topic: Compiler Directives - Alphabetical List
Related information
Object Code - Interprogram Communication
The Object-Computer Paragraph
File Description Entry Skeleton
The RECORD Clause
Screen Section Entry Skeleton
The SIZE Clause
The ACCEPT Statement
The ADD Statement
The CALL Statement
The CHAIN Statement
The COMPUTE Statement
The DISPLAY Statement
The DIVIDE Statement
The ENTRY Statement
The INVOKE Statement
The MULTIPLY Statement
The SET Statement
The START Statement
The STOP Statement
The STRING Statement
The SUBTRACT Statement
The COPY Statement
The REPLACE Statement
Data Description Entry Skeleton
The EXTERNAL Clause
The OCCURS Clause
The PROCEDURE DIVISION Header
The EXAMINE Statement
The INITIALIZE Statement
The INSPECT Statement
The PERFORM Statement
The UNSTRING Statement
XML Syntax - IDENTIFIED BY Clause
The VALUE Clause
The VALUE OF Clause
The VALUE Clause in the Screen Section
The VALUE Clause (Report Writer)
Key to Compiler Directives


RTNCODE-SIZE

Specifies the size of the RETURN-CODE special register and its alignment in memory.

Syntax:

>>-.---.--RTNCODE-SIZE--"integer"----------><
   +-/-+

Parameters:

integer
One of:
2
PIC S9(4) COMP: size 2 bytes, aligned on a two-byte boundary.
4
PIC S9(9) COMP: size 4 bytes, aligned on a four-byte boundary.
8
PIC S9(18) COMP: size 8 bytes, aligned on an eight-byte boundary.

Properties:

Default: | RTNCODE-SIZE"4"
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to RTNCODE-SIZE"4" immediately by XOPEN.

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.

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

Dependencies:

If OMF"GNT", PPLITLINK sets OMF"OBJ" at end.

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 - Object File Format

  • OMF
    Specifies whether to produce generated code.
Parent topic: Object Code, Size, and Optimization


OMF

Specifies whether to produce generated code.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.--OMF--"code"----------------------><
   +-/-+

Parameters:

code
OBJ, that is, produce a .obj file

Properties:

Default: | OMF"OBJ"
Phase: | Generate
$SET: | No

Comments:

You should use the OBJ directive in preference to this directive.

Parent topic: Object Code - Object File Format
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.
  • HOSTSIGNS
    Allows arithmetic and moves with COMP-3 items with illegal sign nibbles (such as those produced by a redefinition of the item) to produce the desired result.
  • 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: | NOFASTINIT
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


HOSTSIGNS

Allows arithmetic and moves with COMP-3 items with illegal sign nibbles (such as those produced by a redefinition of the item) to produce the desired result.
Note: This directive is supported for native COBOL only.
Note:

This directive is deprecated and may be removed in a future product. Use the checker options SIGN-FIXUP, HOST-NUMMOVE, and HOST-NUMCOMPARE instead.

Syntax:

>>-.---.-.----.---HOSTSIGNS------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOHOSTSIGNS
Phase: | Generate
$SET: | Initial

Comments:

Specifying HOSTSIGNS causes COMP-3 arithmetic to be performed by a non-optimized route, reducing the efficiency of your programs.

For smaller, faster code you should not specify HOSTSIGNS.

Parent topic: Object Code - Size and Speed
Parent topic: Compiler Directives - Alphabetical List


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.

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

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: | NORECURSECHECK
Phase: | Generate
$SET: | Initial
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"(Dialect)
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.
  • 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 on 64-bit development systems. NOFCD3 on 32-bit development systems
Phase: | Syntax check
$SET: | No

Dependencies:

Set to FCD3 immediately by the Compiler directive P64.

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.
  • CONVERTRET
    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.
  • 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.
  • 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
    Specifies the default parameter passing type for methods.
  • NATIVE
    Specifies the default collating sequence for comparisons.
  • NLS
    Enables the National Locale Support facility.
  • 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
    Affects the operation of comparisons between integer numeric data items of USAGE DISPLAY and alphanumeric literals or figurative constants.
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" (Dialect)
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.

With CHARSET"EBCDIC" set, if you want the application to run on a machine where only COBOL Server is installed, you must link in the object associated with your codepage (by default cs0437.obj).

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Run-time Behavior - General
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 ANSI, ISO2002, COBOL370, ENTCOBOL, MVS, OS390, OSVS, VSC2 .

Properties:

Default: | CHECKDIV"ANSI" (Dialect)
Phase: | Syntax check
$SET: | Initial

Comments:

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.

Setting NOCHECKDIV results in optimal code for divides.

This directive has no effect on arithmetic statements that use the ON SIZE ERROR phrase.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Run-time Behavior - General
Key to Compiler Directives


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


CONVERTRET

Causes COMP and COMP-X items specified in CALL ... RETURNING and EXIT PROGRAM ... RETURNING phrases to be converted to COMP-5.
Note: This directive has been deprecated. It is provided for backward compatibility only and may be removed in later releases.

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 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.
Note: This directive is supported for native COBOL only.

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(Dialect)
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 ASCII code of the character, in decimal.

Properties:

Default: | DEFAULTBYTE"32" (Dialect)
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".

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Run-time Behavior - General
MS
IBM-MS
PC1
CHARSET
Language Fundamentals


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

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


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 (Dialect)
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 (Dialect)
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"------------.><
   +-/-+  +----+--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.

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.

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


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.

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

Specifies the default parameter passing type for methods.

Syntax:

>>-.---.-.----.--METHODDEFAULT--"pass-type"------><
   +-/-+

Parameters:

pass-type
REFERENCE
By default parameters are by reference.
VALUE
By default parameters are by value.

Properties:

Default: | METHODDEFAULT(REFERENCE)
Phase: | Check
$SET: | Initial
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related information
Key to Compiler Directives


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


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 which 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 compile with OUTDD and are producing an executable, you need to link in outddfh.obj.

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 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 (Dialect)
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
Run-time Behavior - General
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 (Dialect)
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
Run-time Behavior - General
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 (Dialect)
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

Affects the operation of comparisons between integer numeric data items of USAGE DISPLAY and alphanumeric literals or figurative constants.

Syntax:

 >>-.---.-.----.--ZWB-----------------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOZWB
Phase: | Syntax check
$SET: | Any

Comments:

The ZWB directive affects the range of comparisons that HOST-NUMCOMPARE"1" applies to. With ZWB on, only unsigned comparisons are affected. Otherwise, all comparisons are affected.

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.
  • 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.
TRUNC20
Truncate the number of digits to the right of the decimal point to 20 at each step of the evaluation of the expression. This provides similar results to the truncation provided in COBOL Workbench. You should only use this directive if you need to obtain evaluation results similar to those provided in COBOL Workbench.
If you specify TRUNC20, you must not change the setting of the INTLEVEL Compiler directive from its default value of 2. This means that you cannot use some of the newer features, such as numeric pictures with more than 18 total digits, with the TRUNC20 parameter.
VSC2
Truncate according to the rules of VS COBOL II and COBOL/370.

Properties:

Default: | ARITHMETIC"MF" (Dialect)
Phase: | Syntax check
$SET: | No
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
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.

Syntax:

>>-.---.--COMP-6--"integer"----------------><
   +-/-+

Parameters:

integer
Must be 1 or 2.
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.

Properties:

Default: | COMP-6"2"
Phase: | Syntax check
$SET: | Initial

Dependencies:

ADDRSV"COMP-6" must be set.

Comments:

The binary format used when you set COMP-6"1" is as described in the chapter Ryan McFarland COBOL V2.0 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.

Parent topic: Run-time Behavior - Arithmetic
Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
Compiler Directives - Alphabetical List
Key to Compiler Directives
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" (Dialect) (Dialect)
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to TRUNC"ANSI" immediately by NORM.

Set to NOTRUNC immediately by RM or RM"ANSI".

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 compatibility with mainframe-style pointers.
  • APOST
    Makes the Compiler interpret the figurative constant QUOTE as the single-quote character (').
  • BYTE-MODE-MOVE
    Controls behavior for alphanumeric moves between overlapping data items.
  • COMP5-BYTE-ORDER
    Specifies the byte ordering to be used for COMP-5 data.
  • 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 between integer numeric data items of USAGE DISPLAY and alphanumeric literals, figurative constants, or numeric operands.
  • 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
    Determines whether report files are written using WRITE AFTER ADVANCING for better mainframe emulation when the MAINFRAMEPRINT=ON option is set.
  • IBMCOMP
    Turns on word-storage mode.
  • 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.
  • OLDCOPY
    Makes COPY statements follow the ANSI'68 standard.
  • PERFORM-TYPE
    Specifies the behavior of return jumps from nested PERFORM statements.
  • QUOTE
    Makes the Compiler interpret the figurative constant QUOTE as the double-quote character (").
  • 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 compatibility with mainframe-style pointers.
Note: This directive is supported for native COBOL only.

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:

The AMODE directive must be used with any program module which:

  • Must create mainframe-style pointer items (using SET pointer-item TO ADDRESS OF data-item syntax)
  • Uses mainframe-style pointer items (using SET ADDRESS OF linkage-item TO pointer-item syntax)
  • Contains a working-storage item that will be passed to a subprogram that creates a mainframe-style pointer item to point to that working-storage item

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


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: Run-time Behavior - 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


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


COMP5-BYTE-ORDER

Specifies the byte ordering to be used for COMP-5 data.

Syntax:

>>-.--------.-COMP5-BYTE-ORDER-.--"ordering"----><
   +-/-+    +--COMP5BYTEORDER--+

Parameters:

ordering
One of:
NATIVE
The byte ordering of COMP-5 data items varies depending on the platform on which they are compiled.
PORTABLE
The byte ordering of COMP-5 data items is always the same as the byte ordering used on the mainframe.

Properties:

Default: | COMP5-BYTE-ORDER"NATIVE"
Phase: | Syntax check
$SET: | Initial

Comments:

You must not set COMP5-BYTE-ORDER"PORTABLE" if you are compiling SQL programs.

You might need to set COMP5-BYTE-ORDER"PORTABLE" if you are compiling mainframe CICS programs.

COMP-5 data is only available for use with the following dialects:

  • BS2000
  • BS2000-OFFLOAD
  • ENTCOBOL
  • MF
  • OS390

Setting COMP5-BYTE-ORDER for any other dialect has no effect.

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

Syntax:

 >>-.---.-.---FP-ROUNDING--"dialect"----.--------><
    +-/-+ +-NOFP-ROUNDING---------------+

Parameters:

dialect COB370, ISO2002, ENTCOBOL, MVS, OS390, OSVS or VSC2 .

Properties:

Default: | NOFP-ROUNDING (Dialect)
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"COB370" 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"COB370" 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
Run-time Behavior - Mainframe Compatibility
Key to Compiler Directives


HOST-NUMCOMPARE

Controls the operation of comparisons between integer numeric data items of USAGE DISPLAY and alphanumeric literals, figurative constants, or numeric operands.
Note: This directive is supported for native COBOL only.
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 numeric data items or numeric literals.

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.

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.
Note: This directive is supported for native COBOL only.

Syntax:

>>--.---.--.----.--HOST-NUMMOVE------><
    +-/-+  +-NO-+

Parameters:

None

Properties:

Default: | NOHOST-NUMMOVE
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-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.

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

Determines whether report files are written using WRITE AFTER ADVANCING for better mainframe emulation when the MAINFRAMEPRINT=ON option is set.

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 (Dialect)
Phase: | Syntax check
$SET: | Initial

Dependencies:

IBMCOMP sets ALIGN"8" 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


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(Dialect)
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
Run-time Behavior - Mainframe Compatibility
Key to Compiler Directives


OLDCOPY

Makes COPY statements follow the ANSI'68 standard.

Syntax:

 >>-.---.-.----.--OLDCOPY-------------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOOLDCOPYDialect)
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


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.
COB370, 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"COB370" 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:

PERFORM-TYPE"OSVS" sets TRICKLE at end.

Comments:

Note: PERFORM-TYPE "OSVS", PERFORM-TYPE "VSC2" and PERFORM-TYPE "COB370" are supported in native COBOL only.
Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
STICKY-PERFORM
Run-time Behavior - Compatibility with Other COBOL Dialects
Key to Compiler Directives


QUOTE

Makes the Compiler interpret the figurative constant QUOTE as the double-quote character (").

Syntax:

>>-.---.--QUOTE----------------------------><
   +-/-+

Parameters:

None

Properties:

Default: | QUOTE (Dialect)
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: Run-time Behavior - Mainframe Compatibility
Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List


REMAINDER

Enables you to select how the remainder is calculated in a DIVIDE statement.

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. All current IBM mainframe compilers use this non-standard algorithm.

Properties:

Default: | REMAINDER"1" (Dialect)
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


SIGN-FIXUP

Provides limited emulation of mainframe compiler options NUMPROC(NOPFD) and NUMPROC(PFD) for MOVE and COMPARE statements.
Note: This directive is supported for native COBOL only.
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.

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" (Dialect)
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 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.
  • 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
    Facilitates 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 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
    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.

Syntax:

>>-.---.-.----.--COMP----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOCOMP
Phase: | Syntax check
$SET: | Initial

Comments:

This COMP code produced by the Compiler behaves in a way that is not the ANSI standard in cases of numeric overflow. 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.

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" (Dialect)
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 (Dialect)
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 subscripts.

Syntax:

>>-.---.-.----.--OLDINDEX------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOOLDINDEX (Dialect)
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to NOOLDINDEX immediately by NORM. Set to OLDINDEX immediately by RM and RM"ANSI".

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

Causes space characters in numeric data items of USAGE DISPLAY to be treated as zeros.
Note:
  • This directive has been deprecated; it is provided for backward compatibility only. You should instead use SIGN-FIXUP.
  • This directive can adversely affect the performance of generated code.
  • The .NET Framework does not support SPZERO or SIGN-FIXUP.

Syntax:

>>-.---.-.----.--SPZERO--------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOSPZERO (Dialect)
Phase: | Both
$SET: | Any

Comments:

With NOSPZERO, space characters in numeric data items give unpredictable results.

Parent topic: Run-time Behavior - Compatibility with Older Micro Focus Products
Parent topic: Compiler Directives - Alphabetical List


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.
  • COMP-6
    Specifies whether COMP-6 data is to be held in binary or packed decimal format.
  • 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 runtime encoding.
  • SIGN
    Specifies which convention numeric DISPLAY items with included signs should use.
  • 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" (Dialect)
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
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


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-SEARCH-PATH 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".

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

Parameters:

None

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

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

Comments:

With DBSPACE, 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").

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

Syntax:

>>--.---.----RUNTIME-ENCODING--"encoding"-.-><

Parameters:

encoding
Possible values are:
ANSI
OEM
UTF-8

Properties:

Default: | OEM
Phase: | Syntax check
$SET | Initial

Dependencies:

If this directive is not specified, the runtime encoding is determined by the SOURCE-ENCODING directive. In this case, if the source encoding is any of the possible UTF variants, the runtime 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 which convention numeric DISPLAY items with included signs should use.

Syntax:

>>-.---.--SIGN--"convention"---------------><
   +-/-+

Parameters:

convention The sign storage convention. Must be one of
  • ASCII
  • MF (identical to ASCII)
  • EBCDIC
  • IBM (identical to EBCDIC)
  • acu
  • mbp
  • ncr
  • realia
  • vax

Properties:

Default: | SIGN"ASCII"
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to SIGN"ASCII" immediately by CHARSET"ASCII".

Set to SIGN"EBCDIC" at end by CHARSET"EBCDIC".

Comments:

If you specify CHARSET"ASCII" and SIGN"EBCDIC", and either HOSTNUMMOVE or HOSTNUMCOMPARE are already on, SIGN"EBCDIC" is ignored.

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

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.

Properties:

Default: | NOSSRANGE
Phase: | Syntax check
$SET: | Initial

Dependencies:

Sets BOUND immediately

Comments:

If you set SSRANGE without an integer, the behavior is the same as SSRANGE(2).

Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List
Related information
BOUND
Run-time Behavior - Compatibility with Other COBOL Dialects
Key to Compiler Directives


STICKY-PERFORM

Specifies the behavior of PERFORM statements when a program is reentered.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--STICKY-PERFORM------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOSTICKY-PERFORM (Dialect)
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" (Dialect)
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.
  • 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"-----------------><
   +-/-+

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.

Properties:

Default: | ALIGN"8" (Dialect)
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to ALIGN"8" immediately by IBMCOMPor NORM. Set to ALIGN"2" immediately by RM or RM"ANSI".

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.

Setting integer to a number that is not a multiple of four could impair the efficiency of the generated code.

Parent topic: Run-time Behavior - Speed or Size
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Run-time Behavior - Speed or Size
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 (Dialect)
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 concepts
Table Bound Checking
Related information
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 concepts
Table Bound Checking


CHECKREFMOD

Turns on bounds checking for reference modification.

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 reference
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"-----------------><
   +-/-+ +-NO-+

Parameters:

type 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.
IDE equivalent | Specifies how to apply the directive using the IDE
Assembly Manifest Attribute | Defines the attribute that is set in the assembly manifest
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 ACU COBOL.
  • ACUOPT
    Enables you to set various options specifically for compilation of ACU COBOL applications.
  • ACUSYNC
    Changes the effect of the SYNC clause so that it matches that used in ACU programs.
  • 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 compatibility with 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.
  • ARITHMETIC
    Specifies how arithmetic expressions are to be evaluated.
  • ASM
    Causes the generator to create a .grp file containing an assembly listing of the native code produced.
  • ASMHEX
    Makes the compiler include machine code byte values in the assembler listing.
  • 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 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
    Makes the Compiler 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.
  • CALLMCS
    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.
  • 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.
  • 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.
  • COMP
    Makes the Compiler produce very compact and efficient code for some statements involving COMP data items, by treating COMP items as COMP-X.
  • COMP5-BYTE-ORDER
    Specifies the byte ordering to be used for COMP-5 data.
  • 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.
  • COMS85
    Allows your program to contain syntax introduced in the Communications Module of the ANSI'85 COBOL Standard.
  • CONFIRM
    Makes the Compiler echo all subsequent directives to the screen.
  • CONSTANT
    Declares a constant for use in the program.
  • CONVERTRET
    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.
  • DOSVS
    Specifies that words reserved in IBM DOS/VS COBOL are to be treated as reserved words.
  • DOTNET
    Sets the reserved words needed for the .NET COBOL language.
  • DPC-IN-SUBSCRIPT
    Turns on or off DECIMAL-POINT IS COMMA when processing subscripts.
  • DYNAM
    Specifies that CANCEL statements are not to be ignored.
  • 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..
  • 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
    Makes the Compiler ask, each time it gives an error message, whether you want to stop compiling.
  • 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.
  • FAULTFIND
    Enables file input and output to be logged by FaultFinder.
  • 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
    Makes the Compiler ask, each time it gives a flagging message, whether you want to stop compiling.
  • 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.
  • HIDE-MESSAGE
    Registers the number of a syntax check 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 between integer numeric data items of USAGE DISPLAY and alphanumeric literals, figurative constants, or numeric operands.
  • 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
    Determines whether report files are written using WRITE AFTER ADVANCING for better mainframe emulation when the MAINFRAMEPRINT=ON option is set.
  • HOSTSIGNS
    Allows arithmetic and moves with COMP-3 items with illegal sign nibbles (such as those produced by a redefinition of the item) to produce the desired result.
  • 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 indexed files.
  • IDYSRCPATH
    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.
  • 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.
  • 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 functionality. Supported for backward compatibility only.
  • ILOUTPUT
    Sets the path of the output assembly file or Java class file.
  • ILPINVOKE
    Makes the specified unmanaged code available, so that the entry points in the unmanaged code are available to the program being compiled. See the Visual Studio Help topic Calling Native Functions from Managed Code.
  • 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 makes the Visual Studio Framework classes in the specified assembly available to the program being compiled.
  • ILRESOURCE
    Specifies a resource file to embed in the assembly file when it is culture neutral.
  • ILSMARTLINKAGE
    Exposes the linkage section and entry points 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.
  • 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.
  • ILSTATIC
    Exposes the entry points of a COBOL program as static methods for compatibility with previous releases.
  • ILSUBSYSTEM
    Specifies the subsystem directive to the MSIL Assembler (ilasm.exe). See the Visual Studio Help topic 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
    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.
  • 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.
  • 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).
  • 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.
  • 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
    Specifies the default parameter passing type for methods.
  • MF, MFLEVEL
    Facilitates 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.
  • 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.
  • 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.
  • NSYMBOL
    Defines the default USAGE for PIC N clauses and controls the interpretation of national literals.
  • 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 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
  • OMF
    Specifies whether to produce generated code.
  • 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
    Compiles a program for execution in a 64-bit run-time environment.
  • 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 as well as to show all data passed to the Compiler by a preprocessor.
  • 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
    Makes the Compiler ask, each time it is unable to find a copybook, what it should do.
  • 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.
  • 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 Ryan-McFarland COBOL V2.0 are to be regarded as reserved words, and changes the behavior of certain features to be compatible with that COBOL system.
  • RTNCODE-SIZE
    Specifies the size of the RETURN-CODE special register and its alignment in memory.
  • RUNTIME-ENCODING
    Determines the runtime 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 which convention numeric DISPLAY items with included signs should use.
  • 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
    Selects free, fixed, variable, or terminal format for COBOL source.
  • SOURCETABSTOP
    Sets the number of space characters by which to expand tab characters in the source code when it is parsed by the checker.
  • SPZERO
    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
    Tells the Compiler that the program contains legal but unstructured perform-ranges, and that certain optimizations cannot, therefore, be made.
  • 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.
  • 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
    Affects the operation of comparisons between integer numeric data items of USAGE DISPLAY and alphanumeric literals or figurative constants.
Parent topic: Compiler Directives


Environment Variables

These are the most common environment variables that can be used with the Micro Focus products.

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 the locations in which to search for data files.
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 .
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.
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 | Used to override the default configuration filename a Fileshare V2 client program user.
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.
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.
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
To use test coverage from the command line for native COBOL


Error Messages

  • Syntax Checking Error Messages
  • Code Generation Error Messages
  • Run-time System Error Messages
  • COBOL Preprocessor Error Messages
  • Explanation of Error Codes
Parent topic: General Reference


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 COBCH400
  • 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 COBCH2000 and above
Parent topic: Error Messages


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

Check the operands allowed for this syntax (click Related Topics).

Parent topic: COBCH0001 - COBCH0020


COBCH0015 Procedure Division too large

Your program's Procedure Division exceeds the maximum size allowed.

Resolution:

Redesign your program as a set of smaller independent programs that call one another.

Parent topic: COBCH0001 - COBCH0020


COBCH0016 Data space too large

Your program's Data Division exceeds the maximum size allowed.

Resolution:

Redesign your program as a set of independent programs with smaller Data Divisions.

Parent topic: COBCH0001 - COBCH0020


COBCH0017 Incorrect use of reserved word word

Parent topic: COBCH0001 - COBCH0020


COBCH0018 Preprocessor error on initialization

An integrated preprocessor invoked by the COBOL system detected an error during its initialization and was unable to continue.

Resolution:

If the preprocessor displayed any further information correct the problem and resubmit the command

Parent topic: COBCH0001 - COBCH0020


COBCH0019 BASIS line number sequencing error

You have made an error in the sequence of line numbers in one of the statements that implement the BASIS mechanism. For example, the statement DELETE 100-60 is incorrect. (BASIS requires numeric sequence values.)

Resolution:

Correct the sequence error.

Parent topic: COBCH0001 - COBCH0020


COBCH0020 Numeric literal expected

You must specify a numeric literal in this context.

Resolution:

Ensure that your numeric literal complies with the syntax rules.

Parent topic: COBCH0001 - COBCH0020


COBCH0021 - COBCH0040

Lists the Syntax Checking error messages from COBCH0021 through COBCH0040.

  • COBCH0021 Too many qualifiers
    You have used too many qualifiers when referring to a qualified data-name, procedure-name or text-name.
  • COBCH0022 SKIP1/2/3, EJECT and TITLE must be alone on line
    Source program lines containing these words must not contain any other words.
  • COBCH0023 Nonnumeric literal expected
    You must specify a nonnumeric literal in this context.
  • COBCH0024 Illegal qualifier
    You have specified a qualified data-name, procedure-name, or text-name incorrectly.
  • COBCH0025 Qualification not permitted
    You cannot qualify a data-name, procedure-name, or text-name in this context.
  • COBCH0026 Literal too long
    The literal value you have specified is longer than the maximum literal length permitted.
  • COBCH0027 Number too large
    You have declared a numeric value that is too large.
  • COBCH0028 Data item too long
    You have declared a data item that is too long for the specified data-type.
  • COBCH0029 Not a data-name
    You have specified an operand that is not a data item where a valid data item is expected. For example, you might have specified an FD-name or a condition-name instead of a data-name.
  • COBCH0030 Should be a group
    You have specified an elementary item as the sending or receiving field in a MOVE CORRESPONDING statement.
  • COBCH0031 Should be elementary
    You have specified the name of a group data item in a context in which an elementary item must be used.
  • COBCH0032 Should be unitary
    You have specified a subscripted or indexed data item where one is not allowed.
  • COBCH0033 Should be procedure name
    A procedure-name (that is, a paragraph or section-name) is expected in this context. You have probably specified a data-name.
  • COBCH0034 Operand operand should be numeric
    A numeric value is required in this context, and you have specified a nonnumeric value.
  • COBCH0035 Integer required
    An integer value is required in this context, and you have specified a noninteger value.
  • COBCH0036 Should be alphanumeric
    An alphanumeric value is required in this context, and you have specified a numeric value.
  • COBCH0037 Should have USAGE DISPLAY
    The data item should have USAGE DISPLAY.
  • COBCH0038 Paragraph or phrase repeated illegally
    You have specified a paragraph or phrase more than once, when you might specify it only once.
  • COBCH0039 Too many COPY ... REPLACING statements
    The program contains more than 255 COPY...REPLACING statements.
  • COBCH0040 Missing or illegal file name
    The filename you have specified either does not conform to COBOL rules for filenames, or has not been declared in the FILE-CONTROL paragraph. This might be due to a misspelled valid filename.
Parent topic: Messages COBCH0001 to COBCH0100


COBCH0021 Too many qualifiers

You have used too many qualifiers when referring to a qualified data-name, procedure-name or text-name.

Resolution:

Change the reference in error so that it uses no more than the permitted number of qualifiers.

Parent topic: COBCH0021 - COBCH0040


COBCH0022 SKIP1/2/3, EJECT and TITLE must be alone on line

Source program lines containing these words must not contain any other words.

Resolution:

Edit your program so that these words are on a line of their own.

Parent topic: COBCH0021 - COBCH0040


COBCH0023 Nonnumeric literal expected

You must specify a nonnumeric literal in this context.

Resolution:

Ensure that the literal you have specified conforms to the rules for nonnumeric literals.

Parent topic: COBCH0021 - COBCH0040


COBCH0024 Illegal qualifier

You have specified a qualified data-name, procedure-name, or text-name incorrectly.

Resolution:

Correct the qualified reference.

Parent topic: COBCH0021 - COBCH0040


COBCH0025 Qualification not permitted

You cannot qualify a data-name, procedure-name, or text-name in this context.

Resolution:

Make the reference an unqualified reference.

Parent topic: COBCH0021 - COBCH0040


COBCH0026 Literal too long

The literal value you have specified is longer than the maximum literal length permitted.

Resolution:

If your literal is numeric, it can be up to 18 digits in length (or up to 38 digits if you specify INTLEVEL"4"). If it is nonnumeric, it can contain up to 160 characters in the Procedure Division, or 2048 characters in the Data Division. Ensure that the literal value you have specified in your program is not longer than the maximum length permitted.

Parent topic: COBCH0021 - COBCH0040


COBCH0027 Number too large

You have declared a numeric value that is too large.

Resolution:

Click Related Topics for information on the maximum value.

Parent topic: COBCH0021 - COBCH0040


COBCH0028 Data item too long

You have declared a data item that is too long for the specified data-type.

Resolution:

Click Related Topics for information on the maximum sizes of data items of various types.

Parent topic: COBCH0021 - COBCH0040


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

Click Related Topics for information on the correct length of the operand.

Parent topic: COBCH0041 - COBCH0060


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


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:

Click Related Topics for details of the operations you can perform on pointer items.

Parent topic: COBCH0041 - COBCH0060


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:

Click 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


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 Cannot have COPY REPLACING within REPLACE or vice versa
    You cannot specify text replacement when text replacement is already active.
  • 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 Cannot have COPY REPLACING within REPLACE or vice versa

You cannot specify text replacement when text replacement is already active.

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:

Click Related Topics for the valid structure of a nested program.

Parent topic: COBCH0061 - COBCH0080


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
    Related Topics
  • 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

Related Topics

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
    Related Topics
  • 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

Related Topics

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:

Click Related Topics for information on the use of the ACCESS MODE clause.

Parent topic: COBCH0121 - COBCH0140


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:

Click Related Topics for more information.

Parent topic: COBCH0121 - COBCH0140


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

Parent topic: COBCH0161 - COBCH0180


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
    Related Topics
  • 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

Related Topics

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 more than 18 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 more than 18 numeric positions

A PICTURE string defined in a PICTURE clause in your Data Division exceeds the maximum permitted by your COBOL system.

Resolution:

Numeric data items can be up to 18 characters in length, numeric edited up to 512 characters and alphanumeric up to 256 Mb.

Parent topic: COBCH0201 - COBCH0220


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:

Click Related Topics for topics giving information on the rules governing the use of the VALUE clause.

Parent topic: COBCH0201 - COBCH0220


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
    Related Topics
  • COBCH0236 Record > maximum size given in FD statement
    Related Topics
  • 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

Related Topics

Parent topic: COBCH0221 - COBCH0240


COBCH0236 Record > maximum size given in FD statement

Related Topics

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
    Related Topics
  • 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

Related Topics

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
    Related Topics
  • COBCH0286 Not specified in CONTROL clause of RD
    Related Topics
  • COBCH0287 Data record specified for Report file
  • COBCH0288 SYNC with USAGE IS INDEX
    Related Topics
  • COBCH0289 SYNC at group level
    Related Topics
  • 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
    Related Topics
  • COBCH0292 SIGN different from that at group level
    Related Topics
  • COBCH0293 SYNC on non-01 level group
    Related Topics
  • 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
    Related Topics
  • COBCH0297 OCCURS .. DEPENDING clause without "integer TO". "1 TO" assumed
    Related Topics
  • 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

Related Topics

Parent topic: COBCH0281 - COBCH0300


COBCH0286 Not specified in CONTROL clause of RD

Related Topics

Parent topic: COBCH0281 - COBCH0300


COBCH0287 Data record specified for Report file

Parent topic: COBCH0281 - COBCH0300


COBCH0288 SYNC with USAGE IS INDEX

Related Topics

Parent topic: COBCH0281 - COBCH0300


COBCH0289 SYNC at group level

Related Topics

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

Related Topics

Parent topic: COBCH0281 - COBCH0300


COBCH0292 SIGN different from that at group level

Related Topics

Parent topic: COBCH0281 - COBCH0300


COBCH0293 SYNC on non-01 level group

Related Topics

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

Related Topics

Parent topic: COBCH0281 - COBCH0300


COBCH0297 OCCURS .. DEPENDING clause without "integer TO". "1 TO" assumed

Related Topics

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 COBCH400

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


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:

Click Related Topics for details of the COBOL syntax for complicated arithmetic tasks.

Parent topic: COBCH0301 - COBCH0320


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 COBCH400


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
    Related Topics
  • 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
    Related Topics
  • 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 COBCH400


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

Related Topics

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

Related Topics

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
    Related Topics
  • COBCH0376 Table superordinate to operand is not indexed
  • COBCH0377 SORT table does not support complex OCCURS DEPENDING ON tables
    Related Topics
  • 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
    Related Topics
Parent topic: Messages COBCH0301 to COBCH400


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

Related Topics

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

Related Topics

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

Related Topics

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
    Related Topics
  • COBCH0382 Only one Procedure-name in GO TO ... DEPENDING
    Related Topics
  • 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
    Related Topics
  • COBCH0388 Key is right hand side of condition
  • COBCH0389 EXIT not in separate paragraph
    Related Topics
  • COBCH0390 OPEN EXTEND on non-sequential file
    Related Topics
  • COBCH0391 MF format Accept/Display
    Related Topics
  • COBCH0392 More than two AFTER phrases
    You have included more than the maximum of two AFTER phrases in your program.
  • COBCH0393 Inline PERFORM
    Related Topics
  • COBCH0394 No section header after END DECLARATIVES
    Related Topics
  • COBCH0395 FROM literal
    Related Topics
  • 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 COBCH400


COBCH0381 TALLYING option has ALL etc. distributed over multiple identifiers

Related Topics

Parent topic: COBCH0381 - COBCH0400


COBCH0382 Only one Procedure-name in GO TO ... DEPENDING

Related Topics

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

Related Topics

Parent topic: COBCH0381 - COBCH0400


COBCH0388 Key is right hand side of condition

Parent topic: COBCH0381 - COBCH0400


COBCH0389 EXIT not in separate paragraph

Related Topics

Parent topic: COBCH0381 - COBCH0400


COBCH0390 OPEN EXTEND on non-sequential file

Related Topics

Parent topic: COBCH0381 - COBCH0400


COBCH0391 MF format Accept/Display

Related Topics

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

Related Topics

Parent topic: COBCH0381 - COBCH0400


COBCH0394 No section header after END DECLARATIVES

Related Topics

Parent topic: COBCH0381 - COBCH0400


COBCH0395 FROM literal

Related Topics

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
    Related Topics
  • COBCH0406 Limit exceeded - length of file/copy/library name > limit
  • COBCH0409 Limit exceeded - number of SELECT filenames > limit
    Related Topics
  • COBCH0410 Limit exceeded - number of SAME RECORD AREA clauses > limit
    Related Topics
  • COBCH0411 Limit exceeded - number of MULTIPLE FILE filenames > limit
    Related Topics
  • COBCH0412 Limit exceeded - number of ALTERNATE RECORD KEY clauses in a file > limit
    Related Topics
  • COBCH0413 Limit exceeded - length of RECORD KEY > limit characters
    Related Topics
  • COBCH0414 Limit exceeded - length of Data Division > limit
  • COBCH0415 Limit exceeded - length of Data Section > limit
  • COBCH0419 Limit exceeded - BLOCK size > limit characters
    Related Topics
  • COBCH0420 Limit exceeded - RECORD length > limit characters
    Related Topics
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

Related Topics

Parent topic: COBCH0401 - COBCH0420


COBCH0406 Limit exceeded - length of file/copy/library name > limit

Parent topic: COBCH0401 - COBCH0420


COBCH0409 Limit exceeded - number of SELECT filenames > limit

Related Topics

Parent topic: COBCH0401 - COBCH0420


COBCH0410 Limit exceeded - number of SAME RECORD AREA clauses > limit

Related Topics

Parent topic: COBCH0401 - COBCH0420


COBCH0411 Limit exceeded - number of MULTIPLE FILE filenames > limit

Related Topics

Parent topic: COBCH0401 - COBCH0420


COBCH0412 Limit exceeded - number of ALTERNATE RECORD KEY clauses in a file > limit

Related Topics

Parent topic: COBCH0401 - COBCH0420


COBCH0413 Limit exceeded - length of RECORD KEY > limit characters

Related Topics

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

Related Topics

Parent topic: COBCH0401 - COBCH0420


COBCH0420 Limit exceeded - RECORD length > limit characters

Related Topics

Parent topic: COBCH0401 - COBCH0420


COBCH0421 - COBCH0440

Lists the Syntax Checking error messages from COBCH0421 through COBCH0440.

  • COBCH0421 Limit exceeded - number of FD filenames > limit
    Related Topics
  • COBCH0422 Limit exceeded - number of SD filenames > limit
    Related Topics
  • 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
    Related Topics
  • COBCH0432 Limit exceeded - length of PICTURE replication > limit
    Related Topics
  • 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
    Related Topics
  • COBCH0437 Limit exceeded at limit - length of ASC/DESC KEYs > limit characters
    Related Topics
  • COBCH0438 Limit exceeded - number of INDEXED BY clauses > limit
    Related Topics
  • COBCH0440 Limit exceeded - number of paragraph labels > limit
Parent topic: Messages COBCH0401 to COBCH0500


COBCH0421 Limit exceeded - number of FD filenames > limit

Related Topics

Parent topic: COBCH0421 - COBCH0440


COBCH0422 Limit exceeded - number of SD filenames > limit

Related Topics

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

Related Topics

Parent topic: COBCH0421 - COBCH0440


COBCH0432 Limit exceeded - length of PICTURE replication > limit

Related Topics

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

Related Topics

Parent topic: COBCH0421 - COBCH0440


COBCH0437 Limit exceeded at limit - length of ASC/DESC KEYs > limit characters

Related Topics

Parent topic: COBCH0421 - COBCH0440


COBCH0438 Limit exceeded - number of INDEXED BY clauses > limit

Related Topics

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
    Related Topics
  • COBCH0442 Limit exceeded - OCCURS nesting > limit
    Related Topics
  • COBCH0443 Limit exceeded - number of GO TO DEPENDING ON names > limit
    Related Topics
  • COBCH0444 Limit exceeded - number of IF nesting levels > limit
    Related Topics
  • COBCH0445 Limit exceeded - number of CALL parameters > limit
    Related Topics
  • COBCH0446 Limit exceeded - number of SORT/MERGE input files > limit
    Related Topics
  • COBCH0447 Limit exceeded - number of SORT/MERGE keys > limit
    Related Topics
  • COBCH0448 Limit exceeded - number of conditions in a SEARCH ALL > limit
    Related Topics
  • COBCH0449 Limit exceeded - number of UNSTRING delimiters > limit
  • COBCH0450 Limit exceeded - number of operands in INSPECT TALLYING/REPLACING > limit
    Related Topics
  • COBCH0451 Limit exceeded - length of SORT/MERGE keys > limit characters
    Related Topics
  • COBCH0452 Limit exceeded - number of PROCEDURE DIVISION USING parameters > limit
    Related Topics
  • COBCH0453 Limit exceeded - number of ENTRY USING parameters > limit
    Related Topics
  • COBCH0460 Previous item crosses 64K boundary. Segment checking code produced
Parent topic: Messages COBCH0401 to COBCH0500


COBCH0441 Limit exceeded - number of PERFORMs > limit

Related Topics

Parent topic: COBCH0441 - COBCH0460


COBCH0442 Limit exceeded - OCCURS nesting > limit

Related Topics

Parent topic: COBCH0441 - COBCH0460


COBCH0443 Limit exceeded - number of GO TO DEPENDING ON names > limit

Related Topics

Parent topic: COBCH0441 - COBCH0460


COBCH0444 Limit exceeded - number of IF nesting levels > limit

Related Topics

Parent topic: COBCH0441 - COBCH0460


COBCH0445 Limit exceeded - number of CALL parameters > limit

Related Topics

Parent topic: COBCH0441 - COBCH0460


COBCH0446 Limit exceeded - number of SORT/MERGE input files > limit

Related Topics

Parent topic: COBCH0441 - COBCH0460


COBCH0447 Limit exceeded - number of SORT/MERGE keys > limit

Related Topics

Parent topic: COBCH0441 - COBCH0460


COBCH0448 Limit exceeded - number of conditions in a SEARCH ALL > limit

Related Topics

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

Related Topics

Parent topic: COBCH0441 - COBCH0460


COBCH0451 Limit exceeded - length of SORT/MERGE keys > limit characters

Related Topics

Parent topic: COBCH0441 - COBCH0460


COBCH0452 Limit exceeded - number of PROCEDURE DIVISION USING parameters > limit

Related Topics

Parent topic: COBCH0441 - COBCH0460


COBCH0453 Limit exceeded - number of ENTRY USING parameters > limit

Related Topics

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
  • 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
Parent topic: Messages COBCH0401 to COBCH0500


COBCH0461 Table crosses 64K boundary. Segment checking code produced

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

Parent topic: COBCH0461 - COBCH0480


COBCH0473 SORT key not within the first %1_s bytes of the file record_

Parent topic: COBCH0461 - COBCH0480


COBCH0474 A duplicate "RECORD" clause was found in an "FD" or "SD" entry_

Parent topic: COBCH0461 - COBCH0480


COBCH0475 A FUNCTION cannot be the subject of an INSPECT REPLACING statement

Parent topic: COBCH0461 - COBCH0480


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
    Related Topics
  • COBCH0504 ORGANIZATION clause in SELECT statement of sort file
    Related Topics
  • COBCH0505 VALUE OF clause in SD or CD
    Related Topics
  • 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
    Related Topics
  • COBCH0508 NEXT used in READ of sequential file
    Related Topics
  • COBCH0509 SET operation on non-index data item
    Related Topics
  • COBCH0510 ZEROS or ZEROES in BLANK WHEN clause. Treated as ZERO
    Related Topics
  • 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
    Related Topics
  • COBCH0517 Jump out of inline PERFORM
    Related Topics
  • 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
    Related Topics
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

Related Topics

Parent topic: COBCH0501 - COBCH0520


COBCH0504 ORGANIZATION clause in SELECT statement of sort file

Related Topics

Parent topic: COBCH0501 - COBCH0520


COBCH0505 VALUE OF clause in SD or CD

Related Topics

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

Related Topics

Parent topic: COBCH0501 - COBCH0520


COBCH0508 NEXT used in READ of sequential file

Related Topics

Parent topic: COBCH0501 - COBCH0520


COBCH0509 SET operation on non-index data item

Related Topics

Parent topic: COBCH0501 - COBCH0520


COBCH0510 ZEROS or ZEROES in BLANK WHEN clause. Treated as ZERO

Related Topics

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

Related Topics

Parent topic: COBCH0501 - COBCH0520


COBCH0517 Jump out of inline PERFORM

Related Topics

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

Related Topics

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)
    Related Topics
  • COBCH0522 BY CONTENT literal/LENGTH OF identifier
    Related Topics
  • COBCH0523 Declarative Section without USE statement
    Related Topics
  • COBCH0524 ALPHABET IS ASCII
    Related Topics
  • 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
    Related Topics
  • COBCH0528 Data-name data-name in ASC/DESC key clause is not uniquely identified
    Related Topics
  • 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
    Related Topics
  • COBCH0533 START ... LESS/NOT GREATER THAN ...
    Related Topics
  • COBCH0534 Entry treated as documentary
  • COBCH0535 ALPHABET is EBCDIC
  • COBCH0536 CICS LINKAGE items generated
  • COBCH0537 BASIS mechanism (BASIS, DELETE or INSERT)
    Related Topics
  • COBCH0538 Picture string is continued
    Related Topics
  • 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)

Related Topics

Parent topic: COBCH0521 - COBCH0540


COBCH0522 BY CONTENT literal/LENGTH OF identifier

Related Topics

Parent topic: COBCH0521 - COBCH0540


COBCH0523 Declarative Section without USE statement

Related Topics

Parent topic: COBCH0521 - COBCH0540


COBCH0524 ALPHABET IS ASCII

Related Topics

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

Related Topics

Parent topic: COBCH0521 - COBCH0540


COBCH0528 Data-name data-name in ASC/DESC key clause is not uniquely identified

Related Topics

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

Related Topics

Parent topic: COBCH0521 - COBCH0540


COBCH0533 START ... LESS/NOT GREATER THAN ...

Related Topics

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)

Related Topics

Parent topic: COBCH0521 - COBCH0540


COBCH0538 Picture string is continued

Related Topics

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
    Related Topics
  • COBCH0542 VALUE clause on group COMP
    Related Topics
  • COBCH0543 VALUE clause on variable length group
    Related Topics
  • COBCH0544 VALUE clause with OCCURS or subsidiary to group OCCURS
    Related Topics
  • COBCH0545 ALTERNATE RECORD KEY is not in SAA
    Related Topics
  • 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
    Related Topics
  • COBCH0548 Program is nested
  • COBCH0549 USING identifier must not be a redefinition
    Related Topics
  • 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

Related Topics

Parent topic: COBCH0541 - COBCH0560


COBCH0542 VALUE clause on group COMP

Related Topics

Parent topic: COBCH0541 - COBCH0560


COBCH0543 VALUE clause on variable length group

Related Topics

Parent topic: COBCH0541 - COBCH0560


COBCH0544 VALUE clause with OCCURS or subsidiary to group OCCURS

Related Topics

Parent topic: COBCH0541 - COBCH0560


COBCH0545 ALTERNATE RECORD KEY is not in SAA

Related Topics

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

Related Topics

Parent topic: COBCH0541 - COBCH0560


COBCH0548 Program is nested

Parent topic: COBCH0541 - COBCH0560


COBCH0549 USING identifier must not be a redefinition

Related Topics

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
    Related Topics
  • 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
    Related Topics
  • 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
    Related Topics
  • COBCH0572 INITIALIZE operand does not have fixed location
    Related Topics
  • COBCH0573 More than one REPLACING phrase
    Related Topics
  • COBCH0574 Conditional statement not terminated by its scope-delimiter
    Related Topics
  • 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
    Related Topics
  • COBCH0579 PROGRAM-ID is DBCS name
    Related Topics
  • 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

Related Topics

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

Related Topics

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

Related Topics

Parent topic: COBCH0561 - COBCH0580


COBCH0572 INITIALIZE operand does not have fixed location

Related Topics

Parent topic: COBCH0561 - COBCH0580


COBCH0573 More than one REPLACING phrase

Related Topics

Parent topic: COBCH0561 - COBCH0580


COBCH0574 Conditional statement not terminated by its scope-delimiter

Related Topics

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

Related Topics

Parent topic: COBCH0561 - COBCH0580


COBCH0579 PROGRAM-ID is DBCS name

Related Topics

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
    Related Topics
  • COBCH0582 Redefined item has OCCURS phrase
    Related Topics
  • COBCH0583 EXIT PROGRAM in GLOBAL declarative
    Related Topics
  • COBCH0584 Inline PERFORM statement not terminated by END-PERFORM
    Related Topics
  • 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
    Related Topics
  • COBCH0589 Procedure Division does not finish with complete sentence
    Related Topics
  • COBCH0590 USING/GIVING file does not have ORGANIZATION SEQUENTIAL
    Related Topics
  • COBCH0591 USING/GIVING file has ACCESS RANDOM
    Related Topics
  • COBCH0592 USING/GIVING file has ACCESS DYNAMIC
    Related Topics
  • COBCH0593 Sequence number contains nonnumeric characters
  • COBCH0594 Variable length group is operand of INITIALIZE statement
    Related Topics
  • COBCH0595 SORT file has FILE STATUS clause
    Related Topics
  • COBCH0596 01 level record in Report Section is elementary
  • COBCH0597 Object of SUM clause belongs to different report
    Related Topics
  • COBCH0598 Assignment-name is alphanumeric literal
  • COBCH0599 Literal form of CODE phrase
    Related Topics
  • COBCH0600 Name is implicitly qualified
Parent topic: Messages COBCH0501 to COBCH0600


COBCH0581 END-SEARCH used with NEXT SENTENCE

Related Topics

Parent topic: COBCH0581 - COBCH0600


COBCH0582 Redefined item has OCCURS phrase

Related Topics

Parent topic: COBCH0581 - COBCH0600


COBCH0583 EXIT PROGRAM in GLOBAL declarative

Related Topics

Parent topic: COBCH0581 - COBCH0600


COBCH0584 Inline PERFORM statement not terminated by END-PERFORM

Related Topics

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

Related Topics

Parent topic: COBCH0581 - COBCH0600


COBCH0589 Procedure Division does not finish with complete sentence

Related Topics

Parent topic: COBCH0581 - COBCH0600


COBCH0590 USING/GIVING file does not have ORGANIZATION SEQUENTIAL

Related Topics

Parent topic: COBCH0581 - COBCH0600


COBCH0591 USING/GIVING file has ACCESS RANDOM

Related Topics

Parent topic: COBCH0581 - COBCH0600


COBCH0592 USING/GIVING file has ACCESS DYNAMIC

Related Topics

Parent topic: COBCH0581 - COBCH0600


COBCH0593 Sequence number contains nonnumeric characters

Parent topic: COBCH0581 - COBCH0600


COBCH0594 Variable length group is operand of INITIALIZE statement

Related Topics

Parent topic: COBCH0581 - COBCH0600


COBCH0595 SORT file has FILE STATUS clause

Related Topics

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

Related Topics

Parent topic: COBCH0581 - COBCH0600


COBCH0598 Assignment-name is alphanumeric literal

Parent topic: COBCH0581 - COBCH0600


COBCH0599 Literal form of CODE phrase

Related Topics

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
    Related Topics
  • COBCH0602 Neither LINE nor LINES specified
    Related Topics
  • COBCH0603 SIGN phrase in Report Section
    Related Topics
  • COBCH0604 GLOBAL specified for entry without data-name
    Related Topics
  • COBCH0605 More than one SUM for single item
    Related Topics
  • COBCH0606 Program does not contain Procedure Division
    Related Topics
  • COBCH0607 PROCEDURE DIVISION header missing
    Related Topics
  • 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)
    Related Topics
  • COBCH0610 Quote found with APOST directive (future occurrences not flagged)
  • COBCH0611 Line: line-no Column: column-no
  • COBCH0612 EXIT PROGRAM not in separate paragraph
    Related Topics
  • COBCH0613 Invalid program name
  • COBCH0614 Previous LINE clause specified same number
    Related Topics
  • 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

Related Topics

Parent topic: COBCH0601 - COBCH0620


COBCH0602 Neither LINE nor LINES specified

Related Topics

Parent topic: COBCH0601 - COBCH0620


COBCH0603 SIGN phrase in Report Section

Related Topics

Parent topic: COBCH0601 - COBCH0620


COBCH0604 GLOBAL specified for entry without data-name

Related Topics

Parent topic: COBCH0601 - COBCH0620


COBCH0605 More than one SUM for single item

Related Topics

Parent topic: COBCH0601 - COBCH0620


COBCH0606 Program does not contain Procedure Division

Related Topics

Parent topic: COBCH0601 - COBCH0620


COBCH0607 PROCEDURE DIVISION header missing

Related Topics

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)

Related Topics

Parent topic: COBCH0601 - COBCH0620


COBCH0610 Quote found with APOST directive (future occurrences not flagged)

Parent topic: COBCH0601 - COBCH0620


COBCH0611 Line: line-no Column: column-no

Parent topic: COBCH0601 - COBCH0620


COBCH0612 EXIT PROGRAM not in separate paragraph

Related Topics

Parent topic: COBCH0601 - COBCH0620


COBCH0613 Invalid program name

Parent topic: COBCH0601 - COBCH0620


COBCH0614 Previous LINE clause specified same number

Related Topics

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
    Related Topics
  • 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
    Related Topics
  • COBCH0629 Use of signed or non-integer numeric literal
  • COBCH0630 INTO not legal for this file
    Related Topics
  • COBCH0631 GLOBAL specified in Linkage Section
    Related Topics
  • COBCH0632 A FUNCTION cannot be a receiving item
    Related Topics
  • COBCH0633 REPORT HEADING extends beyond first detail_ NEXT GROUP NEXT PAGE assumed_
  • COBCH0634 Feature not supported in selected dialect
  • COBCH0635 VALUE specified for external floating point data item
    Related Topics
  • COBCH0636 Level 88 defined on external floating point data item
  • COBCH0637 ACCEPT references internal floating point data item
    Related Topics
  • COBCH0638 Floating point data illegal in DIVIDE with REMAINDER clause
    Related Topics
  • COBCH0639 Reserved word OR missing
    Related Topics
  • COBCH0640 Floating point data item used in SEARCH ALL statement
    Related Topics
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

Related Topics

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

Related Topics

Parent topic: COBCH0621 - COBCH0640


COBCH0629 Use of signed or non-integer numeric literal

Parent topic: COBCH0621 - COBCH0640


COBCH0630 INTO not legal for this file

Related Topics

Parent topic: COBCH0621 - COBCH0640


COBCH0631 GLOBAL specified in Linkage Section

Related Topics

Parent topic: COBCH0621 - COBCH0640


COBCH0632 A FUNCTION cannot be a receiving item

Related Topics

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

Parent topic: COBCH0621 - COBCH0640


COBCH0635 VALUE specified for external floating point data item

Related Topics

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

Related Topics

Parent topic: COBCH0621 - COBCH0640


COBCH0638 Floating point data illegal in DIVIDE with REMAINDER clause

Related Topics

Parent topic: COBCH0621 - COBCH0640


COBCH0639 Reserved word OR missing

Related Topics

Parent topic: COBCH0621 - COBCH0640


COBCH0640 Floating point data item used in SEARCH ALL statement

Related Topics

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
    Related Topics
  • 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
    Related Topics
  • 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
    Related Topics
  • 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
    Related Topics
  • COBCH0659 Screen name mandatory at 01 level in Screen Section
    Related Topics
  • 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

Related Topics

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

Related Topics

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

Related Topics

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

Related Topics

Parent topic: COBCH0641 - COBCH0660


COBCH0659 Screen name mandatory at 01 level in Screen Section

Related Topics

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
    Related Topics
  • COBCH0662 Figurative constant or ALL not allowed here
    Related Topics
  • COBCH0663 LENGTH function in non-standard context
    Related Topics
  • 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
    Related Topics
  • COBCH0668 JUSTIFIED specified on edited field
    Related Topics
  • COBCH0669 EVALUATE statement using partial conditional expressions
    Related Topics
  • COBCH0670 Selection object does not correspond to selection subject
  • COBCH0671 PERFORM UNTIL EXIT
    Related Topics
  • COBCH0672 COPY nested in COPY REPLACING
    Related Topics
  • COBCH0673 Incompatible options specified
  • COBCH0674 Subscripting and indexing used for the same identifier
  • COBCH0675 Numeric FUNCTION used as source of MOVE statement
    Related Topics
  • COBCH0676 THEN used instead of THAN
    Related Topics
  • 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
    Related Topics
  • COBCH0680 N" format literal
Parent topic: Messages COBCH0601 to COBCH0700


COBCH0661 Superfluous TO found in MOVE statement. Ignored

Related Topics

Parent topic: COBCH0661 - COBCH0680


COBCH0662 Figurative constant or ALL not allowed here

Related Topics

Parent topic: COBCH0661 - COBCH0680


COBCH0663 LENGTH function in non-standard context

Related Topics

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

Related Topics

Parent topic: COBCH0661 - COBCH0680


COBCH0668 JUSTIFIED specified on edited field

Related Topics

Parent topic: COBCH0661 - COBCH0680


COBCH0669 EVALUATE statement using partial conditional expressions

Related Topics

Parent topic: COBCH0661 - COBCH0680


COBCH0670 Selection object does not correspond to selection subject

Parent topic: COBCH0661 - COBCH0680


COBCH0671 PERFORM UNTIL EXIT

Related Topics

Parent topic: COBCH0661 - COBCH0680


COBCH0672 COPY nested in COPY REPLACING

Related Topics

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

Related Topics

Parent topic: COBCH0661 - COBCH0680


COBCH0676 THEN used instead of THAN

Related Topics

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

Related Topics

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
    Related Topics
  • 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
    Related Topics
  • COBCH0696 Data-name must be specified with TYPEDEF
    Related Topics
  • COBCH0697 Data item is redefinition of KEY, rather than the key itself
    Related Topics
  • COBCH0698 Use of positive literal in AFTER ADVANCING phrase
    Related Topics
  • 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

Related Topics

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

Related Topics

Parent topic: COBCH0681 - COBCH0700


COBCH0696 Data-name must be specified with TYPEDEF

Related Topics

Parent topic: COBCH0681 - COBCH0700


COBCH0697 Data item is redefinition of KEY, rather than the key itself

Related Topics

Parent topic: COBCH0681 - COBCH0700


COBCH0698 Use of positive literal in AFTER ADVANCING phrase

Related Topics

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
    Related Topics
  • COBCH0702 Alphabetic class expanded to include lower-case letters
  • COBCH0703 ON OVERFLOW will execute under more conditions
    Related Topics
  • 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
    Related Topics
  • COBCH0708 PICTURE consists of A's and B's. Treated as alphanumeric-edited
    Related Topics
  • COBCH0709 Order of initialization different for PERFORM... VARYING.. . AFTER
    Related Topics
  • 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
    Related Topics
  • COBCH0714 Non-space characters following "." are ignored
  • COBCH0715 EXIT not followed by "."
    Related Topics
  • COBCH0716 EXIT PROGRAM not followed by "."
    Related Topics
  • 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
    Related Topics
  • COBCH0720 SEQUENTIAL file used as CALL parameter
    Related Topics
Parent topic: Messages COBCH0701 to COBCH0800


COBCH0701 Alphabet-name must be preceded by ALPHABET

Related Topics

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

Related Topics

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

Related Topics

Parent topic: COBCH0701 - COBCH0720


COBCH0708 PICTURE consists of A's and B's. Treated as alphanumeric-edited

Related Topics

Parent topic: COBCH0701 - COBCH0720


COBCH0709 Order of initialization different for PERFORM... VARYING.. . AFTER

Related Topics

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

Related Topics

Parent topic: COBCH0701 - COBCH0720


COBCH0714 Non-space characters following "." are ignored

Parent topic: COBCH0701 - COBCH0720


COBCH0715 EXIT not followed by "."

Related Topics

Parent topic: COBCH0701 - COBCH0720


COBCH0716 EXIT PROGRAM not followed by "."

Related Topics

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

Related Topics

Parent topic: COBCH0701 - COBCH0720


COBCH0720 SEQUENTIAL file used as CALL parameter

Related Topics

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
    Related Topics
  • COBCH0746 WHEN OTHER must follow other WHEN phrase
    Related Topics
  • COBCH0747 Object of SUM...UPON phrase is not a detail group for this report
    Related Topics
  • 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
    Related Topics
  • 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
    Related Topics
  • COBCH0755 Special register used with ACCEPT/DISPLAY/EXHIBIT or CALL statement
    Related Topics
  • COBCH0756 TYPEDEF name missing
    Related Topics
  • COBCH0757 POINTER name required
    Related Topics
  • COBCH0758 POINTER item has incorrect type
    Related Topics
  • COBCH0759 Illegal use of logical operator
    Related Topics
  • COBCH0760 INITIALIZE TO VALUE statement
    Related Topics
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

Related Topics

Parent topic: COBCH0741 - COBCH0760


COBCH0746 WHEN OTHER must follow other WHEN phrase

Related Topics

Parent topic: COBCH0741 - COBCH0760


COBCH0747 Object of SUM...UPON phrase is not a detail group for this report

Related Topics

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

Related Topics

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

Related Topics

Parent topic: COBCH0741 - COBCH0760


COBCH0755 Special register used with ACCEPT/DISPLAY/EXHIBIT or CALL statement

Related Topics

Parent topic: COBCH0741 - COBCH0760


COBCH0756 TYPEDEF name missing

Related Topics

Parent topic: COBCH0741 - COBCH0760


COBCH0757 POINTER name required

Related Topics

Parent topic: COBCH0741 - COBCH0760


COBCH0758 POINTER item has incorrect type

Related Topics

Parent topic: COBCH0741 - COBCH0760


COBCH0759 Illegal use of logical operator

Related Topics

Parent topic: COBCH0741 - COBCH0760


COBCH0760 INITIALIZE TO VALUE statement

Related Topics

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
    Related Topics
  • COBCH0774 COBOL word contains 31 characters.
  • COBCH0775 Data item too small - must have at least 4 digits.
  • COBCH0776 Partial word replacement.
  • COBCH0777 Only one word allowed with partial word replacement.
  • COBCH0778 Additional messages suppressed
  • COBCH0779 The intermediate code may not be portable at the intlevel set
Parent topic: Messages COBCH0701 to COBCH0800


COBCH0761 DELIMITED BY SIZE omitted

Parent topic: COBCH0761 - COBCH0780


COBCH0762 Must be a typed pointer

Parent topic: COBCH0761 - COBCH0780


COBCH0763 RETURNING phrase cannot be used on an ENTRY statement

Parent topic: COBCH0761 - COBCH0780


COBCH0764 ENTRY statement in a program with a PROCEDURE DIVISION RETURNING phrase

Parent topic: COBCH0761 - COBCH0780


COBCH0765 Failed to create directory %1_s

Parent topic: COBCH0761 - COBCH0780


COBCH0766 Failed to create class file (%1_s) %2_s_

Parent topic: COBCH0761 - COBCH0780


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

Related Topics

Parent topic: COBCH0761 - COBCH0780


COBCH0774 COBOL word contains 31 characters.

Parent topic: COBCH0761 - COBCH0780


COBCH0775 Data item too small - must have at least 4 digits.

Parent topic: COBCH0761 - COBCH0780


COBCH0776 Partial word replacement.

Parent topic: COBCH0761 - COBCH0780


COBCH0777 Only one word allowed with partial word replacement.

Parent topic: COBCH0761 - COBCH0780


COBCH0778 Additional messages suppressed

Parent topic: COBCH0761 - COBCH0780


COBCH0779 The intermediate code may not be portable at the intlevel set

If you have set INTLEVEL(or it has implicitly been set by language features) to a HIGHER level, it won't be portable if you take it to another platform with an older product that does not support the higher level.

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
  • 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 '%1_s' not found or is not a delegate class
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

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 '%1_s' not found or is not a delegate class

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 too large_ _ 16Mbytes_
  • 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
Related concepts
Checker


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 too large_ _ 16Mbytes_

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

Restriction: This applies to .NET managed 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 '%1_s' 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 '%1_s' is referenced but has no addressability_

Parent topic: COBCH0961 - COBCH0980


COBCH0973 Must specify at least one CATCH or FINALLY clause_

Parent topic: COBCH0961 - COBCH0980


COBCH0974 Inherited class does not have a default constructor_

Parent topic: COBCH0961 - COBCH0980


COBCH0975 An anonymous method can only be used as a parameter to a delegate constructor_

Parent topic: COBCH0961 - COBCH0980


COBCH0976 SET CONTENT syntax cannot be used with jagged arrays_

Parent topic: COBCH0961 - COBCH0980


COBCH0977 Anonymous method signature does not match that of delegate_

Parent topic: COBCH0961 - COBCH0980


COBCH0978 Anonymous method returning item does not match that of delegate_

Parent topic: COBCH0961 - COBCH0980


COBCH0979 Anonymous method parameter must be new item specified with AS clause_

Parent topic: COBCH0961 - COBCH0980


COBCH0980 YIELDING phrase can only be used in the context of an iterator_

Parent topic: COBCH0961 - COBCH0980


COBCH0981 - COBCH1000

Lists the Syntax Checking error messages from COBCH0981 through COBCH1000.

  • COBCH0981 YIELDING phrase must be used in the context of an iterator_
  • COBCH0982 Statement can only be used in the context of an iterator_
  • COBCH0983 Cannot initialize MicroFocus_COBOL_Compiler_dll_
  • COBCH0984 Could not find suitable '%1_s' method_
  • COBCH0985 Attribute class has multiple constructors with equally valid signature
  • COBCH0986 A method invoke cannot be a receiving item
  • COBCH0987 Could not find method '%1_s' with this signature - will generate dynamic call
  • COBCH0988 Operand must be Boolean
  • COBCH0989 GROUP-USAGE must be NATIONAL or BIT
  • COBCH0990 No period following EXEC SQL INCLUDE END-EXEC_ DB2 coprocessor will fail
  • COBCH0991 A readonly field cannot be a receiving item
  • COBCH0992 Program requires setting of INTLEVEL(4)
  • COBCH0993 Number of parameters in CALL (%1_s) different from number in target method (%2_s)
  • COBCH0994 Illegal function argument
  • COBCH0995 Iterator parameters must be passed BY VALUE
  • COBCH0996 A class can only be PUBLIC or INTERNAL
  • COBCH0997 Feature not yet supported when compiling for _NET - statement ignored
  • COBCH0998 Can only be PUBLIC or INTERNAL
  • COBCH0999 PROFILE directive ignored for nested programs
  • COBCH1000 Open fail _ %1_s
Parent topic: Messages COBCH0901 to COBCH1000


COBCH0981 YIELDING phrase must be used in the context of an iterator_

Parent topic: COBCH0981 - COBCH1000


COBCH0982 Statement can only be used in the context of an iterator_

Parent topic: COBCH0981 - COBCH1000


COBCH0983 Cannot initialize MicroFocus_COBOL_Compiler_dll_

Parent topic: COBCH0981 - COBCH1000


COBCH0984 Could not find suitable '%1_s' method_

Parent topic: COBCH0981 - COBCH1000


COBCH0985 Attribute class has multiple constructors with equally valid signature

Parent topic: COBCH0981 - COBCH1000


COBCH0986 A method invoke cannot be a receiving item

Parent topic: COBCH0981 - COBCH1000


COBCH0987 Could not find method '%1_s' with this signature - will generate dynamic call

Parent topic: COBCH0981 - COBCH1000


COBCH0988 Operand must be Boolean

Parent topic: COBCH0981 - COBCH1000


COBCH0989 GROUP-USAGE must be NATIONAL or BIT

Parent topic: COBCH0981 - COBCH1000


COBCH0990 No period following EXEC SQL INCLUDE END-EXEC_ DB2 coprocessor will fail

Parent topic: COBCH0981 - COBCH1000


COBCH0991 A readonly field cannot be a receiving item

Parent topic: COBCH0981 - COBCH1000


COBCH0992 Program requires setting of INTLEVEL(4)

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 31 characters. Word truncated
    The name that you have specified is longer than 31 characters. Your COBOL system treats this as a name consisting of the first 31 characters of your original name.
  • 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 31 characters. Word truncated

The name that you have specified is longer than 31 characters. Your COBOL system treats this as a name consisting of the first 31 characters of your original name.

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
    Related Topics
  • 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
    Related Topics
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

Related Topics

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

Related Topics

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
    Related Topics
  • COBCH1043 PERFORM may be recursive
    Related Topics
  • COBCH1044 Load failure on SLOAD - STRUCT ignored
  • COBCH1045 Capacity of POINTER may be exceeded
    Related Topics
  • 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
    Related Topics
  • COBCH1050 Invalid condition in $IF
    Related Topics
  • 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
    Related Topics
  • 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
    Related Topics
  • COBCH1057 REFERENCE/ CONTENT/ VALUE phrase does not match that specified in prototype
    Related Topics
  • 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
    Related Topics
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

Related Topics

Parent topic: COBCH1041 - COBCH1060


COBCH1043 PERFORM may be recursive

Related Topics

Parent topic: COBCH1041 - COBCH1060


COBCH1044 Load failure on SLOAD - STRUCT ignored

Parent topic: COBCH1041 - COBCH1060


COBCH1045 Capacity of POINTER may be exceeded

Related Topics

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

Related Topics

Parent topic: COBCH1041 - COBCH1060


COBCH1050 Invalid condition in $IF

Related Topics

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

Related Topics

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

Related Topics

Parent topic: COBCH1041 - COBCH1060


COBCH1057 REFERENCE/ CONTENT/ VALUE phrase does not match that specified in prototype

Related Topics

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

Related Topics

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
    Related Topics
  • COBCH1062 Not allowed in EXTERNAL program
    Related Topics
  • COBCH1063 EXTERNAL not allowed with nested, INITIAL or COMMON programs - ignored
    Related Topics
  • COBCH1064 Illegal use of literal
    Related Topics
  • COBCH1065 OO: SELF only allowed in CLASS program
    Related Topics
  • COBCH1066 OO: SUPER not allowed - CLASS has no INHERITING phrase
    Related Topics
  • COBCH1067 OO: RETURNING phrase not allowed in METHOD
    Related Topics
  • 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
    Related Topics
  • COBCH1071 OO: Missing OBJECT-STORAGE SECTION, required for inheritance
    Related Topics
  • COBCH1072 OO: Not allowed in PROGRAM-ID. OBJECT
    Related Topics
  • COBCH1073 LOCAL-STORAGE should be used with PERFORM-TYPE(MF).
    Related Topics
  • COBCH1074 OO: INVOKE data-item not yet supported by OOPS run-time
    Related Topics
  • COBCH1075 Invalid combination of RECORD and RECORDING MODE clauses
    Related Topics
  • 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

Related Topics

Parent topic: COBCH1061 - COBCH1080


COBCH1062 Not allowed in EXTERNAL program

Related Topics

Parent topic: COBCH1061 - COBCH1080


COBCH1063 EXTERNAL not allowed with nested, INITIAL or COMMON programs - ignored

Related Topics

Parent topic: COBCH1061 - COBCH1080


COBCH1064 Illegal use of literal

Related Topics

Parent topic: COBCH1061 - COBCH1080


COBCH1065 OO: SELF only allowed in CLASS program

Related Topics

Parent topic: COBCH1061 - COBCH1080


COBCH1066 OO: SUPER not allowed - CLASS has no INHERITING phrase

Related Topics

Parent topic: COBCH1061 - COBCH1080


COBCH1067 OO: RETURNING phrase not allowed in METHOD

Related Topics

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

Related Topics

Parent topic: COBCH1061 - COBCH1080


COBCH1071 OO: Missing OBJECT-STORAGE SECTION, required for inheritance

Related Topics

Parent topic: COBCH1061 - COBCH1080


COBCH1072 OO: Not allowed in PROGRAM-ID. OBJECT

Related Topics

Parent topic: COBCH1061 - COBCH1080


COBCH1073 LOCAL-STORAGE should be used with PERFORM-TYPE(MF).

Related Topics

Parent topic: COBCH1061 - COBCH1080


COBCH1074 OO: INVOKE data-item not yet supported by OOPS run-time

Related Topics

Parent topic: COBCH1061 - COBCH1080


COBCH1075 Invalid combination of RECORD and RECORDING MODE clauses

Related Topics

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
    Related Topics
  • COBCH1084 OO: Missing OBJECT-STORAGE SECTION, required for class extension
    Related Topics
  • 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

Related Topics

Parent topic: COBCH1081 - COBCH1100


COBCH1084 OO: Missing OBJECT-STORAGE SECTION, required for class extension

Related Topics

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
    Related Topics
  • COBCH1136 No CLOSE statement was found for file
    Related Topics
  • 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
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

Related Topics

Parent topic: COBCH1121 - COBCH1140


COBCH1136 No CLOSE statement was found for file

Related Topics

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


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
    Related Topics
  • COBCH1146 procedure-name lies in more than one PERFORM THRU range
    Related Topics
  • 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
    Related Topics
  • COBCH1157 JUSTIFIED specified on edited field
    Related Topics
  • 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

Related Topics

Parent topic: COBCH1141 - COBCH1160


COBCH1146 procedure-name lies in more than one PERFORM THRU range

Related Topics

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

Related Topics

Parent topic: COBCH1141 - COBCH1160


COBCH1157 JUSTIFIED specified on edited field

Related Topics

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 GNTANLZ(COUNT) to work, recompile with GNTANLZ(TICK)
  • COBCH1165 GIVING option treated as documentary
    Related Topics
  • COBCH1166 BLANK WHEN ZERO phrase ignored
    Related Topics
  • COBCH1167 Use of COMP-5 data type
    Related Topics
  • 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
    Related Topics
  • 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
    Related Topics
  • 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 GNTANLZ(COUNT) to work, recompile with GNTANLZ(TICK)

Parent topic: COBCH1161 - COBCH1180


COBCH1165 GIVING option treated as documentary

Related Topics

Parent topic: COBCH1161 - COBCH1180


COBCH1166 BLANK WHEN ZERO phrase ignored

Related Topics

Parent topic: COBCH1161 - COBCH1180


COBCH1167 Use of COMP-5 data type

Related Topics

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

Related Topics

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

Related Topics

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


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
    Related Topics
  • COBCH1202 Original item is larger than redefinition (size1 > size2)
  • COBCH1203 LABEL clause processed as comment
    Related Topics
  • COBCH1204 BLOCK CONTAINS clause processed as comment
    Related Topics
  • COBCH1205 Previous paragraph or section contains no statements
  • COBCH1206 Procedure Division does not start with a section
    Related Topics
  • COBCH1207 Original item is smaller than redefinition (size1 < size2)
  • COBCH1208 USE clause omitted
    Related Topics
  • COBCH1209 COMP-5 is machine specific format. (Future occurrences not indicated)
    Related Topics
  • COBCH1210 COMP processed as DISPLAY (future occurrences not indicated)
    Related Topics
  • COBCH1211 COMP-6 processed as COMP (future occurrences not indicated)
    Related Topics
  • COBCH1212 COMP-1 processed as PIC S9(4) COMP (future occurrences not indicated)
    Related Topics
  • COBCH1213 COMP-0 field exceeds S9(5), converted to USAGE DISPLAY
    Related Topics
  • COBCH1214 COMP-0 processed as PIC S9(4) COMP (future occurrences not indicated)
    Related Topics
  • COBCH1215 UNIT phrase processed as comment
    Related Topics
  • COBCH1216 Literal exceeds 160 characters
    Related Topics
  • COBCH1217 procedure-name same as level 78 name
  • COBCH1218 RERUN clause processed as comment
    Related Topics
  • COBCH1219 No REPLACE currently in effect
  • COBCH1220 COMP-4 processed as PIC S9(9) COMP (future occurrences not indicated)
    Related Topics
Parent topic: Messages COBCH1201 to COBCH1300


COBCH1201 Zero suppression PICTURE string overrides the BLANK WHEN ZERO clause

Related Topics

Parent topic: COBCH1201 - COBCH1220


COBCH1202 Original item is larger than redefinition (size1 > size2)

Parent topic: COBCH1201 - COBCH1220


COBCH1203 LABEL clause processed as comment

Related Topics

Parent topic: COBCH1201 - COBCH1220


COBCH1204 BLOCK CONTAINS clause processed as comment

Related Topics

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

Related Topics

Parent topic: COBCH1201 - COBCH1220


COBCH1207 Original item is smaller than redefinition (size1 < size2)

Parent topic: COBCH1201 - COBCH1220


COBCH1208 USE clause omitted

Related Topics

Parent topic: COBCH1201 - COBCH1220


COBCH1209 COMP-5 is machine specific format. (Future occurrences not indicated)

Related Topics

Parent topic: COBCH1201 - COBCH1220


COBCH1210 COMP processed as DISPLAY (future occurrences not indicated)

Related Topics

Parent topic: COBCH1201 - COBCH1220


COBCH1211 COMP-6 processed as COMP (future occurrences not indicated)

Related Topics

Parent topic: COBCH1201 - COBCH1220


COBCH1212 COMP-1 processed as PIC S9(4) COMP (future occurrences not indicated)

Related Topics

Parent topic: COBCH1201 - COBCH1220


COBCH1213 COMP-0 field exceeds S9(5), converted to USAGE DISPLAY

Related Topics

Parent topic: COBCH1201 - COBCH1220


COBCH1214 COMP-0 processed as PIC S9(4) COMP (future occurrences not indicated)

Related Topics

Parent topic: COBCH1201 - COBCH1220


COBCH1215 UNIT phrase processed as comment

Related Topics

Parent topic: COBCH1201 - COBCH1220


COBCH1216 Literal exceeds 160 characters

Related Topics

Parent topic: COBCH1201 - COBCH1220


COBCH1217 procedure-name same as level 78 name

Parent topic: COBCH1201 - COBCH1220


COBCH1218 RERUN clause processed as comment

Related Topics

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)

Related Topics

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
    Related Topics
  • COBCH1222 COMP-3 unsigned, converted to signed COMP-3
    Related Topics
  • COBCH1223 BLANK WHEN ZERO clause overrides the zero suppression PICTURE string
    Related Topics
  • 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
    Related Topics
  • 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
    Related Topics
  • COBCH1235 Conflicting definition of level 78 item item
  • COBCH1236 Duplicate, equivalent definition of level 78 item
  • COBCH1237 File handling used with REENTRANT Directive
    Related Topics
  • COBCH1238 Conflict with REENTRANT Directive and user code or other Directives
    Related Topics
Parent topic: Messages COBCH1201 to COBCH1300


COBCH1221 COMP-4 field exceeds S9(10), converted to USAGE DISPLAY

Related Topics

Parent topic: COBCH1221 - COBCH1240


COBCH1222 COMP-3 unsigned, converted to signed COMP-3

Related Topics

Parent topic: COBCH1221 - COBCH1240


COBCH1223 BLANK WHEN ZERO clause overrides the zero suppression PICTURE string

Related Topics

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

Related Topics

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

Related Topics

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

Related Topics

Parent topic: COBCH1221 - COBCH1240


COBCH1238 Conflict with REENTRANT Directive and user code or other Directives

Related Topics

Parent topic: COBCH1221 - COBCH1240


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


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 native arrays
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 native arrays

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


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.
  • COBCH1601 - COBCH1620
    Lists the Syntax Checking error messages from COBCH1601 through COBCH1620.
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 _ %1_s %2_s
  • 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 (20 max)
  • COBCH1520 Error - duplicate file name
Parent topic: Messages COBCH1501 to COBCH1600


COBCH1501 Insufficient memory

Parent topic: COBCH1501 - COBCH1520


COBCH1502 Open fail _ '%1_s'

Parent topic: COBCH1501 - COBCH1520


COBCH1503 Read error_ '%1_s'

Parent topic: COBCH1501 - COBCH1520


COBCH1504 I-O error _ %1_s %2_s

Parent topic: COBCH1501 - COBCH1520


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 (20 max)

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 the JAVA_HOME environment variable is set to the appropriate runtime engine that your application is being compiled for.

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
  • LIBPATH on AIX and HP-UX
Parent topic: COBCH1541 - COBCH1560


COBCH1561 - COBCH1580

Lists the Syntax Checking error messages from COBCH1561 through COBCH1580.

  • COBCH1561 JVM support not found: possibly the type info helper classes were not on the classpath
  • 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


COBCH1561 JVM support not found: possibly the type info helper classes were not on the classpath

Parent topic: COBCH1561 - COBCH1580


COBCH1562 $ statement not recognized

Incorrect syntax has been specified after $ in a declaration statement for a Compiler directive.

Ensure that the statement syntax is as follows, also ensuring that $ appears in column 7:

$set directive-name{options}

For example:

$set sourceformat(free)
Parent topic: COBCH1561 - COBCH1580


COBCH1563 Directive %1$s is deprecated and may be removed in future releases

The specified Compiler directive has been deprecated and no longer has an effect on your source code.

You should plan to remove the directive from your source code.

Parent topic: COBCH1561 - COBCH1580


COBCH1564 First parameter to an extension method must be passed BY VALUE

The first parameter passed to an extension method must be a value parameter, not reference parameter.

To define an extension method:

  • Use the EXTENSION keyword in the method header.
  • The method must be in a static class that is not nested or generic. The method is implicitly static.
  • In the method body, the first parameter is the type to extend. It is always a value parameter.

Example:

The following extension method extends the string class, by adding a method to count the number of words in a string:

       class-id MyCount static.
       method-id CountWords extension. *> extension method is implicitly static
       procedure division using 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


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


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.

To help you diagnose further, use the Assembly Binding Log Viewer (fuslogvw.exe), available as part of the Visual Studio tools.

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 2010, but not with the Visual Studio 2010 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


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.
Parent topic: Messages COBCH1501 to COBCH1600


COBCH1601 Property cannot have parameters

The Procedure Division header within a property-id has parameters specified.

The Procedure Division header in a property-id must not have any parameters.

class-id myClass.
property-id myProp1 string.
procedure division using myField as string. *> this is incorrect
    getter.
    set property-value to "Micro Focus"
end property.

property-id myProp2 string.
procedure division.	*> this is correct
    getter.
    set property-value to "Visual COBOL"
end property.
end class.
Parent topic: COBCH1601 - COBCH1620


COBCH1602 Indexer must have at least one parameter

The Procedure Division header within an indexer-id does not have a parameter specified.

You must specify at least one parameter in the Procedure Division header:

class-id myClass1.
indexer-id string.
procedure division. *> this is incorrect - no parameter specified
    getter.
    set property-value to "abc"
end indexer.
end class.

class-id myClass2.
01 myField string value "abc".
indexer-id string.
procedure division using value myParam as binary-long. *> this is correct
    getter.
    set property-value to a
end indexer.
end class.
Parent topic: COBCH1601 - COBCH1620


COBCH1603 No indexer found for class '%1$s'

An instance of a type that does not contain an indexer is being accessed as an array.

A type must contain an indexer if an instance of that type is being accessed as an array, as shown in the following example:

class-id myClass1.
method-id main.
01 myField type myClass2.
    display myField[0]
end method.
end class.

class-id myClass2.
indexer-id string.		*> add an indexer to resolve the error
procedure division using value myParam as binary-long.
    getter.
    set property-value to myParam
end indexer.
end class.
Parent topic: COBCH1601 - COBCH1620


COBCH1604 Cannot inherit from interface '%1$s'

The interface that you are trying to inherit does exist, but there is a problem with its construction.

For example, the following example fails because the interface that is being inherited is empty.

class-id myClass inherits type myInterface.
...
end class.

interface-id myInterface.
end interface.

Add a method or some other valid construction to the interface to fix the error.

Parent topic: COBCH1601 - COBCH1620


COBCH1605 Entry name '%1$s' reserved for use by Micro Focus

The specified entry point name is reserved for managed COBOL syntax.

You must change the name of your entry point.

Parent topic: COBCH1601 - COBCH1620


COBCH1606 Syntax can only be used with LIST and DICTIONARY items

Certain syntax can only be used on items of type LIST or DICTIONARY.

Some syntax is specifically designed for collection types. To use this syntax, the item must be of LIST or DICTIONARY type.

Parent topic: COBCH1601 - COBCH1620
Related concepts
Structural Syntax Elements


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


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


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
Property Specification - syntax


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
Property Specification - syntax


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
Property Specification - syntax


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: Error Messages


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

Lists all Code Generation error messages, including COBOP001 through 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:
  • 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)
  • 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.
  • 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)
  • COBOP076 Inefficient code produced for this statement (Cautionary)
  • 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


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


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


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


COBOP076 Inefficient code produced for this statement (Cautionary)

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


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.
  • 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: Error Messages
Related reference
Extended File Status Codes


Key to Run-time System Error Messages

These messages are output by the run-time system (RTS), and so can be produced while you are compiling, debugging, or running your program. When you select an error message number, its text and severity is listed, along with an explanation of the error or problem that caused the message, and advice on how to prevent the error.

Run-time system error messages have the following format:

ErrorCode Description

where the parameters are:

ErrorCode A code containing the following information:
  • The component that the error occurred in.
  • The operation that was taking place when the error occurred.
  • The error message number.
For run-time system errors, ErrorCode is generally of the form COBRTnnnn.
Description A description of the cause of the error.

There are two types of run-time error:

Fatal | A message is sent to the screen and the program terminates immediately.
Recoverable | The error is reported to the program. You can trap these errors in your program, but often they are the result of an error in your program's logic. If the program does not trap the error a message is sent to the screen and the program terminates immediately.
Parent topic: Run-time System Error Messages


COBRT001 - COBRT020

Lists the Run-time System error messages from COBRT001 through 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 Attempt to write to a file opened for INPUT (Recoverable)
    You have tried to WRITE to a file that is open for input only.
  • 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 Attempt to write to a file opened for INPUT (Recoverable)

You have tried to WRITE to a file that is open for input only.

Resolution:

Close the file and open it with a mode such as I-O, which allows you to write to 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


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, put a new disk in a floppy disk drive and redirect your program's file operations to this.

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 doesn't exist. If the directory is full, either delete any files that you no longer need or, if your operating system supports this, put a new disk in a floppy disk drive and redirect your program's file operations to it. 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

Lists the Run-time System error messages from COBRT021 through 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

Lists the Run-time System error messages from COBRT041 through COBRT060.

  • COBRT041 Corrupt index file (Recoverable)
    Your run-time system does not recognize the control information for an indexed file and as the index has been corrupted in some way the data in the file is no longer accessible by your system. This error is recoverable in the sense that it can be trapped but should you receive it, you can do little except to close any open files and stop your program's run.
  • COBRT042 Attempt to write on broken pipe (Recoverable)
    One of the following has occurred:
  • COBRT043 File information missing for indexed file (Fatal)
    The most likely reason for this error is that the names of either the data part or the index part of the file are not consistent with the setting of the IDXNAMETYPE FIle Handler configuration option.
  • COBRT044 Attempt to OPEN an NLS file in a non-NLS program (Fatal)
    The logical file-name is preceded by "%NLS%", but the program which OPENS the file has been compiled without the NLS directive set: the OPEN fails.
  • COBRT045 Attempt to OPEN an NLS file using incompatible language definition (Fatal)
    The NLS control information for a file in your program does not match the same NLS control information in the header of your index file. Alternatively, your index file has become corrupted.
  • COBRT047 Indexed structure overflow (Fatal)
    The structure of your indexed file contains a fault. You have probably tried to put another entry in the index when there is no room for it. This may be because you have reached the maximum number of duplicate keys.
  • COBRT048 Attempt to divide by zero (Fatal)
    You are executing a program that is trying to perform a divide by zero.
  • COBRT055 Routine table overflow (Fatal)
    You have tried to load too many programs simultaneously.
Parent topic: Run-time System Error Messages


COBRT041 Corrupt index file (Recoverable)

Your run-time system does not recognize the control information for an indexed file and as the index has been corrupted in some way the data in the file is no longer accessible by your system. This error is recoverable in the sense that it can be trapped but should you receive it, you can do little except to close any open files and stop your program's run.

Resolution:

You should identify the cause of the error. It might be something obvious such as a crash. You can run Rebuild using the /f option to find more about the nature of the corruption.

You should rerun your program using the backup copy of that file. If you have added a great deal of information to the file since you last took a backup you might like to rebuild the file using the Rebuild utility, which reads the data (if this has not been corrupted) and builds a new index for it.

Parent topic: COBRT041 - COBRT060


COBRT042 Attempt to write on broken pipe (Recoverable)

One of the following has occurred:

  • Your program has created a process as a result of a DD_ logical file-name mapping assignment (for example, the process might be a line printer spooler). The process was not created properly, or has ended prematurely. This error occurs when your program tries to write to the process.
  • Your application has terminated abnormally or prematurely, thus breaking the pipe.

Resolution:

You can trap the error status returned by the write operation, then open the file again.

Parent topic: COBRT041 - COBRT060


COBRT043 File information missing for indexed file (Fatal)

The most likely reason for this error is that the names of either the data part or the index part of the file are not consistent with the setting of the IDXNAMETYPE FIle Handler configuration option.

Other possibilities are that you have copied the indexed file from one disk to another but have copied either only the data part of the file or only the index, or that there was a system crash during your program's previous run, while the file was open.

Resolution:

Check that the setting of the IDXNAMETYPE FIle Handler configuration option is consistent with the naming of the index files used on your system.

If the error was the result of a faulty copy you should be able to restore the missing part of the file from the .dat or .idx file.

If the error is the result of a crash then whether you can access the necessary data or not is entirely system dependent.

Parent topic: COBRT041 - COBRT060


COBRT044 Attempt to OPEN an NLS file in a non-NLS program (Fatal)

The logical file-name is preceded by "%NLS%", but the program which OPENS the file has been compiled without the NLS directive set: the OPEN fails.

Parent topic: COBRT041 - COBRT060


COBRT045 Attempt to OPEN an NLS file using incompatible language definition (Fatal)

The NLS control information for a file in your program does not match the same NLS control information in the header of your index file. Alternatively, your index file has become corrupted.

Resolution:

Rebuild your index file, or rerun your program using the backup copy of that file. If you have added a great deal of information since you last took a backup, you might want to rebuild the file using a utility that is able to read the data, if it is not corrupt, and build a new index for it.

Parent topic: COBRT041 - COBRT060


COBRT047 Indexed structure overflow (Fatal)

The structure of your indexed file contains a fault. You have probably tried to put another entry in the index when there is no room for it. This may be because you have reached the maximum number of duplicate keys.

Alternatively, you have tried to access an old format indexed file, created perhaps using CIS COBOL.

Resolution:

If your index has no room for further entries you should either reorganize your file or convert it to IDXFORMAT"4" using Rebuild, to allow a greater number of duplicate keys.

If you have tried to access an old format indexed file, you can run the Rebuild utility to check the consistency of this indexed file, and to construct a new indexed file if the old one was found to be corrupt.

Parent topic: COBRT041 - COBRT060


COBRT048 Attempt to divide by zero (Fatal)

You are executing a program that is trying to perform a divide by zero.

Resolution:

Recode your program so that you can trap the error with an ON SIZE ERROR clause

Parent topic: COBRT041 - COBRT060


COBRT055 Routine table overflow (Fatal)

You have tried to load too many programs simultaneously.

Resolution:

Cancel any programs that you are no longer using, or use fewer separate programs.

Parent topic: COBRT041 - COBRT060


COBRT061 - COBRT080

Lists the Run-time System error messages from COBRT061 through COBRT080.

  • COBRT065 File locked (Recoverable)
    You have tried to open a file which has already been locked, or opened for output by another user. Alternatively, you have tried to lock or open for output a file which another user already has open.
  • COBRT066 Attempt to add duplicate record key to indexed file (Fatal)
    You have tried to add a duplicate key for a key which you have not defined as being able to have duplicates.
  • COBRT067 Indexed file not open (Recoverable)
    You are trying to access an indexed file which you have not opened.
  • COBRT068 Record locked (Recoverable)
    You have tried to access a record which is currently locked by another user.
  • COBRT069 Illegal argument to isam module (Fatal)
    This is the result of an internal system error.
  • COBRT070 Too many indexed files open (Recoverable)
    You are trying to open an indexed file but you have already exhausted the system limit which specifies how many of these files can be opened at any one time.
  • COBRT071 Bad indexed file format (Fatal)
    You are either using a file which has been corrupted, or there is an internal system error.
  • COBRT072 End of indexed file (Fatal)
    This is the result of an internal system error.
  • COBRT073 No record found in indexed file (Fatal)
    This is the result of an internal system error.
  • COBRT074 No current record in indexed file (Fatal)
    This is the result of an internal system error.
  • COBRT075 Indexed data file name too long (Fatal)
    When creating indexed files, the extension .idx is added to the user-defined filename, so your filename must not exceed x-4 characters in length, where x is the maximum length of filename.
  • COBRT076 Can't create lock file in /isam directory (Fatal)
    For some reason your system is unable to create a lock file in the /isam directory. One reason for this could be that in its previous run your program terminated abnormally (perhaps due to a power failure) leaving some files locked.
  • COBRT077 Internal ISAM module error (Fatal)
    This is the result of an internal system error.
  • COBRT078 Illegal key description in indexed file (Fatal)
    This is the result of an internal system error.
  • COBRT079 COBCONFIG syntax error (Fatal)
    An error exists in the run-time configuration file accessed via the environment variable COBCONFIG_.
  • COBRT080 Can't convert to/from Unicode codeset (Fatal)
    You have tried to use the additional language variants but there are no mapping tables to convert to/from one of the codesets.
Parent topic: Run-time System Error Messages


COBRT065 File locked (Recoverable)

You have tried to open a file which has already been locked, or opened for output by another user. Alternatively, you have tried to lock or open for output a file which another user already has open.

Resolution:

Your program can inform the system operator (if there is one) that it is unable to access this file and should wait until the other user has finished using the file and closes it. You should then be able to continue to run your program.

Parent topic: COBRT061 - COBRT080


COBRT066 Attempt to add duplicate record key to indexed file (Fatal)

You have tried to add a duplicate key for a key which you have not defined as being able to have duplicates.

Resolution:

As this error implies that your program logic contains a mistake, you probably should recode.

Parent topic: COBRT061 - COBRT080


COBRT067 Indexed file not open (Recoverable)

You are trying to access an indexed file which you have not opened.

Resolution:

Open the file in the relevant access mode and then retry the unsuccessful file operation.

Parent topic: COBRT061 - COBRT080


COBRT068 Record locked (Recoverable)

You have tried to access a record which is currently locked by another user.

Resolution:

Your program can inform the system operator (if there is one) that the record is currently locked, and you should then wait until the other user has released the lock on that record. You should then be able to access the relevant record. You should not continually retry to gain access to the record without operator intervention, as this could result in your application hanging.

Parent topic: COBRT061 - COBRT080


COBRT069 Illegal argument to isam module (Fatal)

This is the result of an internal system error.

Resolution:

Contact Technical Support who will help you discover the cause of your error and how it can be rectified.

Parent topic: COBRT061 - COBRT080


COBRT070 Too many indexed files open (Recoverable)

You are trying to open an indexed file but you have already exhausted the system limit which specifies how many of these files can be opened at any one time.

Resolution:

Close some of the open indexed files which you are not currently accessing. You should then be able to open the indexed file which you require and to continue the program run.

Parent topic: COBRT061 - COBRT080


COBRT071 Bad indexed file format (Fatal)

You are either using a file which has been corrupted, or there is an internal system error.

Resolution:

If the disk you are using is corrupt, rerun your program using your backup copy of the disk. If this is not the cause of the error then you should contact Technical Support who will help you discover the cause of your error and how it can be rectified.

Parent topic: COBRT061 - COBRT080


COBRT072 End of indexed file (Fatal)

This is the result of an internal system error.

Resolution:

Contact Technical Support who will help you discover the cause of your error and how it can be rectified.

Parent topic: COBRT061 - COBRT080


COBRT073 No record found in indexed file (Fatal)

This is the result of an internal system error.

Resolution:

Contact Technical Support who will help you discover the cause of the error and how it can be rectified.

Parent topic: COBRT061 - COBRT080


COBRT074 No current record in indexed file (Fatal)

This is the result of an internal system error.

Resolution:

Contact Technical Support who will help you discover the cause of the error and how it can be rectified.

Parent topic: COBRT061 - COBRT080


COBRT075 Indexed data file name too long (Fatal)

When creating indexed files, the extension .idx is added to the user-defined filename, so your filename must not exceed x-4 characters in length, where x is the maximum length of filename.

Resolution:

Rename the file with a shorter filename, that is, one that is less than 10 characters in length.

Parent topic: COBRT061 - COBRT080


COBRT076 Can't create lock file in /isam directory (Fatal)

For some reason your system is unable to create a lock file in the /isam directory. One reason for this could be that in its previous run your program terminated abnormally (perhaps due to a power failure) leaving some files locked.

Resolution:

You should manually remove all of the files that are still locked from the /isam directory before you can successfully run your program.

Parent topic: COBRT061 - COBRT080


COBRT077 Internal ISAM module error (Fatal)

This is the result of an internal system error.

Resolution:

Contact Technical Support who will help you discover the cause of your error and how it can be rectified.

Parent topic: COBRT061 - COBRT080


COBRT078 Illegal key description in indexed file (Fatal)

This is the result of an internal system error.

Resolution:

Contact Technical Support who will help you discover the cause of your error and how it can be rectified.

Parent topic: COBRT061 - COBRT080


COBRT079 COBCONFIG syntax error (Fatal)

An error exists in the run-time configuration file accessed via the environment variable COBCONFIG_.

Resolution:

Check the syntax of the entries in the configuration file. You might have used incorrect syntax, or syntax that is not compatible with the type of run-time tunable you are configuring (this could include assigning an illegal value to the tunable).

Parent topic: COBRT061 - COBRT080


COBRT080 Can't convert to/from Unicode codeset (Fatal)

You have tried to use the additional language variants but there are no mapping tables to convert to/from one of the codesets.

Resolution:

Check that the operating system Unicode mapping tables have been installed on your machine. If converting to/from the current locale, ensure that operating system mapping tables exist for the corresponding codeset.

Parent topic: COBRT061 - COBRT080


COBRT101 - COBRT120

Lists the Run-time System error messages from COBRT101 through COBRT120.

  • COBRT081 Key already exists in indexed file (Fatal)
    This is the result of an internal system error.
  • COBRT082 CALL convention not supported (Fatal)
    The CALL convention you have specified is not supported.
  • COBRT086 Remote file system failure (Fatal)
  • COBRT099 Illegal operation in SORT/MERGE module (Fatal)
    A SORT or MERGE module has received a RELEASE operation outside the Input procedure, or a RETURN operation either outside the Output procedure, or before the Input procedure has terminated correctly.
  • COBRT100 Invalid file operation (Fatal)
    You have tried a file operation which violates a general rule of COBOL in some way. The most likely cause of this error is that you have tried a rewrite on a sequential file opened I-O, or on a relative file with access mode sequential also opened I-O, without preceding it with a successful read NEXT.
  • 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


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: COBRT101 - COBRT120


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: COBRT101 - COBRT120


COBRT086 Remote file system failure (Fatal)

Parent topic: COBRT101 - COBRT120


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: COBRT101 - COBRT120


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: COBRT101 - COBRT120


COBRT101 Illegal operation on an indexed file (Fatal)

This is the result of an internal system error.

Resolution:

Contact Technical Support who will help you discover the cause of your error and how it can be rectified.

Parent topic: COBRT101 - COBRT120


COBRT102 Sequential file with non-integral number of records (Fatal)

You have either specified an incorrect record length for a sequential file, or the sequential file you are trying to access is corrupt in some way, or the file which you have specified is not a sequential file.

Resolution:

Recode your program so that it specifies the correct type of file, or if the error is the result of a corrupt file, try to run the program again using a backup copy of that file.

Parent topic: COBRT101 - COBRT120


COBRT103 Parameter cannot be passed BY VALUE (Fatal)

Parent topic: COBRT101 - COBRT120


COBRT104 Null file name used in a file operation (Fatal)

You specified a data-name for a file-name instead of a literal, and the data item contained only spaces when you tried to open the file.

Alternatively, you have attempted to do a CALL dataname in which the dataname has at least one leading space character.

Resolution:

Recode your program specifying the correct file-name.

Ensure the target program name is space terminated.

Parent topic: COBRT101 - COBRT120


COBRT105 Memory allocation error (Fatal)

The run-time system is unable to allocate sufficient memory space to successfully carry out the tried operation, probably because of insufficient memory space on your system.

Resolution:

You should obtain more memory in which to run your program. Refer to your operating system documentation for details of how you can obtain more memory, if this is possible.

Parent topic: COBRT101 - COBRT120


COBRT106 Dictionary error (Fatal)

This could be the result of a read or write error to file or disk, but it is more likely to be the result of an internal system error.

Alternatively, your application might have called many programs without canceling them afterward, so that memory becomes exhausted during animation.

Resolution:

Contact Technical Support who will help you to discover the cause of your error and how it can be rectified.

Ensure that as much memory as possible is available during animation by CANCELing any program you do not currently need to access.

Parent topic: COBRT101 - COBRT120


COBRT107 Operation not implemented in this run-time system (Fatal)

You are trying to perform a file operation which your run-time system does not support.

Resolution:

You should recode your program so that it does not try such operations, or you should acquire a version of your system that does support this facility.

Parent topic: COBRT101 - COBRT120


COBRT108 Failure to initialize data division (Fatal)

The run-time system cannot load your program properly because the data needed to correctly initialize the Data Division has become corrupted.

Resolution:

You should compile your program again to try to obtain good intermediate code.

Parent topic: COBRT101 - COBRT120


COBRT109 Invalid checksum in run-time system (Recoverable)

The internal information in the run-time system has been altered. The run-time system might have become corrupted, or you might have illegally tried to change the internal run-time system information.

The internal information in the run-time system has been altered. The run-time system might have become corrupted, or you might have illegally tried to change the internal run-time system information.

Parent topic: COBRT101 - COBRT120


COBRT110 Generated code not supported by this RTS (Fatal)

Resolution:

Contact Technical Support who will help you to discover the cause of the error and how it can be rectified.

Parent topic: COBRT101 - COBRT120


COBRT111 Incompatible Class Library and Run-Time Environment versions (Fatal)

The version numbers for these components do not match.

Resolution:

Check that you have fully installed both the Class Library and the Run-Time Environment from the same version of your COBOL system. If you have more than one version installed, check that your PATH and COBDIR environment variables specify an appropriate path for the version you are using.

Parent topic: COBRT101 - COBRT120


COBRT112 Unable to locate/access the required security key (Recoverable)

The run-time system cannot locate or cannot access the coded security key (dongle) that is required to execute this application.

Resolution:

Connect the security key that was supplied with your COBOL system to the parallel port of your computer, then re-run the application.

Parent topic: COBRT101 - COBRT120


COBRT114 Attempt to access item beyond bounds of memory (Fatal)

Memory access violation has been detected by your operating system.

The file mfdebug.log is automatically generated in your current directory.

Parent topic: COBRT101 - COBRT120


COBRT115 Unexpected signal (Fatal)

A signal the run-time system was not expecting has been caught.

If you are running under Windows, the file mfdebug.log is automatically generated in your current directory.

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

Lists the Run-time System error messages from COBRT121 through COBRT140.

  • COBRT121 Symbol is not in TEXT section (Fatal)
    You have tried to call a subprogram that is not an executable program.
  • COBRT122 Coblongjmp() called below level of cobsavenv() (Fatal)
    You might have returned control to a higher level in the CALL/PERFORM hierarchy than the level at which cobsetjmp was called. Coblongjmp must be called only from the same or from a lower level in the CALL/PERFORM hierarchy as cobsavenv was.
  • COBRT123 Unknown relocation type (Fatal)
    You are using incompatible versions of the object file and the COBOL run-time library.
  • COBRT124 Communication failure during I/O request to the central file handler
  • COBRT125 All locks/ current transactions canceled due to exceeding time limit
  • COBRT126 Record size exceeds system limit (Fatal)
    One of the following has occurred:
  • COBRT127 coblongjmp() called from a different thread to cobsetjmp() (Fatal)
    You have called coblongjmp() in a different thread from the corresponding call to cobsetjmp(). coblongjmp() must be called from the same thread as the corresponding call to cobsetjmp().
  • COBRT129 Attempt to access record zero of relative file (Recoverable)
    The value specified in the RELATIVE KEY data item contains the value zero.
  • COBRT135 File not found (Recoverable)
    The operating system has been unable to find a file which you have tried to access in your program.
  • COBRT136 Corrupt or invalid executable file (Fatal)
    An attempt was made to execute a .gnt file or a library file that is not valid. The file might be corrupted or truncated.
  • COBRT137 Illegal device specification - not mass storage
  • COBRT138 File closed with lock - cannot be opened (Recoverable)
    You are trying to open a file which you previously closed with lock, which violates one of the general rules of COBOL programming.
  • COBRT139 Record length or key data inconsistency (Recoverable)
    A discrepancy exists between the length of a record, or the keys which you have specified, in your current program and its definition in the program in which it was first opened.
Parent topic: Run-time System Error Messages


COBRT121 Symbol is not in TEXT section (Fatal)

You have tried to call a subprogram that is not an executable program.

Alternatively, you have used the same name for a called program as for a previously defined data item.

Resolution:

Check that the subprogram being called is an executable one. If required, correct the subprogram's name in the calling program and resubmit it to your COBOL system.

Once your program has terminated, recode it to remove the naming duplication. Resubmit your program to your COBOL system.

Parent topic: COBRT121 - COBRT140


COBRT122 Coblongjmp() called below level of cobsavenv() (Fatal)

You might have returned control to a higher level in the CALL/PERFORM hierarchy than the level at which cobsetjmp was called. Coblongjmp must be called only from the same or from a lower level in the CALL/PERFORM hierarchy as cobsavenv was.

Resolution:

Check and correct the logic of your program, and then resubmit your program to your COBOL system.

Parent topic: COBRT121 - COBRT140


COBRT123 Unknown relocation type (Fatal)

You are using incompatible versions of the object file and the COBOL run-time library.

Resolution:

Once the program has terminated, resubmit your object file to your COBOL system with the current version of your COBOL run-time library. If this does not work, contact Technical Support who will help you to discover the specific cause of the error.

Parent topic: COBRT121 - COBRT140


COBRT124 Communication failure during I/O request to the central file handler

Parent topic: COBRT121 - COBRT140


COBRT125 All locks/ current transactions canceled due to exceeding time limit

Parent topic: COBRT121 - COBRT140


COBRT126 Record size exceeds system limit (Fatal)

One of the following has occurred:

  • You have attempted to open for output a file whose record length is greater than the system limits. For C-ISAM format files, the limit is 32,767 bytes. For Micro Focus format files, the limit is 268,433,408 bytes.
  • You have attempted a REWRITE on a sequential file using data compression where the compressed length of the new record differs from that of the original.

Resolution:

Correct the record size.

Parent topic: COBRT121 - COBRT140


COBRT127 coblongjmp() called from a different thread to cobsetjmp() (Fatal)

You have called coblongjmp() in a different thread from the corresponding call to cobsetjmp(). coblongjmp() must be called from the same thread as the corresponding call to cobsetjmp().

Resolution:

Check and correct the logic of your program, then resubmit it to your COBOL system.

Parent topic: COBRT121 - COBRT140


COBRT129 Attempt to access record zero of relative file (Recoverable)

The value specified in the RELATIVE KEY data item contains the value zero.

Resolution:

You should ensure that the value in the RELATIVE KEY data item is greater than zero, then continue to run your program.

Parent topic: COBRT121 - COBRT140


COBRT135 File not found (Recoverable)

The operating system has been unable to find a file which you have tried to access in your program.

Resolution:

Ensure that you are in the correct directory or that a path to the file concerned exists. You can then try the file operation again. If the error is the result of a spelling mistake then ask for the correct file and try the file operation again.

Parent topic: COBRT121 - COBRT140


COBRT136 Corrupt or invalid executable file (Fatal)

An attempt was made to execute a .gnt file or a library file that is not valid. The file might be corrupted or truncated.

Resolution:

Recompile the source code or recreate the library file, ensuring that it is processed without errors.

Parent topic: COBRT121 - COBRT140


COBRT137 Illegal device specification - not mass storage

Parent topic: COBRT121 - COBRT140


COBRT138 File closed with lock - cannot be opened (Recoverable)

You are trying to open a file which you previously closed with lock, which violates one of the general rules of COBOL programming.

Resolution:

You cannot open the relevant file. As this error implies that your program logic contains a mistake, you might want to close any remaining open files, execute a STOP RUN statement and recode.

Parent topic: COBRT121 - COBRT140


COBRT139 Record length or key data inconsistency (Recoverable)

A discrepancy exists between the length of a record, or the keys which you have specified, in your current program and its definition in the program in which it was first opened.

Resolution:

Your program has a fault, so you probably should edit your code, then resubmit it to your COBOL system before running it again.

Parent topic: COBRT121 - COBRT140


COBRT141 - COBRT160

Lists the Run-time System error messages from COBRT141 through 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

Lists the Run-time System error messages from COBRT161 through 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

Lists the Run-time System error messages from COBRT181 through COBRT200.

  • COBRT181 Invalid parameter error (Fatal)
    A parameter which you have used is not one which is recognized by your system.
  • COBRT182 Console input or console output open in wrong direction (Fatal)
    You are either trying to read input from the screen or write to the keyboard.
  • COBRT183 Attempt to open line sequential file for I-O (Fatal)
    You have tried to open a line-sequential file in the input-output open mode, but this mode is not supported for files with this organization.
  • COBRT184 ACCEPT/DISPLAY I-O error (Fatal)
    You have either tried to read input from the screen or write to the keyboard, or the ADIS module has not been able to open your terminal's channels for I-O.
  • COBRT185 File malformed (Recoverable)
  • COBRT186 Attempt to open stdin, stdout or stderr with incorrect mode (Recoverable)
    You have tried to open either a standard input file with output mode, or some other file in an incorrect mode.
  • COBRT187 Run-time system not found on $COBDIR path (Fatal)
    The run-time system cannot be found on the path you have set up in the COBDIR environment variable. Alternatively, you might not have installed your COBOL system correctly.
  • COBRT188 Filename too large (Fatal)
    A file-name which you have used has more characters than the maximum number allowed by your operating system.
  • COBRT189 Intermediate code load error (Fatal)
    You are unable to load your intermediate code. You might have tried to load intermediate code that either has not been successfully produced, or has been corrupted in some way.
  • COBRT190 Too many arguments to CALL (Fatal)
    A CALL statement in your program cannot be successfully executed because of the number of arguments which you have used with it.
  • COBRT191 Terminal type not defined (Fatal)
    Your terminal is not defined.
  • COBRT192 Required terminal capability description missing (Fatal)
    A compulsory entry, for example cursor movement or clear screen, is missing from your terminal configuration database.
  • COBRT193 Error in variable length count (Fatal)
    The intermediate code which is currently being processed is not a valid operation. You are probably trying to execute a corrupt file or one which has not been produced.
  • COBRT194 File size too large (Fatal)
    A file which your program is accessing is too large for successful execution to continue.
  • COBRT195 DELETE/REWRITE not preceded by a read (Fatal)
    Before a DELETE or a REWRITE statement can be successfully executed in sequential access mode the last input-output statement executed for the associated file must have been a successful read. In your code no read statement precedes your tried DELETE or REWRITE.
  • COBRT196 Record number too large in relative or indexed file (Fatal)
    The relative record key has exceeded the system limit, that is, the file is too large for the system to handle.
  • COBRT197 Screen handling system initialization error (Fatal)
    This error can be caused by one of the following:
  • COBRT198 Load failure (Fatal)
    The system cannot load a program module or, in a multi-threading program, start a new thread.
  • COBRT199 Operating System error code lies outside expected range (Fatal)
    A system call has returned an unexpected error number which is not documented.
  • COBRT200 Run-time system internal logic error (Fatal)
    The amount of memory available on your machine is so low that not even the run-time system can be fully loaded.
Parent topic: Run-time System Error Messages


COBRT181 Invalid parameter error (Fatal)

A parameter which you have used is not one which is recognized by your system.

Resolution:

Revise your code to contain a parameter which is known by your system.

Parent topic: COBRT181 - COBRT200


COBRT182 Console input or console output open in wrong direction (Fatal)

You are either trying to read input from the screen or write to the keyboard.

Resolution:

You should recode your program.

Parent topic: COBRT181 - COBRT200


COBRT183 Attempt to open line sequential file for I-O (Fatal)

You have tried to open a line-sequential file in the input-output open mode, but this mode is not supported for files with this organization.

Resolution:

When your program has terminated you should recode your program to ensure that the file with organization line sequential is opened for input, output, or extend. You can then rerun your code.

Parent topic: COBRT181 - COBRT200


COBRT184 ACCEPT/DISPLAY I-O error (Fatal)

You have either tried to read input from the screen or write to the keyboard, or the ADIS module has not been able to open your terminal's channels for I-O.

Resolution:

Your program logic contains a mistake, so you must recode.

Parent topic: COBRT181 - COBRT200


COBRT185 File malformed (Recoverable)

Parent topic: COBRT181 - COBRT200


COBRT186 Attempt to open stdin, stdout or stderr with incorrect mode (Recoverable)

You have tried to open either a standard input file with output mode, or some other file in an incorrect mode.

Parent topic: COBRT181 - COBRT200


COBRT187 Run-time system not found on $COBDIR path (Fatal)

The run-time system cannot be found on the path you have set up in the COBDIR environment variable. Alternatively, you might not have installed your COBOL system correctly.

Resolution:

Ensure that the run-time system is on the path you have set up in the COBDIR environment variable. Alternatively, ensure that your COBOL system has been installed correctly. If it has not, you must reinstall your COBOL system.

Parent topic: COBRT181 - COBRT200


COBRT188 Filename too large (Fatal)

A file-name which you have used has more characters than the maximum number allowed by your operating system.

Resolution:

You should recode your program to check the length of the file in error, and rename it with a shorter file-name. You can then run your program again.

Parent topic: COBRT181 - COBRT200


COBRT189 Intermediate code load error (Fatal)

You are unable to load your intermediate code. You might have tried to load intermediate code that either has not been successfully produced, or has been corrupted in some way.

Resolution:

Try to obtain good intermediate code, for example, by resubmitting (or submitting) your source code to your COBOL system. You should then be able to load your code and run the program successfully.

Parent topic: COBRT181 - COBRT200


COBRT190 Too many arguments to CALL (Fatal)

A CALL statement in your program cannot be successfully executed because of the number of arguments which you have used with it.

Resolution:

When your program has terminated you can recode it using group items rather than elementary ones. You should then be able to run your program successfully.

Parent topic: COBRT181 - COBRT200


COBRT191 Terminal type not defined (Fatal)

Your terminal is not defined.

Resolution:

Your terminal type is undefined, so your operating system is unable to drive your terminal. Set up the necessary environment for your terminal.

Parent topic: COBRT181 - COBRT200


COBRT192 Required terminal capability description missing (Fatal)

A compulsory entry, for example cursor movement or clear screen, is missing from your terminal configuration database.

Resolution:

Add the missing entry to your terminal configuration database.

Parent topic: COBRT181 - COBRT200


COBRT193 Error in variable length count (Fatal)

The intermediate code which is currently being processed is not a valid operation. You are probably trying to execute a corrupt file or one which has not been produced.

Resolution:

You should resubmit your source code to your COBOL system.

Parent topic: COBRT181 - COBRT200


COBRT194 File size too large (Fatal)

A file which your program is accessing is too large for successful execution to continue.

Resolution:

When your program has terminated you should recode your program spreading the data over more than one file to ensure that no file becomes too large for your operating system to handle. Having recoded your program you can then rerun it.

Parent topic: COBRT181 - COBRT200


COBRT195 DELETE/REWRITE not preceded by a read (Fatal)

Before a DELETE or a REWRITE statement can be successfully executed in sequential access mode the last input-output statement executed for the associated file must have been a successful read. In your code no read statement precedes your tried DELETE or REWRITE.

Resolution:

When your program has terminated, recode your program, making sure that the last input-output statement to be executed before the DELETE or REWRITE is a read statement.

Parent topic: COBRT181 - COBRT200


COBRT196 Record number too large in relative or indexed file (Fatal)

The relative record key has exceeded the system limit, that is, the file is too large for the system to handle.

Alternatively, the record key which you have specified is too large for the system to deal with successfully, or the pointer to the record has been corrupted in some way so that it is either too large or it is not a multiple of the record length.

Parent topic: COBRT181 - COBRT200


COBRT197 Screen handling system initialization error (Fatal)

This error can be caused by one of the following:

  • Your display adapter is in the wrong mode.
  • Your screen handling interface has not been correctly initialized because your terminal does not have the required capabilities.
  • Memory has been incorrectly allocated.

Resolution:

The monitor must be in alphanumeric display mode rather than graphics display mode.

Parent topic: COBRT181 - COBRT200


COBRT198 Load failure (Fatal)

The system cannot load a program module or, in a multi-threading program, start a new thread.

A CALL statement has failed because:

  • In the case of a DLL, the specified entry point does not exist in the file
  • In the case of an .int or .gnt file, the file has been corrupted
  • In the case of a call of the form $PROG, name mapping has failed
  • In the case of a call-by-number library routine (CALL data-name, where data-name is a pic x with value greater than x'80'), the routine does not exist

Any call or attempt to start a thread can fail where internal structures have been corrupted; for example, by a protection violation.

A statement of the form SET PROCEDURE POINTER TO ENTRY entry-point has failed because the entry point cannot be found on disk or in the current run-unit.

The Entry Point Mapping facility has found a program on disk with the same name as an alias definition. Whether or not this condition results in a COBRT198 error depends on the setting of the entry_point_mapper_alias_exists_error tunable.

Rarely, this error can be caused by a CALL statement failing because of insufficient available memory or because the run-time system version is too old.

Resolution:

Check that the target of your call exists and has not been corrupted.

Test that a procedure pointer is valid before using it by including code of the form:

set bad-pointer to entry 'just-not-there-ever'...set procedure-pointer to entry 'myentrypoint'if procedure-pointer = bad-pointer display errorend-if
Parent topic: COBRT181 - COBRT200


COBRT199 Operating System error code lies outside expected range (Fatal)

A system call has returned an unexpected error number which is not documented.

Resolution:

Contact Technical Support who will help you to discover the specific cause of this error.

This error generates a Consolidated Tracing Facility warning event. To capture the generated event you must configure the Consolidated Tracing Facility as follows:

  • Set the trace level for the mf.rts component to WARN, INFO or DEBUG.
  • Set the API or FSYS property of the mf.rts component to TRUE.

If you want the event to appear in the Windows Application Event log you can configure the Consolidated Tracing Facility to do this with configuration entries such as the following:

mftrace.dest = WINEVENT
mftrace.level = WARN

mftrace.emitter.winevent#level = 2
mftrace.comp.mf.rts#api = TRUE

The mftrace.emitter.winevent#level = 2 entry is required because by default the WINEVENT emitter does not output any events below level 3 (ERROR).

In previous versions of this COBOL system, the error returned by the system call was written to the Windows Application Event log. You can revert to this behavior by setting the os_error_log tunable to true. If you set os_error_log to true and configure the Consolidated Tracing Facility as described above, each COBRT199 error causes two entries to be written to the Windows Application Event log.

Parent topic: COBRT181 - COBRT200


COBRT200 Run-time system internal logic error (Fatal)

The amount of memory available on your machine is so low that not even the run-time system can be fully loaded.

Alternatively, your run-time system has stopped as a result of an internal logic error from which you cannot recover.

Resolution:

Free some memory and then you should be able to run your program successfully.

Contact Technical Support who will help you to discover the cause of the error.

Parent topic: COBRT181 - COBRT200


COBRT201 - COBRT220

Lists the Run-time System error messages from COBRT201 through 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, or insert a new floppy disk.

Parent topic: COBRT201 - COBRT220


COBRT203 CALL parameter not supplied (Fatal)

The item you are trying to access in the Linkage Section of the currently executing program has not been initialized.

Resolution:

Recode your program to ensure that it contains all of the necessary parameters, or check that it is a valid caller.

Parent topic: COBRT201 - COBRT220


COBRT205 Invalid mainframe pointer value (Fatal)

You are trying to reference an invalid mainframe address.

Resolution:

Check the logic of your program, and recode the appropriate statements.

Parent topic: COBRT201 - COBRT220


COBRT206 Reading unwritten data from memory (Fatal)

You are trying to read data which has not been written, from the core file.

Parent topic: COBRT201 - COBRT220


COBRT207 Machine does not exist (Recoverable)

You have tried to access a machine that is not connected to your network, or which is not on-line.

Resolution:

Make sure the machine is connected to the network and is on-line, then try to access it again.

Parent topic: COBRT201 - COBRT220


COBRT208 Error in multi-user system (Fatal)

This is normally caused by an unexpected error occurring in the network or file-sharing facilities. A corrupted network message also causes this error to be returned.

Resolution:

Retry the unsuccessful operation. If the error persists, contact Technical Support who will help you to discover the specific cause of this error.

Parent topic: COBRT201 - COBRT220


COBRT209 Network communication error (Recoverable)

This is normally given if an incorrect checksum has been received in a communications packet.

Resolution:

Your program should continue to execute after you have received this error but results might be undefined.

Parent topic: COBRT201 - COBRT220


COBRT210 File is closed with lock (Fatal)

You have tried to open a file which you have previously closed with lock.

Resolution:

Recode your program to avoid opening a file which has previously been closed with lock.

Parent topic: COBRT201 - COBRT220


COBRT211 Program not executable by Run-Time System (Fatal)

An attempt was made to run a program that is incompatible with the currently-specified run-time system. For example, system executable, shared library, and callable shared object files that have been linked using older COBOL systems could be incompatible.

On dual 32-bit/64-bit COBOL systems, all code must be compiled and linked using the same word length. A 64-bit run-time system does not run programs compiled and/or linked on 32-bit platforms or in 32-bit mode. Similarly, a 32-bit run-time system does not run programs compiled and/or linked on 64-bit platforms in 64-bit mode.

Resolution:

Recompile and/or relink your program so that it is compatible with the current run-time system.

Parent topic: COBRT201 - COBRT220


COBRT212 Run-Time System version incompatible with object-oriented program (Fatal)

You attempted to run an OO program that was compiled using a version of your COBOL system that is incompatible with the OO support provided in the run-time system you are using.

Resolution:

Recompile and/or relink your program so that it is compatible with the current run-time system.

Parent topic: COBRT201 - COBRT220


COBRT213 Too many locks (Recoverable)

You have either tried to exceed the maximum number of simultaneous record locks per file you can have, or you have exhausted an operating system or network resource; for example dynamic memory.

Resolution:

Execute a COMMIT or an UNLOCK operation on the relevant file and you should then be able to continue to run your program. You should try not to retain a record lock for longer than is necessary.

Parent topic: COBRT201 - COBRT220


COBRT214 GO TO has not been ALTERed (Fatal)

You have violated one of the general rules of COBOL programming.

Resolution:

Close any files which might be open, execute a STOP RUN statement and then edit your program to avoid such illegal operations.

Parent topic: COBRT201 - COBRT220


COBRT215 Cannot DEBUG a program running COMMUNICATIONS (Fatal)

You have tried to debug a program which makes use of the communications module. This cannot be done as both Debugger and the communications module need full use of the CRT.

Resolution:

You should run your program without the aid of Debugger.

Parent topic: COBRT201 - COBRT220


COBRT216 Cannot initialize the named communications device (Fatal)

A device driver is probably missing.

Resolution:

Ensure that all communications drivers are loaded before you try to run Communications.

Parent topic: COBRT201 - COBRT220


COBRT217 Incompatible host for native code file (Fatal)

The .gnt file is not valid for the host processor.

Resolution:

You must resubmit your program to your COBOL system.

Parent topic: COBRT201 - COBRT220


COBRT218 Malformed MULTIPLE REEL/UNIT file (Fatal)

Either your file header is not correctly formatted, or you are not using a MULTIPLE REEL/UNIT file.

Resolution:

You should try to run your program again using a backup copy of the relevant file.

Parent topic: COBRT201 - COBRT220


COBRT219 Operating system shared file limit exceeded (Recoverable)

You have tried to exceed your operating system's limit on the number of shared files that you can have open simultaneously. As this figure is operating system dependent, you should consult your Release Notes for details of how many shared files your system permits to be open at any one time.

Resolution:

Close some of the open shared files you are no longer accessing and retry the file operation.

Parent topic: COBRT201 - COBRT220


COBRT220 Attempt to execute more than one SORT or MERGE simultaneously (Fatal)

You have coded your program in such a way that it is trying to execute more than one SORT or MERGE operation at the same time. For example, you might have coded a SORT statement in the input or output procedure of another SORT statement, an operation that is specifically prohibited under the rules of ANSI COBOL.

Alternatively you are trying to sort or merge a file that is not open with the correct permissions.

Alternatively you have set the TMP environment variable to point to a directory that does not exist.

Alternatively you are trying to run a SORT with a SORTSPACE too small to do so.

Alternatively the SORTSPACE you have set is too small for the SORT you are performing.

Resolution:

Recode your program to ensure that it does not execute more than one SORT or MERGE at any one time.

Check that the files are open with the correct permissions.

Set $TMP to point to a directory that does exist or unset $TMP.

Set SORTSPACE to something more appropriate.

Either increase SORTSPACE or set SORTSCHEME=0 if it is set.

Parent topic: COBRT201 - COBRT220


COBRT221 - COBRT240

Lists the Run-time System error messages from COBRT221 through COBRT240.

  • COBRT222 Merge files out of sequence (Fatal)
    An attempt to merge two files has been unsuccessful. One or more of your files might be out of sequence.
  • COBRT223 NLS language expansion error (Fatal)
    You have used the SORT verb, but the output buffer is not large enough.
  • COBRT224 External Language Initialization failure
  • COBRT225 Dynamic load error - program component missing (Fatal)
    The run-time system cannot locate the root or overlay of a program that is currently loaded in memory.
  • COBRT226 EXTERNAL file definition inconsistent
    Two or more programs define the same external file but with different formats. For example, maximum and minimum record lengths might be different.
  • COBRT227 EXTERNAL data definition inconsistent (Fatal)
    Two or more programs are defining the same external data item, but the first loaded program has defined the size differently from the second or subsequent loaded program.
  • COBRT228 Could not allocate memory for EXTERNAL item (Fatal)
  • COBRT229 SORT/MERGE module does not support EXTERNAL using/giving files (Recoverable)
    You have tried a SORT or MERGE operation which has USING/ GIVING files which are defined as EXTERNAL. The SORT/ MERGE module does not support USING/ GIVING files defined as EXTERNAL.
  • COBRT231 GENERATE encountered before corresponding INITIATE in report (Fatal)
    A GENERATE (Report Writer syntax) statement has been executed before a corresponding INITIATE statement.
  • COBRT232 Reference modification out of bounds
    An error has occurred because reference modification has referred to data beyond the boundaries of the base data item.
  • COBRT235 Error in debugger communications channel (Fatal)
    The Debugger has encountered system limits or conflicts resulting in communications errors.
  • COBRT236 Debugged program has terminated unexpectedly (Fatal)
    A program you are debugging has terminated without following the standard run-time system shut-down process. The termination was probably either initiated by the user or caused by a severe run-time error.
  • COBRT237 Unable to initialize debugged process (Fatal)
    The Debugger has encountered system limits in starting your program. The debugged program cannot start because of insufficient memory .
  • COBRT238 STOP RUN encountered during GNT animation (Informational)
    The Debugger has encountered a STOP RUN statement while debugging your .gnt code program.
  • COBRT239 Shared run-time system initialization failure (Informational)
    You are calling a COBOL module from a non-COBOL program, and have not initialized the shared run-time system.
  • COBRT240 Object reference not valid (Fatal)
    You have tried to use an object reference that contains an incorrect or non-existent object handle.
Parent topic: Run-time System Error Messages


COBRT222 Merge files out of sequence (Fatal)

An attempt to merge two files has been unsuccessful. One or more of your files might be out of sequence.

Resolution:

Make sure that the files you are trying to merge are in sequence.

Parent topic: COBRT221 - COBRT240


COBRT223 NLS language expansion error (Fatal)

You have used the SORT verb, but the output buffer is not large enough.

Resolution:

Use either the SORTNLSEXPAND or SORTNLSOVERHEAD environment variable to control the values used by SORT when calling CBL_NLS_TRANSFORM.

SORTNLSEXPAND calculates the output buffer given the input buffer.

The value of SORTNLSOVERHEAD is added to the length of the output buffer after using SORTNLSEXPAND.

The default values for both is 6.

Parent topic: COBRT221 - COBRT240


COBRT224 External Language Initialization failure

Parent topic: COBRT221 - COBRT240


COBRT225 Dynamic load error - program component missing (Fatal)

The run-time system cannot locate the root or overlay of a program that is currently loaded in memory.

Alternatively, you have insufficient memory to load your program.

Alternatively, the run-time system could not find enough file handles to open and, therefore, load the code.

Resolution:

Either the library that contained the program has been canceled, or the program is no longer available on the program search path. Ensure that the program is available either on disk or on an open library.

Either free some memory or restructure your application so that it uses less memory.

Increase your operating system file handles limit.

Parent topic: COBRT221 - COBRT240


COBRT226 EXTERNAL file definition inconsistent

Two or more programs define the same external file but with different formats. For example, maximum and minimum record lengths might be different.

Resolution

Make sure that all of your programs define the external file with the same format so that they are consistent. It is useful to have the file definition in a COPY file.

Parent topic: COBRT221 - COBRT240


COBRT227 EXTERNAL data definition inconsistent (Fatal)

Two or more programs are defining the same external data item, but the first loaded program has defined the size differently from the second or subsequent loaded program.

Resolution:

Make sure that both or all of your programs define the size of the external data item as being the same.

Parent topic: COBRT221 - COBRT240


COBRT228 Could not allocate memory for EXTERNAL item (Fatal)

Parent topic: COBRT221 - COBRT240


COBRT229 SORT/MERGE module does not support EXTERNAL using/giving files (Recoverable)

You have tried a SORT or MERGE operation which has USING/ GIVING files which are defined as EXTERNAL. The SORT/ MERGE module does not support USING/ GIVING files defined as EXTERNAL.

Resolution:

Recompile your program to use the callable SORT module (EXTSM).

Parent topic: COBRT221 - COBRT240


COBRT231 GENERATE encountered before corresponding INITIATE in report (Fatal)

A GENERATE (Report Writer syntax) statement has been executed before a corresponding INITIATE statement.

Resolution:

Correct by revising your program execution flow.

Parent topic: COBRT221 - COBRT240


COBRT232 Reference modification out of bounds

An error has occurred because reference modification has referred to data beyond the boundaries of the base data item.
Note: This error is only reported if you are using the Compiler directive setting SSRANGE"2".

Resolution:

Check your code for data items being manipulated with reference modification and ensure that the reference modification parameters are set correctly.

Parent topic: COBRT221 - COBRT240


COBRT235 Error in debugger communications channel (Fatal)

The Debugger has encountered system limits or conflicts resulting in communications errors.

Resolution:

Copy the debugged program file to a different directory and try debugging.

Parent topic: COBRT221 - COBRT240


COBRT236 Debugged program has terminated unexpectedly (Fatal)

A program you are debugging has terminated without following the standard run-time system shut-down process. The termination was probably either initiated by the user or caused by a severe run-time error.

Resolution:

Run your program without debugging to determine if it runs successfully; if so, debug the program without cross-session or intrasession debugging.

Parent topic: COBRT221 - COBRT240


COBRT237 Unable to initialize debugged process (Fatal)

The Debugger has encountered system limits in starting your program. The debugged program cannot start because of insufficient memory .

Resolution:

Debug your program when the load on the system has reduced. Run the program without debugging to determine if it runs successfully; if so, debug the program without cross-session or intrasession debugging. Ask your system administrator to expand the number of process slots and virtual memory page maps.

Parent topic: COBRT221 - COBRT240


COBRT238 STOP RUN encountered during GNT animation (Informational)

The Debugger has encountered a STOP RUN statement while debugging your .gnt code program.

Resolution:

Step or Zoom the debugged program, and the Debugger will terminate the program and its current session.

Parent topic: COBRT221 - COBRT240


COBRT239 Shared run-time system initialization failure (Informational)

You are calling a COBOL module from a non-COBOL program, and have not initialized the shared run-time system.

Resolution:

Ensure that your application calls the cobinit() function before executing any COBOL modules. See your COBOL System Referencefor more information about the cobinit() function.

Parent topic: COBRT221 - COBRT240


COBRT240 Object reference not valid (Fatal)

You have tried to use an object reference that contains an incorrect or non-existent object handle.

Resolution:

Ensure that the object reference uses the correct object handle, and that your program has not previously destroyed the object by sending it a Finalize message.

Parent topic: COBRT221 - COBRT240


COBRT241 - COBRT260

Lists the Run-time System error messages from COBRT241 through COBRT260.

  • COBRT221 Internal sort error (Fatal)
  • COBRT241 Cannot instantiate an abstract class (Fatal)
    You have tried to create an instance of a class that has been declared ABSTRACT. Such classes cannot be instantiated.
  • COBRT242 Could not resolve DoesNotUnderstand message (Fatal)
    The run-time system could not resolve the DoesNotUnderstand message. This is usually because you have defined a class in such a way that this method cannot be found.
  • COBRT243 Class could not be loaded (Fatal)
    An attempt to load an object class has failed because the class does not contain a valid Class-Control section, or because the class is not defined correctly.
  • COBRT244 Licensing initialization error (Fatal)
    An error occurred initializing the run-time license.
  • COBRT245 There are no valid product licenses (Fatal)
    There are no run-time licenses installed on either the local machine or license server, or all the licenses have expired.
  • COBRT246 Maximum number of product licenses exceeded (Fatal)
    All the run-time licenses installed on either the local machine or on the license server are in use.
  • COBRT247 Licensing error (Fatal)
    A error occurred whilst trying to get a run-time license.
  • COBRT249 Process killed (signal-number) (Fatal)
    The run-time system has passed a a SIGTERM signal to a service execution process (SEP) running on an enterprise server. This may occur for the following reasons:
  • COBRT250 Not enough mainframe address space to load or run the program (Fatal)
    This program has been compiled with one of the compiler directives AMODE(24) or AMODE(31), which request the program's data division be registered with the Mainframe Pointer Manager. However, there is not enough free mainframe address space to allow this. For example, if you have compiled with the AMODE(24) compiler directive, the total address space required for your program's data division should not exceed 16 megabytes.
  • COBRT251 Attempt to load AMODE(24) program when current setting is AMODE(31) only (Fatal)
    The settings for the current project indicate that only AMODE(31) programs can be invoked, but an attempt was made to invoke an AMODE(24) program.
  • COBRT252 Memory corruption detected (Fatal)
    The run-time system has detected a memory corruption in a block of memory that it had previously allocated.
  • COBRT253 Cannot load file - unsupported format (Fatal)
    The file specified is not recognized as a format that the run-time system can load and execute.
  • COBRT254 Keyboard interrupt to ANIMATOR during ACCEPT (Fatal)
    While using Animator you have terminated your program with a keyboard interrupt.
Parent topic: Run-time System Error Messages


COBRT221 Internal sort error (Fatal)

Resolution:

Contact Technical Support who will help you to discover the cause of the error and how it can be rectified.

Parent topic: COBRT241 - COBRT260


COBRT241 Cannot instantiate an abstract class (Fatal)

You have tried to create an instance of a class that has been declared ABSTRACT. Such classes cannot be instantiated.

Resolution:

Ensure that you have specified the correct class name. Check to see if there is a subclass that you should use instead.

Parent topic: COBRT241 - COBRT260


COBRT242 Could not resolve DoesNotUnderstand message (Fatal)

The run-time system could not resolve the DoesNotUnderstand message. This is usually because you have defined a class in such a way that this method cannot be found.

Resolution:

Check the logic in your program to ensure that it invokes only methods that are supported by the object, or ensure that the object supports the DoesNotUnderstand method.

Parent topic: COBRT241 - COBRT260


COBRT243 Class could not be loaded (Fatal)

An attempt to load an object class has failed because the class does not contain a valid Class-Control section, or because the class is not defined correctly.

Resolution:

Check the definition of the class.

Parent topic: COBRT241 - COBRT260


COBRT244 Licensing initialization error (Fatal)

An error occurred initializing the run-time license.

Additional information regarding this error is available in a CTF trace.

Resolution

Ensure that the license server installer is run on the local machine.

Parent topic: COBRT241 - COBRT260


COBRT245 There are no valid product licenses (Fatal)

There are no run-time licenses installed on either the local machine or license server, or all the licenses have expired.

Resolution

Run the License System Administration tool CESAdminTool and install run-time licenses.

Parent topic: COBRT241 - COBRT260


COBRT246 Maximum number of product licenses exceeded (Fatal)

All the run-time licenses installed on either the local machine or on the license server are in use.

Resolution

Run the License System Administration tool CESAdminTool and install additional run-time licenses.

Parent topic: COBRT241 - COBRT260


COBRT247 Licensing error (Fatal)

A error occurred whilst trying to get a run-time license.

Additional information is displayed after the error message and/or in a CTF trace.

Resolution

Either run the CESAdminTool on the local machine or resolve any issues on the license server or with the network.

Parent topic: COBRT241 - COBRT260


COBRT249 Process killed (signal-number) (Fatal)

The run-time system has passed a a SIGTERM signal to a service execution process (SEP) running on an enterprise server. This may occur for the following reasons:

  • Implicitly as part of MSS's runaway task processing when the server manager notices that a CICS transaction appears to be looping.

Resolution:

Investigate the reason for the service or CICS transaction looping, for example, by analysing enterprise server dumps or traces, or by animating the service or transaction.

Parent topic: COBRT241 - COBRT260


COBRT250 Not enough mainframe address space to load or run the program (Fatal)

This program has been compiled with one of the compiler directives AMODE(24) or AMODE(31), which request the program's data division be registered with the Mainframe Pointer Manager. However, there is not enough free mainframe address space to allow this. For example, if you have compiled with the AMODE(24) compiler directive, the total address space required for your program's data division should not exceed 16 megabytes.

Resolution:

Reduce the amount of mainframe address space required by cancelling any other AMODE programs that are not currently in use.

Parent topic: COBRT241 - COBRT260


COBRT251 Attempt to load AMODE(24) program when current setting is AMODE(31) only (Fatal)

The settings for the current project indicate that only AMODE(31) programs can be invoked, but an attempt was made to invoke an AMODE(24) program.

Resolution:

Either change the current project settings to allow for the invocation of AMODE(24) programs, or recompile the program that was causing the error as AMODE(31).

Parent topic: COBRT241 - COBRT260


COBRT252 Memory corruption detected (Fatal)

The run-time system has detected a memory corruption in a block of memory that it had previously allocated.

Resolution:

You need to isolate the actual point in execution where the memory corruption occurs the investigate the cause. To do this you could:

  • Run with a memory strategy that indicates that memory is to be validated each time an allocation or free operation occurs (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


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 and 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.
  • 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.
Parent topic: Error Messages
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


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


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: Error Messages


File Handling Reference

  • Compiler Directives - File Handling
  • File Handler
  • FSView
  • File Status
  • File Structures
  • Library Routines
  • Limits
  • Rebuild Command Line Options
  • Rebuild Error, Information and Warning Messages
  • Run-time Switches
  • Sorting Files
Parent topic: General Reference


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 Options
  • Data Structures
  • Operation Codes
Parent topic: File Handling Reference


Configuration File Options

The following list shows the options that can be set via the File Handler configuration file.

  • ASCIIMAINFRAMEPRINT
    The ASCIIMAINFRAMEPRINT option specifies whether to use ASCII printer control characters when CHARSET is set to ASCII and the FILETYPE is set to mainframe print format where “WRITE BEFORE ADVANCING SYNTAX” is used.
  • BASENAME
    The BASENAME option determines whether filenames specified in tags can be expressed without pathnames. By default, such filenames have to be expressed with full path information as passed to the File Handler by the calling program. By setting BASENAME=ON, it is possible to specify the filename without the path.
  • CBL_CFGREAD_DYNFH
    The CBL_CFGREAD_DYNFH option determines whether the File Handler should reread its configuration file for configurable custom file handlers.
  • COMMITFLUSH
    In the context of a program that is not using Fileshare, the COMMITFLUSH option specifies whether the COMMIT and ROLLBACK statements cause all file updates to be flushed to disk, as well as record locks to be released.
  • CONCATNAME
    The CONCATNAME option determines whether filenames including the plus ('+') character are to be interpreted as normal filenames, or as file concatenations.
  • CONVERTDBSPACE
    The CONVERTDBSPACE option enables conversion of double-byte character set (DBCS) spaces to ASCII spaces when reading a line sequential file.
  • CONVERTEUCKATAKANA
    The CONVERTEUCKATAKANA option enables conversion of EUC single-width double-byte characters to their double-width Katakana equivalents when reading a line sequential file.
  • CONVERTSTATUS
    The CONVERTSTATUS option specifies the name of a program that is called after the File Handler has finished processing to map returned status values for emulation purposes.
  • DATACOMPRESS
    The DATACOMPRESS option specifies whether data compression is in effect and the type of compression. The directive only affects record sequential and indexed files.
  • DATAFILE
    The DATAFILE option maps the filename passed to an OPEN statement onto another name.
  • EXPANDPOSITIONING
    When using the WRITE AFTER POSITIONING statement (OS/VS COBOL compatibility), the first character of the record area can hold carriage control information. The EXPANDPOSITIONING option determines whether the written record includes this carriage control information.
  • EXPANDTAB
    The EXPANDTAB option determines whether to expand TAB characters encountered in line sequential or line advancing files during a READ operation into the equivalent number of spaces.
  • 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.
  • FILEMAXSIZE
    The FILEMAXSIZE option specifies the number of bytes used internally to store file offsets.
  • FILEPOINTERSIZE
    For format 8 indexed files, the FILEPOINTERSIZE parameter specifies the length in bytes to use to store file pointers.
  • FSIDXINTEGRITY
    In the context of a Fileshare system, the FSIDXINTEGRITY option causes any changed nodes held within the File Handlers index cache (as configured with the INDEXCOUNT option) to be written to disk before Fileshare returns status information to the client program. This option improves the integrity of indexed files processed by Fileshare at the expense of a small amount of additional file I/O.
  • IDXDATBUF
    The IDXDATBUF option determines the size of buffer used when accessing the data portion of a file with organization INDEXED.
  • IDXFORMAT
    The IDXFORMAT option specifies the format to use when creating indexed files.
  • IDXNAMETYPE
    The IDXNAMETYPE option specifies the format of the filename type for both the data file and, if present, the index file.
  • IGNORELOCK
    The IGNORELOCK option specifies whether to ignore locks when reading files open for input.
  • INDEXCOUNT
    The INDEXCOUNT option specifies the number of index nodes to be cached for an indexed file.
  • INDEXFILE
    The INDEXFILE option maps the name of the index file (for those indexed file formats that have a separate index file). This name can include full path information.
  • INSERTNULL
    When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTNULL option determines whether to insert NULL (x"00") characters before non-printable characters. The option also determines whether to strip out those NULL characters during READ operations.
  • INSERTTAB
    When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTTAB option determines whether to replace sequences of spaces with TAB characters.
  • 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.
  • 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.
  • 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.
  • 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: File Handler


ASCIIMAINFRAMEPRINT

The ASCIIMAINFRAMEPRINT option specifies whether to use ASCII printer control characters when CHARSET is set to ASCII and the FILETYPE is set to mainframe print format where “WRITE BEFORE ADVANCING SYNTAX” is used.

Syntax:

ASCIIMAINFRAMEPRINT = { ON } { OFF }

Parameters:

ON
Printer Control Characters are in ASCII when CHARSET is set to ASCII.
OFF
Printer Control Characters are in EBCDIC where CHARSET is set to ASCII.

Properties:

Default: OFF

Comments:

You use an entry in the File Handler Configuration File (EXTFH.cfg) to enable the printer control characters to be ASCII when the CHARSET is set to ASCII:

[xfh-default]
 ASCIIMAINFRAMEPRINT=ON

The default value is OFF.

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


BASENAME

The BASENAME option determines whether filenames specified in tags can be expressed without pathnames. By default, such filenames have to be expressed with full path information as passed to the File Handler by the calling program. By setting BASENAME=ON, it is possible to specify the filename without the path.

Syntax:

BASENAME = { ON } { OFF }

Parameters:

ON
Filename tags can be expressed without path information.
OFF
All filename tags in the configuration file must be expressed with full path information.

Properties:

Default: OFF

Comments:

This parameter can be set globally only, that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


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: Configuration File Options
Parent topic: File and Filename Routines
Parent topic: Alphabetical List of 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.

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 Ryan MacFarland 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
Data and Key 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


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


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


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.

Only 32-bit (4GB) support is provided for Novell systems.

Parent topic: Configuration File Options


FILEPOINTERSIZE

For format 8 indexed files, the FILEPOINTERSIZE parameter specifies the length in bytes to use to store file pointers.

Syntax:

FILEPOINTERSIZE = { 6 } { 8 }

Parameters:

6
Use 6 bytes, allowing for files up to 256 terabytes.
8
Use 8 bytes, allowing for files over 256 terabytes.

Properties:

Default: 6

Comments:

The FILEPOINTERSIZE=8 option uses up more space to store file pointers. Therefore, the resulting file size might increase slightly.

Parent topic: Configuration File Options


FSIDXINTEGRITY

In the context of a Fileshare system, the FSIDXINTEGRITY option causes any changed nodes held within the File Handlers index cache (as configured with the INDEXCOUNT option) to be written to disk before Fileshare returns status information to the client program. This option improves the integrity of indexed files processed by Fileshare at the expense of a small amount of additional file I/O.

Syntax:

FSIDXINTEGRITY = { ON } { OFF }

Parameters:

ON
Changes to the File Handler's index cache are written to disk before Fileshare returns control the client program.
OFF
Changes to the File Handler's index cache are written to disk when space is needed for other operations.

Properties:

Default: ON

Comments:

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


IDXDATBUF

The IDXDATBUF option determines the size of buffer used when accessing the data portion of a file with organization INDEXED.

Syntax:

IXDATBUF = { integer } { 0 }

Parameters:

integer
Round up the value that you enter to the next power of 2 that is greater or equal.
0
Do not use buffering.

Properties:

Default: 0

Comments:

A non-zero value can be beneficial while the file is being created. Otherwise, you might not achieve a gain in performance; in fact, performance can be degraded.

For those files where index and data are held in the same physical file, this option has no effect.

Parent topic: Configuration File Options


IDXFORMAT

The IDXFORMAT option specifies the format to use when creating indexed files.

Syntax:

IDXFORMAT = integer

Parameters:

0
Default format for the operating system (identical to 8.)
1
C-ISAM.
3
Micro Focus default indexed file format.
4
Optimized format for fast duplicate key handling.
8
Large indexed file format.
9
Indexed with single key, non-duplicate, key ordered records.
10
Reserved.
11
Mainframe print file format.
12-13
Reserved.
14
Heap file.
15
ESDS
16-255
Reserved.

Properties:

Default: 0

Comments:

Rebuild will not take the setting of this configuration option into account when generating a new file. Refer to the Rebuild Options /t topic in the Reference section for further information.

You can also set the index format using the IDXFORMAT Compiler directive, which will override the setting specified in the file handler configuration file.

Parent topic: Configuration File Options


IDXNAMETYPE

The IDXNAMETYPE option specifies the format of the filename type for both the data file and, if present, the index file.

Syntax:

IDXNAMETYPE = { 0 } { 1 } { 2 }

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.

Properties:

Default: 0

Comments:

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 file names:

0 | abc.def and abc.idx
1 | abc.def and abc.def.idx
2 | abc.def.dat and abc.def.idx
Parent topic: Configuration File Options


IGNORELOCK

The IGNORELOCK option specifies whether to ignore locks when reading files open for input.

Syntax:

IGNORELOCK = { ON } { OFF }

Parameters:

ON
Ignore locks when reading files open for input.
OFF
Do not ignore locks when reading files open for input.

Properties:

Default: OFF
Parent topic: Configuration File Options


INDEXCOUNT

The INDEXCOUNT option specifies the number of index nodes to be cached for an indexed file.

Syntax:

INDEXCOUNT = node-count

Parameters:

node-count
The number of nodes to be cached. Can be any value between 4 and 255.

Properties:

Default: 16
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
Related information
N run-time switch


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


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
Data and 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 information
LOGFILENAME


LOGFILENAME

When the LOG option is active, the LOGFILENAME option specifies the name of the log file to produce.

Syntax:

LOGFILENAME = name

The log file lists any unusual file-related situations, such as corrupted files, or automatic file recovery. Contact technical support if you need more information regarding the contents of the file.

Parameters:

name
Name of the log file.

Properties:

Default: XFHLOG

Comments:

This option can be set globally only, that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Use the program cobfhprint to create and display a text version of the log file:

cobfhprint filename
Parent topic: Configuration File Options


LSFILETERM

The option controls the behavior of the File Handler upon encountering the EOF character x"1a" when reading line sequential files.

Syntax:

LSFILETERM = { ON } OFF

Parameters:

ON
Interpret x"1a" characters as EOF markers.
OFF
Ignore EOF characters and continue reading until the physical end of file.

Properties:

Default: ON

Comments:

This option corresponds to bit h"10" of the fcd-flags-2 field in the File Control Description (FCD).

Parent topic: Configuration File Options


LSRECDELIM

The LSRECDELIM option specifies the characters to be used as the record delimiter in line sequential files.

Syntax:

LSRECDELIM = { 0A } { 0D0A }

Parameters:

0A
The hexadecimal character x"0A" is used as the record delimiter for line sequential files.
0D0A
The hexadecimal characters x"0D0A" are used as the record delimiter for line sequential files.

Properties:

Default: 0D0A.
Parent topic: Configuration File Options


MAINFRAMEPRINT

For those files using WRITE AFTER ADVANCING or WRITE BEFORE ADVANCING, the MAINFRAMEPRINT option determines whether to use mainframe printer file format (filetype 11).

Syntax:

MAINFRAMEPRINT = { ON } { OFF }

Parameters:

ON
Use mainframe printer file format.
OFF
Do not use mainframe printer file format.

Properties:

Default: OFF
Parent topic: Configuration File Options


NAMEOPTIONS

The NAMEOPTIONS option specifies whether the name you pass to the OPEN statement can contain File Handler options.

Syntax:

NAMEOPTIONS = { ON } { OFF }

Parameters:

ON
The name you pass to the OPEN statement can contain File Handler options enclosed in round or square brackets. For example:
fil1[PRINTER]
OFF
The name you pass to the OPEN statement cannot contain File Handler options.

Properties:

Default: OFF

Comments:

If set to OFF, the brackets and the characters they enclose are considered as part of the file name.

Note:
  • This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.
  • This parameter is provided for compatibility with older products - you should use it only if you require compatibility with Micro Focus Workbench V4.0.
Parent topic: Configuration File Options


NFSFILELOCK

The NFSFILELOCK option enables applications to detect record locks and file locks on UNIX NFS file systems.

Syntax:

NSFILELOCK = { ON } { OFF } { HP }

Parameters:

ON
Enables programs to detect record and file locks on UNIX NFS file systems.
OFF
Windows applications cannot detect record and file locks on UNIX NFS systems.
HP
Specify HP if you are accessing Hewlett-Packard systems.

Properties:

Default: OFF
Parent topic: Configuration File Options


NODESIZE

The NODESIZE option specifies the size of the index nodes to use for an indexed file.

Syntax:

NODESIZE = size_of_node

Parameters:

size_of_node
Use the following minimum NODESIZE values depending on the length of your keys:
Key Length in Bytes | Minimum NODESIZE Value in Bytes
Less than 51 | 512
51 through 100 | 1024
101 through 512 | 4096
513 through 4080 | 16384

Properties:

Default: The minimum NODESIZE value for the key length, except that for key lengths less than 50 bytes, the default is 1024.

Comments:

In most circumstances you should allow the File Handler to work out the appropriate default node size. However, if file size is an issue, smaller node sizes do result in a smaller index file, but you should be aware that they also increase processing time as the tree depth is greater.

Parent topic: Configuration File Options


NOSEQCHECK

The NOSEQCHECK option disables sequence-checking of keys in indexed files.

Setting this option ON enables records to be written in any order to indexed files opened in sequential access mode. Otherwise records must be written in ascending order of prime key.

Syntax:

NOSEQCHECK = { ON } { OFF }

Parameters:

ON
Do not check the sequence of prime keys when writing to an indexed file with ACCESS SEQUENTIAL.
OFF
Return status 21 if prime keys are written out of sequence to an indexed file with ACCESS SEQUENTIAL.

Properties:

Default: OFF

Comments:

Note:

Micro Focus strongly suggest that you control the order in which records are written to indexed files within the program itself, by using the ACCESS SEQUENTIAL or ACCESS DYNAMIC syntax, and avoid using the NOSEQCHECK configuration option.

Parent topic: Configuration File Options


OPENINPUTSHARED

The OPENINPUTSHARED option specifies whether files that you open for input, and for which you do not specify a LOCK MODE clause, can be shared by other users.

Syntax:

OPENINPUTSHARED = { ON } { OFF }

Parameters:

ON
Other users can have the file open for INPUT only.
OFF
The system behaves as if you are specifying LOCK MODE IS MANUAL for the file. That is, other users can have the file open for I-O, provided they specify a LOCK MODE for the file.

Properties:

Default: OFF
Parent topic: Configuration File Options


OSVSREWRITE

The OSVSREWRITE option specifies whether to permit the WRITE statement for sequential files that are open for output. If so, these WRITE statements behave exactly like REWRITE statements.

Syntax:

OSVSREWRITE = { ON } { OFF }

Parameters:

ON
Permit the WRITE statement for sequential files that are open for output.
OFF
Do not permit the WRITE statement for sequential files that are open for output.

Properties:

Default: OFF

Comments:

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


READSEMA

The READSEMA option specifies whether the system attempts to gain a semaphore for shared files when I/O operations are performed that do not modify the file.

Syntax:

READSEMA = { ON } { OFF }

Parameters:

ON
Attempt to gain a semaphore for every file operation, including READ and START operations.
OFF
Do not attempt to gain a semaphore for shared files during operations such as READ and START.

Properties:

Default: OFF

Comments:

Where a file is being read by multiple users, to improve throughput set this parameter to OFF.

Parent topic: Configuration File Options


READTODELIM

The READTODELIM option specifies whether the file pointer is advanced to the next logical record in the file when reading in a record that is longer than the user data area. In these circumstances, the data record would effectively be truncated.

The option affects only line sequential files.

Syntax:

READTODELIM = { ON } { OFF }

Parameters:

ON
Records are truncated to the length of the user record area if necessary.
OFF
The file pointer is not advanced to the next logical record so one logical record might require several READs to consume it.

Properties:

Default: OFF
Parent topic: Configuration File Options


RELDATBUF

The RELDATBUF option determines the size of buffer used when accessing a file with organization RELATIVE.

Syntax:

RELDATBUF = { integer } { 0 }

Parameters:

integer
Round up the value that you enter to the next power of 2 that is greater or equal.
0
Do not use buffering.

Properties:

Default: 4096

Comments:

A non-zero value can be beneficial in the following circumstances:

  • While you are creating the file.
  • When most of the access to the file is sequential.

However, in other cases there is likely to be no performance gain. In fact, performance may be degraded.

Parent topic: Configuration File Options


RELRECDELIM

The RELRECDELIM option specifies the characters to be used as the record delimiter in fixed-length relative files.

Syntax:

RELRECDELIM = { 0A } { 0D0A }

Parameters:

0A
The hexadecimal character x"0A" is used as the record delimiter for fixed-length relative files.
0D0A
The hexadecimal characters x"0D0A" are used as the record delimiter for fixed-length relative files.

Properties:

Default: 0D0A.
Parent topic: Configuration File Options


RETRYLOCK

The RETRYLOCK option indicates whether you wish to retry a READ operation that fails because the record is locked.

Syntax:

RETRYLOCK = { ON } { OFF } { NOSTATUS } { integer }

Parameters:

ON
Retry the operation until no lock is encountered.
OFF
Do not attempt a retry.
NOSTATUS
Retry the operation for those files for which no status field is defined.
integer
Specify the number of attempts or the number of seconds for which you wish to retry the operation before a locked record status is returned. The RETRYTIME option controls the meaning of integer; for more information see the topic RETRYTIME.

Properties:

Default: OFF
Parent topic: Configuration File Options
Related information
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
Parent topic: Configuration File Options
Related information
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
Parent topic: Configuration File Options
Related information
RETRYLOCK
RETRYOPEN


RUNITLOCKDETECT

The RUNITLOCKDETECT option specifies whether the File Handler checks whether a record has been locked by a separate OPEN statement issued from within the same run unit.

Syntax:

RUNITLOCKDETECT = { ON } { OFF }

Parameters:

ON
Detect record locks.
OFF
Do not detect record locks.

Properties:

Default: ON

Comments:

Locks set within a given run unit are detected, even if RUNITLOCKDETECT is on, if this is supported by the operating system.

Parent topic: Configuration File Options


SEARCHONCREATE

The SEARCHONCREATE parameter determines whether the File Handler searches each specified directory on a multi-directory path for a file with the same name as the one being created. This option applies only to files which are opened with OPEN OUTPUT.

Syntax:

SEARCHONCREATE = { ON } { OFF }

Parameters:

ON
The path will be searched for the file and, if found, the directory where it is found will be used for the creation of the new file.
OFF
The file will be created in the first directory on the search path.

Properties:

Default: OFF

Comments:

This parameter can be set globally only, that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


SEQDATBUF

The SEQDATBUF option determines the size of buffer to use when accessing a file with organization SEQUENTIAL.

Syntax:

SEQDATBUF = integer

Parameters:

integer
Round up the value that you enter to the next power of 2. The minimum value is 4096.

Properties:

Default: 4096
Parent topic: Configuration File Options


SKIPLOCK

The SKIPLOCK option specifies whether to advance the current record pointer when a locked record is encountered during a sequential READ.

Syntax:

SKIPLOCK = { ON } { OFF }

Parameters:

ON
Advance the current record pointer when a locked record is encountered.
OFF
Do not advance the current record pointer.

Properties:

Default: OFF
Parent topic: Configuration File Options


SPACEFILL

The SPACEFILL option determines whether to fill with spaces that part of the record area beyond the data that is read when performing READ operations on line sequential or line advancing files.

Syntax:

SPACEFILL = { ON } { OFF }

Parameters:

ON
Fill the area with spaces.
OFF
Do not fill the area with spaces.

Properties:

Default: ON
Parent topic: Configuration File Options


STARTUNLOCK

The STARTUNLOCK option determines whether a START operation will remove existing locks for files specified with single record locking; that is, without the WITH LOCK ON MULTIPLE RECORDS phrase.

Syntax:

STARTUNLOCK = { ON } { OFF }

Parameters:

ON
A START operation will clear any existing lock for files specified with single record locking.
OFF
A START operation will not clear any existing lock for files specified with single record locking.

Properties:

Default: OFF

Comments:

This option is provided only for compatibility. Micro Focus recommend you do not change it.

Parent topic: Configuration File Options


STRIPSPACE

The STRIPSPACE parameter determines whether to remove trailing space characters when performing WRITE or REWRITE operations on line sequential or line advancing files.

Syntax:

STRIPSPACE = { ON } { OFF }

Parameters:

ON
Remove trailing space characters when performing WRITE or REWRITE operations on line sequential or line advancing files.
OFF
Do not remove trailing space characters when performing WRITE or REWRITE operations on line sequential or line advancing files.

Properties:

Default: ON
Parent topic: Configuration File Options


SUPPRESSADV

The SUPPRESSADV option determines whether to ignore the ADVANCING phrase of the WRITE statement for record sequential files.

Syntax:

SUPPRESSADV = { ON } { OFF }

Parameters:

ON
Ignore the ADVANCING phrase of the WRITE statement for record sequential files.
OFF
Do not ignore the ADVANCING phrase of the WRITE statement for record sequential files.

Properties:

Default: OFF
Parent topic: Configuration File Options


TRACE

The TRACE option specifies whether Xfhtrace, the File Handler trace module, is enabled. The Xfhtrace module traces File Handler operations and logs all activity to a trace file. It is supplied to help you diagnose any problems you may have with COBOL files.

Syntax:

TRACE = { ON } { OFF }

Parameters:

ON
Set tracing on either for the individual file or, if specified under the [XFH-DEFAULT] tag, for all files.
OFF
Do not produce a trace file.

Properties:

Default: OFF
Parent topic: Configuration File Options


TRACEFILEEXTEND

The TRACEFILEEXTEND option determines whether to write trace information to the end of the current trace file, if the trace file already exists. This option has no effect if TRACE is OFF.

Syntax:

TRACEFILEEXTEND = { ON } { OFF }

Parameters:

ON
Extend existing trace file when File Handler is first invoked.
OFF
Overwrite existing trace file when File Handler is first invoked.

Properties:

Default: OFF

Comments:

This parameter can be set globally only, that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


TRACEFILENAME

The TRACEFILENAME option specifies the name of the trace file to produce when the TRACE option is active.

Syntax:

TRACEFILENAME = filename

Parameters:

filename
Name of the trace file.

Properties:

Default: XFHTRACE.XFH

Comments:

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


USEVSAMKEYDEFS

Use the keys defined in the catalog via the JCL and IDCAMS instead of the keys defined in the executing program.

Syntax:

USEVSAMKEYDEFS = { ON } { OFF }

Parameters:

ON
Use the catalog's key definitions.
OFF
Use executing program's key definitions.

Properties:

Default: ON
Parent topic: Configuration File Options


WRITELINE

The WRITELINE parameter determines whether mainframe or PC behavior is used for WRITE record.

Syntax:

WRITELINE = { ON } { OFF }

Parameters:

ON
Mainframe behavior is used for WRITE record.
OFF
PC behavior is used for WRITE record.

Properties:

Default: OFF

Comments:

Set WRITELINE=OFF if you want PC print behavior for WRITELINE when using mainframe dialects.

Parent topic: Configuration File Options


WRITETHRU

The WRITETHRU option determines whether modifications to a file are written out to disk immediately or buffered internally, either by the COBOL system or by the operating system, and flushed to disk at a later stage.

Syntax:

WRITETHRU = { ON } { OFF }

Parameters:

ON
Write out all modifications to disk immediately.
OFF
Flush modifications later.

Properties:

Default: OFF

Comments:

You can obtain greater security, at the cost of significantly reduced performance, by setting this parameter to ON.

Parent topic: Configuration File Options


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
Reserved. Must be set to binary zeros.
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
6 | btrieve-non-ansi
8 | IDXFORMAT"8"
11 | Mainframe print file
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 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
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 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.

Parent topic: Standard Operation Codes


DELETE

Logically removes a record from a disk file.

Opcode | Operation | File Types
F7 | DELETE | vS R I

Input Fields

fcd-relative-key | Relative key of record to remove (R)
fcd-record-address | Pointer to the record area of the record to remove (I)

Output Fields

fcd-file status File status
Parent topic: Standard Operation Codes


DELETE FILE

Physically removes the specified file from the physical devices on which it resides.

Opcode | Operation | File Types
F8 | DELETE FILE | L S R I

Input Fields

Filename area |
fcd-organization | File organization
fcd-name-length | Filename length
fcd-file-format | File format
fcd-filename-address | Pointer to the filename area

Output Fields

fcd-file status File status
Parent topic: Standard Operation Codes


OPEN

Initiates the processing of a file. It also performs checking and writing of labels and other I/O operations.

Opcode | Operation | File Types
00 | OPEN INPUT | L S R I
01 | OPEN OUTPUT | L S R I
02 | OPEN I-O | L S R I
03 | OPEN EXTEND | L S R I
04 | OPEN INPUT WITH NO REWIND | L S
05 | OPEN OUTPUT WITH NO REWIND | L S
08 | OPEN INPUT REVERSED | L S

Input Fields

Filename area |
Key definition block |
fcd-organization | File organization
fcd-access-mode | Access mode
fcd-open-mode | Open mode
fcd-name-length | Length of filename
fcd-lock-mode | Lock mode flags
fcd-other-flags | Other flags
fcd-file-format | File format
fcd-max-rec-length | Maximum record length
fcd-recording-mode | Recording mode
fcd-min-rec-length | Minimum record length
fcd-filename-address | Pointer to the filename area
fcd-key-def-address | Pointer to the key definition block (I)
fcd-data-compress | Data compression
fcd-locktypes | Type of file locks

Output Fields

fcd-file status | File status
fcd-open-mode | Open mode
fcd-handle | Pointer to the file; use for all subsequent accesses to this file

Comments

You must have set up a key definition block for this file if it is an indexed file.

You can assign several FCDs to the same physical file and have them all open at the same time. The operating system counts it as just one open file. The physical file is not closed until every logical file assigned to it has been closed.

Parent topic: Standard Operation Codes


READ

For sequential access, makes available the next or previous logical record from a file. For random access, makes available a specified record from a disk file.

Opcode | Operation | File Types
8D | READ(sequential) WITH NO LOCK | L S R I
D8 | READ (sequential) WITH LOCK | L S R I
D9 | READ (sequential) WITH KEPT LOCK | L S R I
F5 | READ (sequential) | L S R I
8C | READ PREVIOUS WITH NO LOCK | R I
DE | READ PREVIOUS WITH LOCK | R I
DF | READ PREVIOUS WITH KEPT LOCK | R I
F9 | READ PREVIOUS | R I
8E | READ (random) WITH NO LOCK | R I
DA | READ (random) WITH LOCK | R I
DB | READ (random) WITH KEPT LOCK | R I
F6 | READ (random) | R I
8F | READ (direct) WITH NO LOCK | L S R I
D6 | READ (direct) WITH LOCK | L S R I
D7 | READ (direct) WITH KEPT LOCK | L S R I
C9 | READ (direct) | L S R I
F1 | READ (position) | L S R I

Input Fields

fcd-relative-key | Relative record number (R) if READ random or direct
fcd-key-id | Key identifier (I)
fcd-record-address | Pointer to the record area

Output Fields

fcd-file status | File status
fcd-current-rec-len | Current record length
fcd-reladdr-offset or fcd-reladdr-big | Relative byte address
Parent topic: Standard Operation Codes


REWRITE

Replaces an existing record in a file.

Opcode | Operation | File Types
F4 | REWRITE | L S R I

Input Fields

cfd-relative-key | Relative record number (R)
fcd-current-rec-len | Current record length
fcd-record-address | Pointer to the record area

Output Fields

fcd-file-status | File status
fcd-reladdr-offset or fcd-reladdr-big | Relative byte address
Parent topic: Standard Operation Codes


ROLLBACK

Releases all record locks in all files held by this run unit.

Opcode | Operation | File Types
DD | ROLLBACK (unlocks all files) | L S R I

Input Fields

None

Output Fields

None

Comments

This operation code requires an FCD for one of the files, but it can be completely empty.

Parent topic: Standard Operation Codes


START

Provides a basis for logical positioning in a relative or indexed file, for subsequent retrieval of records.

Opcode | Operation | File Types
E8 | START equal to full length prime key | R I
E9 | START equal to (any key/record number) | R I
EA | START greater than (>) | R I
EB | START not less than (>=) | R I
FE | START less than (<) | R I
FF | START less than or equal to (<=) | R I

Input Fields

fcd-relative key | Relative record number (R)
fcd-key id | Key identifier (I)
fcd-key-length | Effective key length (I)
fcd-record-address | Pointer to the record area

Output Fields

fcd-file status File status
Parent topic: Standard Operation Codes


STEP

Steps to the next, previous, first or last physical record in the file . This operation enables very fast access to a record.

Opcode | Operation | File Types
90 | STEP NEXT WITH NO LOCK | L S R I
91 | STEP PREVIOUS WITH NO LOCK | L S R I
92 | STEP FIRST WITH NO LOCK | L S R I
93 | STEP LAST WITH NO LOCK | L S R I
CA | STEP NEXT | L S R I
CB | STEP PREVIOUS | L S R I
CC | STEP FIRST | L S R I
CD | STEP LAST | L S R I
CE | STEP LAST WITH LOCK | L S R I
CF | STEP LAST WITH KEPT LOCK | L S R I
D0 | STEP FIRST WITH LOCK | L S R I
D1 | STEP FIRST WITH KEPT LOCK | L S R I
D2 | STEP PREVIOUS WITH LOCK | L S R I
D3 | STEP PREVIOUS WITH KEPT LOCK | L S R I
D4 | STEP NEXT WITH LOCK | L S R I
D5 | STEP NEXT WITH KEPT LOCK | L S R I

Input Fields

fcd-record-address Pointer to the record area

Output Fields

fcd-file-status File status

Comments

STEP operations are a method of sequentially retrieving records in a relative or indexed file without having to read via a key or relative record number. Generally, this is a faster method of accessing data in the file.

A STEP NEXT operation returns the record that is physically stored immediately after the one that was last retrieved in the file (either by a STEP or READ operation).

A STEP PREVIOUS operation returns the record that is physically stored immediately before the one that was last retrieved in the file (either by a STEP or READ operation).

A STEP FIRST operation returns the record at the beginning of the file.

A STEP LAST operation returns the record at the end of the file.

If you are using relative byte addressing and you have specified that the current record pointer should be updated to the record you have just accessed, STEP operations are relative to this new position.

The relative byte address is returned on every STEP operation, so if you need to update the current record pointer to the record just retrieved, you can use the READ (direct) operation using the address returned.

Note:

The current record pointer is not affected by STEP operations.

Parent topic: Standard Operation Codes


UNLOCK

Releases all record locks held by the run unit on a named file.

Opcode | Operation | File Types
0E | UNLOCK | L S R I

Input Fields

None

Output Fields

fcd-file-status File status
Parent topic: Standard Operation Codes


WRITE

Writes a new record to a file.

For sequential files, it can also be used for vertical positioning of lines in a logical page.

Opcode | Operation | File Types
E1 | WRITE BEFORE | L S
E2 | WRITE AFTER | L S
E3 | WRITE BEFORE TAB | L S
E4 | WRITE AFTER TAB | L S
E5 | WRITE BEFORE PAGE | L S
E6 | WRITE AFTER PAGE | L S
EC | WRITE BEFORE mnemonic-name | S
ED | WRITE AFTER mnemonic-name | S
F3 | WRITE | L S R I

Input Fields

cfd-relative-key | Relative record number (R)
fcd-current-rec-len | Current record length
fcd-line-count | Line count (WRITE only) (S)
fcd-record-address | Pointer to the record area

Output Fields

fcd-file-status | File status
fcd-reladdr-offset or fcd-reladdr-big | Relative byte address
Parent topic: Standard Operation Codes


Special Operation Codes

Not all operation codes are appropriate with all file organizations. Each operation code description includes a list of the file organizations for which it is valid.

  • Special Operation Codes - Overview
  • File Information
  • Create Index File
  • Get Next Record
  • Add Key Value
  • Re-index File
  • Flush File
  • Unlock Record
Parent topic: Operation Codes


Special Operation Codes - Overview

Special operation codes contain x"00" in the most significant byte. The least significant byte indicates the specific operation.

File Information | Returns general file information for all file organizations with headers and, for indexed files, information on the file keys in the form of the Key Definition Block.
Get Next Record | Gets the next physical record from the data file part of an indexed file.
Add Key Value | Adds a key value to the index file part of an indexed file.
Re-index File | Re-indexes the file using a supplied key definition block.
Flush File | Flushes all data for a specific file to disk.
Unlock Record | Unlocks a specific record in a file.

Not all operation codes are appropriate with all file organizations. Each operation code description includes a list of the file organizations for which it is valid, using the following key:

L | Line sequential
S | Record sequential (including vS)
R | Relative (including vR)
I | Indexed
vS | Record sequential variable format only
vR | Relative variable format only
Parent topic: Special Operation Codes


File Information

Returns general file information for all file organizations with headers and, for indexed files, information on the file keys in the form of the key definition block.

Opcode | Operation | File Types
06 | Return file information | I vS vR

Input Fields

fcd-organization | File organization (can be x"FF")
fcd-name-length | Length of filename
fcd-filename-address | Pointer to the filename area
fcd-key-def-address | Pointer to the key definition block (I)

Output Fields

Key definition block (I) |
fcd-file-status | File status
fcd-organization | File organization
fcd-file-format | File format
fcd-max-rec-length | Maximum record length
fcd-recording-mode | Recording mode
fcd-min-rec-length | Minimum record length
fcd-reladdr-offset or fcd-reladdr-big | File size
fcd-data-compress | Data compression routine

It is your responsibility to ensure that you have enough space allocated for the key definition block to hold all the information returned. Failure to allocate enough space causes corruption of some data areas.

For variable-length sequential files and variable-length relative files, no key definition information exists.

If you can set the organization byte of the FCD to x"FF" before using this operation code, an attempt is made to determine the file type and return with the relevant information set. This mode of operation is not recommended if you use any fixed-length sequential files as it might be impossible to determine the difference between the first record of a fixed-length sequential file and the header of a variable-length sequential file. If the file type cannot be determined, the error code 9/161 is returned.

Parent topic: Special Operation Codes


Create Index File

Creates a new .idx file, containing only header information for the file to allow new indexes to be added.

Opcode | Operation | File Types
07 | Open new index | I

Input Fields

As OPEN.

Output Fields

As OPEN

Parent topic: Special Operation Codes


Get Next Record

Gets the next physical record from the data file part of an indexed file.

Opcode | Operation | File Types
08 | Get next record | I

Input Fields

fcd-record-address Pointer to the record area

Output Fields

fcd-file-status | File status
fcd-current-rec-len | Current record length
fcd-reladdr-offset or fcd-reladdr-big | Relative byte address
Parent topic: Special Operation Codes


Add Key Value

Adds a key value to the index file part of an indexed file.

Opcode | Operation | File Types
09 | Add key value | I

Input Fields

fcd-key-id | Key identifier
fcd-record-address | Pointer to the record area

Output Fields

fcd-file-status File status
Parent topic: Special Operation Codes


Re-index File

Re-indexes the file using a supplied key definition block.

Opcode | Operation | File Types
0B | Re-index file | I

Input Fields

Offset 64 Pointer to key definition block.

Output Fields

None
Parent topic: Special Operation Codes


Flush File

Flushes all data for a specific file to disk.

Opcode | Operation | File Types
0C | Flush File | L S R I

Input Fields

None

Output Fields

fcd-file-status File status
Parent topic: Special Operation Codes


Unlock Record

Unlocks a specific record in a file.

Opcode | Operation | File Types
0F | Unlock record | I

Input Fields

fcd-record-address Pointer to the record area

Output Fields

fcd-file-status File status
Parent topic: Special Operation Codes


FSView

  • FSVIEW API
  • FSVIEW Command Line
Parent topic: File Handling Reference


FSVIEW API

  • FSVIEW 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-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).
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:

FSV-C-add-login-user  using      l-new-user-name
                                        l-new-password-name

Parameters:

l-new-user-name
pic x(20)
l-new-password
pic x(20)

On Entry:

l-new-user-name
The new user name
l-new-password
The password associated with the new user

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:

FSV-C-add-to-dbase-list list using      number-of-entries
                                        fsvw-data-block

Parameters:

number-of-entries | pic xx comp-x.
fsvw-data-block | A group item defined as:
fsvw-insert-list-box-item ( i ) | occurs 10.

See the topic FSVIEW Datablock for a complete definition of fsvw-data-block.

On Entry:

number-of-entries | The number of entries
fsvw-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:

FSV-C-add-to-user-list using      number-of-entries
                                  fsvw-data-block

Parameters:

number-of-entries | pic xx comp-x.
fsvw-data-block | A group item defined as:
fsvw-insert-list-box-item ( i ) | occurs 10.

See the topic FSVIEW Datablock for a complete definition of fsvw-data-block.

On Entry:

number-of-entries | The number of entries
fsvw-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:

FSV-C-add-to-file-list using      number-of-entries
                                  fsvw-data-block

Parameters:

number-of-entries | pic xx comp-x.
fsvw-data-block | A group item defined as:
fsvw-insert-list-box-item ( i ) | occurs 10

See the topic FSVIEW Datablock for a complete definition of fsvw-data-block.

On Entry:

number-of-entries | The number of entries
fsvw-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:

call FSV-C-change-server using      l-server-name
                                    l-user-name
                                    l-server-password

Parameters:

l-server-name | pic x(20).
l-user-name | pic x(20).
l-server-password | pic x(20).

On Entry:

l-server-name | The name of the server
l-user-name | The user ID
l-server-password | The password associated with the user ID

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:

call FSV-C-check-password using      l-server-password

Parameters:

l-server-password pic x(20)

On Entry:

l-server-password The FSVIEW password

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:

call FSV-C-get-comms-info using      fsvw-data-block

Parameters:

fsvw-data-block | A group item defined as:
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).

See the topic FSVIEW Datablock for a complete definition of fsvw-data-block.

On Entry:

None.

On Exit:

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

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:

call FSV-C-get-database-info using      fsvw-data-block

Parameters:

fsvw-data-block | A group item defined as:
fsvw-dbase-filename | pic x(255).
fsvw-dbase-filename-size | pic x(2) comp-x.
fsvw-dbase-filesize | pic x(16).

See the topic FSVIEW Datablock for a complete definition of fsvw-data-block.

On Entry:

None.

On Exit:

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

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

call FSV-C-get-log-file-info using      fsvw-data-block

Parameters:

fsvw-data-block | A group item defined as:
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).

See the topic FSVIEW Datablock for a complete definition of fsvw-data-block.

On Entry:

None.

On Exit:

fsvw-log-filename | The log file name of the server currently selected
fsvw-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:

call FSV-C-get-open-files using fsvw-data-block

Parameters:

fsvw-data-block | A group item defined as:
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).

See the topic FSVIEW Datablock for a complete definition of fsvw-data-block.

On Entry:

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.

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

call FSV-C-get-server-info using      fsvw-data-block

Parameters:

fsvw-data-block | A group item defined as:
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.

See the topic FSVIEW Datablock for a complete definition of fsvw-data-block.

On Entry:

None.

On Exit:

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

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:

call FSV-C-get-user-info using      fsvw-data-block

Parameters:

fsvw-data-block | A group item defined as:
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).

See the topic FSVIEW Datablock for a complete definition of fsvw-data-block.

On Entry:

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.

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:

call FSV-C-logoff-user using      l-user-id

Parameters:

l-user-id pic 9(5).

On Entry:

l-user-id The user ID of the user to be logged off

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

  • 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


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.

Parent topic: FSVIEW Command Line
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).

Parent topic: FSVIEW Command Line
Related reference
Admin logon
Exit
Help
Server get
Server set
Server shutdown


Exit

Exits FSVIEW.

Syntax:

exit

Parameters:

None.

Parent topic: FSVIEW Command Line
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
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


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
Related reference
File close
Files get


Files get

Gets the list of open files.

Syntax:

files get

Parameters:

None.

Parent topic: FSVIEW Command Line
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
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
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
Related reference
Logfile autorename


Opentrace toggle

Toggles the XFH open trace.

Syntax:

opentrace toggle

Parameters:

None.

Parent topic: FSVIEW Command Line
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
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
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
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
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
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
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
Related reference
Server get
Server set
Admin password


Trace toggle

Toggles the Fileshare trace.

Syntax:

trace toggle

Parameters:

None.

Parent topic: FSVIEW Command Line
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
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
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
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
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
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

00
Successful completion if ISAM is utilized.
If Database Connector interfaces are utilized, data has been duplicated in the secondary key.
02
Indexed files only. One of two possibilities: For a READ statement, the key value for the current key is equal to the value of that same key in the next record in the current key of reference. For a WRITE or REWRITE statement, the record just written created a duplicate key value for at least one alternate record key for which duplicates are allowed.
04
The length of the record being processed does not conform to the fixed file attributes for that file.
05
The referenced optional file is not present at the time the OPEN statement is executed.
07
Sequential files only. For an OPEN or CLOSE statement with the REEL/UNIT phrase the referenced file is a non-reel/unit medium.
10
No next logical record exists. You have reached the end of the file.
14
Relative files only. The number of significant digits in the relative record number is larger than the size of the relative key data item described for that file.
21
Sequentially accessed files only. Indicates a sequence error. The ascending key requirements of successive record key values has been violated, or, the prime record key value has been changed by a COBOL program between successful execution of a READ statement and execution of the next REWRITE statement for that file.
22
Indexed and relative files only. Indicates a duplicate key condition. Attempt has been made to store a record that would create a duplicate key in the indexed or relative file OR a duplicate alternate record key that does not allow duplicates.
23
Indicates no record found. An attempt has been made to access a record, identified by a key, and that record does not exist in the file. Alternatively a START or READ operation has been tried on an optional input file that is not present.
24
Relative and indexed files only. Indicates a boundary violation arising from one of the following conditions: an attempt is made to write beyond the externally defined boundaries of a file; a sequential WRITE operation has been tried on a relative file, but the number of significant digits in the relative record number is larger than the size of the relative key data item described for the file.
30
The I/O statement was unsuccessfully executed as the result of a boundary violation for a sequential file or as the result of an I/O error, such as a data check parity error, or a transmission error.
34
The I/O statement failed because of a boundary violation. This condition indicates that an attempt has been made to write beyond the externally defined boundaries of a sequential file.
35
An OPEN operation with the I-O, INPUT, or EXTEND phrases has been tried on a non-OPTIONAL file that is not present.
37
An OPEN operation has been tried on a file which does not support the open mode specified in the OPEN statement.
38
An OPEN operation has been tried on a file previously closed with a lock.
39
A conflict has been detected between the fixed file attributes and the attributes specified for that file in the program.
41
An OPEN operation has been tried on a file already opened.
42
A CLOSE operation has been tried on a file already clsoed.
43
Files in sequential access mode. The last I/O statement executed for the file, before the execution of a DELETE or REWRITE statement, was not a READ statement.
44
A boundary violation exists. Possible violations are:
  • An attempt has been made to WRITE or REWRITE a record that is larger than the largest, or smaller than the smallest record allowed by the RECORD IS VARYING clause of the associated file.
  • An attempt has been made to REWRITE a record to a file, and the record is not the same size as the record being replaced.
46
A sequential READ operation has been tried on a file open in the INPUT or I-O mode but no valid next record has been established.
47
A READ or START operation has been tried on a file not opened INPUT or I-O.
48
A WRITE operation has been tried on a file not opened in the OUTPUT, I-O, or EXTEND mode, or on a file open I-O in the sequential access mode.
49
A DELETE or REWRITE operation has been tried on a file that is not opened I-O.
Parent topic: File Status


Extended File Status Codes

When using ANSI'74 or ANSI'85 file status codes, run-time system returns extended file status codes if the extended file status is more specific.

Extended file status codes are of the form:

9/nnn

where nnn is a numeric value that is the same as the numeric value of the corresponding run-time system error. For example, if an extended file status code of 9/029 is returned, run-time system error COBRT029 (Attempt to delete open file) provides more information about the cause.

Parent topic: File Status
Related concepts
Run-time System Error Messages


Microsoft COBOL V2 File Status Codes

Status Key 1 | Status Key 2 | Description
0 | 0 | Successful completion.
 | 2 | Duplicate key and duplicates are allowed.
1 | 0 | End of file.
2 | 1 | Sequence error in writing sequential access file.
 | 2 | Duplicate key and duplicates are not allowed.
 | 3 | Key not found.
 | 4 | Disk space full.
3 | 0 | Permanent error or file not found.
 | 4 | Disk space full.
9 | 1 | File structure error.
 | 4 | File or record locked.
 | 5 | Indexed file system not available.
Parent topic: File Status


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 DOS or Windows the default record delimiter is the carriage return/line feed character specified by the byte pair x"ODA". 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"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
  • 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. 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. Indexed files only.
22 | 14 | Reserved.
36 | 2 | Reserved. Value 62 decimal; x"00 3E".
38 | 1 | Not used. Set to zeros.
39 1 Organization:
  1. Sequential
  2. Indexed
  3. Relative
40 | 1 | Not used. Set to zeros.
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 | Not used. Set to zeros.
43 | 1 | Indexed files only - type of indexed file.
44 | 4 | Reserved.
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 | Not used. Set to zeros.
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 | Not used. Set to zeros.
108 | 4 | Version and build data for the indexed file handler creating the file. Indexed files only.
112 | 16 | Not used. Set to zeros.
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.

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


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
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
Parent topic: 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: 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 | Length of the file header.
39 | 1 | Always contains value 2 for indexed organization.
62 | 14 | Always contains zeros.
76 | 1 | Reserved. Set to 4.
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 | Value zeros.
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", 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" 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", 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" 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: 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

A number of limits affect file handling.

  • 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" or IDXFORMAT"8" directive | 4,294,967,297
Components in a split key: With IDXFORMAT"4" or IDXFORMAT"8" directive
 | (using Micro Focus format file) | 62
 | (using C-ISAM format file) | 8

Record sizes

All file types 62 KB

Sort keys

Sort key size | 4096
Number of sort keys | 64
Parent topic: Limits


File Size Limits - General

The following limits affect file size in general:
  • 32-bit Windows platforms impose a file size limit of 4 Gbytes.
  • 64-bit Windows platforms allow for very large file sizes.
Note: the default kernel settings 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 | 4 Gb | 2 Gb | 1 Gb | 4
8 | 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 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 | 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 supports very large files with the default locking mechanism. Therefore, you are recommended to use IDXFORMAT 8 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 reconstruct 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 - /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:
  • 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.
Parent topic: Rebuild Command Line Options
Related reference
Rebuild through Fileshare


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

Default

When /e is not set, Rebuild ends with an "Error on output file - status 22" error.

Parent topic: Rebuild Command Line Options


Rebuild Options - /f

Validates an indexed file.

If the file is corrupt, Rebuild returns a non-zero value.

Parameters

c
Specifies the validation to be performed. The default is 10.
Value | Description
2 | Checks the structure of the free space list (FSL).
8 | Checks the index file structure.
256 | Checks the data file structure with file open for sharing in another process. You cannot specify this check in combination with any other check.
0 | Nothing.
1 | Error messages only.
2 | Messages showing the options you have specified.
3 | Information about the file. This includes key definition, records lengths, data compression, and the version of the file handler that created and updated the file.
4 The different types of record present in the file:
  1. IDXFORMAT"4" information record.
  2. Deleted record.
  3. System record.
  4. Data record that has been reduced in size by a rewrite.
  5. Data record that has been increased in size by a rewrite, and therefore cannot fit into the original record area. Instead, this record points to another record area that contains the record.
  6. The record pointed to by a type 6 record.
  7. The record pointed to by a type 6 record.
  8. The record pointed to by a type 6 record.
5 | Statistics about each key structure. This includes information about how much space is being saved by key compression.
You can select a combination of checks 2 and 8 by adding the numbers together. The more checks you perform, the longer the validation takes.
d
Specifies the message level.
These values are cumulative, so if you specify level 4, you will also receive messages at levels 1, 2 and 3. The default is 5.
Value | Description
0 | Nothing.
1 | Error messages only.
2 | Messages showing the options you have specified.
3 | Information about the file. This includes key definition, records lengths, data compression, and the version of the file handler that created and updated the file.
4 The different types of record present in the file:
  1. IDXFORMAT"4" information record.
  2. Deleted record.
  3. System record.
  4. Data record that has been reduced in size by a rewrite.
  5. Data record that has been increased in size by a rewrite, and therefore cannot fit into the original record area. Instead, this record points to another record area that contains the record.
  6. The record pointed to by a type 6 record.
  7. The record pointed to by a type 6 record.
  8. The record pointed to by a type 6 record.
5 | Statistics about each key structure. This includes information about how much space is being saved by key compression.

Examples

rebuild test.dat -f:c8

checks the structure of the index file.

rebuild test.dat -f:d1

specifies error messages only.

rebuild test.dat -f:c2d1

checks the structure of the FSL and specifies error messages only.

rebuild test.dat -f

Performs a full integrity check on a file, displaying all possible information. This is the same as specifying -f:c10.

Note:

The display might end with one of the following messages:

File is corrupt

This means that the control information in the file is not consistent with the data. For example, a record may have been deleted but the list of deleted records does not include it. Such a file is reported as corrupt, even though the data itself is not corrupt.

File contains transaction data

This means that the control information may not be consistent with the data because the file contains records which were part of a Fileshare transaction which was not subject to a successful COMMIT or ROLLBACK.

For example, a record may have been written as part of a transaction, but a system failure caused Fileshare to stop processing before the transaction was COMMITed. If you are not using Fileshare Roll-Forward recovery, you can use rebuild to remove this transaction data by using the /d option and rebuilding to a new file. Note to quickly recover the file to a usable state that you can rebuild to the same file, this will recreate the index correctly (treating transaction data as deleted records) but the transaction record data will remain in the file, the space will not be reused and rebuild /f will continue to report that the “File contains transaction data”.

Parent topic: Rebuild Command Line Options
Related information
Overview of Rebuild command line options


Rebuild Options - /i

Displays information about the input and output files, including record lengths, file type and key structure.

If you want to display this information but do not want to perform any other processing, use the /n option instead.

Parent topic: Rebuild Command Line Options
Related reference
Rebuild Options - /n


Rebuild Options - /k

Defines the key structure of an indexed file.

The key structure is used to rebuild the index of an indexed file when the original index is missing or corrupt.

When converting non-indexed files to indexed files, this option is required to specify the key information for the new output file.

You can also use this option to

  • Replace the key structure of an existing indexed file with an alternative structure
  • Convert one indexed file to another with a different key structure.
  • Add a new key to an indexed file or remove an existing key without having to rebuild to a new file

Each key is defined by its starting character position within the record (the first character position in a record is 1) and its length in characters. The starting position and length must be separated by a plus sign (+) or the letter L.

The definition of one key is separated from the definition of the next key by a colon (:).

Each key can be defined as a number of parts (split key), each part being separated by a comma (,).

Alternate keys (those other than the first defined) can be terminated by the parameter d, indicating WITH DUPLICATES.

You can use the s parameter to specify a sparse key. The s parameter must be followed by the sparse character itself. If the sparse character is non-printable, or a lower or upper case 'd', the s parameter must be followed by d value, where value is the decimal value of the sparse character.

Different key compression values can be specified for each key by using the c parameter, indicating compression. The c parameter must be followed by a key compression value between 0 and 7.

You can add or remove a key without having to rebuild to a new file or specify all the keys again. To add a key you use the a parameter; to remove a key you use the r parameter. You can only add or remove one key at a time, and you can only rebuild in place. You cannot use any other functions when you are adding or removing a key

Examples

  • This example defines a single key, starting at character position 1 and 20 characters in length.
    -k:1+20
  • This example defines three keys. The first key, the primary key, starts at character position 5 and is 5 characters in length; the second key, an alternate key allowing duplicates, starts at character position 20 and is 1 character in length; the third key, a split alternate key, has two parts, the first starting at character position 40 and 2 characters in length and the second starting at character position 43 and 10 characters in length.
    -k:5+5:20+1d:40+2,43+10
  • This example defines two keys. The first key, the primary key, starts at character position 1 and is 5 characters in length; the second key, an alternate, sparse key allowing duplicates, starts at character position 20 and is 10 characters in length, the sparse character is Z.
    -k:1+5:20+10dsZ
  • This example defines two keys. The first key, the primary key, starts at character position 1 and is 5 characters in length. The second key, an alternate, sparse key allowing duplicates, starts at character position 20 and is 10 characters in length; the sparse character is the null character.
    -k:1+5:20+10dsh0
  • This example defines two keys. The first key, the primary, starts at character position 1 and is 10 characters in length. The second key, an alternate compressed key allowing duplicates, starts at character position 11 and is 20 characters in length. The types of key compression being used are compression of duplicates (1) and compression of leading characters (2).
    -k:1+10:11+20dc3
  • This example adds a new key which allows duplicates. The key starts at character position 1 and is 3 characters in length.
    -k:a:1+3d
  • This example removes the key that starts at character position 10 and is 5 characters in length.
    -k:r:10+5
  • This example shows how to correctly rebuild the index of an index file when the original index is missing. Use the s parameter to select an idxformat 4 index.
    Note: When the index is missing you should specify the key information exactly as the original key specification for idxformat 4 files, as the data file contains control information related to keys which allow duplicates. If the new key information does not exactly match, it can result in file corruptions or loss of data. We recommend you use the f parameter to validate the rebuild once the new key has been created.
    rebuild infile.dat, outfile.dat -k:1+5:6:10d -s:MF4
Parent topic: Rebuild Command Line Options


Rebuild Options - /l

Specifies the loading and unloading of files.

Use the /l option when you are loading to and unloading from IDXFORMAT 9 files.

For loading, you need to define the record size and key definition (one key only).

All records must be the key order of the target file and there must be no records which result in duplicate keys.

You do not need to define the record size and key definition for unloading.

Parameters

r9 | Load a record sequential file to an IDXFORMAT 9 file
9r | Unload an IDXFORMAT 9 file to a record sequential file

Examples

rebuild /l:r9 file1, file2 /k:1+10 /r:v20-30

This example loads a record sequential file to an IDXFORMAT 9 file, with the key structure specified by the /k option and the recording mode and record lengths specified with the /r option.

rebuild /l:9r file1, file2

This example unloads an IDXFORMAT 9 file to a record sequential file.

Parent topic: Rebuild Command Line Options


Rebuild Options - /n

Displays information about a file.

The /n option displays the same information as the /i option, plus the number of data records in the file, but without performing any other processing.

Parent topic: Rebuild Command Line Options
Related reference
Rebuild Options - /i


Rebuild Options - /o

Specifies the organization of the input and output files.

If the input file is line sequential and the record contains COMP or COMP-3 items, the file must have been created with the INSERTNULL configuration option set to ON. If the file has been created with INSERTNULL set to OFF, or has come from a third party and does not precede non-printable characters with null bytes, the file will not be correctly processed if the COMP/COMP-3 items contain bytes with the values x"00", x"09" (tab), x"0A" (newline) or x"0D" (carriage return).

Parameters

/o:infile-org[,outfile-org]

infile-org and outfile-org can be any of the following:

Value | Description
lseq | line sequential
seq | sequential
rel | relative
ind | indexed

This format enables you to convert from any one file organization to another.

If outfile-org is omitted, the output file will have the same organization as the input file.

Using this syntax, you can convert a line sequential file to an indexed file, or an indexed file to a variable sequential file, and so on.

Examples

rebuild in-file, out-file /o:lseq,ind /t:mf /k:1+10 /r:v20-30

converts a line sequential file to an indexed file with the key structure specified by the /k option, the file format specified by the /t option, and the recording mode and recording lengths specified by the /r option. The key information must be wholly contained within the minimum record length.

rebuild in-file, out-file /o:ind,seq /r:v20-30

converts an indexed file to a variable length sequential file with the recording mode and record lengths specified by the /r option.

Parent topic: Rebuild Command Line Options


Rebuild Options - /p

Instructs Rebuild to rebuild an IDXFORMAT"8" file in place.

The rebuild uses less disk space, but if it fails the file is lost. You must back up the file before you attempt a rebuild with this option.

Parent topic: Rebuild Command Line Options


Rebuild Options - /r

Defines the record structure of the input and output files.

You can specify a different record structure for the output file, and if the record length of the output file is greater than the record length of the input file, you can specify a padding character. You need to specify the record structure of the input file only where the file does not have a header. If you do not specify the record structure of the output file it will have the same structure as the input file. If you only specify one record structure, it is taken to be the record structure of the output file, unless the input file has no header, in which case it is taken to be the record structure of the input file.

Parameters

frecord-length | specifies a fixed-length record format with records of record-length
vmin-record-length-max-record-length | specifies a variable-length format where min-record-length is the minimum record length and max-record-length is the maximum record length. Separate the lengths with a hyphen
ppad-character|[ddecimal-value] | specifies the padding character where the output record length is greater than the input record length. The default is spaces for line sequential files and NULLs for all other file organizations. d indicates that the padding character is supplied as a decimal value in the range 0 through 255, indicating the ANSI character to be used

Examples

r:f100

(where the input file has no header) specifies that the input file has a fixed record length of 100 bytes and that the output file will have the same fixed record length.

-r:v100-200

(where the input file has a header) specifies that the output file will have a variable record length with a minimum record length of 100 bytes and a maximum record length of 200 bytes.

r:f20,f30pZ

specifies that the input file has a fixed record length of 20 bytes, and that the output file will have a fixed record length of 30 bytes with Z used as a padding character.

r:f40pd49

specifies that the output file will have a fixed record length of 40 bytes with the character "I" used as a padding character.

Parent topic: Rebuild Command Line Options


Rebuild Options - /s

Specifies the format of the input file.

Parameters

/s:lii
/s:l2
/s:mf
/s:mf4
/s:mf8
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:lii
/t:l2
/t:mf
/t:mf4
/t:mf8
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.

Parent topic: Rebuild Command Line Options


Rebuild Options - /z

Instructs Rebuild to use a Fileshare server for file access.

Use this option for using Rebuild through Fileshare.

Parameters

/z:server-name
server-name The name of a Fileshare server.
Parent topic: Rebuild Command Line Options


Rebuild Options - //q

Suppresses the display of the Rebuild banner.

Parent topic: Rebuild Command Line Options


Rebuild Options - //v

Displays the version number of Rebuild.

Parent topic: Rebuild Command Line Options


Rebuild Error, Information and Warning Messages

Rebuild may output error, information or warning messages when rebuilding, converting or reorganizing an indexed file.

Also, when Rebuild encounters a problem, it searches for the next good record and writes it to a file called rebuild.1af.

  • Syntax Errors
    These occur when an error is encountered, the command line is displayed with a caret (^) symbol under the point at which the error was detected and error message is displayed.
  • Execution Errors
    These occur when the program sets the return code to a value other than zero to indicate the type of error that has occurred.
  • Information Messages
    These messages are displayed for information purposes only.
  • Warning Messages
    Depending on the operation selected, some command line options are unnecessary. In these cases, the incorrect usage will be indicated, but the option will be ignored and processing will continue. Note that the option may be correct, but omission of other information may have caused Rebuild to select the wrong process. If this is the case, correct the command line and rerun.
Parent topic: File Handling Reference


Syntax Errors

These occur when an error is encountered, the command line is displayed with a caret (^) symbol under the point at which the error was detected and error message is displayed.

If an error in the syntax of the command line occurs, the return code will be set to 9.

  • Key positions must be specified using /k option
    You did not supply a key definition for the index of the file being generated from a sequential or relative file, or from an indexed file with a missing .idx component
  • Data compression out of range
    The integer you specified for data compression is not within the allowable range.
  • Data compression specified more than once
    You have specified the option for data compression more than once; that is, /c:[dn][dn]
  • Input file same as output file
    You have given the output file the same name as the input file.
  • Index compression out of range
    The integer you specified for index compression is not within the allowed range.
  • Index compression specified more than once
    You have specified the option for index compression more than once; that is, /c[in][in].
  • Invalid command line
    The command line contains an error other than those described in more specific syntax error messages.
  • Invalid compression choice - must be 'd' or 'i'
    The specification of data or index compression was not correct.
  • Invalid format
    The value you specified for index file format is invalid.
  • Invalid key length - cannot be zero
    One of the keys you defined has a zero length, which is illegal. This may be due to incorrect use of separator characters.
  • Invalid key specification - key not contained in record
    One of the keys, as defined, is not wholly contained in the record. This is illegal.
  • Invalid key start - cannot be zero
    One of the keys defined has a start character position of zero, which is illegal. This may be due to incorrect use of separator characters.
  • Invalid key structure - '+' expected
    A key part parameter of the /k option is incorrect.
  • Invalid option
  • Invalid organization
    The syntax of the /o option is incorrect.
  • Invalid organization - must be indexed for index rebuild
    You have specified a non-indexed input file with no output file. If there is no output file Rebuild assumes that you want to rebuild an indexed file.
  • Invalid record length - cannot be zero
    You have specified that the length of a record is zero. This is invalid.
  • Invalid record lengths - maximum must not be less than minimum
    The integers you have used to specify the maximum and minimum lengths of a record indicate that the maximum length is less than the minimum length. This is invalid.
  • Invalid record parameter - '-' expected
    When specifying the record structure of a variable length file, you have not separated the minimum record length and the maximum record length with a hyphen (-).
  • Invalid record type - 'F' or 'V' expected
    You have entered record type other than fixed or variable. This is invalid.
  • Invalid format
    The format of the /s or /t option is incorrect.
  • No output file specified for /t option to refer to
    You did not specify a name for the output file which was referred to with the /t option.
  • No output file specified for data compression
    You did not specify an output filename for data compression.
  • Number expected
    You have specified another character where a number was expected.
  • Output organization was specified but not output file name
    You did not supply a filename although you specified an output organization.
  • Options file not found
    The options file specified on the command line cannot be found.
Parent topic: Rebuild Error, Information and Warning Messages


Key positions must be specified using /k option

You did not supply a key definition for the index of the file being generated from a sequential or relative file, or from an indexed file with a missing .idx component

Resolution:

Specify a key definition.

Parent topic: Syntax Errors


Data compression out of range

The integer you specified for data compression is not within the allowable range.

Resolution:

Data compression requires an integer in the range 0 through 255.

Parent topic: Syntax Errors


Data compression specified more than once

You have specified the option for data compression more than once; that is, /c:[dn][dn]

Resolution:

Use the correct format: /c:[dn][in]

Parent topic: Syntax Errors


Input file same as output file

You have given the output file the same name as the input file.

Resolution:

Use a different output filename.

Parent topic: Syntax Errors


Index compression out of range

The integer you specified for index compression is not within the allowed range.

Resolution:

Specify an integer in the range 0 through 15.

Parent topic: Syntax Errors


Index compression specified more than once

You have specified the option for index compression more than once; that is, /c[in][in].

Resolution:

Use the correct format: /c:[dn][in].

Parent topic: Syntax Errors


Invalid command line

The command line contains an error other than those described in more specific syntax error messages.

Resolution:

Check the syntax, spelling, and spacing in the command line you are trying to enter.

Parent topic: Syntax Errors


Invalid compression choice - must be 'd' or 'i'

The specification of data or index compression was not correct.

Resolution:

Specify the d or i parameter.

Parent topic: Syntax Errors


Invalid format

The value you specified for index file format is invalid.

Resolution

Specify a valid value: C-ISAM, CISAM, MF, MF4, MF8, 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, 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.

The file definition block is a table of pointers to the FCDs for each of the USING and GIVING files involved in the sort operation. The fcd-fildef-address field in the Sort FCD is a pointer to this area. The length of the file definition block is four times the total of the contents of the fields at offsets 52 and 53.

Parent topic: Callable Sort Module
Related information
Key Definition Block


SORT Environment Variables

The following environment variables can be used for configuring SORT:

  • 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 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.
  • TEMPDIR/ TMP/ TEMP
    Determines where the run-time system of the directory stores paging files.
Parent topic: Sorting Files


MFJSERET

Determines the response to an unsuccessful sort, copy or merge operation.

If this environment variable is not set, an unsuccessful operation and its program will terminate with an unrecoverable error (return code 16).

Parameters

ABEND
The operation will abend and its program will continue instead of terminating with an unrecoverable error (return code 16)

The default is that the variable is not set.

Example

MFJSERET=ABEND
Parent topic: SORT Environment Variables
Related reference
MFJSTATS
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
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.

The default is OFF.

Example

MFJSSTRICTSORT=ON
Parent topic: SORT Environment Variables
Related reference
MFJSTATS
MFJSERET
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


MFJSTATS

Produces a report for the 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
Parent topic: SORT Environment Variables
Related reference
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


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 reference
MFJSTATS
MFJSERET
MFJSSTRICTSORT
TEMPDIR/ TMP/ TEMP
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 reference
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
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 reference
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTEMPSPACE
SORTSPACE
SORTCOMPRESS


SORTSPACE

Determines the amount of memory allocated to internal workspace for SORT operations.

Typically, increasing SORTSPACE will improve the overall performance of SORT operations. This can be improved further by the use of SORTSCHEME when the files to be sorted are over 1GB.

Parameters

workspace size

Specify the amount of memory in one of the following formats:

Format | Workspace size
64M | 64 megabytes
2G | 2 gigabytes
1000000 | 1,000,000 bytes

The default value is 1,048,576 bytes (1MB).

The minimum value is 65,536 bytes (64KB).

The maximum value is 4,294,967,295 bytes (4GB - 1 byte).

Examples

SORTSPACE=64M
SORTSPACE=2G
SORTSPACE=1000000
Parent topic: SORT Environment Variables
Related reference
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTEMPSPACE
SORTSCHEME
SORTCOMPRESS


SORTTEMPSPACE

Determines the amount of temporary memory allocated for SORT operations.

If you cannot set SORTSPACE to allocate enough contiguous memory for a SORT operation, set SORTTEMPSPACE to the required amount, and then reduce the amount allocated by SORTSPACE. The memory required for the SORT operation can then be allocated in smaller chunks.

We recommend that you use SORTTEMPSPACE only if you are receiving COBRT105 Memory allocation error (Fatal) errors.

Parameters

workspace size

Specify the amount of memory in one of the following formats:

Format | Workspace size
64M | 64 megabytes
2G | 2 gigabytes
1000000 | 1,000,000 bytes

The default value is 1,048,576 bytes (1MB).

The minimum value is 65,536 bytes (64KB).

The maximum value is 4,294,967,295 bytes (4GB - 1 byte).

Example

SORTTEMPSPACE=64M
Parent topic: SORT Environment Variables
Related reference
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
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 reference
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


Mfsort Error Messages

Select the range containing your message number:

  • Messages 0001 to 0099
  • Messages 0100 to 0199
  • Messages 0200 to 0399
Parent topic: Sorting Files


Messages 0001 to 0099

Select the number of the message you require details about:

  • SORT011U SYSIN dataset value missing
  • SORT012U SYSIN dataset value missing
  • SORT013U I/O error on dataset value
  • SORT014U Status = value
  • SORT015U Command statement error(s) detected
    The sort will not execute because of errors found during the parsing of the command.
  • SORT019I Key length truncated to 4096 bytes
  • SORT020U SORT(EXTSM) failed - sort engine status = Value
    An unexpected failure occured after the sort had been initiated. This message indicates the returned sort file status value.
  • SORT032I Number records sorted
  • SORT033I Number records merged
  • SORT034I Number records copied
  • SORT036U SORTIN record length missing or invalid
    You did not specify a record length in the RECORD instruction, or else you specified an invalid length.
  • SORT037U SYSIN RECFM value invalid
  • SORT038U SORTIN RECFM value invalid
    The record format in the RECORD instruction for the input file is invalid.
  • SORT039U SORTOUT RECFM value invalid
    The record format in the RECORD instruction for the output file is invalid.
  • SORT040U SORT terminated by E15 Operator
    The user exit routine E15 has terminated the sort process.
  • SORT041U SORT terminated by E35 Operator
    The user exit routine E35 has terminated the sort process.
  • SORT042U Memory allocation failure
    The mfsort utility was unable to allocate the required memory.
  • SORT043U Too many OUTFIL files specified
    You have specified too many files in the OUTFIL option.
  • SORT044U Too many USE files specified
    You have specified too many files in the USE instruction.
  • SORT045U Too many GIVE files specified
    You have specified too many files in the GIVE instruction.
  • SORT050U ICETOOL input file not found
    The file that is to be sorted has not been found.
  • SORT051U ICETOOL output file not found
    The definition for the output file has not been found.
  • SORT090U SORT terminated - missing SYSOUT
    No catalog entry has been found for the SYSOUT file.
  • SORT091U SORT terminated - missing SYSIN
  • SORT092U SORT terminated - missing SORTOUT
  • SORT093U SORT terminated - missing SORTIN or SORTIN01
  • SORT094U SORT terminated - missing SORTOFvalue
  • SORT095U SORT terminated - Bad data in CHANGE field
    Please see the CHANGE and DFSORT documentation on the Micro Focus Web site.
  • SORT096U SORT terminated - missing FNAMES dataset value
    Please see the FNAMES and DFSORT documentation on the Micro Focus Web site.
Parent topic: Mfsort Error Messages


SORT011U SYSIN dataset value missing

Parent topic: Messages 0001 to 0099


SORT012U SYSIN dataset value missing

Parent topic: Messages 0001 to 0099


SORT013U I/O error on dataset value

Parent topic: Messages 0001 to 0099


SORT014U Status = value

Parent topic: Messages 0001 to 0099


SORT015U Command statement error(s) detected

The sort will not execute because of errors found during the parsing of the command.

Parent topic: Messages 0001 to 0099


SORT019I Key length truncated to 4096 bytes

Parent topic: Messages 0001 to 0099


SORT020U SORT(EXTSM) failed - sort engine status = Value

An unexpected failure occured after the sort had been initiated. This message indicates the returned sort file status value.

Resolution:

Investigate the file status. See the topic File Status.

Parent topic: Messages 0001 to 0099
Related information
File Status


SORT032I Number records sorted

Parent topic: Messages 0001 to 0099


SORT033I Number records merged

Parent topic: Messages 0001 to 0099


SORT034I Number records copied

Parent topic: Messages 0001 to 0099


SORT036U SORTIN record length missing or invalid

You did not specify a record length in the RECORD instruction, or else you specified an invalid length.

Resolution:

Provide or correct the record length and resubmit the sort.

Parent topic: Messages 0001 to 0099


SORT037U SYSIN RECFM value invalid

Parent topic: Messages 0001 to 0099


SORT038U SORTIN RECFM value invalid

The record format in the RECORD instruction for the input file is invalid.

Resolution:

Correct the record format and resusbmit the sort.

Parent topic: Messages 0001 to 0099


SORT039U SORTOUT RECFM value invalid

The record format in the RECORD instruction for the output file is invalid.

Resolution:

Correct the record format and resusbmit the sort.

Parent topic: Messages 0001 to 0099


SORT040U SORT terminated by E15 Operator

The user exit routine E15 has terminated the sort process.

Parent topic: Messages 0001 to 0099


SORT041U SORT terminated by E35 Operator

The user exit routine E35 has terminated the sort process.

Parent topic: Messages 0001 to 0099


SORT042U Memory allocation failure

The mfsort utility was unable to allocate the required memory.

Resolution:

Try reducing the value of the SORTSPACE environment variable.

Parent topic: Messages 0001 to 0099
Related reference
Environment variables


SORT043U Too many OUTFIL files specified

You have specified too many files in the OUTFIL option.

Resolution:

Respecify your mfsort command with an OUTFIL instruction that names up to 100 files.

Parent topic: Messages 0001 to 0099


SORT044U Too many USE files specified

You have specified too many files in the USE instruction.

Resolution:

Respecify your mfsort command with a USE instruction that names up to 100 files.

Parent topic: Messages 0001 to 0099


SORT045U Too many GIVE files specified

You have specified too many files in the GIVE instruction.

Resolution:

Respecify your mfsort command with a GIVE instruction that names up to 100 files.

Parent topic: Messages 0001 to 0099


SORT050U ICETOOL input file not found

The file that is to be sorted has not been found.

Parent topic: Messages 0001 to 0099


SORT051U ICETOOL output file not found

The definition for the output file has not been found.

Parent topic: Messages 0001 to 0099


SORT090U SORT terminated - missing SYSOUT

No catalog entry has been found for the SYSOUT file.

Parent topic: Messages 0001 to 0099


SORT091U SORT terminated - missing SYSIN

Parent topic: Messages 0001 to 0099


SORT092U SORT terminated - missing SORTOUT

Parent topic: Messages 0001 to 0099


SORT093U SORT terminated - missing SORTIN or SORTIN01

Parent topic: Messages 0001 to 0099


SORT094U SORT terminated - missing SORTOFvalue

Parent topic: Messages 0001 to 0099


SORT095U SORT terminated - Bad data in CHANGE field

Please see the CHANGE and DFSORT documentation on the Micro Focus Web site.

Parent topic: Messages 0001 to 0099


SORT096U SORT terminated - missing FNAMES dataset value

Please see the FNAMES and DFSORT documentation on the Micro Focus Web site.

Parent topic: Messages 0001 to 0099


Messages 0100 to 0199

Select the number of the message you require details about:

  • SORT100E Missing operator
    An operator was expected but was not found. An operator identifies the type of operation to be performed, SORT or MERGE.
  • SORT101E Malformed operator
  • SORT102E Expected operand missing
  • SORT103E Invalid operator operator
    You have specified an unexpected operator in a command file.
  • SORT104E Invalid operand keyword keyword
    You have specified unexpected syntax in the middle of an instruction.
  • SORT105E Expected continuation not present
    The sort instruction is not complete and is not continued on the next line.
  • SORT106E Field formats improperly specified
    You specified an invalid data type in the FIELDS instruction.
  • SORT107E Field format field-format invalid
    You specified invalid data in the FIELDS instruction.
  • SORT108E Sequence sequence invalid
    You specified an invalid sort order in FIELDS instruction..
  • SORT109E Too many fields specified
    You specified too many fields. The maximum is 100.
  • SORT110E Non-numeric data detected
    Non-numeric data was read where numeric data was expected.
  • SORT111E operator operator already processed
    You have already specified this instruction or parameter to an instruction.
  • SORT112E exit exit not supported
    You tried to use a user exit that is not supported.
  • SORT114E Expected '(' not found
    You specified an instruction that takes multiple parameters inside parentheses, but the opening parenthesis was not found.
  • SORT115E Boolean operator operator invalid
    The combination of format and bit operator is invalid.
  • SORT118E SORT / MERGE conflict
    You have specified both SORT and MERGE.
  • SORT119E INCLUDE / OMIT conflict
    You have specified both INCLUDE and OMIT.
  • SORT120E SORT statement missing FIELDS operand
    You have omitted the FIELDS instruction.
  • SORT121E MERGE statement missing FIELDS operand
    You have omitted the FIELDS instruction.
  • SORT122E INCLUDE statement missing COND operand
    You have omitted the COND parameter from the INCLUDE instruction.
  • SORT123E OMIT statement missing COND operand
    You have omitted the COND parameter from the INCLUDE instruction.
  • SORT124E FIELD position field-position invalid
    The starting position of the field is greater than the record length.
  • SORT125E FIELD length field-length invalid
    The field length is invalid in the FIELDS instruction.
  • SORT126E RECORD length record-length invalid
  • SORT127E Missing SORT/MERGE/COPY command statement
    You have not specified a SORT or a MERGE or a COPY instruction.
  • SORT128E Expected ')' not found
    You specified an instruction that takes multiple parameters inside parentheses, but the closing parenthesis was not found.
  • SORT129E Expected '=' not found
    You specified an instruction that takes multiple parameters specified using keyword=value pairs. No = sign was found.
  • SORT130E Expected 'F' OR 'V' not found
    The format parameter in the RECORDS instruction was not followed by F (for fixed) or V(for variable).
  • SORT131E Expected 'IX', 'RL', 'SQ', or 'LS' not found
    You have specified an ORG instruction for the USE or GIVE instruction but have not specified one of the above options.
  • SORT132E Prime key must be specified first
    The primary key was not specified first in the KEY instruction.
  • SORT133E Expected 'P', 'AD', 'A', or 'C' not found
    You have specified a KEY instruction for an indexed file in the GIVE instruction but have not specified one of the above options.
  • SORT134E Keyword/value value invalid for DFSORT emulation
    You have specififed a keyword=value pair that is invalid in mfsort's emulation of DFSORT.
  • SORT135E Keyword/value value invalid for SYNCSORT emulation
    You have specififed a keyword=value pair that is invalid in mfsort's emulation of SYNCSORT.
  • SORT136E No GIVE file specified for OUTFIL group
    You have not specified a GIVE file for the OUTFIL option.
  • SORT137E No USE file specified
    You have not specified a USE file.
  • SORT138E Target literal literal too long in CHANGE
    The target literal for the parameter CHANGE is too long.
  • SORT139E Substring comparison must be with character literal
    In the substring comparison of an INCLUD or OMIT condition, you have not specified a character literal for the right-hand side of the comparison.
  • SORT140E Invalid binary digit detected
  • SORT141E Cannot specify SAVE with either INCLUDE or OMIT
    In an OUTFIL group, you have specified SAVE with both INCLUDE and OMIT.
  • SORT142E Repeated FILE= or FNAMES=
  • SORT191I Operator operator ignored
    You have specified syntax that is not supported.
  • SORT192I Operand operand ignored
    You have specified syntax that is not supported.
  • SORT193E Invalid hex digit detected
  • SORT194 I No ALTSEQ command specified for 'AQ' SORT field formats; 'CH' assumed
  • SORT196E SUM / COPY conflict
    You have specified SUM together with the COPY option.
  • SORT197E INREC / MERGE conflict
  • SORT198E Non-numeric data detected in 'ZD' SUM field
  • SORT199E Too many OUTFIL statements
Parent topic: Mfsort Error Messages


SORT100E Missing operator

An operator was expected but was not found. An operator identifies the type of operation to be performed, SORT or MERGE.

Resolution:

Ensure that your SORT or MERGE instruction appears between columns 2 and 71 on the command line.

Parent topic: Messages 0100 to 0199


SORT101E Malformed operator

Parent topic: Messages 0100 to 0199


SORT102E Expected operand missing

Parent topic: Messages 0100 to 0199


SORT103E Invalid operator operator

You have specified an unexpected operator in a command file.

Resolution:

Resubmit the command file after removing the invalid operator.

Parent topic: Messages 0100 to 0199


SORT104E Invalid operand keyword keyword

You have specified unexpected syntax in the middle of an instruction.

Resolution:

Respecify the command removing the invalid keyword.

Parent topic: Messages 0100 to 0199


SORT105E Expected continuation not present

The sort instruction is not complete and is not continued on the next line.

Resolution:

Provide a complete instruction, using a continuation line if necessary.

Parent topic: Messages 0100 to 0199


SORT106E Field formats improperly specified

You specified an invalid data type in the FIELDS instruction.

Parent topic: Messages 0100 to 0199


SORT107E Field format field-format invalid

You specified invalid data in the FIELDS instruction.

Parent topic: Messages 0100 to 0199


SORT108E Sequence sequence invalid

You specified an invalid sort order in FIELDS instruction..

Resolution:

Resubmit the sort specifying either A (ascending) or D (descending).

Parent topic: Messages 0100 to 0199


SORT109E Too many fields specified

You specified too many fields. The maximum is 100.

Parent topic: Messages 0100 to 0199


SORT110E Non-numeric data detected

Non-numeric data was read where numeric data was expected.

Parent topic: Messages 0100 to 0199


SORT111E operator operator already processed

You have already specified this instruction or parameter to an instruction.

Resolution:

Remove the duplication and resubmit.

Parent topic: Messages 0100 to 0199


SORT112E exit exit not supported

You tried to use a user exit that is not supported.

Resolution:

Only user exits E15 and E35 are supported.

Parent topic: Messages 0100 to 0199


SORT114E Expected '(' not found

You specified an instruction that takes multiple parameters inside parentheses, but the opening parenthesis was not found.

Parent topic: Messages 0100 to 0199


SORT115E Boolean operator operator invalid

The combination of format and bit operator is invalid.

Parent topic: Messages 0100 to 0199


SORT118E SORT / MERGE conflict

You have specified both SORT and MERGE.

Resolution:

Respecify the command using either SORT or MERGE.

Parent topic: Messages 0100 to 0199


SORT119E INCLUDE / OMIT conflict

You have specified both INCLUDE and OMIT.

Resolution:

Respecify the command using either INCLUDE or OMIT.

Parent topic: Messages 0100 to 0199


SORT120E SORT statement missing FIELDS operand

You have omitted the FIELDS instruction.

Parent topic: Messages 0100 to 0199


SORT121E MERGE statement missing FIELDS operand

You have omitted the FIELDS instruction.

Parent topic: Messages 0100 to 0199


SORT122E INCLUDE statement missing COND operand

You have omitted the COND parameter from the INCLUDE instruction.

Parent topic: Messages 0100 to 0199


SORT123E OMIT statement missing COND operand

You have omitted the COND parameter from the INCLUDE instruction.

Parent topic: Messages 0100 to 0199


SORT124E FIELD position field-position invalid

The starting position of the field is greater than the record length.

Parent topic: Messages 0100 to 0199


SORT125E FIELD length field-length invalid

The field length is invalid in the FIELDS instruction.

Parent topic: Messages 0100 to 0199


SORT126E RECORD length record-length invalid

Parent topic: Messages 0100 to 0199


SORT127E Missing SORT/MERGE/COPY command statement

You have not specified a SORT or a MERGE or a COPY instruction.

Resolution:

Respecify the mfsort command using one of these instructions.

Parent topic: Messages 0100 to 0199


SORT128E Expected ')' not found

You specified an instruction that takes multiple parameters inside parentheses, but the closing parenthesis was not found.

Parent topic: Messages 0100 to 0199


SORT129E Expected '=' not found

You specified an instruction that takes multiple parameters specified using keyword=value pairs. No = sign was found.

Parent topic: Messages 0100 to 0199


SORT130E Expected 'F' OR 'V' not found

The format parameter in the RECORDS instruction was not followed by F (for fixed) or V(for variable).

Parent topic: Messages 0100 to 0199


SORT131E Expected 'IX', 'RL', 'SQ', or 'LS' not found

You have specified an ORG instruction for the USE or GIVE instruction but have not specified one of the above options.

Resolution:

Respecify the ORG instruction for the USE or GIVE instruction using one of the options IX, RL, SQ, or LS.

Parent topic: Messages 0100 to 0199


SORT132E Prime key must be specified first

The primary key was not specified first in the KEY instruction.

Resolution:

Reorganise the key definition so that you specify the primary key first.

Parent topic: Messages 0100 to 0199


SORT133E Expected 'P', 'AD', 'A', or 'C' not found

You have specified a KEY instruction for an indexed file in the GIVE instruction but have not specified one of the above options.

Resolution:

Respecify the KEY for the GIVE instruction using one of P, AD, A, or C.

Parent topic: Messages 0100 to 0199


SORT134E Keyword/value value invalid for DFSORT emulation

You have specififed a keyword=value pair that is invalid in mfsort's emulation of DFSORT.

Parent topic: Messages 0100 to 0199


SORT135E Keyword/value value invalid for SYNCSORT emulation

You have specififed a keyword=value pair that is invalid in mfsort's emulation of SYNCSORT.

Parent topic: Messages 0100 to 0199


SORT136E No GIVE file specified for OUTFIL group

You have not specified a GIVE file for the OUTFIL option.

Resolution:

Specify the GIVE file.

Parent topic: Messages 0100 to 0199


SORT137E No USE file specified

You have not specified a USE file.

Resolution:

Specify one or more USE files.

Parent topic: Messages 0100 to 0199


SORT138E Target literal literal too long in CHANGE

The target literal for the parameter CHANGE is too long.

Parent topic: Messages 0100 to 0199


SORT139E Substring comparison must be with character literal

In the substring comparison of an INCLUD or OMIT condition, you have not specified a character literal for the right-hand side of the comparison.

Resolution:

Respecify the substring comparison, replacing its right-hand side with a character literal.

Parent topic: Messages 0100 to 0199


SORT140E Invalid binary digit detected

Parent topic: Messages 0100 to 0199


SORT141E Cannot specify SAVE with either INCLUDE or OMIT

In an OUTFIL group, you have specified SAVE with both INCLUDE and OMIT.

Resolution:

Respecify the SAVE instruction with either INCLUDE or OMIT.

Parent topic: Messages 0100 to 0199


SORT142E Repeated FILE= or FNAMES=

Parent topic: Messages 0100 to 0199


SORT191I Operator operator ignored

You have specified syntax that is not supported.

Parent topic: Messages 0100 to 0199


SORT192I Operand operand ignored

You have specified syntax that is not supported.

Parent topic: Messages 0100 to 0199


SORT193E Invalid hex digit detected

Parent topic: Messages 0100 to 0199


SORT194 I No ALTSEQ command specified for 'AQ' SORT field formats; 'CH' assumed

Parent topic: Messages 0100 to 0199


SORT196E SUM / COPY conflict

You have specified SUM together with the COPY option.

Resolution:

Respecify your mfsort command with either SUM or COPY.

Parent topic: Messages 0100 to 0199


SORT197E INREC / MERGE conflict

Parent topic: Messages 0100 to 0199


SORT198E Non-numeric data detected in 'ZD' SUM field

Parent topic: Messages 0100 to 0199


SORT199E Too many OUTFIL statements

Parent topic: Messages 0100 to 0199


Messages 0200 to 0399

Select the number of the message you require details about:

  • SORT200E Bad or unknown symbol
  • SORT201E No previous offset defined for symbols
  • SORT202E No previous length defined for symbols
  • SORT203E No previous format defined for symbols
  • SORT204I *********************Sort Statistics*********************
  • SORT205I INPUT file filename
  • SORT206I OUTPUT file filename
  • SORT207I OUTFIL file filename
  • SORT214I Format operand ignored
  • SORT215E Reformatting field error
  • SORT216I Record type is V - Data starts at position 5
    You specified variable organisation for a file and also a start position in the FIELDS instruction before position 5.
  • SORT217I Record length L1 or L3 overridden
  • SORT232E Field length exceeds maximum allowed
  • SORT399I End of Micro Focus MFJSORT Utility
Parent topic: Mfsort Error Messages


SORT200E Bad or unknown symbol

Parent topic: Messages 0200 to 0399


SORT201E No previous offset defined for symbols

Parent topic: Messages 0200 to 0399


SORT202E No previous length defined for symbols

Parent topic: Messages 0200 to 0399


SORT203E No previous format defined for symbols

Parent topic: Messages 0200 to 0399


SORT204I *********************Sort Statistics*********************

Parent topic: Messages 0200 to 0399


SORT205I INPUT file filename

Parent topic: Messages 0200 to 0399


SORT206I OUTPUT file filename

Parent topic: Messages 0200 to 0399


SORT207I OUTFIL file filename

Parent topic: Messages 0200 to 0399


SORT214I Format operand ignored

Parent topic: Messages 0200 to 0399


SORT215E Reformatting field error

Parent topic: Messages 0200 to 0399


SORT216I Record type is V - Data starts at position 5

You specified variable organisation for a file and also a start position in the FIELDS instruction before position 5.

This message is followed by message SORT217I Record length L1 or L3 overridden.

Parent topic: Messages 0200 to 0399


SORT217I Record length L1 or L3 overridden

Parent topic: Messages 0200 to 0399


SORT232E Field length exceeds maximum allowed

A sum field is longer than 18 digits. This is the maximum size of any numeric string used in MFJSORT.

Parent topic: Messages 0200 to 0399


SORT399I End of Micro Focus MFJSORT Utility

Parent topic: Messages 0200 to 0399


Integrated Preprocessor Interface

  • Overview - Integrated Preprocessor Interface
  • Invoking a Preprocessor
  • Writing a Preprocessor
  • CP Preprocessor
  • Example Integrated Preprocessor
  • COBOL Preprocessor Error Messages
Parent topic: General Reference


Overview - Integrated Preprocessor Interface

Note: The Integrated Preprocessor is supported for native COBOL only.

Language preprocessors (also known as precompilers) are used to convert non-standard COBOL, or non-COBOL code embedded in COBOL, into a form that the Compiler can process.

A non-integrated preprocessor takes as input a source file, reads and parses it, and produces a modified source file which is then passed as input to the COBOL compiler. This has the following disadvantages:

  • There are two steps involved in compiling a program
  • There can be no integration between the Compiler and editor; for example if an error occurs during compilation there is no possibility of the editor highlighting the original source line in error
  • Listing output and debugging tools do not show the original source program

These factors can significantly lengthen the development cycle.

The Integrated Preprocessor Interface overcomes these problems by enabling the preprocessor to mark the relationship between the original source code and the modified form. Although the Compiler will actually process the modified COBOL, it will only ever show the original code.

The Integrated Preprocessor Interface enables a preprocessor to read source files and pass modified source lines to the Compiler. This makes the interface completely general purpose. The disadvantage of this approach is that the preprocessor itself has to handle COBOL constructs such as continuation, copybook expansion and the effects of REPLACE and REPLACING. Micro Focus provides the CP preprocessor, which can handle REPLACE and REPLACING, although this does require that COPY statements conform to normal COBOL syntax rules. If, by comparison, the Compiler read source files and passed single tokens to the preprocessor, restrictions such as the format of a token and the syntax of a COPY (or equivalent) statement would be imposed.

The underlying code that is actually compiled might be significantly different from the original. You might therefore notice that:

  • The debugger cannot query a data item, as the data item does not exist in the underlying code.
  • The debugger does not reference lines that were modified by the preprocessor, as the compiler does not process these lines and is unaware of their contents.
  • An accurate cross reference listing is not produced by the XREF Compiler because information for code inserted by the preprocessor is not shown, even if the original source line referenced the same data items.
  • Certain directives, most notably FLAG and language switches such as MF, cause the Compiler to reject or flag code produced by a preprocessor, whether integrated or not. The Integrated Preprocessor Interface eases the task of preventing such problems by:
    • Never flagging lines inserted by a preprocessor
    • Enabling the preprocessor to query Compiler directive settings.

    A preprocessor can generate lines containing $SET statements to switch directive settings, but this might cause problems, especially if your code uses names for data items that conflict with reserved words in the language selected by the preprocessor.

A supplied preprocessor reads and expands source files (including copybooks), and returns additional information to other preprocessors in the stack about the effect of REPLACE and REPLACING.

Parent topic: Integrated Preprocessor Interface
Related reference
The COPY Statement
The REPLACE Statement
FLAG
MF, MFLEVEL
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
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

Note:

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.

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.

Parent topic: Writing a Preprocessor
Related information
FLAG
MF, MFLEVEL
The REPLACE Statement
The COPY Statement


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 they 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; andl tells the preprocessor to abort
3 | resp-main of 17 supported

Preprocessor support levels

response-code-2 | Feature
32767 or less | Base level
32768 | Compiler might tell the preprocessor to abort
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 seperated 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.
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
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
FLAG
MF, MFLEVEL
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 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
  • It is not designed to accept program source containing double-byte character set (DBCS) characters
  • Copybook Expansion
  • REPLACE Notification
  • CP Directives
Parent topic: Integrated Preprocessor Interface
Related concepts
Using the CP Preprocessor to Expand Copybooks
Preprocessor Response Codes
Related information
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
FLAG
MF, MFLEVEL
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.

  • CONFIRM, C
    Specifies whether directives are to be shown on the screen if accepted.
  • 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


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


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


Example Integrated Preprocessor

Note: The Integrated Preprocessor is supported for native COBOL only.

There are two example integrated preprocessors for you to look at; these have been designed to be stacked. Also provided are an example source program and an example copybook for the preprocessors to process. By copying and pasting these, you could create projects to contain these files and see how they work, or you could create your own preprocessors based on these examples.

The example preprocessors can be used as a basis for other preprocessors. They demonstrate the following:

  • How the preprocessor is invoked and opens source input
  • How source is passed without editing to the Compiler
  • How source is edited and then passed to the Compiler
  • How lines containing more than one verb are expanded
  • How COPY statements are processed
  • How warnings and errors are produced
  • How preprocessors can be stacked

Specification of the Example Preprocessors

The example preprocessors recognize and process several verbs as follows:

  • MOV is converted to MOVE
  • DIS is converted to two lines, the first being DISPLAY SPACE UPON CRT and the second containing the original line with the word DIS replaced by DISPLAY
  • PRINT is converted to DISPLAY
  • CPY is converted to COPY, and thus expanded by the Compiler: COPY is expanded by the preprocessor
  • WARN causes a warning message to be placed in the listing file
  • ERROR causes a serious error message to be displayed. If you request that compilation should continue, the serious error count is increased.

In order to demonstrate stackable preprocessors, these functions are split into two separate programs. The two preprocessors are very similar, containing much common code.

The preprocessors include an example of a lexical analyzer for COBOL, which handles lexical tokens that do not continue across records.

Example Programs

The files asmcobol.cbl and working.cbl contain commands that can be interpreted by preprocessing the files using compiled versions of the Preproc or Preprox example preprocessors.

  • To build the demonstration preprocessor
  • To debug the demonstration preprocessor
Parent topic: Integrated Preprocessor Interface
Related tasks
To build the demonstration preprocessor
To debug the demonstration preprocessor
Related reference
FLAG
MF, MFLEVEL


To build the demonstration preprocessor

  1. From the Example Integrated Preprocessor topic, create the files preproc.cbl, working.cbl and asmcobol.cbl.
  2. Create a new project.
  3. Add preproc.cbl to this project.
  4. Ensure that the build settings for preproc.cbl use the MF dialect.
  5. Build the project.
  6. Create a second new project.
  7. Place the asmcobol.cbl and working.cbl files in the same folder as the new project file. Do not place them in a separate source folder.
  8. Add asmcobol.cbl to this project.
  9. Ensure that the build settings for asmcobol.cbl use the MF dialect.
  10. Specify the folder where asmcobol.cbl is as a Copybook folder. This enables the COBOL development system to find working.cbl.
  11. Edit asmcobol.cbl and comment out the $SET statement at the top of the program.
  12. In the build settings for asmcobol.cbl add the following directives:
    p (absolute_directory_path\preproc.int) endp

    For example:

    p (c:\mfuser\projects\preproc\loadlib\preproc.int) endp

    You specify the location of preproc.int in this way rather than in the $SET statement you deleted at step 10 because the preprocessor's parsing is quite basic and cannot handle the colon in the path-name.

  13. Build the project.

    You can now use the preprocessor.

Parent topic: Example Integrated Preprocessor
Related reference
FLAG
MF, MFLEVEL
Example Integrated Preprocessor


To debug the demonstration preprocessor

  1. From the Example Integrated Preprocessor topic, create the files preproc.cbl, working.cbl and asmcobol.cbl.
  2. Edit preproc.cbl to specify the following as the first statement in the START-PARA section:
    call "CBL_DEBUGBREAK" end-call

    This a call to the COBOL run-time system to invoke the COBOL debugger.

  3. Perform the relevant steps from the topic To build the demonstration preprocessor. If you have already created the projects, you will just need to rebuild the project containing preproc.cbl.

    When you debug the second project, the call to CBL_DEBUGBREAK that you inserted at step 2 invokes the debugger, enabling you to debug the preprocessor code.

Parent topic: Example Integrated Preprocessor
Related reference
FLAG
MF, MFLEVEL
Example Integrated Preprocessor


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
  • NLS Message-file Handling 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
  • 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 Windows, 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 may be greater than 4Gb
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.

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 | Read/write files greater than 4Gb
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.

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

  • 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


PC_WIN_CHAR_TO_OEM

Translates a buffer of ANSI characters into the OEM character set.
Note: This routine is not supported in JVM COBOL.

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.
Note: This routine is not supported in JVM COBOL.

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.
Note: This routine is not supported in JVM COBOL.

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.

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.

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.

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.

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.
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-LEVFLGS-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-LEVFLGS-LEVEL-INFO
                            by reference " "

 call "CBL_CTF_LEVEL" using by value 0
                            by value 78-LEVFLGS-LEVEL-WARNING
                            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.

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.
  • CBL_DEBUG_START
    Enables a COBOL program to initiate advanced remote debugging or cross-session debugging.
  • CBL_DEBUG_STOP
    Enables a COBOL program to stop or suspend animation.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_DEBUGBREAK

Enables a COBOL program to invoke the debugger.

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. If the program is not being debugged when it calls CBL_DEBUGBREAK, it starts the debugger and then comes to a halt, as if you had been debugging it already and then pressed the Stop button on the toolbar.

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.

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 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 and the specified timeout has elapsed.
0
Start local 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.
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. 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.

Parent topic: Debugging Routines
Parent topic: Alphabetical List of Library Routines
Related reference
Setting Run-time Switches
A1 run-time switch
Related information
Overview - Debugging Native COBOL Programs


CBL_DEBUG_STOP

Enables a COBOL program to stop or suspend animation.
Note: This routine is supported for native COBOL only.

Syntax:

CALL "CBL_DEBUG_STOP" using  by value    flags
                               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)
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 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.
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.

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

Note: This routine is supported for 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.

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

Note: This routine is supported for 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

Restriction: These routines are supported for native COBOL only.

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.

Note: This routine is supported for native COBOL only.

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 the chapter Adis 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.

The chapter Adis describes the features and parameter in detail.

Parent topic: Enhanced ACCEPT and DISPLAY Syntax Routines
Parent topic: Alphabetical List of Library Routines


X"A7" function 18

Makes console I/O redirectable.

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

Note: This routine is supported for native COBOL only.

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.

Note: This routine is supported for native COBOL only.

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.

Note: This routine is supported for native COBOL only.

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


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

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.

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.

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.

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. For native Windows projects this is the filename only, for JVM and UNIX projects it is the filename with relative path.
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.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


CBL_DIR_SCAN_START

Initializes a search for a file or directory.

Syntax:

CALL "CBL_DIR_SCAN_START" using  by reference   handle
                                                pattern
                                 by value       search-attribute
                                                flags
                                 returning      search-status

Parameters:

handle
usage pointer.
pattern
A group item containing the following subordinate items:
01 pattern
  03 pattern-length   cblt-x2-comp5. *> pic x(2) comp-5
  03 pattern-content  pic x(n)
search-attribute
Call prototype: cblt-x4-comp5
Picture: pic x(4) comp-5
search-status
See Library Routines - Key

On Entry:

pattern-length
Length of pattern string in the pattern-content field. It is associated with the handle and cannot be changed during a scan. A length of zero indicates a null-terminated pattern-content field. You can set pattern-length to less than the length of the pattern-content field, but not to more.
pattern-content
String for name searches. It is associated with the handle and cannot be changed during a scan. Can contain a full or partial directory path with or without a filename or just a filename. Elements in a path must be separated by "\". Null-terminated strings are recognised if the null is before the end of the string as provided in pattern-length, or if pattern-length is set to zero. If you set bit 1 of flags, the filename can contain wildcard characters: "*" means any arbitrary sequence of characters and "?" means any single character. If you set bit 0 flags the pling character "!" is available for use as an escape character. For more information about using wildcards and escape characters see the section Comments below.
search-attribute
Can be used to specify file properties to be searched for. It is associated with the handle and cannot be changed during a scan. Valid values are:
Value | Bit Set | Meaning
1 | 0 | Search for a file.
2 | 1 | Search for a directory.
4 | 2 | Search for any entry that is neither a file or a directory.
Bits above those specified are ignored. Bits 0 to 2 are always combined by OR, for example, to search for either a file or a directory set bits 0 and 1 (value 3). To search for all types of entry set bits 0, 1 and 2 (value 7).
flags
You can set one of the following values:
Value | Bit Set | Meaning
1 | 0 | Turns on processing of escape sequences in pattern-content. The default is no processing of escape sequences.
2 | 1 | Turns on the use of wildcards in the pattern-content field. Wildcards have significance as such only if this option is set.
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.

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
Group item defined as
01 actual-file-spec
   03 buffer-len   cblt-x2-compx   pic x(2) comp-x.
   03 buffer       pic x(n).       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.
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, please refer to the section File Striping in the chapter File Handler Configuration of your File Handling book.

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.

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:

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.

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.

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.

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:

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.

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

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)
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. The default is 65536, and the minimum is 8192 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.

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

Note: These routines are not supported in JVM COBOL.

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

Note: These routines are not supported in JVM COBOL.
  • 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
Multi-threading Routines


CBL_THREAD_CREATE

Creates a thread from a named entry point.
Note: This routine is not supported in JVM COBOL.

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 locked by this thread when the thread terminates can cause a run-time system error.
1 | An error will not be issued if monitors are locked when the thread terminates
Bit 3
0 Create active
1 Create suspended
Restriction: This is deprecated in the .NET environment
Bit 4
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.
Note: This routine is not supported in JVM COBOL.

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 locked by this thread when the thread terminates can cause a run-time system error.
1 | An error will not be issued if monitors are locked when the thread terminates
Bit 3
0 Create active
1 Create suspended
Restriction: This is deprecated in the .NET environment
Bit 4
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.

Note: This routine is not supported in JVM COBOL.

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.

Note: This routine is not supported in JVM COBOL.

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.
Note: This routine is not supported in JVM COBOL.

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.

Note: This routine is not supported in JVM COBOL.

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.

Note: This routine is not supported in JVM COBOL.

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.
Restriction: This routine is not currently supported in COBOL for JVM.

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.

Note: This routine is not supported in JVM COBOL.

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 | Detached
1 | Not 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.

Note: This routine is not supported in JVM COBOL.

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 | Detached
1 | Not 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.

Note: This routine is not supported in JVM COBOL.

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.

Note: This routine is not supported in JVM COBOL.

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


CBL_THREAD_SLEEP

Causes the calling thread to give up control to the processor for the given number of milliseconds.
Note: This routine is not supported in JVM COBOL.

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.

Note: This routine is not supported in JVM COBOL.

Syntax:

call "CBL_THREAD_WAIT" using by value thread-id
                       by reference   thr-return
                       returning      status-code

Parameters:

 | Using call prototype (see Key) | Picture
thread-id | cblt-pointer | usage pointer.
thr-return | cblt-pointer | usage pointer.

On Entry:

thread-id A pointer to the thread identifier

On Exit:

thr-return | The thread's return value.
status-code | See RETURN-CODE Values For Thread-control Routines

Comments:

The behavior of this routine is undefined if:

  • thread-id is invalid.
  • thread-id specifies a previously detached thread.
  • Two threads attempt to use CBL_THREAD_WAIT and/or CBL_THREAD_DETACH on the same thread at the same time.
  • While in a CBL_THREAD_WAIT, the target thread is killed by CBL_THREAD_KILL.

If the routine is successful, the thread's return value is stored in thr-return, the target thread is detached, and the call returns 0.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_YIELD

Yields the rest of the current thread's timeslice.

Syntax:

call "CBL_THREAD_YIELD"

Parameters:

None.

On Exit:

return-code A value indicating whether the routine has succeeded or not. See RETURN-CODE Values For Thread-control Routines

Comments:

If possible this routine yields to other threads in the same process, but might yield to a thread in a different process.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


RETURN-CODE Values For Thread-control Routines

The following values are provided as RETURN-CODE values from the thread-control routines:

0 | No error was encountered.
1000 | Memory allocation error.
1001 | The thread is invalid. The handle is not a valid handle for the synchronization object, and no operations are valid on it. It is possible that the handle specified was once valid but it has been closed and memory reused.
1002 | The thread has been closed. No operations are valid on this handle. The handle was once valid but has since been closed.
1003 | The thread is detached. CBL_THREAD_DETACH cannot detach the thread since it has already been detached. CBL_THREAD_WAIT cannot wait on the thread since it has already been detached.
1004 | Too many threads. CBL_THREAD_CREATE cannot create another thread since too many threads exist in the system already.
1005 | The stack size is invalid. CBL_THREAD_CREATE cannot create this thread as the operating system will not allow the provided stack size to be used.
1006 | Invalid operation. CBL_THREAD_CREATE cannot create a thread while the system is deinitializing. or: An invalid thread-control routine was attempted on a thread that was not created with CBL_THREAD_CREATE. or: CBL_THREAD_PROG_LOCK was not called directly or indirectly from a COBOL program.
1007 | A system error was encountered. The last operation caused a system error in low level object manipulation.
1008 | Threading not supported in this run-time system. A threaded application attempted to use a multi-threading routine while running with a non-threaded run-time system.
1009 | Invalid parameter passed into a multi-threading library routine. A parameter has been detected that is not within the valid range, or that is inconsistent with the library routine.
1010 | No resources available. A semaphore or mutex cannot be acquired because its count is zero and the user requested no automatic wait. or: An event is not posted and the user has no wait on the CBL_EVENT_WAIT call.
1011 | Program or entry-point name not found. The program or entry-point name specified to CBL_THREAD_CREATE was not found, or there was an error loading it.
Parent topic: Thread-control Routines


Using the Program Thread-locking Routines

The following code at the entry to a program ensures that only the first thread entering a program will initialize data and all following threads will have that preinitialized data available:

if  first-time = 0
         call "cbl_thread_prog_lock"
        if  first-time = 0
             initialize my-data-division
            move 1 to first-time
        end-if
        call "cbl_thread_prog_unlock"
    end-if

Note the double check of the first-time variable. The first check is an optimization that avoids the overhead of locking the program if we know for sure that it has already been initialized.

Parent topic: Thread-control Routines


Using CBL_THREAD_SELF to Check Operating System

You can use CBL_THREAD_SELF to check that the operating system supports multi-threading as follows:

call 'cbl_thread_self' using thread-id
     on exception
         *> no cbl_thread api support
     end-call
     if  return-code = 1008
         *> running in a single threaded only rts
     end-if
Parent topic: Thread-control Routines


Synchronization Routines

Note: These routines are not supported in JVM COBOL.

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

Note: These routines are not supported in JVM COBOL.
  • 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
Related information
Synchronization Routines
RETURN-CODE Values For 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.

A thread that has acquired a read lock on a particular monitor might acquire another read lock on the same monitor. However, when a read lock has been acquired, the thread may not request a browse or write lock, unless an "outer" browse or write lock exists in which the read lock is nested. Any attempt to break this rule will result in an run-time system error. When interleaved priority is requested on a monitor it is possible that a nested read lock will block waiting for a writer to finish his request, but since the first read lock is still active, the writer will never be granted write access - this is single thread deadlock. If you expect nested read locks to be obtained then either use reader priority or obtain a write or browse lock at the highest level of locking.

A thread that has acquired a browse lock on a particular monitor may acquire another browse lock on the same monitor. It may also acquire a write lock. It may also acquire a read lock, as long as that read lock is released before the original browse lock is converted into a write lock, and before any write lock is requested.

A thread that has acquired a write lock on a particular monitor may also acquire another write, browse or read lock on the same monitor.

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.
Note: This routine is not supported in JVM COBOL.

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.

Note: This routine is not supported in JVM COBOL.

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 A monitor name.

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.

Note: This routine is not supported in JVM COBOL.

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 A space-terminated or null-terminated monitor name.

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 A space-terminated or null-terminated monitor name.

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 A space-terminated or null-terminated monitor name.

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.

Note: This routine is not supported in JVM COBOL.

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 A space-terminated or null-terminated monitor name.

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 A space-terminated or null-terminated monitor name.

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

Note: These routines are not supported in JVM COBOL.
  • 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
Related information
RETURN-CODE Values For Synchronization Routines
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.
Restriction: This routine is not currently supported in COBOL for JVM.

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.
Note: This routine is not supported in JVM COBOL.

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.

Note: This routine is not supported in JVM COBOL.

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

Note: These routines are not supported in JVM COBOL.

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
Related information
RETURN-CODE Values For Synchronization Routines
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.
Note: This routine is not supported in JVM COBOL.

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.
Note: This routine is not supported in JVM COBOL.

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.

Note: This routine is not supported in JVM COBOL.

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

Note: These routines are not supported in JVM COBOL.
  • 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
Related information
RETURN-CODE Values For Synchronization Routines
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.
Note: This routine is not supported in JVM COBOL.

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.

Note: This routine is not supported in JVM COBOL.

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.
Note: This routine is not supported in JVM COBOL.

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

Note: These routines are not supported in JVM COBOL.

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

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


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


NLS Message-file Handling Routines

  • CBL_NLS_COMPARE
    Compares two strings.
  • CBL_NLS_INFO
    Gets/sets national language information.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_NLS_COMPARE

Compares two strings.

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: NLS Message-file Handling Routines
Parent topic: Alphabetical List of Library Routines


CBL_NLS_INFO

Gets/sets national language information.

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: NLS Message-file Handling Routines
Parent topic: Alphabetical List of Library Routines
Related information
Library Routines - Key
NLS
NLS Message-file Handling 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

Country code. See your operating system documentation for an explanation of country codes.

cblte-osi-code-page

Code page. See your operating system documentation for an explanation of code page codes.

cblte-osi-process-type
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-31 | Reserved for future use and will be set to 0 by this routine
cblte-osi-product
Product identifier:
0 | Unknown (backward compatibility)
1 | Server Express
2 | Net Express
3 | Mainframe Express (up to V3.0)
4 | Mainframe Express (V3.01 or later)
5 | Visual COBOL
cblte-osi-product-version
Product version, for example, for the COBOL development system 4.0, this field would be set to 4
cblte-osi-product-revision
Product revision, for example, for the COBOL development system 4.5, this field would be set to 5
cblte-osi-product-sp
Product service pack level, for example, for Server Express 4.0 Service Pack 1, this field would be set to 1
cblte-osi-fixpack
On Windows this field indicates the RTS fixpack version, for example, for the COBOL development system 4.0 RTS09N40 FixPack, this field would be set to 9.
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

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
    Retreives the height and width of 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 logicial 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.

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 1 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 in COBOL for JVM.

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.

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.

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.

status-code | Printer Handling Routines Return Codes

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
Related information
Printer Handling Routines Return Codes
Printer Routines


PC_PRINTER_DEFAULT_NAME

Sets the default printer for all PC_PRINTER_ routines.

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.

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.
status-code
Printer Handling Routines Return Codes

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
Related information
Printer Handling Routines Return Codes
Printer Routines


PC_PRINTER_DRAW_RECTANGLE

Draws an outline or filled rectangle at position start-x,start-y to end-x,end-y.

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
draw-rectangle-options | cblt-x4-comp5 | pic x(4) comp-5.
start-x | cblt-x4-comp5 | pic x(4) comp-5.
end-x | cblt-x4-comp5 | pic x(4) comp-5.

On Entry:

 | Value | Meaning
box-style | 0 | outline
 | 1 | filled

On Exit:

status-code Printer Handling Routines Return Codes

Comments:

Does not change the logicial position on the page.

Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_ENUM_CLOSE

Ends the process of enumerating printers.

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
Printer Routines


PC_PRINTER_ENUM_NEXT

Gets the name of the next enumerated printer.

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 cblte-pn-name returned.
cblte-pn-name
The 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
Related information
Printer Handling Routines Return Codes
Printer Routines


PC_PRINTER_ENUM_START

Starts the process of enumerating printers.

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
Printer Routines


PC_PRINTER_FREE_BMP

Frees a bitmap from memory, releasing its image and palette back to the operating system.

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

Retreives the height and width of loaded bitmap

Syntax:

call "PC_PRINTER_GET_BMP_INFO" using
                               by value bitmap-handle
                               by value bitmap-height
                               by value bitmap-width
end-call

Parameters:

 | Using call prototype (see Key) | Picture
bitmap-height | cblt-x4-comp5 | pic x(4) comp-5.

On Entry:

bitmap-handle Must be valid handle returned from PC_PRINTER_LOAD_BMP

On Exit:

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

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.

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.

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_LINE_FROM_TO

Draws a line from start-x,start-y to end-x,end-y.

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-y | cblt-x4-comp5 | pic x(4) comp-5.
end-y | cblt-x4-comp5 | pic x(4) comp-5.

On Exit:

status-code Printer Handling Routines Return Codes

Comments:

Does not change the logicial position on the page.

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.

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, GIF, EXIF, JPG, PNG and TIFF.

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

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.
status-code | Printer Handling Routines Return Codes

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
Related information
Printer Handling Routines Return Codes
Printer 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.

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.

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
background-mode | cblt-x4-comp5 | pic x(4) comp-5.

On Entry:

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

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.

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(4) 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.
    05 cblte-pd-printer-browse-namelen cblt-x2-comp5. *> pic x(4) comp-5.
    05 cblte-pd-reserved               cblt-x2-comp5. *> pic x(4) 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".

 linkage section.
 01 lnk-hwnd                 pic x(4) comp-5.

 procedure division using by value lnk-hwnd.
     move BROWSE-DEFAULT-PRINTER to option of default-info
     move lnk-hwnd to hwnd of MyDefaultPrinter
     move 127 to len of MyDefaultPrinter

     call "PC_PRINTER_SET_DEFAULT" using
                             by value option of default-info
                             by reference hwnd
                   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.

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.

status-code | Printer Handling Routines Return Codes

On Exit:

status-code Printer Handling Routines Return Codes
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines
Related information
Printer Handling Routines Return Codes
Printer Routines


PC_PRINTER_SET_PEN

Set the width, style and colour for lines and rectangles when drawn using a printer.

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-red | cblt-x | pic x
pen-blue | 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-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

Comments:

The units used for page dimensions in .NET COBOL are different to the ones used in your native COBOL programs; therefore, hard-coded settings for such things as line size may produce unexpected results when using older source code in a .NET environment. To preserve compatibility of your old source code, we recommend that you use conditional compilation; otherwise, amend your code for .NET accordingly.

call "PC_PRINTER_SET_PEN" using
     by reference handle
    $if ILGEN set									*> ILGEN directive indicates .NET COBOL
          by value 1
    $else
          by value 5
    $end
          by value PS-SOLID
          by value 255
          by value 0
          by value 0
     end-call
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_SET_POSITION

Move the logicial printer position ready for the next PC_PRINTER_WRITE.

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
set-options | cblt-x4-comp5 | pic x(4) comp-5.
new-y | cblt-x4-comp5 | pic x(4) comp-5.

On Entry:

 | Value | Meaning
set-options | 0 | use logical units
 | 1 | use char units

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.

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.

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:

This routine is available only in the Windows environment.

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, 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: Function 8 of this routine (return number of arguments) is 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 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 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 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.
Restriction: Function 8 (return number of arguments) is supported for native COBOL only.
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, 1and 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.
Bits 4-31
Reserved for future use - must be set to 0.
cblte-gpi-handle
A handle created by function 0 or 1.
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 (this Compiler directive is supported in native code only).
Bit 1
0 | Program not compiled using AMODE"32" Compiler directive.
1 | Program compiled using the AMODE(31) Compiler directive (this Compiler directive is supported in native code only).
Bit 2
0 | Program compiled using the CHARSET(ASCII) Compiler directive.
1 | Program compiled using the CHARSET(EBCDIC) Compiler directive.
Bit 3
0 | Program not compiled using the ANS85 Compiler directive.
1 | Program compiled using the ANS85 Compiler directive.
Bit 4
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
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-25
Reserved for future use - must be set to 0.
Bit 26
0 | Program is not a system program.
1 | Program is a system program.
Bit 27
Reserved for future use - must be set to 0.
Bit 28
0 | Program is not a member not of a subsystem.
1 | Program is a member of a subsystem.
Bit 29
0 | Program exists in current call stack.
1 | Program does not exist in current call stack.
Bit 30
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.

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_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
Related information
Memory Allocation Routines
Alphabetical List of 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. Must be level 01.
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 . 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
Ignored.
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.
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 unique handle identifying 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 | Internal logic error
255 | Called program 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.
Parent topic: Run-unit Handling Routines
Parent topic: Alphabetical List of Library Routines


CBL_GET_SHMEM_PTR

Reads a named value.

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_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.
  • X"E5"
    Sounds the bell.
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
                     returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
character | cblt-x1-compx | pic x.
attribute | cblt-x1-compx | pic x.
status-code | See Library Routines - Key |

On Entry:

character | The character to write.
attribute | The attribute to write.

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): pic x (n).
Picture: pic x (n).
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.
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): pic x (n).
Picture: pic x (n).
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): pic x (n).
Picture: pic x (n).
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.
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): 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.
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): 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
attribute-buffer | The attributes 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

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): 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.
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
                                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): 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 | The attribute 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

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): 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.
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
                                      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
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 | The attribute to write.
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
                                      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): 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 attributes 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
                                        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
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 | The attribute to write.
string-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


X"E5"

Sounds the bell.

Syntax:

call x"E5"

Parameters:

None

Comments:

The duration and pitch of the bell depends on the environment.

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


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-handle. | pic x(2).
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.
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 routine is supported for native COBOL 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.

Parent topic: Windows Routines
Parent topic: Alphabetical List of Library Routines


Miscellaneous Routines

  • 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
    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
    Searches a directory for a given file specification.
Parent topic: Library Routines
Related information
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

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 has been deprecated in Net Express 4.0 onwards: it is provided for backward compatibility only. You should instead 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

Searches a directory for a given file specification.

Note:
  • This function has been deprecated and is provided for backward compatibility only. You should instead 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


Alphabetical List of Library Routines

  • 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_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.
  • CBL_DEBUG_START
    Enables a COBOL program to initiate advanced remote debugging or cross-session debugging.
  • CBL_DEBUG_STOP
    Enables a COBOL program to stop or suspend animation.
  • 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_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_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_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.
  • 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
    Retreives the height and width of 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 logicial 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.
  • 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
    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
    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


CBL_NLS_CLOSE_MSG_FILE

Closes a National Locale Support (NLS) message file.

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: Alphabetical List of Library Routines
Related information
Library Routines - Key
NLS
NLS Message-file Handling Routines


CBL_NLS_OPEN_MSG_FILE

Open a National Locale Support (NLS) message file.

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 returning an identifying handle that you can use with the CBL_NLS_READ_MSG and CBL_NLS_CLOSE_MSG_FILE routines.

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.

Parent topic: Using NLS Library Routines in Your Programs
Parent topic: Alphabetical List of Library Routines


CBL_NLS_READ_MSG

Reads a message from a National Locale Support (NLS) message file.

Syntax:

call "CBL_NLS_READ_MSG" using     msg-file-handle
                                  full-msg-number
                                  msg-ins-struct
                                  msg-buffer
                        returning status-code

Parameters

msg-file-handle
Call prototype (see Key): cblt-x4-compx .
Picture: pic x(4).
full-msg-number
Group predefined as cblt-nls-msg-params containing:
01 cblt-nls-msg-params          typedef.
  03 cblte-nmpb-set-number      cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-nmpb-number          cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-nmpb-max-buffer-len  cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-nmpb-actual-msg-len  cblt-x2-compx. 	*> pic x(n) comp-x.
  03 cblte-nmpb-flags           cblt-x2-compx. 	*> pic x(2) comp-x.
msg-ins-struct
Group predefined as cblt-nls-msg-ins-struct containing:
01 cblt-nls-msg-ins-struct      typedef.
  03 cblte-nmis-ins-count       cblt-x2-compx.  *> pic x(2) comp-x.
  03 cblte-nmis-ins-pointer     cblt-pointer.   *> usage pointer.
                                                *> Occurs depending on ins-count.
msg-buffer
Call prototype (see Key): pic x(n).
Picture: pic x(n).
status-code
See Library Routines - Key.

On Entry:

msg-file-handle
The identifying handle of the message file to fetch the message from.
cblte-nmnp-set-number
The set in the message file to fetch the message from.
cblte-nmnp-number
The message number in the message set to fetch the message from.
cblte-nmis-ins-count
The number of portions of text to insert in the message.
cblte-nmis-ins-pointer
A pointer to a null-terminated portion of text to insert in the message.
cblte-nmb-buff-len
The length of msg-buff-text.

On Exit:

cblte-nmb-buff-text
The returned text (null-terminated).
status-code
Indicates whether the routine was successful:
0 | Success
40 | NLS module not initialized
401 | Message set not found
402 | Message not found in set
403 | Message too long for message text buffer
404 | Invalid msg-file-handle
If status-code contains a value other than these, it is the number of a run-time error message.

Comments:

In each message 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

Parent topic: Using NLS Library Routines in Your Programs
Parent topic: Alphabetical List of Library Routines


Managed COBOL

  • Managed COBOL Reference
  • Comparison of COBOL with Other Managed Languages
  • Type Compatibility of Managed COBOL with Other Managed Languages
    Many managed COBOL types have a strict correspondence with managed types in other languages, such as binary-long and float-short. For those that don't have a correspondence, there are alternatives.
  • MicroFocus.COBOL.RuntimeServices
Parent topic: General Reference


Managed COBOL Reference

Managed COBOL supports the key aspects of the managed framework (both .NET and JVM). It provides new syntax specifically designed to support these features.

In addition, managed COBOL continues to support all of the existing COBOL syntax (for native COBOL) with very few exceptions.

This reference describes the syntax designed and recommended for managed COBOL. The syntax for native COBOL is documented in the COBOL Language Reference.

  • Program Structure
  • Structural Syntax Elements - Alphabetic List
  • Common Phrases
  • Statements - Alphabetic List
  • Concepts - Managed COBOL
Parent topic: Managed COBOL
Related concepts
Managed COBOL Language Features
Comparison of COBOL with Other Managed Languages
ILSMARTNEST
Related information
COBOL Language Reference


Program Structure

The overall structure of a program is one or more type specifications.

type-specification ...
Parent topic: Managed COBOL Reference


Types

Context:

    Program Structure

type-specification

class-specification delegate-specification enum-specification interface-specification valuetype-specification

Example

Class A.
...
end class.

Interface I.
...
end interface.


Classes

A class defines the data members and function members for object instances that are created from that class. Managed COBOL allows a class to inherit from one or more other classes.

Context:

    Program Structure
        Types

class-specification

class-header constraints-paragraph constraints-paragraph static-or-instance-member type-specification

class-header

access-modifier type-specifier type-specifier attribute-clause generic-using-phrase

Example

class A.
01 sField string.
Method doStuff.
   ...
end method.

class nestedClass.
...
end class.

end class.

See also the Core sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Class Header Keywords

ABSTRACT
Declares a class that is only intended to be used as a base class. An abstract class can be thought of as an incomplete class that must be inherited to access its members.
FINAL
Declares a class whose definition is complete. The FINAL modifier on a class implies that the class cannot have subclasses.
STATIC
Declares a class that cannot be instantiated.
PARTIAL
Indicates that the declaration is one of two or more parts that make up the full declaration. Partial classes enable you split a class declaration into logical parts.
INHERITS
Defines that a class is inherited, where type-specifier specifies the class that is inherited. Inheritance enables a class to implicitly contain members of its inherited class type.
IMPLEMENTS
Indicates that an interface is implemented, where type-specifier specifies the interface that is implemented.

Abstract Classes

An abstract class is a class that cannot be instantiated, but can only be inherited from. Because of this, an abstract class is typically used as a base class. Members of an abstract class are only declared in the abstract class, and cannot be implemented. Because abstract classes must be inherited from, the FINAL modifier cannot be used when declaring an abstract class.

An abstract class typically contains abstract methods, which cannot be implemented in the class declaration, similar to method declarations in an interface. Because abstract classes cannot be instantiated, subclasses that inherit the abstract class must provide the implementations of abstract methods defined in the abstract class. Only an abstract class can contain abstract methods.

Abstract classes are useful when you do not want objects created from the class. Declare a class as abstract when you want to use subclasses to complete the implementation.

When any non-abstract class derives from an abstract class through inheritance, the inherited class must implement all the abstract members of the abstract class. Use OVERRIDE when implementing the members of an abstract class in the non-abstract members of the derived class, as shown in the following example:

       class-id. Animal abstract.
       method-id MakeNoise abstract.
      *> No implementation allowed
       end method.

       end class.

       class-id Dog inherits type Animal.
      *> Overrides the MakeNoise method in the Animal class
       method-id MakeNoise override.
           display "Woof!"
       end method.
       end class.

In this example, the abstract class Animal contains the abstract method MakeNoise. Because the non-abstract class Dog inherits from the abstract class Animal, it must provide an implementation of MakeNoise using the OVERRIDE modifier.

An abstract class can contain non-abstract methods in addition to abstract methods.

A class that inherits an abstract class must also be declared as an abstract class if it does not provide implementation of the inherited class' members.

Final Classes

A final class cannot be inherited. Because of this, methods in a final class cannot be overridden.

Declaring a class as FINAL is useful to prevent subversion of the class. It prevents a subclass from potentially changing the intended class functionality by overriding its intended behavior.

Nested Classes

Nested classes can access static fields, properties and methods within the containing classes using the syntax:

self::memberName

The optional SHARING PARENT phrase in the nested class definition enables 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 using the self:: syntax, 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 self::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 cannot access instance members of the containing class with the self:: syntax, but only do it using an explicit object reference.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Access Modifiers
Attributes
Constraints Paragraph
Related information
Program Structure - in COBOL and C#
Objects - in COBOL and C#
Nested Classes in Managed COBOL


Constraints Paragraph

The Constraints paragraph allows specification of properties of parameters of a generic type or method, and therefore allows the use of methods or properties on data items whose type is specified as that parameter.

Context:

    Classes
     ValueTypes
     Interfaces
     Methods

constraints-paragraph

type-specifier type-specifier

Example

The following shows a static generic method with a USING phrase that declares the generic argument T. This generic argument is constrained as the type System.IComparable. The method expects two parameters both of which must be of the same type as the generic argument.

       method-id Min using T static.
       constraints.
           constrain T implements type System.IComparable.
       procedure division using by value item1 as T item2 as T
                      returning res as T.
           if item1::CompareTo(item2) < 0
               set res to item1
           else
               set res to item2
           end-if
       end method.

In this case the CompareTo method may be invoked since T is known to implement the IComparable interface.

Parent topic: Common Phrases
Related reference
Access Modifiers
Attributes
Classes
Interfaces
Properties
ValueTypes
Generic Using Phrase
Related information
Generics, Defining - in COBOL and C#


Fields

A class, valuetype and interface can define a set of static or instance fields.

Context:

    Classes
     ValueTypes
     Interfaces
     Methods

static-or-instance-field

variable-field constant-field

variable-field

type-specifier access-modifier attribute-clause

constant-field

type-specifier access-modifier attribute-clause

Example

    01 dAmount  decimal.
    01 asNames string occurs 5.
    01 abFigures binary-long occurs any.

    78 Max_Students value 25.  *> default is public, binary-long

See also the Core sample available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

INITIALIZE ONLY Keywords

The INITIALIZE ONLY phrase defines a static or instance field that can only be modified within a class constructor or constructor (respectively). For example:

    class-id a.
    01 s string static value "Shouldn't see this" initialize only.
    method-id main static.
        display s
    end method.
    method-id new static.
        set s to "Hello world"
    end method.
    end class.

INITIALIZE ONLY fields and constant fields differ as follows:

INITIALIZE ONLY field:
  • Can be either instance-level or static
  • Evaluated at run time
  • Can be initialized in declaration or by code in the constructor
Constant field (78-level):
  • Always implicitly static
  • Evaluated at compile time
  • Initialized at declaration only

EVENT Keyword

The EVENT keyword is allowed only on items that are declared as delegates.

The keyword EVENT on a delegate instance ChangeEvent creates two methods, which are named add_ and remove _ with the delegate instance name appended. These methods can be used to hook a new method into the delegate, and subsequently to remove it, respectively.

For example, the keyword EVENT in the following statement creates two methods add_ChangeEvent and remove_ChangeEvent:

       01 ChangeEvent type ChangeDelegate event public.
       ...
       delegate-id ChangeDelegate.
       procedure division using by value x1 as binary-long.
       end delegate.

See also the Events sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET.

PROPERTY Keyword

You can expose a field using the PROPERTY keyword. As with other areas of the syntax, use the AS clause to specify the name of the property including the case that it will be known by externally.

    01 public-field pic x property as "Field1".

The PROPERTY keyword generates two accessor methods to retrieve and update the field. These methods are named get_ and set_ with the field name appended and are commonly known as getter and setter methods. Languages within the framework that support properties will hide these methods from you and appear to allow you to get and set these member fields directly. In fact, the Compiler is substituting the property name with the relevant get_ or set_ routine.

See also the Properties sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Delegates
Properties
Local Data Item Declaration
Access Modifiers
Attributes
Type Specifier
Related information
Data Types - in COBOL and C#
Constants - in COBOL and C#
String Handling in Managed COBOL


Type Members

A class, valuetype or interface can define a set of members, such as methods and properties.

Context:

    Classes
     ValueTypes
     Interfaces
     Methods

static-or-instance-member

method-specification constructor-specification property-specification indexer-specification operator-specification iterator-specification
Parent topic: Structural Syntax Elements - Alphabetic List


Methods

A method defines a block of code to be executed when the method is invoked.

Context:

    Classes
    ValueTypes
    Interfaces
        Type Members

method-specification

method-header constraints-paragraph procedure-division

method-header

access-modifier attribute-clause

Example

method-id methodA static.
01 s string value "Hello".
procedure division.
   display s
end method.

See also the Core sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Static and Instance Methods

Methods can be either static methods or instance methods, and are by default instance. An instance method operates on a given instance of a class, whereas a static method does not operate on a given instance.

A static method can invoke static methods only and can access static fields only. A static method can reside in a static class or an instance class. Where a static method is in an instance class, all objects instantiated from the class share a single copy of the static methods.

For example, the following class contains static and instance methods, and static and instance fields.

       class-id MyCounter.

       01 totalCount binary-long static.
       01 myCount binary-long.

       method-id New.
       procedure division.
           set myCount to totalCount
           set totalCount to totalCount + 1
       end method.

       method-id GetCount.
       procedure division returning returnItem as binary-long.
           set returnItem to myCount
       end method.

       method-id GetTotalCount static.
       procedure division returning returnItem as binary-long.
           set returnItem to totalCount
       end method.

       method-id SetCount static.
       procedure division using by value aCount as binary-long.
           set totalCount to aCount
       end method.
       end class.

Here is the program that invokes the above code:

       program-id StaticInstanceProgram.
       01 myInstance1 type MyCounter.
       01 myInstance2 type MyCounter.

       procedure division.
           invoke type MyCounter::SetCount(10)
           set myInstance1 to new type MyCounter
           set myInstance2 to new type MyCounter
           display myInstance1::GetCount()         *> displays 10
           display myInstance2::GetCount()         *> displays 11
           display type MyCounter::GetTotalCount() *> displays 12

       end program.

To use static and instance methods:

  • To declare a static method, use the STATIC keyword. If the method is in a static class, you must specify STATIC.
  • To declare an instance method, don't use the keyword STATIC.
  • To access a static method, you use the name of the class, followed by :: and then the method name. For example: MyCounter::GetTotalCount() as in the above code.
  • To access an instance method, you use the name of the instance object, then :: followed by the method. For example: myInstance1::GetCount() as in the above code.

Instance Method Modifiers

The following modifiers indicate the extent to which the method inherits and is inherited:

ABSTRACT
declares an empty method. To use an abstract method, you must inherit it and include the required code in the subclass.
OVERRIDE

specifies that this method overrides the inherited method of the same name and signature.

REDEFINE

hides a method in a superclass, where the subclass contains the redefine method. The REDEFINE keyword hides the superclass method only when the redefine method is invoked on an item defined as being in the subclass containing the redefine method.

FINAL
prevents a derived class from further overriding the method.

In summary, you can think of the keywords like this:

  • An abstract method provides the name and signature of a method
  • A virtual method is the first implementation of a method
  • An override method is another implementation of a method
  • A final method is the last implementation of a method

Abstract Methods

An abstract method has no implementation. To use an abstract method, you inherit it and in the inheriting subclass, you provide the implementation of the method. An abstract class can contain methods that are not abstract, as well as abstract ones. The methods that aren't abstract can provide a default implementation, which can be overridden by a subclass method. For example:

class-id MyAbstractClass abstract.
       01 myField  value 0 binary-long property.

       method-id AbstractMethod abstract. *> no implementation
       end method.

       method-id NonAbstractMethod.       *> not abstract
       procedure division.
            set myField to 1   *> Default behavior, which can be overridden
       end method.

       end class.

An abstract class can contain methods that are not abstract. These methods can provide a default implementation, which can be overridden by a subclass method.

       class-id MySubClass inherits type MyAbstractClass.

       method-id AbstractMethod override.
       procedure division.
           *> Subclass method implements abstract method
           display "myField is: " self::myField  *> displays 0
       end method.

       method-id NonAbstractMethod override.
       procedure division.
           *> Subclass method overrides method that is not abstract
           set self::myField to 6
           display "myField is: " self::myField  *> displays 6
       end method.

       end class.

To define and use methods in abstract classes:

  • You use the ABSTRACT keyword to define any members that are abstract, and omit it for members that are not abstract. Abstract members must be within an abstract class.
  • The subclass must inherit the abstract superclass, and must contain an implementation of all the abstract members of the superclass. However, the subclass itself can be abstract and in this case, will not contain implementations.
  • The subclass methods must use the keyword OVERRIDE.
  • An abstract method cannot be private. It can be public, protected or internal.

Override Methods

An override method is a method that overrides an inherited virtual method of the same name and signature.

For example, a subclass Circle inherits from a superclass Shape. Both classes contain a Draw method. The Draw method in the Circle subclass overrides the Draw method in the Shape superclass.

       class-id Shape.
       method-id Draw.
           display "let's draw a super shape"
       end method.
       end class.

       class-id Circle inherits type Shape.
       method-id Draw override.
           display "let's draw a circle"
       end method.
       end class.

To define an override method:

  • Specify the OVERRIDE modifier in the method-id header
  • Ensure that the method has the same name and signature as the method to be overridden in the inherited class

You cannot override a final method in the inherited class. You can override only virtual methods (methods not defined as final).

Redefine Methods

The REDEFINE keyword is used to hide a method inherited from a class. To hide an inherited method, declare it in the derived class using the same name and specify REDEFINE.

A redefine method is similar to an override method, in that it is a method with the same name and signature as a method in the superclass. However, unlike an override method, the redefine method might or might not override depending on how it is invoked. When the method is invoked on an item defined as being in the:

  • Superclass, even when that item actually holds an instance of the subclass, the superclass method is executed
  • Subclass - the subclass redefine method is executed and the superclass method is overridden

For example, we have two subclasses Circle and Square, which inherit from the Shapes superclass. All the classes have a Draw method. The Circle class's Draw method overrides the Draw method in the Shapes superclass. The Square class's Draw method redefines the Draw method in the Shapes superclass.

       class-id Shape.
       method-id Draw.
           display "let's draw a super shape"
       end method.
       end class.

       class-id Circle inherits type Shape.
       method-id Draw override.
           display "let's draw a circle"
       end method.
       end class.

       class-id Square inherits type Shape.
       method-id Draw redefine.
           display "let's draw a square"
       end method.
       end class.

You can invoke the Circle and Square classes as follows:

       program-id. RedefineSampleProgram.

       01 myShape type Shape.
       01 myCircle type Circle.
       01 mySquare type Square.

       procedure division.
           set myShape to new type Shape
           set myCircle to new type Circle
           set mySquare to new type Square

           invoke myCircle::Draw   *> Circle Draw method is invoked
           invoke mySquare::Draw   *> Square Draw method is invoked
                                   *> Shape Draw method is hidden, redefined

           set myShape to myCircle *> Superclass instance is set to subclass
           invoke myShape::Draw    *> Circle Draw method is invoked
                                   *> as it overrides Shape Draw method

           set myShape to mySquare *> Superclass instance is set to subclass
           invoke myShape::Draw    *> Shape Draw method is invoked as
                                   *> Square Draw method doesn't override it

       end program.

The above invocations produce the following output:

let’s draw a circle
let’s draw a square
let’s draw a circle
let’s draw a super shape

Another place to use REDEFINE is where the method in the superclass is defined as FINAL and so it cannot be inherited nor overridden. In this case, you can use REDEFINE to hide the subclass method and use the superclass method instead, when polymorphism in use.

Final Methods

A method that is declared as final is prevented from being overridden in any subclasses. This enables a class to inherit a superclass, while preventing a superclass method from being overridden in the subclass.

For example, we have a class MySubClass, which inherits from MySuperClass. MySuperClass has one final method and one virtual (not final) method. The subclass overrides the virtual method, but it cannot inherit or override the final method.

       class-id MySuperClass.

       method-id VirtualMethod. *> Methods are virtual by default
       procedure division.
           display "Virtual method in the superclass"
       end method.

       method-id FinalMethod final. *> Final methods are not virtual
       procedure division.
           display "Final method in the superclass"
       end method.

       end class.

The subclass is defined as follows:

       class-id MySubClass inherits type MySuperClass.

       method-id VirtualMethod override.
       procedure division.
           display "Overridden virtual method in the subclass"
       end method.

      * method-id FinalMethod override.
      *>COBCH0954 Method 'FinalMethod' cannot OVERRIDE a nonvirtual method

       end class.

The classes are invoked as follows:

       program-id FinalOverrideSampleProgram.
       01 mySuper type MySuperClass.
       01 mySub type MySubClass.

       procedure division.
           set mySuper to new type MySuperClass
           invoke mySuper::FinalMethod()
           invoke mySuper::VirtualMethod()

           set mySub to new type MySubClass
           invoke mySub::VirtualMethod()

       end program.

The above sample program produces output as follows:

Final method in the superclass
Virtual method in the superclass
Overridden virtual method in the subclass

Although a final method cannot be overridden in a subclass, it can be redefined in the subclass.

Extension Methods

The EXTENSION keyword declares a method as an extension method.

Extension methods enable you to add methods to existing types without the need to edit or recompile the code. Extension methods appear as additional methods available on an object instance while they are implemented elsewhere.

For example, the following extension method extends the string class, by adding a method to count the number of words in a string:
       class-id MyCount static.
       method-id CountWords extension. *> extension method is implicitly static
       procedure division using str as string
                          returning wordCount as binary-long.
            set wordCount to str::Split(' ')::Length
       end method.
       end class.

To declare an extension method:

  • Use the EXTENSION keyword in the method header.
  • The method must be in a static class that is not nested or generic. The method is implicitly static.
  • In the method body, the first parameter is the type to extend. It is always a value parameter.

There is no special syntax for calling extension methods from managed COBOL. You consume an extension method in the same way as any other method, except you specify the first parameter as the type of the method, using this syntax:

parameter-1::method-name(more parameters)

In JVM COBOL, there are two extensions that are preloaded before compilation:

  • An extension operator for string equality
  • An extension method for substring

These two extensions ensure that managed COBOL produces the same results, regardless of whether it is compiled to JVM COBOL or .NET COBOL. For more detail, see Extension Methods and Operators.

Synchronized Methods

The SYNC modifier locks the values of the arguments sent to the method, so that they do not change while the method is processing.

When an argument is sent to a method and is received as a reference parameter, the value of the parameter and its corresponding sending argument might be updated. Without the SYNC modifier, the value of the sending argument is unknown, while the method is processing.

The SYNC modifier on a method is equivalent to wrapping the whole method in a SYNC statement.

For example:

       01 a binary-long value 20.
       ...
       invoke self::Adjust(a)
       display a                 *> displays 93

       method-id Adjust sync.
       procedure division using reference x as binary-long
           set x to x + 73
       end method.
       end class.

In the above example, the SYNC modifier is applied to the method Adjust(). This ensures that the variables within the method (in this case, the variable x locally, but variable a in the invoking code) cannot be accessed until the method has finished processing.

Invoking a Method

You can invoke a method in two ways: by using the INVOKE statement or by invoking inline using the SET statement.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Constructors
Access Modifiers
Attributes
Procedure Division
INVOKE Statement
SET Statement
Related information
Extension Methods and Operators
Method Overloading in Managed COBOL
Functions, Methods - in COBOL and C#
Constructors and Deconstructors - in COBOL and C#
Invoking a Method
Extension Methods and Operators


Procedure Division

The procedure division defines the code to be executed, when a type or member is invoked. The procedure division header defines any parameters to pass in to the code and any returning item to pass back.

Context:

    Methods
    Constructors
    Iterators
    Operators

procedure-division

procedure-division-header statement-block

procedure-division-header

attribute-clause attribute-clause attribute-clause attribute-clause attribute-clause

The PARAMS phrase is optional, but must be last.

See the Core sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Constructors


Constructors

A constructor is a class method that is executed when the class is created.

Context:

    Classes
    ValueTypes
    Interfaces
        Type Members

constructor-specification

constructor-header procedure-division

constructor-header

attribute-clause

Example

method-id new.
procedure division.
    set powerLevel to 0
end method.

method-id new.
procedure division using by value powerLevel as binary-long.
    set powerLevel to powerLevel
end method.

Further Information

A constructor is a class method that is executed when the class is created. Constructors are named "new", and do not have a returning item.

A class can define multiple constructors with different arguments.

If no constructor is defined, the Compiler generates a default one.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Attributes
Methods
Procedure Division
Related information
Functions, Methods - in COBOL and C#
Constructors and Deconstructors - in COBOL and C#


Properties

Properties are members with associated types. They are similar to fields but they have accessors that provide the means to read and write values.

Context:

    Classes
    ValueTypes
    Interfaces
        Type Members

property-specification

property-header procedure-division-header access-modifier statement-block access-modifier statement-block

property-header

type-specifier access-modifier attribute-clause

Example

class-id MyClass.
working-storage section.
01 volume binary-long private.
property-id Volume binary-long.
  getter.
    set property-value to volume
  setter.
    if property-value < 0
      set volume to 0
    else
      set volume to property-value
    end-if
end property.
end class.
property-id PropertyReadOnly string.
  getter.
    set property-value to field-5
end property.

See also the Properties sample, available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Further Information

A property specified using PROPERTY-ID must contain a get or set accessor (or both), using the GETTER and SETTER keywords respectively. The Compiler then generates get_ and set_ methods accordingly.

There are two ways of exposing a field as a property within a COBOL program:

  • The simplest way is to specify the keyword PROPERTY on any data declaration within the program. This automatically sets up two accessor methods for getting and setting the value of the data item. There are optional phrases that follow the PROPERTY keyword that you can use to suppress either the get or the set accessor. You can also use the AS clause to change the external name.
  • The alternative way is to specify a PROPERTY-ID with the GETTER or SETTER phrases to be executed whenever the property is accessed. This mechanism, though slightly more complicated than the PROPERTY keyword, gives you complete control over the statements that are executed when the property is accessed. See PROPERTY Keyword
Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Indexers
Access Modifiers
Attributes
Constraints Paragraph
Fields
Type Specifier
Related information
Properties - in COBOL and C#


Procedure Division Header

The procedure division header defines the parameters passed to a member and also any returning item, the value computed by the member.

Context:

    Procedure Division
    Delegates
    Indexers

procedure-division-header

attribute-clause attribute-clause attribute-clause attribute-clause attribute-clause

The PARAMS phrase is optional, but must be last.

See the Core sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Parameters

Parameters are values or variable references that are passed to a method. The actual values of the parameters are specified when the method is invoked. Each parameter and its type is specified in the procedure division header in the USING clause.

When you invoke a method, you specify the parameters in the invocation. The invoked method receives the parameters in the same order as in the invocation. For example:

       invoke type MyClass::MyMethod(a,b)
       ...
       method-id MyMethod.
       procedure division using x as string
                                y as binary-long.
       ...
       end method.

The arguments a and b above are passed to the invoked method, and these correspond to the parameters x and y respectively, in the invoked method. The types of the parameters are specified in the AS phrase of the USING clause.

The following types of parameters can be passed:

  • Value parameters. These are used for input only. Any updates are not passed back to the invoking code.
  • Reference parameters. These are used for both input and output. Unlike a value parameter, when the method finishes, any updates are passed back to the invoking code.
  • Output parameters. These are similar to reference parameters. The main difference is that they don't need to be assigned on entry to the method, but they must be assigned on exit from the method.
  • Returning items. These are for output only .

Parameters are passed by reference by default (except in extension methods where they are passed by value). You can change the default to be value parameters by setting the METHODDEFAULT (VALUE) Compiler directive.

When specifying multiple value parameters, the keyword VALUE is assumed for subsequent consecutive parameters. In the following example, v and vv are passed by value, and the others are passed by reference:

       procedure division using a as binary-long
                          value v as binary-long
                                vv as binary-long
                      reference r as binary-long
                                rr as binary-long.

VALUE Parameters

A value parameter corresponds to a local variable. Its initial value is established when the method is invoked. When the method processes, it can change the value of the local variable. When the method finishes, the original argument in the invoking code remains unchanged. For example:

       declare a as binary-long=3.
       invoke type MyUtils::CheckByValue(a)
       display a              *> a is still 3

       method-id CheckByValue static.
       procedure division using value x as binary-long.
           set x to x + 1          *> x is now 4
       end method.

In the above example, the parameter a is passed by value. The invoked method increments the value. However, on return to the invoking code, the variable a remains unchanged.

Usage:

  • Use a value parameter for input to a method. Use a value parameter when you don't need to output the parameter from the method.
  • To pass a parameter by value, specify the VALUE keyword for the parameter in the method signature in the procedure division using clause. When specifying multiple value parameters, the keyword VALUE is assumed for subsequent consecutive parameters.
  • Value parameters that are managed types are exposed as the corresponding COBOL types. For example, signed numeric items with no implied decimal point are exposed as int8, int16, int32, int64, depending on the size.

    Value parameters that are not managed types but are other COBOL data types are exposed as defined in the COBOL Type Compatibility table. For example: PIC X fields and groups are exposed as string. See Type Compatibility of Managed COBOL with Other Managed Languages.

REFERENCE Parameters

A reference parameter contains a reference to the required value rather than the value itself.

A reference parameter corresponds to a local variable, whose value is established when the method is invoked, and whose value can change while the method is processing. Unlike a value parameter, when the method finishes, the value of the original argument in the invoking code is changed accordingly.

Note, that a reference parameter does not necessarily create a copy of the variable local to the method. Instead, it might refer to the original argument in the location in use when the method was invoked. While the method is processing, the variable can change locally, but the original argument in the invoking code does not necessarily change. It might change or it might not. The value of the original argument is unknown until the method finishes. When the method finishes and returns to the invoking code, the value of the original argument in the invoking code is updated.

For example:

       declare a as binary-long=3.
       invoke type MyUtils::CheckByReference(a)
       display a              *> a is now 4

       method-id CheckByReference static.
       procedure division using reference x as binary-long.
           set x to x + 1          *> x is now 4
       end method.

In the above example, the parameter a is passed by reference. The invoked method increments the variable a. On return to the invoking code, the variable a is updated with the incremented value.

Usage:

  • Use a reference parameter for both input and output. Use it to input a value to the method and to output the resulting value to the invoking code.
  • Parameters are passed by reference by default, except where the previous parameter in the method signature is not a reference parameter. In this case, the keyword REFERENCE is required.
  • While the method is running, the value of a sending argument that corresponds to a reference parameter might change. The value is unknown. To lock the sending argument so that it does not change while the method is running, use the SYNC clause. When the method finishes, the lock is released and the sending argument is updated as necessary.
  • Reference parameters that refer to managed types are exposed directly as managed pointers to the corresponding managed type.

    Reference parameters that do not correspond to managed types (such as PIC X fields, groups, numeric fields other than binary-long and so on) are exposed as COBOL pointers .

OUTPUT Parameters

Like reference parameters, output parameters don't create a new storage location, but use the storage location of the variable specified on the invocation.

Output parameters are very similar to reference parameters. The main difference is that they must be assigned before returning to the invoking code.

For example:

       declare a as binary-long=4.
       declare b as binary-long.
       invoke type MyUtils::CheckByOutput(a,b)
       display "Value Param a = " &  a          *> a is still 4
       display "Output Param b = " & b          *> b is 16

       method-id CheckByOutput static.
       procedure division using value x as binary-long
                               output y as binary-long.
           set x to x + 10     *> x is now 14
           set y to x + 2      *> y is now 16
       end method.

In the above example, two parameters are passed, where variable b is not initialized and passed by output. The method CheckByOutput updates the variables x and y. On return, the output variable b is updated but the variable a remains unchanged.

Usage:

  • Typically used in methods where there are multiple return values.
  • Can optionally be initialized or assigned a value for input to the method.
  • Must be assigned for return, when the method finishes.
  • Output parameters that refer to managed types are exposed directly as managed pointers to the corresponding managed type.

    Output parameters that do not correspond to managed types (such as PIC X fields, groups, numeric fields other than binary-long and so on) are exposed as COBOL pointers .

RETURNING Items

Returning items pass the results of a method back to the invoking code. For example:

        procedure division returning myReturn as condition-value.

Each method can have only one returning item. However you can package a set of return information in an object. For example, the following AddMins() method receives and returns an instance object reference myTime :

       program-id ParamAsObject.
       01 myTime type MyTimer value new MyTimer(5 45).

       procedure division.
           set myTime to myTime::AddMins(myTime 70) *> inline invocation
           display myTime::anHour & ":" myTime::aMin
       end program.

       class-id MyTimer.
       01 anHour binary-long property.  *> property keyword enables get/set
       01 aMin binary-long property.
       ...
       method-id AddMins.
       01 h binary-long value 0.
       01 m binary-long value 0.
       procedure division using value a as type MyTimer
                                      b as binary-long
                            returning c as type MyTimer.
           set b to a::aMin + b
           divide b by 60 giving h remainder m
           set c to new MyTimer(a::anHour + h , m)
       end method.

       end class.

The example above shows the inline invocation syntax, in the statement:

       set myTime to myTime::AddMins(myTime 70)

Here, the invoked method AddMins() returns an item, myTime. The invoked method specifies the returning item in its signature.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
INVOKE Statement
Local Data Item Declaration
Related information
Type Compatibility of Managed COBOL with Other Managed Languages
Types and Type Conversion
Type Mappings from Native COBOL to Managed Code


Indexers

Indexers resemble properties except that their accessors take parameters. Indexers allow instances of a class or valuetype to be indexed just like arrays.

Context:

    Classes
    ValueTypes
    Interfaces
        Type Members

indexer-specification

indexer-header procedure-division-header access-modifier statement-block access-modifier statement-block

indexer-header

type-specifier access-modifier attribute-clause

Example

In the following example, a class is defined and provided with simple getter and setters as a means of assigning and retrieving values. Square brackets used to access arrays, use 0-based indexing. Round brackets use 1-based indexing.

       class-id SimpleIndexer.
       01 myArray string occurs 100.

       indexer-id string.
       procedure division using by value i as binary-long.
       getter.
           set property-value to myArray[i]
       setter.
           set myArray[i] to property-value
       end indexer.

       end class.

See also the IndexerDemo.cbl in the Properties sample, available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Access Modifiers
Attributes
Properties
Iterators
Type Specifier
Related information
Arrays - in COBOL and C#
Iterators - in COBOL and C#


Operators

A set of default operators are predefined and implemented. You can overload an operator and define your own behavior for it.

Context:

    Classes
    ValueTypes
    Interfaces
        Type Members

operator-specification

operator-header procedure-division

operator-header

operator-name attribute-clause

operator-name

binary-operator
comparison-operator arithmetic-operator bitwise-operator
  • =
  • <>
  • <=
  • <
  • >=
  • >
  • +
  • -
  • *
  • /
  • **
  • B-AND
  • B-OR
  • B-XOR
  • B-NOT
  • B-LEFT
  • B-RIGHT
unary-operator
  • +
  • -
  • EXPLICIT
  • IMPLICIT

Example

       operator-id + .
       01 iMins binary-long.
       01 iHour binary-long.
       procedure division
             ...
       end operator.

See also the Operator Overloading sample, available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Conversion Operators, IMPLICIT and EXPLICIT

Conversion operators can be overloaded, so that the appropriate conversion operator is used according to the parameter types in the calling code. The operator with the matching signature (procedure division using clause) is executed. For example, where a data item of type Timer requires converting to binary-long, the operator used is the operator with an input parameter of type Timer and output parameter of binary-long.

To define and use conversion operators:

  • Use the IMPLICIT or EXPLICIT keyword on the operator-id header
  • The operator converts the types specified in the operator's signature (its procedure division using clause)
  • The types converted can be either classes or value-types, but not interfaces
  • Types that inherits from one another cannot be converted using a conversion operator
  • The same conversion cannot be defined twice: once as implicit and as explicit

Operator Overloading

You can overload operators to provide alternative behavior, or behavior for different operand types. For example, where a Timer type is expressed as hours and minutes, you could define one + (plus) operator to add two Timers and another + (plus) operator to add a number of minutes to a Timer type.

To declare overloaded operators:

  • Overloaded operators are public and static. They cannot be defined as abstract, final or override.
  • The parameters in the operator's signature must be declared by value.
  • The following operators can be overloaded, and require the following operator-id signatures:
Operators that can be overloaded | Overload operator-id signature | Notes
Conditional operators, such as: t1 = t2, t1 equals t2 | value t1 t2 returning condition-value | Conditional operators must be specified in pairs. If you declare an equality operator (=), you must also declare an inequality operator (<>).
Binary operators, such as: t1 + t2 | value t1 t2 returning t3 | Binary operators must have two arguments. For binary operators, you might need to specify a pair of operators to enable the two operands to be passed in either order.
Unary operators, such as: -t1 | value t1 returning t3 | Unary overloaded operators can have only one argument.
Logical operators, such as: t1 b-or | value t1 t2 returning t3 |
Shift operators, such as: t1 b-right | value t1 t2 returning t3 |

While the arithmetic operators for addition, subtraction, multiplication and division can all be overloaded, their verb equivalents cannot. For example, ADD in the following statement cannot be overloaded:

       add a to b giving c

To use overloaded operators, the overloaded operator must be in scope.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Attributes
Type Specifier
Related information
Operators - in COBOL and C#
Operator Overloading in Managed COBOL


Iterators

An iterator is a section of code that returns an ordered sequence of values. You can create an iterator by defining a member as an iterator, using iterator-id.

Context:

    Classes
    ValueTypes
    Interfaces
        Type Members

iterator-specification

iterator-header procedure-division

iterator-header

access-modifier attribute-clause

Example

Here we use an iterator-id paragraph GetEven to return the even numbers in the FibonacciArray

    01 m-FibonacciArray binary-long occurs any static.
    01 anyNumber    binary-long.
    procedure division
       ...
       set content of m-FibonacciArray to (1 2 3 5 8 13 21 34 55 89 144)

        display "Even numbers"
        perform varying evenNumbers through iterators::GetEven
            display evenNumbers
        end-perform

    iterator-id GetEven static.
    01 i binary-long.
    procedure division yielding res as binary-long.
        perform varying i through m-FibonacciArray
            if i b-and 1 = 0
                set res to i
                goback
            end-if
        end-perform
        stop iterator *> stops the iterator immediately
    end iterator.     *> stops the iterator implicitly

See also the Iterators sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Further information

The STOP ITERATOR statement stops the iteration.

This statement is not needed if the next statement is END ITERATOR.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Indexers
Access Modifiers
Attributes
Related information
Iterators - in COBOL and C#


ValueTypes

Value types can contain data members and function members, similar to classes. The difference is that value types store the data as values and don't require heap allocation.

Context:

    Program Structure
        Types

valuetype-specification

valuetype-header constraints-paragraph static-or-instance-field static-or-instance-member

valuetype-header

access-modifier type-specifier attribute-clause

Example

valuetype-id StudentRecord.
01 aName string public.
01 gpa float-short public.
method-id new.
procedure division using by value nam as string,
                                  gpa as float-short.
    set aName to nam
    set self::"gpa" to gpa
end method.
end valuetype.

class-id a.
method-id main static.
local-storage section.
01 stu type StudentRecord value new StudentRecord("Bob", 3.5).
01 stu2 type StudentRecord.
procedure division.
    set stu2 to stu
    set stu2::name to "Sue"
    display stu::name   *> Prints Bob
    display stu2::name  *> Prints Sue
end method.
end class.

See also the ValueTypes sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Access Modifiers
Attributes
Constraints Paragraph
Related information
Structures, Value Types - in COBOL and C#


Interfaces

An interface is a list of instance methods specifying names and signatures but without implementation.

Context:

    Program Structure
        Types

interface-specification

interface-header constraints-paragraph interface-member

interface-header

access-modifier type-specifier attribute-clause generic-using-phrase

interface-member

method-specification property-specification indexer-specification

Example

*> Interface definition
interface-id IAlarmClock.
  ...
end interface.

*> Inheriting an interface
interface-id IAlarmClock inherits type IClock.
  ...
end interface.

*> Interface implementation
class-id WristWatch implements type IAlarmClock, type ITimer.
   ...
end class.

See also the Interfaces sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET.

About Interfaces

An interface is a list of instance methods specifying names and signatures but without implementation.

When a program declares that it implements a particular interface this means that the program is required to have implementations for all the methods defined in the interface. To implement an interface you use the IMPLEMENTS phrase of the OBJECT clause in a class definition to declare that a program provides an implementation for the specified interface. You can also declare an object reference to this interface type.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Access Modifiers
Attributes
Constraints Paragraph
Related information
Interfaces - in COBOL and C#


Delegates

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.
Note: This functionality is supported in COBOL for .NET only.

Context:

    Program Structure
        Types

delegate-specification

delegate-header procedure-division-header

delegate-header

access-modifier attribute-clause

Example

delegate-id MsgArrivedEventHandler.
procedure division using by value msg as string.
end delegate.

class-id a.
01 MsgArrivedEvent
     type "MsgArrivedEventHandler" event static.
    *> Delegates must be used with events in COBOL

method-id main static.
    set MsgArrivedEvent to type Delegate::Combine
        (
          MsgArrivedEvent,
          new MsgArrivedEventHandler
             (self::My_MsgArrivedEventCallback)
        )
        as type MsgArrivedEventHandler
    invoke MsgArrivedEvent::Invoke("Test message")
       *> Throws exception if obj is null

    set MsgArrivedEvent to type Delegate::Remove
        (
          MsgArrivedEvent,
          new MsgArrivedEventHandler
              (self::My_MsgArrivedEventCallback)
        )
        as type MsgArrivedEventHandler
    invoke self::add_MsgArrivedEvent
        (
          new MsgArrivedEventHandler
            (self::My_MsgArrivedEventCallback)
        )
    invoke MsgArrivedEvent::Invoke("Test message 2")
       *> Throws exception if obj is null
end method.

method-id My_MsgArrivedEventCallback static.
procedure division using by value str as string.
    display str
end method.
end class.

See also the Delegates and Events samples, available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET.

Further Information

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.

To use a delegate in COBOL there must be a declaration, instantiation and finally invocation, as follows:

Declaring a delegate

To declare a delegate you must declare a method name and its signature. In COBOL you do this by defining a specialized class with a single method that represents the delegate. A delegate declaration looks very much like a class but is declared using the DELEGATE-ID keyword.

Instantiating a delegate

To make use of an existing delegate, for instance System.EventHandler defined in the framework, you must provide a method implementation with the same signature as the delegate. You can then instantiate a new instance of the delegate class by supplying your method as a parameter to the constructor. Depending upon whether this method is a static or an instance member of a class determines how you specify this parameter in the constructor, as specified below:

Static method:     class name::MethodName
Instance method:   object reference::MethodName
Invoking a delegate

When you declare a DELEGATE-ID, the Compiler creates a class that inherits from the System.MulticastDelegate class. All delegates have a method named 'Invoke' whose signature matches the signature of the method in your DELEGATE-ID declaration. Therefore, if you hold an object reference to a delegate instance, you can use the INVOKE method on this object which actually invokes the implementation of the method supplied when the delegate was constructed.

We provide a sample program that declares a new delegate class using DELEGATE-ID and then demonstrates how that delegate can be invoked using either static or instance method implementations. However, it's useful to note that in most cases, the delegate pattern is used in a more client/server like role where one software component provides the delegate definition and a separate component provides the implementation e.g. a method to be executed when a button on a form is clicked.

Further Examples

See also the Delegates sample, available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Access Modifiers
Attributes
Fields
Related information
Delegates and Events - in COBOL and C#


Enums

An enumeration represents a list of constant values, such as values for the days of the week. You can declare an enum type that defines the values and symbolic names for them. You can then refer to the values by name.

Context:

    Program Structure
        Types

enum-specification

enum-header type-specifier enum-constant

enum-header

access-modifier attribute-clause

enum-constant

type-specifier

Example

enum-id Action public.
working-storage section.
01 binary-long.         *> Underlying type for the enum.
                        *> binary-long is the default
    78 Starter value 0. *> Declare enum values as level-78 items
    78 Stop    value 1.
    78 Rewind  value 2.
    78 Forward value 3.
end enum.

See also the Enums sample, available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Further Information

The Compiler adds a static method called 'values' that returns an array containing the values of the enum. You can use this method together with the PERFORM THROUGH construct to iterate over the values of an enum type.

The enum-header is followed by a working-storage section consisting of:

  • A single numeric field of one of the predefined types. By default, this is binary-long.
  • Any number of level 78 items defining the values for the enum. The default value of the first item is 0 and the values of subsequent items are incremented by default.
Note:

In COBOL for .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: Structural Syntax Elements - Alphabetic List
Related reference
Access Modifiers
Attributes
Related information
Enumeration - in COBOL and C#


Structural Syntax Elements - Alphabetic List

  • Classes
    A class defines the data members and function members for object instances that are created from that class. Managed COBOL allows a class to inherit from one or more other classes.
  • Constructors
    A constructor is a class method that is executed when the class is created.
  • Delegates
    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.
  • Enums
    An enumeration represents a list of constant values, such as values for the days of the week. You can declare an enum type that defines the values and symbolic names for them. You can then refer to the values by name.
  • Fields
    A class, valuetype and interface can define a set of static or instance fields.
  • Indexers
    Indexers resemble properties except that their accessors take parameters. Indexers allow instances of a class or valuetype to be indexed just like arrays.
  • Interfaces
    An interface is a list of instance methods specifying names and signatures but without implementation.
  • Iterators
    An iterator is a section of code that returns an ordered sequence of values. You can create an iterator by defining a member as an iterator, using iterator-id.
  • Methods
    A method defines a block of code to be executed when the method is invoked.
  • Operators
    A set of default operators are predefined and implemented. You can overload an operator and define your own behavior for it.
  • Procedure Division
    The procedure division defines the code to be executed, when a type or member is invoked. The procedure division header defines any parameters to pass in to the code and any returning item to pass back.
  • Procedure Division Header
    The procedure division header defines the parameters passed to a member and also any returning item, the value computed by the member.
  • Properties
    Properties are members with associated types. They are similar to fields but they have accessors that provide the means to read and write values.
  • Type Members
    A class, valuetype or interface can define a set of members, such as methods and properties.
  • ValueTypes
    Value types can contain data members and function members, similar to classes. The difference is that value types store the data as values and don't require heap allocation.
Parent topic: Managed COBOL Reference


Common Phrases

  • Access Modifiers
    The access modifiers of an item control the visibility (accessibility) of the item to other code. For example, you can call public methods from anywhere, whereas private methods can be called only from other methods within the same type.
  • Attributes
    Attributes are used to provide additional information about elements within your program.
  • Constraints Paragraph
    The Constraints paragraph allows specification of properties of parameters of a generic type or method, and therefore allows the use of methods or properties on data items whose type is specified as that parameter.
  • Expressions
    An expression is a sequence of operators and operands.
  • Generic Using Phrase
    Generic types and methods can be defined in COBOL with the USING phrase.
  • Local Data Item Declaration
    Local data items are data items (also known as variables) that are declared in the procedure division body.
  • Type Specifier
    A type specifier is a declaration of a type, such as a class, interface, enum and so on.
Parent topic: Managed COBOL Reference


Access Modifiers

The access modifiers of an item control the visibility (accessibility) of the item to other code. For example, you can call public methods from anywhere, whereas private methods can be called only from other methods within the same type.

Context:

    Classes
    ValueTypes
    Interfaces
    Delegates
    Enums

    Fields

    Methods
    Properties
    Indexers
    Iterators

access-modifier

Further Information

By default, all types and members are PUBLIC, with the exception of fields which are PRIVATE.

The modifier affects the visibility of an item as follows:

Modifier: | Item is visible:
PUBLIC | always
PRIVATE | when the calling type is the same as the target type
PROTECTED | when the calling type inherits from the target type.
INTERNAL | when the calling type is in the same assembly as the target
PROTECTED INTERNAL or INTERNAL PROTECTED | when the calling type derives from the target type, or the calling type is in the same assembly as the target
PUBLIC
Indicates that this item may be accessed from any code.
PRIVATE
Indicates that this item may be accessed only from within the containing type.
PROTECTED
Indicates that this item may be accessed only from within the containing type or from a subtype that inherits from the containing type. You cannot specify PROTECTED on an abstract member. PROTECTED restricts access within an inheritance tree. For example, a protected field in a superclass can be accessed from any subclass, but it can't be accessed from a class outside the inheritance tree.
INTERNAL
Indicates that this item may be accessed only from within the current compilation unit.
PROTECTED INTERNAL or INTERNAL PROTECTED
Indicates that this item may be accessed only from within the containing type, from a subtype that inherits from the containing type, or from within the current compilation unit.
Parent topic: Common Phrases
Related reference
Constraints Paragraph
Classes
Delegates
Enums
Indexers
Interfaces
Iterators
Properties
ValueTypes
Fields
Related information
Comparison of COBOL with Other Managed Languages


Attributes

Attributes are used to provide additional information about elements within your program.

Context:

    Classes
    ValueTypes
    Interfaces
    Delegates
    Enums

    Fields

    Methods
    Constructors
    Properties
    Indexers
    Operators
    Iterators

attribute-clause

constructor-parameters property-name = property-value

Example

*> Define attributes on a class
class-id MyClass
          attribute WebService(name Description = "My service")
          attribute Obsolete.

*> Define attributes on a field
01 a binary-long attribute XmlAttribute("UpperB")
          attribute Obsolete static.

*> Define attributes on a property
*> Note that in this case, the attributes must follow
*> the reserved word PROPERTY
01 b binary-long property
          attribute XmlAttribute("UpperB")
          attribute Obsolete static.

*> Define attributes on an event
*> Note that the attributes must follow
*> the reserved word EVENT.
01 d type fred event
          attribute Obsolete static.

*> Define attributes on a method
method-id main
          attribute Obsolete static.
procedure division
    move 999 to a
    display a

end method.

*> Define attributes on a method parameter and return type
method-id stat static.
procedure division
          using by value l1 as binary-long
                   attribute CLSCompliant(true)
                   attribute MarshalAs(3)
          returning l2 as binary-long
                   attribute CLSCompliant(true)
                   attribute MarshalAs(2).
    move 999 to a
    display a
    set d to null
end method.

*> Define attributes on a property
method-id set property prop
          attribute Obsolete static.
procedure division using by value l1 as binary-long.
    move l1 to a
end method.

end class.

*> Define attribute on a delegate
delegate-id fred attribute Obsolete.
procedure division using by value l1 as binary-long.
end delegate.

See also the Custom Attributes sample, available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET.

To Specify Attributes

You can specify attributes using:

constructor parameters
These specify the parameters of a constructor for that attribute. The constructor parameters used in the attribute specification must match a constructor defined by the attribute. In the following example, the constructor expects a single parameter of type string:
 01 a binary-long attribute xml("UpperB").
NAME property-name = property-value
These are named parameters and correspond to properties defined on the attribute class. The named parameters must match properties defined by the attribute. In the following example, Description is a property of type string defined for the attribute class WebService:
attribute WebService(NAME Description="My service")

About Attributes

Attributes (also known as custom attributes) are used to provide additional information about elements within your program. Attributes may be used to describe methods, data items, properties, events, delegates, method parameters, assemblies, classes and method return values.

Much of the syntax used in a COBOL program describes program elements, such as the visibility of methods and fields (such as PUBLIC, PRIVATE and PROTECTED). All these descriptions are embedded as ‘Metadata’ into the dll or exe file output by the Compiler, and can be interrogated by other programs using Reflection. Attributes are a way of adding additional metadata to program elements in a way that is open ended and unlimited.

The attribute specified becomes part of the metadata describing the subject of the entry and is visible to a reflector.

Parent topic: Common Phrases
Related reference
Constraints Paragraph
Classes
Constructors
Delegates
Enums
Indexers
Interfaces
Iterators
Operators
Properties
ValueTypes
Fields
Related information
Attributes - in COBOL and C#


Expressions

An expression is a sequence of operators and operands.

expression

unary-expression binary-expression

unary-expression

unary-operator

binary-expression

binary-operator

method-invocation-expression

type-specifier method-arguments

Where:

method-arguments
The method arguments are values or variable references that are passed to a method. The actual values of the arguments are specified when the method is invoked. Each argument and its type is specified in the method’s procedure division header in the USING clause.

When you invoke a method, you specify the arguments in the invocation. The invoked method receives the arguments in the same order as in the invocation.

subscript-expression

[ subscript ] ( subscript )

Where:

[ subscript ]
Square brackets [ ] indicate that the subscript is zero based. For example:
     myArray[5]   *> sixth item in the array

Square brackets can also be used to pass the parameters to an indexer expression.

( subscript )
Round parentheses ( ) indicate that the subscript is one based. For example:
     myArray(5)   *> fifth item in the array

literal

identifier

Parent topic: Common Phrases


Generic Using Phrase

Generic types and methods can be defined in COBOL with the USING phrase.

Context:

    Classes
    ValueTypes
    Interfaces
    Methods

generic-using-phrase

generic-argument

generic-argument

generic-argument conventionally has a single character upper case name such as T and U.

Example

In this example, the main method finds and displays the greater and the smaller number from two ones. T is a generic argument to the Min method, which in this case is a static generic method. The Min method expects two parameters both of which should be of the same type as the generic parameter. The CompareTo method may be invoked since T is known to implement the IComparable interface.

       class-id GenericMath.

       method-id main static.
       01 n1 binary-double.
       01 n2 binary-double.
           set n1 to 999
           set n2 to 100
           display n1 space n2
           display 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 System.IComparable.
       procedure division using by value item1 as T item2 as T
                      returning res as T.
           if item1::CompareTo(item2) < 0
               set res to item1
           else
               set res to item2
           end-if
       end method.
       method-id Max using T static.
       constraints.
           constrain T implements type System.IComparable.
       procedure division using by value item1 as T item2 as T
                      returning res as T.
           if item1::CompareTo(item2) < 0
               set res to item2
           else
               set res to item1
           end-if
       end method.

       end class.

See also the Generics samples, which are available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET.

Parent topic: Common Phrases
Related reference
Constraints Paragraph
Related information
Generics, Defining - in COBOL and C#


Local Data Item Declaration

Local data items are data items (also known as variables) that are declared in the procedure division body.

Context

    Procedure Division
        DECLARE Statement
        PERFORM Statement
        TRY Statement

local-declaration

type-specifier

Example

       declare i1 as binary-long
       display i1

       *>   Optionally, the variables can be initialised inline
        declare c2 as condition-value = true
        display c2

        declare string-list2 as string occurs 3 = table of string("Bill", "Ben", "LittleWeed")

      **************************************************************************
      * Iteration Variables
      **************************************************************************

      *>   A variable can be declared at the point of use in an iterator.
      *>   In this case the scope of i will be until the end-perform.
           perform varying i as binary-long from 1 by 1 until i > 10
               display i
           end-perform

      **************************************************************************
      * Exception Variables
      **************************************************************************

      *>   The example below shows that you can declare e at the point of use.
      *>   It is in scope until the end-try.
           try
               display "exception test"
           catch e as type Exception
               display e::Message
           end-try

See also the Local Variables sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Further Information

The scope of any inline local variable is from the point of declaration until the end of the innermost containing block, where paragraphs, sections and the whole method are considered to be blocks.

Parent topic: Common Phrases
Related reference
DECLARE Statement
Type Specifier
Procedure Division Header
Fields
Related information
Data Types - in COBOL and C#


Type Specifier

A type specifier is a declaration of a type, such as a class, interface, enum and so on.

Context:

    Classes
    ValueTypes
    Interfaces
    Enums
    Properties
    Indexers
    Fields

type-specifier

simple-type-specifier

simple-type-specifier

predefined-type-specifier

predefined-type-specifier

Example

Predefined Types
  01 dAmount  decimal.
  01 asNames string occurs 5.
  01 abFigures binary-long occurs any.
TYPE keyword
  01 objMyType type MyType.
  01 objDataTime type DateTime.        *> .NET COBOL
  01 objDataTime type java.util.Date.  *> JVM COBOL

Where:

  • objMyType is defined as an object of type MyType
  • objDataTime is defined as an object type DateTime in .NET COBOL or java.util.Date in JVM COBOL.

Long Type Names

To define a namespace to represent long class names so that you need to type a short name only, use the ILUSING directive.

Type Compatibility with Managed Types

All the predefined COBOL data types and any further managed types that you define are mapped onto the corresponding native managed type (.NET or JVM), but they must conform to the following rules. They:

  • Must be declared at 01 (or 77) level
  • Must have no REDEFINES or RENAMES
  • Must never be the subject of reference modification
  • Must never be the subject of the ADDRESS OF clause
  • May use format 3 of the OCCURS clause to declare an array

Any COBOL data item that does not follow these rules, or is of any other category, is not considered to be a managed type (.NET or JVM) and is allocated by the Compiler within an internally managed byte array. COBOL pointer data items always point into one of these byte arrays.

Generic Types

In .NET COBOL, to refer to a generic type using the TYPE literal syntax, you enumerate the generic parameters within square brackets. The following example declares myNames as an item of type Dictionary with both generic parameters set to string (System.String):

myNames type System.Collections.Generic.Dictionary[string, string].
Parent topic: Common Phrases
Related reference
Indexers
Operators
Properties
Local Data Item Declaration
Fields
Related information
Operator Overloading in Managed COBOL
String Handling in Managed COBOL
Types and Type Conversion
Type Compatibility of Managed COBOL with Other Managed Languages
Type Mappings from Native COBOL to Managed Code


Statements - Alphabetic List

  • Statements
  • ACCEPT Statement
    Takes data keyed at the console or supplied by the operating system and makes it available to the program in a specified data item.
  • ADD Statement
    Adds two or more numeric operands and stores the result.
  • CREATE Collection Statement
    Creates or constructs an instance of a list or dictionary.
  • COMPUTE Statement
    Assigns to one or more data items the value of an arithmetic expression.
  • CONTINUE Statement
    The CONTINUE statement is a no operation statement, indicating that no executable statement is present.
  • DECLARE Statement
    Declares one or more local variables within the procedure division body. The scope of any inline local variable is from the point of declaration until the end of the innermost containing block, where paragraphs, sections and the whole method are considered to be blocks.
  • DELETE Collection Statement
    Deletes an element from the list or dictionary.
  • DISPLAY Statement
    Displays the specified data items.
  • DIVIDE Statement
    Divides one numeric data item into others and sets the values of data items equal to the quotient and remainder.
  • EVALUATE Statement
    Describes a multi-branch, multi-join structure, which can evaluate multiple conditions. The subsequent action of the run-time element depends on the results of these evaluations.
  • EXIT Statement
    Causes an exit from a perform loop, method or iterator.
  • GOBACK Statement
    Causes a return from a method.
  • IF Statement
    Evaluates a condition and takes subsequent action depending on whether the value of the condition is true or false.
  • INVOKE Statement
    Invokes a method.
  • MOVE Statement
    Transfers data to one or more data areas.
  • MULTIPLY Statement
    Multiplies numeric data items and sets the values of data items equal to the results.
  • PERFORM Statement
    Controls execution of a statement block in the scope of the PERFORM statement. This statement can also process each element of an array or collection.
  • RAISE Statement
    Raises an exception.
  • READ Collection Statement
    Reads an element in the list or in the dictionary from a given key.
  • RESET Collection Statement
    Deletes all the elements from the list or dictionary.
  • REWRITE Collection Statement
    Overwrites an element in the list or dictionary.
  • SET Statement
    Can set the size of an array; initialize the contents of an array and set the size accordingly; and set the value of a data item or a boolean data item.
  • SORT Statement
    Sorts the elements of a table.
  • SUBTRACT Statement
    Subtracts one, or the sum of two or more, numeric data items from one or more items, and set the values of one or more items equal to the results.
  • SYNC Statement
    Marks a statement block as a critical section by obtaining the mutual-exclusion lock for a given object, executing a block of statements, and then releasing the lock.
  • TRY Statement
    The TRY...CATCH...FINALLY...END-TRY structure is the basis for structured exception handling. 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.
  • WRITE Collection Statement
    Writes an element to the list or dictionary.
Parent topic: Managed COBOL Reference


Statements

Context:

Procedure Division

statement-block

Parent topic: Statements - Alphabetic List


ACCEPT Statement

Takes data keyed at the console or supplied by the operating system and makes it available to the program in a specified data item.

Context:

    Procedure Division
        Statements

accept-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.
Parent topic: Statements - Alphabetic List
Related reference
The ACCEPT Statement


ADD Statement

Adds two or more numeric operands and stores the result.

Context:

    Procedure Division
        Statements

add-statement

Parent topic: Statements - Alphabetic List


CREATE Collection Statement

Creates or constructs an instance of a list or dictionary.

Context:

    Procedure Division
        Statements

create-collection-statement

Where: identifier is the name of the list or dictionary collection type.

Example

The following declares and creates a list collection: and then writes an element to the list:

       declare stringList as list[string]
       create stringList
       write stringList from "item 0"

See also the Collections sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Parent topic: Statements - Alphabetic List


COMPUTE Statement

Assigns to one or more data items the value of an arithmetic expression.

Context:

    Procedure Division
        Statements

compute-statement

Parent topic: Statements - Alphabetic List


CONTINUE Statement

The CONTINUE statement is a no operation statement, indicating that no executable statement is present.

Context:

    Procedure Division
        Statements

continue-statement

Parent topic: Statements - Alphabetic List


DECLARE Statement

Declares one or more local variables within the procedure division body. The scope of any inline local variable is from the point of declaration until the end of the innermost containing block, where paragraphs, sections and the whole method are considered to be blocks.

Context:

    Procedure Division
        Statements

declare-statement

Example

       declare i1 as binary-long
       display i1

       *>   Optionally, the variables can be initialised inline
        declare c2 as condition-value = true
        display c2

        declare string-list2 as string occurs 3 = table of string("Bill", "Ben", "LittleWeed")

See also the Local Variables sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Parent topic: Statements - Alphabetic List
Related reference
Local Data Item Declaration


DELETE Collection Statement

Deletes an element from the list or dictionary.

Context:

    Procedure Division
        Statements

delete-collection-statement

Where: identifier is the name of the list or dictionary collection type.

Parent topic: Statements - Alphabetic List


DISPLAY Statement

Displays the specified data items.

Context:

    Procedure Division
        Statements

display-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.
Parent topic: Statements - Alphabetic List
Related reference
The DISPLAY Statement


DIVIDE Statement

Divides one numeric data item into others and sets the values of data items equal to the quotient and remainder.

Context:

    Procedure Division
        Statements

divide-statement

Parent topic: Statements - Alphabetic List


EVALUATE Statement

Describes a multi-branch, multi-join structure, which can evaluate multiple conditions. The subsequent action of the run-time element depends on the results of these evaluations.

Context:

    Procedure Division
        Statements

evaluate-statement

Parent topic: Statements - Alphabetic List


EXIT Statement

Causes an exit from a perform loop, method or iterator.

Context:

    Procedure Division
        Statements
Program Structure
   Types
      { Classes ValueTypes Interfaces Delegates Enums  }
           *
               Procedure Division
                  statement-block

exit-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.
Parent topic: Statements - Alphabetic List
Related reference
The EXIT Statement


GOBACK Statement

Causes a return from a method.

Context:

    Procedure Division
        Statements

goback-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.
Parent topic: Statements - Alphabetic List
Related reference
The GOBACK Statement


IF Statement

Evaluates a condition and takes subsequent action depending on whether the value of the condition is true or false.

Context:

    Procedure Division
        Statements

if-statement

Parent topic: Statements - Alphabetic List
Related information
Choices - in COBOL and C#


INVOKE Statement

Invokes a method.

Context:

    Procedure Division
        Statements

invoke-statement

method-invocation-expression

Example

In the following example, the arguments a and b above are passed to the invoked method, and these correspond to the parameters x and y respectively, in the invoked method. The types of the parameters are specified in the AS phrase of the USING clause.

       01 a string.
       01 b binary-long.
       invoke type MyClass::MyMethod(a,b)
       ...

       method-id MyMethod.
       procedure division using x as string
                                y as binary-long.
       ...
       end method.

See also the Core sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Parent topic: Statements - Alphabetic List
Related reference
Procedure Division Header
SET Statement
Related information
Types and Type Conversion
Functions, Methods - in COBOL and C#
Objects - in COBOL and C#
Invoking a Method


MOVE Statement

Transfers data to one or more data areas.

Context:

    Procedure Division
        Statements

move-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.
Parent topic: Statements - Alphabetic List
Related reference
The MOVE Statement


MULTIPLY Statement

Multiplies numeric data items and sets the values of data items equal to the results.

Context:

    Procedure Division
        Statements

multiply-statement

Parent topic: Statements - Alphabetic List


PERFORM Statement

Controls execution of a statement block in the scope of the PERFORM statement. This statement can also process each element of an array or collection.

Context:

    Procedure Division
        Statements

perform-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.

Example of local declaration within an iterator

A variable can be declared at the point of use in an iterator, and its scope is until the end of the perform block.

      *>   In this case, the scope of i is until the end of the perform block.
           perform varying i as binary-long from 1 by 1 until i > 10
               display i
           end-perform

      *>   So the i in the following perform block is a new instance of i,
      *>   independent of the i in the preceding perform block.
           perform varying i as binary-short from 0 by 1 until i > 10
               display i
           end-perform

Here, k is declared inline to iterate through a dictionary. Again, it is in scope until the corresponding end-perform.

    01 dict1 dictionary[string string].
           create dict1
           write dict1 from "Anthony" key "A"
           write dict1 from "Brian" key "B"
           write dict1 from "Charles" key "C"
           perform varying key k as string value val as string through dict1
               display k ":" val
           end-perform
           perform varying value val as string through dict1
               display val
           end-perform
           perform varying key k as string through dict1
               display k
           end-perform

See also the Local Variables sample, available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Parent topic: Statements - Alphabetic List
Related reference
The PERFORM Statement
Related information
Loops - in COBOL and C#


RAISE Statement

Raises an exception.

Context:

    Procedure Division
        Statements

raise-statement

Example

See the Exception Handling sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET.

Parent topic: Statements - Alphabetic List
Related reference
TRY Statement
Related information
Exception Handling - in COBOL and C#


READ Collection Statement

Reads an element in the list or in the dictionary from a given key.

Context:

    Procedure Division
        Statements

read-collection-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.

Where: identifier is the name of the list or dictionary collection type.

Example

The following reads an element from a list collection:

       declare val as string
       read stringList into val key 0

The following example, shows exception handling and catching an exception on reading an invalid key in a dictionary collection:

       display "reading an invalid key message : "
       read stringDictionary into val key "RUBBISH"
       invalid key
           display "Caught invalid key"
       not invalid key
           display "Shouldn't see this"
       end-read

See also the Collections sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Parent topic: Statements - Alphabetic List


RESET Collection Statement

Deletes all the elements from the list or dictionary.

Context:

    Procedure Division
        Statements

reset-collection-statement

Where: identifier is the name of the list or dictionary collection type.

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.
Parent topic: Statements - Alphabetic List


REWRITE Collection Statement

Overwrites an element in the list or dictionary.

Context:

    Procedure Division
        Statements

rewrite-collection-statement

Where: identifier is the name of the list or dictionary collection type.

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.

Example

The following overwrites the first element in the list stringList.

       rewrite stringList from "ITEM REWRITE" key 0
       display "The contents of the list after rewrite element 0 : "
       invoke self::displayListContents(stringList)

See also the Collections sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Parent topic: Statements - Alphabetic List


SET Statement

Can set the size of an array; initialize the contents of an array and set the size accordingly; and set the value of a data item or a boolean data item.

Context:

    Procedure Division
        Statements

set-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.

Example

See the Core sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Parent topic: Statements - Alphabetic List
Related reference
INVOKE Statement
The SET Statement
Related information
Invoking a Method
Arrays - in COBOL and C#
Objects - in COBOL and C#


SORT Statement

Sorts the elements of a table.

Context:

    Procedure Division
        Statements

sort-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.
Parent topic: Statements - Alphabetic List
Related reference
The SORT Statement


SUBTRACT Statement

Subtracts one, or the sum of two or more, numeric data items from one or more items, and set the values of one or more items equal to the results.

Context:

    Procedure Division
        Statements

subtract-statement

Parent topic: Statements - Alphabetic List


SYNC Statement

Marks a statement block as a critical section by obtaining the mutual-exclusion lock for a given object, executing a block of statements, and then releasing the lock.

Context:

    Procedure Division
        Statements

sync-statement

Example

class-id Account.
  working-storage section.
  01 balance binary-long.
  01 r type Random value new Random.
  method-id new.
  procedure division using value init as binary-long.
      move init to balance
  end method.

  method-id Withdraw.
  procedure division using value amount as binary-long returning ret as binary-long.
  *> This condition will never be true unless the lock statement
  *> is commented out:
      if balance > 0
          display "< 0"
          raise new Exception("Negative Balance")
      end-if
      sync on self
          if balance >= amount
               display "In critical section"
               *>display "Balance before Withdrawal :  " balance
               *>display "Amount to Withdraw        : -" amount
               compute balance = balance - amount
               *>display "Balance after Withdrawal  :  " balance
               move amount to ret
          else
               display "In critical section"
               move 0 to ret
          end-if
      end-sync
  end method.

  method-id DoTransactions.
  local-storage section.
  01 i binary-long.
  procedure division.
      perform varying i from 0 by 1 until i = 100
          invoke self::Withdraw(r::Next(1, 100))
      end-perform
  end method.
end class.
Parent topic: Statements - Alphabetic List
Related information
Synchronization - in COBOL and C#


TRY Statement

The TRY...CATCH...FINALLY...END-TRY structure is the basis for structured exception handling. The TRY block allows you to test a section of code for exceptions that may occur during its execution. The CATCH block must specify the type of exception you wish to handle if one should occur during the execution of the TRY block. The FINALLY block allows you to execute a section of code following the TRY block, whether or not an exception occurred.

Context:

    Procedure Division
        Statements

try-statement

Example of a local declaration of an exception

      *>   The example below shows that you can declare e at the point of use.
      *>   It is in scope until the end-try.
           try
               display "exception test"
           catch e as type Exception
               display e::Message
           end-try

See also the Local Variables sample and Exception Handling sample, available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Further Information

In the TRY statement, the:

TRY statement-block
specifies a block the section of code to be tested for exceptions that may occur during its execution
CATCH statement-block
specifies the type of exception to handle if an exception occurs during execution of the TRY block
FINALLY statement-block
specifies the section of code to execute following the TRY block, whether or not an exception occurred

Your program can raise an exception using the RAISE statement and pass this exception back to the caller. This is commonly referred to as "throwing an exception".

Parent topic: Statements - Alphabetic List
Related reference
RAISE Statement
Related information
Exception Handling - in COBOL and C#


WRITE Collection Statement

Writes an element to the list or dictionary.

Context:

    Procedure Division
        Statements

write-collection-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.

Example

The following declares and creates a list collection and then writes an element to the list:

       declare stringList as list[string]
       create stringList
       write stringList from "item 0"

The following writes 5 more elements to the list using a perform loop:

       perform varying i as binary-long from 1 by 1 until i > 5
           write stringList from "item " & i
       end-perform

       display "The contents of the list : "
       invoke self::displayListContents(stringList)

See also the Collections sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Parent topic: Statements - Alphabetic List


Concepts - Managed COBOL

  • Extension Methods and Operators
    Extension methods enable you to add methods to existing types thereby providing additional functionality without the need to edit or recompile the code.
  • Invoking a Method
    You can invoke a method in two ways: by using the invoke statement or by using the inline invocation syntax.
  • Method Overloading in Managed COBOL
    Managed COBOL supports method overloading
  • Operator Overloading in Managed COBOL
    You can overload operators to provide alternative behavior, or behavior for different operand types.
  • String Handling in Managed COBOL
    Managed COBOL provides a predefined managed string type and provides powerful techniques for handling strings.
  • Types and Type Conversion
    Types can be converted into other types using the AS syntax or a conversion operator.
  • Type Compatibility of Managed COBOL with Other Managed Languages
    Many managed COBOL types have a strict correspondence with managed types in other languages, such as binary-long and float-short. For those that don't have a correspondence, there are alternatives.
  • Type Mappings from Native COBOL to Managed Code
    COBOL data items are exposed as managed types, when the code is compiled with the ILSMARTLINKAGE directive.
Parent topic: Managed COBOL Reference


Extension Methods and Operators

Extension methods enable you to add methods to existing types thereby providing additional functionality without the need to edit or recompile the code.

Extension Methods

Similar to other managed code languages such as C#, managed COBOL supports extension methods, which enable you to add methods to existing types thereby providing additional functionality without the need to edit or recompile the code.

For example, the following extension method extends the string class, by adding a method to count the number of words in a string:

       class-id MyCount static.
       method-id CountWords extension. *> extension method is implicitly static
       procedure division using str as string
                          returning wordCount as binary-long.
            set wordCount to str::Split(' ')::Length
       end method.
       end class.

You extend a method when you cannot override it. The method you want to extend might be in a final class or in code that you don't have access to. In these cases, you can define and compile the extension method separately and then use it freely.

Defining an extension method

Use the following construction to define an extension method:

       class-id MyExtension static.
       method-id MyExtensionMethod extension.
       procedure division using myName as ExtendedType
                      returning myReturnName as returnType.
           set myReturnName to my code...
       end method.
       end class.

To define an extension method:

  • Use the EXTENSION keyword in the method header.
  • The method must be in a static class that is not nested or generic. The method is implicitly static.
  • In the method body, the first parameter is the type to extend. It is always a value parameter.
Consuming an extension method

There is no special syntax for calling extension methods. You consume extension methods in much the same way as any other method, except you specify the first parameter as the type that is extended. You use this syntax:

parameter-1::method-name(more parameters)

In the example below, you consume with code such as aString::CountWords:

       class-id MyWords.
       method-id CheckWords.
       01 myWordCount binary-long.
       procedure division using value aString as string
                          returning b as condition-value.
           set myWordCount to aString::CountWords
           if myWordCount < 10
               set b to true
           else
               set b to false
           end-if
       end method.
       end class.

You use extension methods as if they were instance methods defined in another class or interface. Extension methods appear as additional methods available on an object instance and yet they are implemented elsewhere. Intellisense shows all methods you can use including the extension methods that are declared elsewhere. An extension method is indicated with a different icon and its tooltip includes the phrase (extension).

When you invoke an extended method, the extension method is not contained in the class specified in the invoking statement. It is contained in another class elsewhere. The invoking and executing classes are different. The method's defined and execution containing types are different.

Extension methods work like this:

  • The Compiler produces a static method with parameters. The type of the first parameter is the type being executed (or invoked). The second and subsequent parameters are the declared parameters. For example, the Compare method effectively has two parameters: the type of the first parameter is a string, and the second parameter is s2.
  • The first parameter is annotated with the System.run-time.CompilerServices.ExtensionAttribute attribute (or in the case of a JVM program, an equivalent that is defined in the JVM runtime system). This attribute is also applied to the containing class and assembly.

Extension Operators

Extension operators are very similar to extension methods. They enable you to provide alternative behavior for an operator, without the need to edit or recompile the code. You define and use extension operators in the same way as extension methods.

For example, you could define and use an extension plus operator, as follows:

       set timer3 to timer1 + myMins
       operator-id + extension.
       01 sumMins binary-long.
       01 m binary-long value 0.
       01 h binary-long value 0.
       procedure division using value a as type Timer
                                      b as binary-long
                            returning c as type Timer.
           set sumMins to a::pMins + b
           divide sumMins by 60 giving h remainder m
           set c to new Timer(a::pHour + h , m)
       end operator.

You extend an operator when you cannot overload it. The operator you want to extend might be in a final class or in code that you don't have access to. In these cases, you can define and compile the extension operator separately and then use it freely.

To declare and use an extension operator:

  • Declare the operator using the EXTENSION keyword. The operator must be in a static class.
  • There is no special syntax for using extension operators.
  • In JVM managed COBOL, the extension operator must be available to the Compiler. You might need to use the ILREF directive in combination with the JVMGEN directive. See Extension Methods for full details.

Extension operators are implemented as methods, such as an op_Equality or op_Addition method. This method is added to a specific dictionary in TypeInfo. This enables the code looking for operator overloads and extensions to look in this dictionary in addition to the classes of the two operands.

Extension Methods (and Operators) in JVM COBOL

When you invoke a method, you specify the class in which the method belongs. In our example, the method CheckWords() in the myWord class and is invoked as follows:

       01 myWord type MyWords.
       01 myDoc string.
       01 sizeOK condition-value.
           set sizeOK to myWord::CheckWords(myDoc)
           ...
       class-id MyWords final.
       method-id CheckWords.
       ...

In the above, since the class can be found, so can the method. The class loader architecture uses the class on which a method is defined to know when to load a class. In this case, the myWord class is loaded before the method CheckWords() is invoked. This happens in much the same way during compilation. When the myWord::CheckWords method is referred to in a class that is being compiled, the Compiler uses a class loader to load the CheckWords method to resolve the method signature and understand how to generate the appropriate code.

Problem: extensions can't be found

However, when you invoke an extended method (or operator), the extension method is not contained in the class specified in the invoking statement. In our example, the extension method CountWords() is invoked on the type of the aString variable (which is a string), but it is executed in your extension class, as follows:

       01 aString string.
       01 myWordCount binary-long.
           set myWordCount to aString::CountWords
           ...
       class-id MyCount static.
       method-id CountWords extension.
       ...

Although the method is invoked on the String class, the method to be executed is contained in a different class (the MyCount class). The class loader can't find the method, because its defined and execution containing types are different. For the Compiler to use extension methods (and extension operators), it has to load their defining classes before compiling the classes that refer to those extensions.

Solution: preload the extensions

To ensure that the Compiler can find the extensions, you use ILREF directive at the command line, combined with the JVMGEN directive. The following example loads the class defined within the ops.class file. The name and package of the class defined in ops.class does not need to be the same as the name and directory of the class file.

Windows:

cobol x.cbl jvmgen ilref(ops.class);

UNIX:

cob x.cbl –C jvmgen  -C ilref(ops.class)

The following command unpacks the file ops.jar and loads the moreOps.class. Note that the .jar file needs to be on the CLASSPATH environment variable or specified in the JVMCLASSPATH directive for it to work.

Windows:

cobol -j x.cbl jvmclasspath(ops.jar) ilref(moreOps.class);

UNIX:

cob -j x.cbl -C jvmclasspath(ops.jar) –C ilref(moreOps.class)

The ILREF directive requires a file in class format. Files with the .class extension are treated as class format.

Preloaded Extensions for JVM

The following extensions are supplied for JVM:

  • String equality extension operator
  • Substring extension method

The classes containing the extensions are preloaded by the Compiler by using the ILREF directive.

String Equality Extension Operator

An extension operator for string equality is preloaded by the Compiler before compilation. This ensures that a check for equality gives the same results in the .NET environment as in the JVM environment. For example, the following code compares two strings:

       01 string1 string value “12345”.
       01 string2 string value “12345”.
       if string1 = string2
              display “the values are the same”
       else
           display “error - the values look the same, but the equality returned false”
       end-if

Without the preloaded extension, the code sees the strings as different, because the JVM java.lang.String::equality(string) method compares the references and the .NET System.String::equality(string) method compares the values. With the preloaded extension, the code sees the strings as the same.

The string equality extension extends both the = and equals operators for the type string. The operator returns true if the two string instances contain exactly the same character sequence, false otherwise. The operator extension is defined as:

       operator-id = extension.
       procedure division using value a as string
                                      b as string
                          returning r as condition-value.

To check for object equality between string instances use:

       if a as object = b as object
Substring Extension Method for JVM COBOL

An extension method for Substring is preloaded by the Compiler before compilation. This ensures that the Substring method gives the same results in the .NET environment as in the JVM environment. For example:

       01 x string value “1234567890”.
       display x::Substring(2,3) “ The .NET way of doing things”
       display x::substring(2,3) “ The JDK way of doing things”

Since, the .NET behavior of System.String::Substring(int, int) differs from the JVM behavior of java.lang.String::Substring(int int), you get different results for .NET and JVM, if the extension is not installed. However, if the extension is installed, the JVM behavior matches that of .NET and you get the same results.

The Substring extension method extends the string type (which is also java.lang.String). This method returns a new instance of string with a signature that matches that of the Substring method in .NET. The Substring method extension is defined as follows:

       method-id Substring extension.
       procedure division using value a as string
                                startIdx as binary-long
                                sslength as binary-long
                      returning r as string.

String Equality Extension Operator for JVM

An extension operator for string equality is preloaded by the Compiler before compilation. This ensures that a check for equality gives the same results in the .NET environment as in the JVM environment. For example, the following code compares two strings:

       01 string1 string value “12345”.
       01 string2 string value “12345”.
       if string1 = string2
              display “the values are the same”
       else
           display “error - the values look the same, but the equality returned false”
       end-if

Without the preloaded extension, the code sees the strings as different, because the JVM java.lang.String::equality(string) method compares the references and the .NET System.String::equality(string) method compares the values. With the preloaded extension, the code sees the strings as the same.

The string equality extension extends both the = and equals operators for the type string. The operator returns true if the two string instances contain exactly the same character sequence, false otherwise. The operator extension is defined as:

       operator-id = extension.
       procedure division using value a as string
                                      b as string
                          returning r as condition-value.

To check for object equality between string instances use:

       if a as object = b as object

Substring Extension Method for JVM COBOL

An extension method for Substring is preloaded by the Compiler before compilation. This ensures that the Substring method gives the same results in the .NET environment as in the JVM environment. For example:

       01 x string value “1234567890”.
       display x::Substring(2,3) “ The .NET way of doing things”
       display x::substring(2,3) “ The JDK way of doing things”

Since, the .NET behavior of System.String::Substring(int, int) differs from the JVM behavior of java.lang.String::Substring(int int), you get different results for .NET and JVM, if the extension is not installed. However, if the extension is installed, the JVM behavior matches that of .NET and you get the same results.

The Substring extension method extends the string type (which is also java.lang.String). This method returns a new instance of string with a signature that matches that of the Substring method in .NET. The Substring method extension is defined as follows:

       method-id Substring extension.
       procedure division using value a as string
                                startIdx as binary-long
                                sslength as binary-long
                      returning r as string.
Parent topic: Concepts - Managed COBOL
Related reference
Methods
Related information
Functions, Methods - in COBOL and C#


Invoking a Method

You can invoke a method in two ways: by using the invoke statement or by using the inline invocation syntax.

INVOKE statement

For example, the following INVOKE statement invokes the replace method on the input string obj-string and returns the results in obj-string. Notice that the case of the method name is different for .NET and JVM. It is replace in .NET and Replace in JVM.

       invoke obj-string::replace("Some" "New")   *> .NET
       invoke obj-string::Replace("Some" "New")   *> JVM
       display obj-string

Inline invocation

Similarly, the following SET statement uses the inline invocation syntax, which employs an implicit set property method. This example statement invokes the Replace() method on the input string obj-string and sets the results in the aString variable.

       set aString to obj-string::replace("Some" "New")   *> .NET
       set aString to obj-string::Replace("Some" "New")   *> JVM
       display aString

In addition, you can use the inline invocation syntax to access properties. In the following example, the Length property of the string myString is accessed and is displayed:

       display "Total characters is " myString::Length

You can invoke any method in the same compilation as the invoking code, either a static or instance method, as follows:

Invoking a static method

To invoke a static method, you specify the class name, followed by :: and then the method name. For example, SimpleClass::StaticMethod as in the invoke statement below:

       invoke type SimpleClass::StaticMethod
       ...
       class-id SimpleClass.
       method-id StaticMethod  static.
          display "In static method"
       end method.
       end class.

Invoking an instance method

To invoke an instance method in the same compilation unit, you instantiate an object first. You can then specify the instance object, followed by :: and then the method name. For example, mySimpleObj::InstanceMethod as in the invoke statement below:

       01 mySimpleObj type SimpleClass.
       set mySimpleObj to new SimpleClass("Hello")
       invoke mySimpleObj::InstanceMethod
       ...
       class-id SimpleClass.
       01 thisString string.

       method-id New.
       procedure division using by value aString as string.
           set thisString to aString
       end method.

       method-id InstanceMethod.
       procedure division.
           display "In instance method"
           display "Instance data is " thisString
       end method.

Examples

See also the Core sample, which is available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Parent topic: Concepts - Managed COBOL
Related reference
SET Statement
INVOKE Statement
Related information
Functions, Methods - in COBOL and C#
Objects - in COBOL and C#


Method Overloading in Managed COBOL

Managed COBOL supports method overloading

About Overloading

Overloading is a programming technique where you overload a method name with more than one implementation.

For example, there may be a method called CalculateBill, taking as a parameter a list of purchases. We may want to have a variant of this method which, in addition to the list of purchases, has another parameter representing a discount code. The two methods can have the same name, and, when the method is invoked, the required one is selected based on the presence or absence of the discount code parameter.

Method Overloading in Managed COBOL

In managed COBOL, it is permissible (and very common practice) for a given class or interface to have multiple methods with the same name, which are distinguished from each other by having different signatures. The signature of a method is determined by the:

  • Number of parameters
  • Type of each parameter
  • Passing mode (BY VALUE, BY REFERENCE, or BY OUTPUT) of each parameter
  • Return type , which in .NET COBOL, this type may be System.Void, which represents a method with no RETURNING item

When code written in COBOL, or any other language, attempts to invoke a method in some class or interface, and more than one method with the given name exists, then a choice of the available methods is made. The choice is based on the number of parameters and the ‘best’ type match for the parameters (the precise definition of ‘best’ is complex and is treated later). If no method with a suitable signature can be found, a ‘method not found’ error results. If there is no method that provides a better match than all the other possible methods with this name, an ‘ambiguous match’ error is given.

Although the type of the RETURNING item is a part of the method's signature, the choice of method to be invoked is never based on the RETURNING type. This is different from .NET and JVM, which allow a class to have multiple methods that differ only by returning type. This is not generally good practice, and COBOL produces an error if it finds such multiple methods within a single class. The only time when such multiple methods can arise from a COBOL program is in the case of the explicit and implicit operators.

Method Signatures

The type of a COBOL parameter may be specified by:

  • Referencing the type explicitly in the PROCEDURE DIVISION phrase using the AS syntax
  • Declaring a linkage section item with a given type and referencing that linkage section item in the PROCEDURE DIVISION USING phrase

For REFERENCE and OUTPUT parameters, managed types are exposed directly as managed pointers to the corresponding managed type. COBOL data types that do not correspond to managed types (such as PIC X fields, groups, numeric fields other than BINARY-LONG and so on) are exposed as COBOL pointers (objects of type MicroFocus.COBOL.Program.Reference, in .NET COBOL).

For VALUE parameters, and RETURNING items, types are exposed as follows:

COBOL types: are exposed as:
Managed types | objects of the corresponding type
Numeric items with more than 19 decimal digit positions | MicroFocus.COBOL.Program.BigDecimal
Numeric items with implied decimal point, such as PIC 9(9)v99, all sizes | - System.Decimal in .NET COBOL
Unsigned numeric items with no implied decimal point: In .NET COBOL:
  • < 3 numeric digits - unsigned int8
  • < 5 numeric digits - unsigned int16
  • < 10 numeric digits - unsigned int32
  • < 19 numeric digits - unsigned int64

In JVM COBOL, they are exposed the same as signed numeric items.

Signed numeric items with no implied decimal point:
  • < 3 numeric digits - int8
  • < 5 numeric digits - int16
  • < 10 numeric digits - int32
  • < 19 numeric digits - int64
All other types PIC X, group and so on | string

Method Overload Resolution

Method overload resolution takes place in two phases:

  1. Selection of all applicable methods, that is, selection of all those methods with the given name for which the arguments specified in the invoking program are compatible with the parameters of the target methods. If no such applicable method is found, then an error (method not found) is produced.
  2. Selection of the ‘best’ match from within the set of applicable methods. The general intent of the selection process is to produce the best match (in the sense of most specific match) for the given set of arguments.

    Formally, the method overload that is ‘better’ than any other of the applicable method overloads is chosen. If no single overload is determined to be better than any other overload, then the match is considered to be ambiguous, and a compiler error results.

    If this process does not result in a unique best match, an error (ambiguous match error) is produced

Note:

In this discussion, the term arguments means the set of parameters specified in the invoking method (for example obj01 in the statement:

INVOKE self::Method1(obj01)

The term parameters means the formal parameters specified in each method definition (in the PROCEDURE DIVISION USING header).

Selection of Applicable Methods

We start with the complete set of all methods with the required name that exist in the target class or in any of its parent classes (excluding those with identical signatures). From this set, any methods that are not visible from the invoking program, based on the visibility attribute encoded into the method, are discarded as follows:

Attribute | Visibility
PRIVATE | Visible only if the calling class is the same as the target class
PUBLIC | Always visible
PROTECTED | Visible only if the calling class derives from the target class
INTERNAL | Visible only if the target class is in the same assembly as the calling class
PROTECTED INTERNAL | Visible only if the calling class derives from the target class, or the calling class is in the same assembly as the target

Next, if the required method is an instance method (a method that is applied to an object instance), all static methods are discarded. Similarly, if the required method is a static method, all instance methods are discarded.

Now each method is examined in turn to see whether it is applicable in normal form. This is determined as follows:

  1. If the number of arguments is different from the number of parameters in the method, then this method is discarded.
  2. If the type of the parameter in the target method is generic COBOL data passed by reference (in .NET, MicroFocus.COBOL.Program.Reference), then any argument type is assumed to match except for .NET native types.
  3. For each argument with an explicit parameter passing mode (BY CONTENT, BY VALUE or BY OUTPUT), that mode must correspond to the definition of the parameter in the method being examined.

  4. For a REFERENCE or OUTPUT parameter, the type of the argument must be exactly the same as the parameter type.

    For a VALUE parameter, an implicit conversion must exist from the type of the argument to the type of the corresponding parameter. If any of these implicit conversions require truncation, this method is said to be a ‘truncation match’.

If a method is not applicable according to these rules, an attempt is made to match the method in expanded form, if both the following are true:

  • The last parameter of the method is an array with the ‘params’ attribute
  • The total number of method parameters (excluding this array parameter) is less than or equal to the number of arguments

The expanded form of the method is derived from the normal form by replacing the array parameter by zero or more value parameters of the same type as the array element, so that the total number of parameters is the same as the number of invoking arguments. If the class already contains a method in normal form with this same expanded signature, then this method is determined to be not applicable. Otherwise the expanded form is tested for applicability in the same way as the test for normal form above.

After the above selection procedure:

  1. If exactly one member is found to be applicable, then that method is known to be the required method.
  2. If more than one method is found to be applicable, then an attempt is made to find the best method.
  3. If any non-truncation matches are found, then all truncation matches are discarded.
  4. If the only matches found are truncation matches, then if only one such match has been found, this becomes the chosen method and a warning is produced. If more than one truncation match is found, then the Compiler returns an error:
    ambiguous match
  5. If no methods are found to be applicable, then the Compiler returns an error:
    method not found

Better Method Overload

Suppose we have an argument list A with a set of argument types (A1, A2,…An) and two applicable method overloads Mp and Mq with parameter types (P1…Pn) and (Q1,…Qn), where if necessary the parameters have been converted to expanded form (see above).

Then, Mp is said to be a better method overload than Mq if both the following are true:

  • For each argument, the implicit conversion from Ax to Px is not worse than the conversion from Ax to Qx (see below for definition of better conversion)
  • There is at least one argument for which the conversion from Ax to Px is better than the conversion from Ax to Qx

Suppose we have two conversions, from type S to types T1 and T2, then T1 is the better conversion when T1 and T2 are as follows:

T1 is: And T2 is one of:
same as S anything
binary-char
  • binary-char unsigned
  • binary-short unsigned
  • binary-long unsigned
  • binary-double unsigned
binary-short
  • binary-short unsigned
  • binary-long unsigned
  • binary-double unsigned
binary-long
  • binary-long unsigned
  • binary-double unsigned
binary-double
  • binary-double unsigned

Otherwise neither conversion is better.

Example of Simple Method Overloading

The following example shows how, even in the case where the supplied argument is not exactly the same as that for any of the target methods, the “most specific” rule takes effect.

       class-id Class1 static.
       method-id main static.
       01 objAnyObject object.
       01 objString string.
       01 objDateTime type DateTime.         *> .NET COBOL
      * 01 objDateTime type java.util.Date.  *> JVM COBOL
       01 ref1 type Class1.
       procedure division.
           set ref1 to new Class1
           invoke ref1::method1                *> uses variant 1
           invoke ref1::method1(objAnyObject)  *> uses variant 2
           invoke ref1::method1(objString)     *> uses variant 3
           invoke ref1::method1(objDateTime)   *> also uses variant 2,
               *> because an object of type DateTime can be assigned
               *> to an Object but not to a String.
       end method.

       method-id method1.     *> Variant 1 (no parameters)
       procedure division.
           display "variant 1"
       end method.

       method-id method1.     *> Variant 2 (object parameter)
       procedure division using by value objAnyObject as object.
           display "variant 2"
       end method.

       method-id method1.     *> Variant 3 (string parameter)
       procedure division using by value objString as string.
           display "variant 3"
       end method.

       end class.

Implicit Conversion

An implicit conversion exists from type S to type T if it is possible to assign an object of type S to an object of type T, with the equivalent of the following statement:

SET obj-T TO obj-S

The following types of implicit conversion are available:

Identity conversions

This simply means that S is the same type as T

Implicit numeric conversions

COBOL generally allows any numeric item to be assigned to any other, with any loss of data being the responsibility of the user. However, when determining if a conversion exists for the purposes of method overloading, we distinguish between proper conversions and truncation conversions. Proper conversions are those for which no loss of data magnitude should result, though even in this case precision can be lost when converting between fixed point and floating point.

For managed COBOL types, proper implicit conversions include:

binary-char
  • binary-short
  • binary-long
  • binary-double
  • float-short
  • float-long
  • decimal
binary-char unsigned

The same as binary-char, plus:

  • binary-short unsigned
  • binary-long unsigned
  • binary-double unsigned
binary-short
  • binary-long
  • binary-double
  • float-short
  • float-long
  • decimal
binary-short unsigned

The same as binary-short, plus:

  • binary-long unsigned
  • binary-double unsigned
binary-long
  • binary-double
  • float-short
  • float-long
  • decimal
binary-long unsigned

The same as binary-long, plus:

  • binary-double unsigned
binary-double
  • float-short
  • float-long
  • decimal
binary-double unsigned

The same as binary-double

character
  • binary-short unsigned
  • binary-long
  • binary-long unsigned
  • binary-double
  • binary-double unsigned
  • float-short
  • float-long
  • decimal
float-short
  • float-long
Implicit enumeration conversions

The value 0 may be converted to any enum type

Implicit reference conversions

If S and T are reference types, S may be assigned to T when:

  • Type S is derived (directly or indirectly) from type T. This includes the case where T is System.Object, since all types derive from that
  • Type S implements interface type T
  • If S is an array type with element type E1 and T is an array type with element type E2, then S can be assigned to T provided:
    • S and T have the same number of dimensions
    • Both E1 and E2 are reference types
    • An implicit conversion exists from E1 to E2
  • Any array type may be assigned to type System.Array in .NET COBOL
  • Any delegate type may be assigned to type System.Delegate
  • Null may be assigned to any reference type
Boxing conversions

Any value type can be converted to a System.Object, type by a process known as boxing. As part of this process the value is copied onto the object heap and a reference is created

Implicit constant expression conversions

Any numeric constant can be converted to any type capable of containing the full value of that constant. For instance the value 1 can be converted both to BINARY-CHAR UNSIGNED and to BINARY-CHAR.

User defined implicit conversions

A user defined implicit conversion consists of an optional implicit numeric conversion from S to S1 followed by the execution of a user defined implicit conversion operator resulting in T1, followed by another optional implicit numeric conversion to T. User defined implicit conversion operators are defined in COBOL with OPERATOR-ID IMPLICIT and result in methods with the name op_Implicit.

Parent topic: Concepts - Managed COBOL
Related reference
Access Modifiers
Methods
Related information
Functions, Methods - in COBOL and C#
Type Compatibility of Managed COBOL with Other Managed Languages
Type Mappings from Native COBOL to Managed Code


Operator Overloading in Managed COBOL

You can overload operators to provide alternative behavior, or behavior for different operand types.

You can overload operators to provide alternative behavior, or behavior for different operand types. For example, where a Timer type is expressed as hours and minutes, you could define one plus operator to add two Timers and another plus operator to add a number of minutes to a Timer type, as follows:

       operator-id + .
       01 sumMins binary-long.
       01 sumHour binary-long.
       01 m binary-long value 0.
       01 h binary-long value 0.
       procedure division using value a as type Timer
                                      b as type Timer
                            returning c as type Timer.
           set sumHour to a::pHour + b::pHour
           set sumMins to a::pMins + b::pMins
           if sumMins >= 60
               divide sumMins by 60 giving h remainder m
               set c to new Timer(sumHour + h, m)
           else
               set c to new Timer(sumHour sumMins)
           end-if
       end operator.

       operator-id + .
       01 sumMins binary-long.
       01 m binary-long value 0.
       01 h binary-long value 0.
       procedure division using value a as type Timer
                                      b as binary-long
                            returning c as type Timer.
           set sumMins to a::pMins + b
           divide sumMins by 60 giving h remainder m
           set c to new Timer(a::pHour + h , m)
       end operator.

To use the overloaded operators, you use statements such as the following:

       program-id OpConversionExtension.
       01 timer1 type Timer value new Timer(1 45).
       01 timer2 type Timer value new Timer(2 45).
       01 timer3 type Timer value new Timer.
       01 myMins binary-long value 30.

       procedure division.
      *> Overloaded operators:
           set timer3 to timer1 + myMins   *> Plus operator adds binary-long to a Timer
           display timer3::pHour & ":" & timer3::pMins   *> displays 2:15

           set timer3 to timer1 + timer2   *> Plus operator adds 2 Timer types
           display timer3::pHour & ":" & timer3::pMins   *> displays 4:30
       end program.

The appropriate operator is executed according to the types of operands being operated on. The operator with a matching signature (procedure division using clause) is executed. Where two Timer types are being added, the operator with a signature that adds two Time types is executed.

Note that the operator signature requires that the arguments are passed in the defined order. In the above example, the Timer type must be first and the binary-long second, as follows:

       set timer3 to timer1 + myMins
       ...
       operator-id + .
       procedure division using value a as type Timer
                                      b as binary-long
                            returning c as type Timer.

To enable the arguments to be passed in the opposite order, you need to declare an another operator where the operands are in the opposite order in the operator's signature. For example:

       set timer3 to myMins + timer1
       ...
       operator-id + .
       procedure division using value a as binary-long
                                      b as type Timer
                            returning c as type Timer.

To use overloaded operators, the overloaded operator must be in scope.

While the arithmetic operators for addition, subtraction, multiplication and division can all be overloaded, their verb equivalents cannot. For example, ADD in the following statement cannot be overloaded:

       add a to b giving c

Further Examples

See also the Operator Overloading sample, available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET .

Parent topic: Concepts - Managed COBOL
Related reference
Operators
Type Specifier
Related information
Operators - in COBOL and C#


String Handling in Managed COBOL

Managed COBOL provides a predefined managed string type and provides powerful techniques for handling strings.

In managed COBOL, you can:

  • Construct a string implicitly by assigning a value
  • Concatenate strings using &
  • Get a substring using the (offset:length) syntax
  • Get the length of a string, using SIZE OF
  • Compare strings using = and <>

The String Predefined Type

Managed COBOL provides a predefined string type corresponding to the managed code string type. You use this type name when declaring a data item, and anywhere that a class name is expected. For example:

01 obj-string string.

Constructing String Objects

String objects are not normally constructed using the "New" method. You can simply assign a value to the string reference and the compiler automatically performs the construction for you. The string value may be set up in this way either to a literal value, or to an alphanumeric, national or group data item. For example:

       set obj-string to "   Some text..."
        display obj-string

Substringing

Substringing is built into managed COBOL with the syntax (offset:stringLength). For example, the following line displays two characters of the string 'a' starting at the sixth character:

display a(6:2)

This looks simple enough, 'a' is a string not a 'pic x'. To do this with C# or Java you have to use a substring method, whereas managed COBOL it is in syntax.

Concatenation

Concatenation is easy using & (ampersand).

You can do string concatenation and string reference modification in the same line; not only that but it seamlessly concatenates COBOL quoted constants with string objects. For example:

       set a to a(1:5) & "-" & a(7:)
       display a

You can concatenate strings with the following using & (ampersand):

string variables | a & b
substrings | a & b(1:3)
quoted string constants | a & "-"
non-string types | 23 & " is a number"
return values from invokes | a & type COBOLString::Split(b,13,7)

The following example combines substringing with concatenation. Here a COBOL quoted constant is automatically cast to a string and the string returned from the invoke is then concatenated with two COBOL quoted constants.

       set a to "Micro Focus Managed COBOL is "                  & *>Micro Focus Managed COBOL is
           type COBOLString::Split("The cake is amazing", 13, 7) & *>amazing
           "ly good for working with strings!"                     *>ly good for working with strings!
       display a

Where the COBOLString::Split() method contains:

       set stringOut to stringIn(offset:stringLength)

Getting the String Length

To get the length of a string, use SIZE OF. For example:

       set n to size of myString

Concatenating Numbers and Strings

The following example concatenates a string variable (a COBOL quoted constant, which is automatically cast to a string) with a number returned from an invoke, which is then concatenated with another COBOL quoted constant.

           display a                           &
              " (this string is "              & *> (this string is
               type COBOLString::CharCount(a)  & *>69
              " bytes long)"                     *> bytes long)

Comparing Strings

To compare strings, use = and <>. For example:

           if a = b
               display "a = b"
            end-if
            if a <> b
               display "a <> b"
            end-if

String comparisons are implemented as overloads to the = and <> operators, which compare character by character (rather than compare object references).

Further Examples

See also the String Handling sample, available from Start > All Programs > Micro Focus Visual COBOL > Samples, under COBOL for .NET.

Parent topic: Concepts - Managed COBOL
Related reference
Fields
Type Specifier
Related information
Strings - in COBOL and C#


Types and Type Conversion

Types can be converted into other types using the AS syntax or a conversion operator.

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 and under COBOL for .NET.

Type Information

Every class has an associated root object, which can be used to get information about the class such as its fields and methods. To obtain type information, you use the following:

  • In NET COBOL, GetType() - to obtain the System.Type object for an object reference
  • In JVM COBOL, getClass() - to obtain the java.lang.Object to obtain the class of an object reference
  • TYPE OF - to obtain the System.Type object for a class, interface, delegate or enumeration
    imperative-clause TYPE OF object

For example, in .NET COBOL:

*> Type information
01 x binary-long.
display x::GetType            *> Prints System.Int32
display type of binary-long   *> Prints System.Int32
display x::GetType::Name      *> Prints Int32

For example, in JVM COBOL:

*> Type information
01 x binary-long.
display x::getClass           *> Prints System.Int32
display type of binary-long   *> Prints System.Int32
display x::getClass::Name     *> Prints Int32

Type Conversion Operators

A conversion operator converts a data item from one data type into another, such as from a type that you have defined into a integer. Conversion operators can be overloaded, so that the appropriate conversion operator is used according to the parameter types in the calling code.

For example, the type Timer, which contains hours and minutes, is converted into minutes as binary-long using the following conversion operator:

       set myMins to timer3 ...
       operator-id Implicit.
       procedure division using value a as type Timer
                          returning b as binary-long.
            set b to a::pHour * 60 + a::pMins
       end operator.

Similarly, you can convert from a binary-long data item (representing a number of minutes) to the type Timer, which is expressed in hours and minutes, using the following conversion operator:

       set timer4 to myMins ...
       operator-id Implicit.
       procedure division using value a as binary-long
                          returning b as type Timer.
             set b to new Timer
             if a >= 60
                 set b::pHour to 1
                 set b::pMins to a - 60
             else
                 set b::pMins to a
             end-if
       end operator.

You can define explicit conversions, in addition to implicit conversions. They differ as follows:

Explicit conversions
Explicit conversions occur only in statements that explicitly state the type to convert from. For example, where the conversion operator is defined as explicit, only the second statement below works:
       set timer4 to myString                *> fails
       set timer4 to myString as type Timer  *> succeeds
       operator-id Explicit.
       01 strH type String.
       01 strM type String.
       01 colonPos  binary-long value 0.

       procedure division using value a as String returning b as Type Timer.
           set b to new Timer()
           set colonPos to a::IndexOf(":")
           try
               set strH to a::Substring(0 colonPos)
               set strM to a::Substring(colonPos + 1 2)
               set b::pHour to type Int32::Parse(strH)
               set b::pMins to type Int32::Parse(strM)
           catch
               display "Invalid time format"
           end-try
       end operator.

You use explicit conversions (as opposed to implicit ones) where the conversion has the potential to lose information or throw an exception. In the above example, the string might contain text or be invalid somehow. In this case, a try-catch block is required to handle the failure.

Implicit conversions
Implicit conversions can occur in all sorts of places, such as assignments and member invocations and an explicit conversion. See the earlier examples.

You can invoke an implicit conversion implicitly or explicitly. For example, the following statements both invoke the implicit conversion:

       set myMins to timer3
       set myMins to timer3 as binary-long

You use implicit conversions where the conversion is reliable, where it will not lose information and will not throw an exception.

Casting Object References Using AS

You can cast an object reference to an instance of another type using AS. The Compiler can then check whether the operation is type safe or not.

In the following example, we know that obj-object points to a System.AppDomain reference so we know we can cast up the class hierarchy from System.Object to System.AppDomain.

    *> set obj-app-domain to obj-object             *> fails if uncommented
     set obj-app-domain to obj-object as type System.AppDomain *> succeeds

Casts can be inline, so you can do the following:

display obj-object as type System.AppDomain::FriendlyName

A cast is only legal if the target type (the type being cast to) derives directly from the source type, or vice versa. In the following statement a System.Type reference (obj-type) can never point to a System.AppDomain instance because the classes are unrelated in the hierarchy.

       *>set obj-app-domain to obj-type as type System.AppDomain *> fails if uncommented

If the cast fails, a System.InvalidCastException is thrown by the CLR. To avoid this, either test for a valid cast first using INSTANCE OF or wrap the cast in an exception block (see exception handling example for more information).

An exception is thrown in the following as we are claiming obj-object references a System.AppDomain instance where in fact it's referencing a System.Type instance.

   *> these statements fail if uncommented
       *> set obj-object to obj-type
       *> set obj-app-domain to obj-object as type System.AppDomain
Parent topic: Concepts - Managed COBOL
Related reference
Procedure Division Header
INVOKE Statement
Type Specifier
Related information
Data Types - in COBOL and C#
Type Compatibility of Managed COBOL with Other Managed Languages
Type Mappings from Native COBOL to Managed Code


Type Compatibility of Managed COBOL with Other Managed Languages

Many managed COBOL types have a strict correspondence with managed types in other languages, such as binary-long and float-short. For those that don't have a correspondence, there are alternatives.

The following table lists the correspondence between managed COBOL types and classes and types in other managed languages.

Managed COBOL | .NET class | JVM type | C# type | 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 unsigned integer Not CLS-compliant
binary-short unsigned | System.UInt16 |  | ushort | A 16-bit signed 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 |  | decimal | A 96-bit decimal value
type System.IntPtr | System.IntPtr |  |  | A signed integer whose size depends on the underlying platform (a 32-bit value on a 32-bit platform and a 64-bit value on a 64-bit platform)
type System.UIntPtr | System.UIntPtr |  |  | An unsigned integer whose size depends on the underlying platform (a 32- bit value on a 32-bit platform and a 64-bit value on a 64-bit platform) Not CLS-compliant
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

Examples:

       local-storage section.
       01 aByte binary-char unsigned.
       01 aSignedByte binary-char.
       01 anInt16 binary-short.
       01 anInt32 binary-long.
       01 anInt64 binary-double.
       01 anUnsignedInt16 binary-short unsigned.
       01 anUnsignedInt32 binary-long unsigned.
       01 anUnsignedInt64 binary-double unsigned.
       01 aSingle float-short.
       01 aDouble float-long.
       01 aBoolean condition-value.
       01 aChar character.
       01 aDecimal decimal.
       01 anIntPtr type IntPtr.
       01 anUnsignedIntPtr type UIntPtr.
       01 anObject object.
       01 aString string.
Parent topic: Concepts - Managed COBOL
Parent topic: Managed COBOL
Related reference
Procedure Division Header
Type Specifier
Related information
Type Compatibility in Interoperation with Managed Code
Types and Type Conversion
Data Types - in COBOL and C#
Type Mappings from Native COBOL to Managed Code


Comparison of COBOL with Other Managed Languages

The following topics show examples of various programming techniques and constructs in COBOL compared with C#.

  • Attributes - in COBOL and C#
  • Arrays - in COBOL and C#
  • Choices - in COBOL and C#
  • Comments - in COBOL and C#
  • Constants - in COBOL and C#
  • Constructors and Deconstructors - in COBOL and C#
  • Data Types - in COBOL and C#
  • Delegates and Events - in COBOL and C#
  • Enumeration - in COBOL and C#
  • Exception Handling - in COBOL and C#
  • Functions, Methods - in COBOL and C#
  • Generics, Consuming - in COBOL and C#
  • Generics, Defining - in COBOL and C#
  • Interfaces - in COBOL and C#
  • Iterators - in COBOL and C#
  • Loops - in COBOL and C#
  • Namespaces - in COBOL and C#
  • Objects - in COBOL and C#
  • Operators - in COBOL and C#
  • Program Structure - in COBOL and C#
  • Properties - in COBOL and C#
  • Strings - in COBOL and C#
  • Structures, Value Types - in COBOL and C#
  • Synchronization - in COBOL and C#
Parent topic: Managed COBOL
Related concepts
Managed COBOL Language Features
Managed COBOL Reference
ILSMARTNEST
Managed COBOL Programming
COBOL Language Reference
Related reference
Access Modifiers
Related information
.NET COBOL Syntax Improvements


Attributes - in COBOL and C#

Attributes in Managed COBOL

*> Define attributes on a class
class-id MyClass
          attribute WebService(name Description = "My service")
          attribute Obsolete.

*> Define attributes on a field
01 a binary-long attribute XmlAttribute("UpperB")
          attribute Obsolete static.

*> Define attributes on a property
*> Note that in this case, the attributes must follow
*> the reserved word PROPERTY
01 b binary-long property
          attribute XmlAttribute("UpperB")
          attribute Obsolete static.

*> Define attributes on an event
*> Note that the attributes must follow
*> the reserved word EVENT.
01 d type fred event
          attribute Obsolete static.

*> Define attributes on a method
method-id main
          attribute Obsolete static.
procedure division
    move 999 to a
    display a

end method.

*> Define attributes on a method parameter and return type
method-id stat static.
procedure division
          using by value l1 as binary-long
                   attribute CLSCompliant(true)
                   attribute MarshalAs(3)
          returning l2 as binary-long
                   attribute CLSCompliant(true)
                   attribute MarshalAs(2).
    move 999 to a
    display a
    set d to null
end method.

*> Define attributes on a property
method-id set property prop
          attribute Obsolete static.
procedure division using by value l1 as binary-long.
    move l1 to a
end method.

end class.

*> Define attribute on a delegate
delegate-id fred attribute Obsolete.
procedure division using by value l1 as binary-long.
end delegate.

Atttributes in C#

// C# terminology : attribute
// Define attributes on a class
[WebService(Description = "MyService")]
[Obsolete]
class MyClass
{
    // Define attributes on a field
    [XmlAttribute("UpperB")]
    [Obsolete]
    long a;

    // Define attribute on a property
    private string prop;

    [Obsolete]
    public string b
    {
        [return:XmlAttribute("UpperB")]
        get { return prop; }

        [value:XmlAttribute("UpperB")]
        set { prop = value; }
    }

    // Define attribute on an event
    [Obsolete]
    public event fred d;

    // Define attribute on a method
    [Obsolete]
    public void main()
    {
    }

    // Define attributes on parameters and returns
    [return:CLSCompliant(true)]
    [return:MarshalAs(2)]
    public long Stat([CLSCompliant(true)][MarshalAs(3)]long l1)
    {
        return 12;
    }

    // Define attributes on a property
    [Obsolete]
    public string b
    {
        set { prop = value; }
    }

    // Define attributes on a delegate
    [Obsolete]
    public delegate void fred(long l1);
}
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Attributes
Related information
Creative Commons License


Arrays - in COBOL and C#

Arrays in Managed COBOL

01 nums binary-long occurs 3 values 1, 2, 3.
*> Can also do:
set content of nums to (1, 2, 3)

*> 5 is the size of the array
01 names string occurs 5.
*> Can also do:
01 names string occurs any.
set size of names to 5
set names(1) to "Rod"  *> first element indexed as 1
set names(6) to "Jane"  *> throws System.IndexOutOfRangeException

*> COBOL cannot resize an array - use copy
01 names2 string occurs 7.
  invoke type Array::Copy(names, names2, names::Length)
*> or:
  invoke names::CopyTo(names2, 0)
*> or:
  invoke type Array::Resize(names, 7)

01 twoD float-short occurs any, any.
  set size of twoD to rows, cols

01 jagged binary-long occurs any, occurs any.
  set size of jagged to 3
  set size of jagged(1) to 5
  set jagged(1 5) to 5

Arrays in C#

int[] nums = {1, 2, 3};
for (int i = 0; i < nums.Length; i++)
{
   Console.WriteLine(nums[i]);
}

// 5 is the size of the array
string[] names = new string[5];
names[0] = "Rod";
names[5] = "Jane";   // Throws System.IndexOutOfRangeException

// C# can't dynamically resize an array.  Just copy into new array.
string[] names2 = new string[7];
// or names.CopyTo(names2, 0);
Array.Copy(names, names2, names.Length);

float[,] twoD = new float[rows, cols];
twoD[2,0] = 4.5f;

int[][] jagged = new int[3][] {
  new int[5], new int[2], new int[3] };
jagged[0][4] = 5;

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Indexers
SET Statement
Related information
Creative Commons License


Choices - in COBOL and C#

Choices in Managed COBOL

*>COBOL has no exact equivalent syntax to x ? y : z

if age < 20
   move "What's up?" to greeting
else
   move "Hello" to greeting
end-if

if x not = 100 and y < 5
   multiply 5 by x
   multiply 2 by y
end-if

*> evaluate is preferred in COBOL rather than if/else if/else
evaluate x
  when > 5
    multiply y by x
  when 5
    add y to x
  when < 10
    subtract y from x
  when other
    divide y into x
end-evaluate

evaluate color   *> can be any type
   when "torquoise"
   when "red"
      add 1 to r
   when "blue"
      add 1 to b
   when "green"
      add 1 to g
   when other
      add 1 to other-color
end-evaluate

Choices in C#

greeting = age < 20 ? "What's up?" : "Hello";

// Good practice is that all consequents are enclosed in {}
// or are on the same line as if.
if (age < 20) greeting = "What's up?";
else
{
   greeting = "Hello";
}

// Multiple statements must be enclosed in {}
if (x != 100 && y < 5)
{
  x *= 5;
  y *= 2;
}

if (x > 5)
{
   x *= y;
}
else if (x == 5)
{
   x += y;
}
else if (x < 10)
{
   x -= y;
}
else
{
   x /= y;
}

// Every case must end with break or goto case
switch (color)                       // Must be integer or string
{
  case "turquoise":
  case "red":
          r++;
          break;
  case "blue":
          b++;
          break;
  case "green":
          g++;
          break;
  default:
          other++;
          break;      // break necessary on default
}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
IF Statement
Related information
Creative Commons License


Comments - in COBOL and C#

Comments in Managed COBOL

      * (in column 7) rest of line is commented (COBOL fixed format)
         *> rest of line is commented
         *> may follow COBOL statements
         *>> <summary>XML comments</summary>

Comments in C#

// Rest of line
/* Multiple
   lines  */
/// <summary>XML comments on single line</summary>
/** <summary>XML comments on multiple lines</summary> */
Parent topic: Comparison of COBOL with Other Managed Languages
Related information
Creative Commons License


Constants - in COBOL and C#

Constants in Managed COBOL

78 MAX_STUDENTS value 25.  *> default public, binary-long

*> INITIALIZE ONLY - instance or static, may be initialized in constructor
01 MIN_DIAMETER float-short value 4.93 initialize only.

Constants in C#

const int MAX_STUDENTS = 25;

// Can set to a const or var; may be initialised in a constructor
readonly float MIN_DIAMETER = 4.93f;
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Fields
Related information
Creative Commons License


Constructors and Deconstructors - in COBOL and C#

Constructors and Deconstructors in Managed COBOL

class-id SuperHero.
working-storage section.
01 powerLevel binary-long.
method-id new.
procedure division.
    set powerLevel to 0
end method.

method-id new.
procedure division using by value powerLevel as binary-long.
    set powerLevel to powerLevel
end method.
method-id Finalize override protected.
    *> Destructor code to free unmanaged resources.
end method.

end class SuperHero.

Constructors and Deconstructors in C#

class SuperHero
{
  private int _powerLevel;

  public SuperHero()
  {
     _powerLevel = 0;
  }

  public SuperHero(int powerLevel)
  {
    this._powerLevel= powerLevel;
  }

  ~SuperHero()
  {
    // Destructor code to free unmanaged resources.
    // Implicitly creates a Finalize method
  }
}
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Constructors
Related information
Creative Commons License


Data Types - in COBOL and C#

Data Types in Managed COBOL

*> Value types
condition-value
binary-char (unsigned)
character
binary-short (unsigned)
binary-long (unsigned)
binary-double (unsigned)
float-short
float-long
decimal
DateTime (not a built-in COBOL type)

*> Reference types
object
string
*> Initializing. Two methods shown.
*> Method 1, in working storage
01 isTrue  condition-value       value true.
01 hex     binary-char unsigned  value h"2a".  *> Hex
01 octal   binary-char unsigned  value o"52".  *> Octal
01 person  object                value null.
01 aName   string                value "Dwight".
01 grade   character             value "B".
01 today   type DateTime         value
               type DateTime::Parse("12/3/2007 12:15:00)
01 amount  decimal               value 35.99.
01 gpa     float-short           value 2.9.
01 pi      float-long            value 3.14159265.
01 lTotal  binary-double         value 123456.
01 sTotal  binary-short          value 123.
01 usTotal binary-short unsigned value 123.
01 uiTotal binary-long           value 123.
01 ulTotal binary-long unsigned  value 123.
*> Method 2, local declaration
declare isTrue  condition-value       value true.
declare hex     binary-char unsigned  value h"2a".  *> Hex
declare octal   binary-char unsigned  value o"52".  *> Octal
declare person  object                value null.
declare aName   string                value "Dwight".
declare grade   character             value "B".
declare today   type DateTime         value
                    type DateTime::Parse("12/3/2007 12:15:00)
declare amount  decimal               value 35.99.
declare gpa     float-short           value 2.9.
declare pi      float-long            value 3.14159265.
declare lTotal  binary-double         value 123456.
declare sTotal  binary-short          value 123.
declare usTotal binary-short unsigned value 123.
declare uiTotal binary-long           value 123.
declare ulTotal binary-long unsigned  value 123.
*> Type information
01 x binary-long.
display x::GetType            *> Prints System.Int32
display type of binary-long   *> Prints System.Int32
display x::GetType::Name      *> Prints Int32
*> Type conversion
01 d float-short value 3.5.   *> automatic conversion
set i to d as binary-long     *> set to 3 (truncates decimal)
*> COBOL types not supported in C# or Java
*> Only a few examples here
01 displayNumber pic 9(9).99.
01 computeNumber pic 9(9)V99.
01 alphaNumberic pic a(23).
01 binaryStorage pic x(12).
*> Also groups and redefines - a few examples
01 arecord.
   03 aSubRecord pic x(10).
   03 aUnion     pic 9(10) redefines aSubrecord.

Data Types in C#

// Value Types
bool
byte, sbyte
char
short, ushort
int, uint
long, ulong
float, double
decimal
DateTime   // (not a built-in C# type)

// Reference Types
object
string

// Initializing
bool     isTrue  = true;
byte     hex     = 0x2A;   // hex

object   person  = null;
string   aName   = "Dwight";
char     grade   = 'B';
DateTime today   = DateTime.Parse("12/31/2007 12:15:00");

decimal  amount  = 35.99m;
float    gpa     = 2.9f;
double   pi      = 3.14159265;
long     lTotal  = 123456L;
short    sTotal  = 123;
ushort   usTotal = 123;
uint     uiTotal = 123;
ulong    ulTotal = 123;

// Type Information
int x;
Console.WriteLine(x.GetType());        // Prints System.Int32
Console.WriteLine(typeof(int));        // Prints System.Int32
Console.WriteLine(x.GetType().Name);   // prints Int32

// Type Conversion
float d = 3.5f;
int i = (int)d;   // set to 3  (truncates decimal)
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Local Data Item Declaration
Fields
Related information
Types and Type Conversion
Type Compatibility of Managed COBOL with Other Managed Languages
Type Mappings from Native COBOL to Managed Code
Creative Commons License


Delegates and Events - in COBOL and C#

Delegates and Events in Managed COBOL

delegate-id MsgArrivedEventHandler.
procedure division using by value msg as string.
end delegate.

class-id a.
01 MsgArrivedEvent
     type "MsgArrivedEventHandler" event static.
    *> Delegates must be used with events in COBOL

method-id main static.
    set MsgArrivedEvent to type Delegate::Combine
        (
          MsgArrivedEvent,
          new MsgArrivedEventHandler
             (self::My_MsgArrivedEventCallback)
        )
        as type MsgArrivedEventHandler
    invoke MsgArrivedEvent::Invoke("Test message")
       *> Throws exception if obj is null

    set MsgArrivedEvent to type Delegate::Remove
        (
          MsgArrivedEvent,
          new MsgArrivedEventHandler
              (self::My_MsgArrivedEventCallback)
        )
        as type MsgArrivedEventHandler
    invoke self::add_MsgArrivedEvent
        (
          new MsgArrivedEventHandler
            (self::My_MsgArrivedEventCallback)
        )
    invoke MsgArrivedEvent::Invoke("Test message 2")
       *> Throws exception if obj is null
end method.

method-id My_MsgArrivedEventCallback static.
procedure division using by value str as string.
    display str
end method.
end class.

Delegates and Events in C#

delegate void MsgArrivedEventHandler(string message);

event MsgArrivedEventHandler MsgArrivedEvent;

// Delegates must be used with events in C#

MsgArrivedEvent +=
    new MsgArrivedEventHandler(My_MsgArrivedEventCallback);
// Throws exception if obj is null
MsgArrivedEvent("Test message");
MsgArrivedEvent -=
    new MsgArrivedEventHandler(My_MsgArrivedEventCallback);

using System.Windows.Forms;

Button MyButton = new Button();
MyButton.Click += new System.EventHandler(MyButton_Click);

private void MyButton_Click(object sender, System.EventArgs e)
{
  MessageBox.Show(this, "Button was clicked", "Info",
    MessageBoxButtons.OK, MessageBoxIcon.Information);
}
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Delegates
Related information
Creative Commons License


Enumeration - in COBOL and C#

Enumeration in Managed COBOL

enum-id Action public.
working-storage section.
01 binary-long.         *> Underlying type for the enum.
                        *> binary-long is the default
    78 Starter value 0. *> Declare enum values as level-78 items
    78 Stop    value 1.
    78 Rewind  value 2.
    78 Forward value 3.
end enum.
*> Short hand version of above.
*> PUBLIC and BINARY-LONG are the defaults
*> The default values are 0 1 2...
enum-id Action.
   78 Starter.
   78 Stop.
   78 Rewind.
   78 Forward.
end enum.
enum-id Status.
   78 Flunk value 50.
   78 Pass value 70.
   78 Excel value 90.
end enum.
program-id main.
   display type Status::Pass as binary-long *> prints 70
   display type Status::Pass                *> prints Pass
end program.

Enumeration in C#

enum Action {Start, Stop, Rewind, Forward};
enum Status {Flunk = 50, Pass = 70, Excel = 90};

Action a = Action.Stop;
if (a != Action.Start)
  Console.WriteLine(a + " is " + (int) a);   // Prints "Stop is 1"

Console.WriteLine((int) Status.Pass);        // Prints 70
Console.WriteLine(Status.Pass);              // Prints Pass
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Enums
Related information
Creative Commons License


Exception Handling - in COBOL and C#

Exception Handling in Managed COBOL

*> Throw an exception
declare myException as type Exception =
         new Exception(“Something is really wrong.").
raise myException

*> Catch an exception.
try
  set y to 0;
  compute x = 10 / y
catch myException  *> Argument is optional, no "When" keyword
  display myException::Message
finally
  invoke type Microsoft.VisualBasic.Interaction::Beep
end-try

Exception Handling in C#

// Throw an exception
Exception up = new Exception("Something is really wrong.");
throw up;

// Catch an exception
try
{
  y = 0;
  x = 10 / y;
}
catch (Exception ex) // Argument is optional, no "When" keyword
{
  Console.WriteLine(ex.Message);
}
finally
{
  Microsoft.VisualBasic.Interaction.Beep();
}
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
RAISE Statement
TRY Statement
Related information
Creative Commons License


Functions, Methods - in COBOL and C#

Functions in Managed COBOL

method-id TestFunc.
procedure division using by value x as binary-long,
                            by reference y as binary-long,
                            output z as binary-long.
   add 1 to x, y
   move 5 to z
end method.

01 a binary-long value 1.
01 b binary-long value 1.
01 c binary-long.  *> c doesn't need initializing

    invoke self::TestFunc(value a reference b output c)
*> Or
    invoke self::TestFunc(a b c)
    display a space b space c

*> sum is an intrinsic function in COBOL
01 total binary-long.
    set total to function sum(4 3 2 1) *> returns 10

*> To create a non intrinsic variable argument list function:
method-id MySum.
local-storage section.
01 i binary-long.
procedure division using params nums as binary-long occurs any
                   returning mysum as binary-long.
    perform varying i through nums
        add i to mysum
    end-perform
end method.

*> then to call it:
method-id main.
local-storage section.
01 i binary-long.
procedure division
    set i to self::MySum(1 2 3 4)
    display i
end method.

*> COBOL doesn't support optional arguments/parameters.
*> Just create two different versions of the same function.
method-id SayHello.
   procedure division using by value nam as string, prefix as string.
   display "Greetings, " prefix space nam
end method SayHello.

method-id SayHello.
   procedure division using by value nam as string.
   invoke self::SayHello(nam "")
end method.

Functions in C#

// Pass by value (in, default), reference (in/out),
// and reference (out)
void TestFunc(int x, ref int y, out int z)
{
   x++;
   y++;
   z = 5;
}

int a = 1, b = 1, c;  // c doesn't need initializing
TestFunc(a, ref b, out c);
Console.WriteLine("{0} {1} {2}", a, b, c);  // 1 2 5

// Accept variable number of arguments
int Sum(params int[] nums)
{
  int sum = 0;
  foreach (int i in nums)
  {
      sum += i;
  }
  return sum;
}

int total = Sum(4, 3, 2, 1);   // returns 10

/* C# doesn't support optional arguments/parameters.
   Just create two different versions of the same function. */
void SayHello(string name, string prefix)
{
   Console.WriteLine("Greetings, " + prefix + " " + name);
}

void SayHello(string name)
{
   SayHello(name, "");
}
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Constructors
INVOKE Statement
Related information
Extension Methods and Operators
Invoking a Method
Creative Commons License


Generics, Consuming - in COBOL and C#

Consuming Generics in Managed COBOL

*> Consuming a generic method via type inference

01 result as type Tuple[binary-long binary-long].
*> Parameters are used to infer type
set result to type Tuple::Create(1 2)

*> Consuming a generic collection
01 x type List[string] value new List[string].
01 i binary-long.
01 val string.
procedure division.
    perform varying i from 0 by 1 until i greater than 100
       invoke x::Add(i::ToString)
    end-perform
    perform varying val through x
       display val
    end-perform

Consuming Generics in C#

// Consuming a generic method via type inference

System.Tuple<int, int> result;
// Parameters are used to infer type
result = new System.Tuple.Create(1, 2);

//Consuming a generic collection
List<string> x = new List<string>();
int i;
for(i=0; i<101; ++i)
{
    x.Add(i.ToString());
}
foreach(string val in x)
{
    Console.WriteLine(val);
}
Parent topic: Comparison of COBOL with Other Managed Languages
Related information
Creative Commons License


Generics, Defining - in COBOL and C#

Defining Generics in Managed COBOL

*> Generic class
class-id Point3D using T.

*> With constraints
class-id Point3D using T.
constraints.
   constrain T implements type IComputable.

*> Generic interface
interface-id IComputable using T.
*> Generic method
method-id MakePoint3D static public using T.
procedure division using by value
       x as T y as T z as T
       returning ret as type Point3D[T].

*> With constraints
method-id MakePoint3D static public using T.
constraints.
   constrain T implements type IComputable.
*> Generic value type
valuetype-id container using T Y.
   01 a T public.
   01 b Y public.
end valuetype.

*> With constraints
valuetype-id container using T Y.
constraints.
   constrain T implements type IComputable.

*> Generic iterator, use a parametrised class
class-id a using T.

iterator-id itg static.
01 val binary-long value 1.
procedure division using by value x as T yielding y as T.
    perform until val = 50
        add 1 to val
        set y to x *> Just for example!
        goback
    end-perform
end iterator.

end class.

*> To use, parametrise the class
perform varying thg through type a[string]::itg("Dog")
    display thg
end-perform

Defining Generics in C#

// Generic class
class Point3D<T>

// Generic class with constraints
class Point3D_c<T> where T : IComputable

// Generic interface
interface IComputable<T>

// Generic method
public static Point3D<T> MakePoint3D<T>(T x, T y, T z)
{
    return new Point3D<T>(x, y, z);
}

// Generic method with constraints
public static void MakePoint3D<T>(T x, T y, T z) where T : IComputable
{
    return new Point3D<T>(x, y, z);
}

// Generic value type
struct container<T, Y>
{
    public T a;
    public Y b;
}

// Generic value type with constraints
struct container<T, Y> where T : IComputable

// Generic iterator, use a parameterised class
class a<T>
{
    public static IEnumerable<T> itg(T x)
    {
        int val = 1;
        while (val < 50)
        {
            val++;
            yield return x;
        }
    }
}

// Using generic iterator
foreach (string dog in a<string>.itg("Dog"))
    System.Console.WriteLine(dog);
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Constraints Paragraph
Generic Using Phrase
Related information
Creative Commons License


Interfaces - in COBOL and C#

Interfaces in Managed COBOL

*> Accessibility keywords
public
private
internal
protected
protected internal
static

*> Inheritance
class-id FootballGame inherits type Competition.
  ...
end class.

*> Interface definition
interface-id IAlarmClock.
  ...
end interface.

*> Inheriting an interface
interface-id IAlarmClock inherits type IClock.
  ...
end interface.

*> Interface implementation
class-id WristWatch implements type IAlarmClock, type ITimer.
   ...
end class.

Interfaces in C#

// Accessibility keywords
public
private
internal
protected
protected internal
static
new

// Inheritance
class FootballGame : Competition
{
  ...
}

// Interface definition
interface IAlarmClock
{
  ...
}

// Extending an interface
interface IAlarmClock : IClock
{
  ...
}

// Interface implementation
class WristWatch : IAlarmClock, ITimer
{
   ...
}
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Interfaces
Related information
Creative Commons License


Iterators - in COBOL and C#

Iterators in Managed COBOL

class-id sillyCount.
working-storage section.
01 c binary-long value 1 static.

method-id main static.
01 i binary-long.
procedure division using by value cmds as string occurs any.
    *> Use perform to loop over an iterator
    perform varying i through self::doCount()
        display i
    end-perform
end method.

*> Create an iterator by defining a member as an iterator
*> Using iterator-id instead of method-id
iterator-id doCount static.
    *> The return value if the iterator is defined using the
    *> yielding keyword
procedure division yielding j as binary-long.
    perform until false
        add 1 to c
        move c to j
        *> Until the iterator is stopped, it will yield on
        *> a goback verb
        goback

        *> then start again directly after the goback
        *> on the next invocation of the iterator
        multiply c by 10 giving j
        if c less then 50
            goback
        else
            *> Stop iterator - as it says
            *> Control goes back to the calling routine.
            stop iterator
            goback
       end-if
    end-perform
    *> COBOL will implicitly stop iterator at the
    *> end of the iterator definition.
    *> In this example – the code never gets here.
end iterator.
end class.

Iterators in C#

class SillyCount
{
    static int c = 1;

    static void Main(string[] args)
    {
        // Use foreach to loop through an iterator
        foreach(int i in doCount())
        {
            System.Console.WriteLine(i);
        }
     }

    // C# lacks specific syntax to mark a method as an iterator
    // you have to create a method with the correct concrete form
    // of the IEnumerable interface and then use the yield return
    // syntax inside the method.
    static IEnumerable<int> doCount()
    {
        while (true)
        {
            c++;
            // C# uses an implicit return 'variable' rather than
            // the named one in COBOL. Yield return returns
            // the value as the current value of the iterator
            yield return  c;

            // then starts immediately after the
            // yield return on the next invocation of
          // the iterator
            if (c < 50)
            {
                yield return c * 50;
            }
            else
            {
                // yield break marks the end of the iterator
                yield break;
            }
        }
    }
}
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Indexers
Iterators
Related information
Creative Commons License


Loops - in COBOL and C#

Loops in Managed COBOL

*> Pre-test loops:
declare c1 as binary-long.
perform until c >= 10
   add 1 to c
end-perform

perform varying c as binary-long from 2 by 2 until c > 10
   display c2
end-perform

*>Post-test loops:
declare c3 as binary-long.
perform with test after until c3 >= 10
   add 1 to c3
end-perform

*> Array or collection looping
01 names string occurs any.
set content of names to ("Rod" "Jane" "Fred")
perform varying s as string through names
   display s
end-perform

*> Breaking out of loops:
01 i1 binary-long value 0.
perform until exit
   if i1 = 5
      exit perform
   end-if
   add 1 to i1
end-perform

*> Continue to next iteration:
declare i2 binary-long value 0
perform varying i2 from 0 by 1 until i2 >= 5
   if i2 < 4
      exit perform cycle
   end-if
   display i2 *>Only prints 4
end-perform

Loops in C#

// Pre-test Loops
// no "until" keyword
int c1;
while (c1 < 10)
{
   c1++;
}

for (int c2 = 2; c2 <= 10; c2 += 2)
{
   Console.WriteLine(c2);
}

// Post-test Loop
int c3;
do
{
  c3++;
} while (c3 < 10);

// Array or collection looping
string[] names = {"Rod", "Jane", "Freddy"};
foreach (string s in names)
{
   Console.WriteLine(s);
}

// Breaking out of loops
int i1 = 0;
while (true)
{
  if (i1 == 5)
  {
      break;
  }
  i1++;
}

// Continue to next iteration
for (int i2 = 0; i2 < 5; i2++)
{
  if (i2 < 4)
  {
    continue;
  }
  Console.WriteLine(i2);   // Only prints 4
}
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
PERFORM Statement
Related information
Creative Commons License


Namespaces - in COBOL and C#

Namespaces in Managed COBOL

Namespaces can be set at the file level.

$set ilnamespace "Harding.Compsci.Graphics"
*> The directive can also be set at the project level
*> to apply the name space to all classes in the project.

Namespaces in C#

namespace Harding.Compsci.Graphics
{
  ...
}

// or

namespace Harding
{
  namespace Compsci
  {
    namespace Graphics
    {
      ...
    }
  }
}

using Harding.Compsci.Graphics;
Parent topic: Comparison of COBOL with Other Managed Languages
Related information
Creative Commons License


Objects - in COBOL and C#

Objects in Managed COBOL

01 hero  type SuperHero value new SuperHero.
01 hero2 type SuperHero.
01 obj object.
01 reader type StreamReader.
01 myLine string.

set hero::Name to SpamMan
set hero::PowerLevel to 3

invoke hero::Defend("Laura Jones")
invoke type SuperHero::Rest   *> Calling static method

set hero2 to hero     *> Both reference the same object
set hero2::Name to "WormWoman"
display hero::Name    *> Prints WormWoman

set hero to null      *> Free the object

if hero = null
    set hero to new SuperHero
end-if

set obj to new SuperHero
if obj is instance of type SuperHero
    display "Is a SuperHero object."
end-if

*> No 'using' construct in COBOL
try
    set reader to type File::OpenText("test.txt")
    perform until exit
        set myLine to reader::ReadLine
        if myLine = null
            exit perform
        end-if
    end-perform
finally
    if reader not = null
        invoke reader::Dispose
    end-if
end-try

Objects in C#

SuperHero hero = new SuperHero();

hero.Name = "SpamMan";
hero.PowerLevel = 3;

hero.Defend("Laura Jones");
SuperHero.Rest();   // Calling static method

SuperHero hero2 = hero;   // Both reference the same object
hero2.Name = "WormWoman";
Console.WriteLine(hero.Name);   // Prints WormWoman

hero = null ;   // Free the object

if (hero == null)
  hero = new SuperHero();

Object obj = new SuperHero();
if (obj is SuperHero)
{
  Console.WriteLine("Is a SuperHero object.");
}

// Mark object for quick disposal
using (StreamReader reader = File.OpenText("test.txt"))
{
  string line;
  while ((line = reader.ReadLine()) != null)
  {
    Console.WriteLine(line);
  }
}
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Classes
INVOKE Statement
SET Statement
Related information
Invoking a Method
Creative Commons License


Operators - in COBOL and C#

Operators in Managed COBOL

*> Comparison
= < > <= >= <>

*> Arithmetic
+ - * /
function mod
*>no direct COBOL equivalent to integer division
**

*> Assignment
move, set, compute

*> Bitwise
b-and, b-or, b-xor, b-not, b-left, b-right

*> Logical
and, or, not

Operators in C#

// Comparison
==  <  >  <=  >=  !=

// Arithmetic
+  -  *  /
%  (mod)
/  (integer division if both operands are ints)
Math.Pow(x, y)

// Assignment
=  +=  -=  *=  /=   %=  &=  |=  ^=  <<=  >>=  ++  --

// Bitwise
&   |   ^   ~   <<   >>

// Logical
&&   ||   &   |   ^   !

//Note: && and || perform short-circuit logical evaluations

// String Concatenation
+
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Operators
Related information
Operator Overloading in Managed COBOL
Creative Commons License


Program Structure - in COBOL and C#

Program Structure in Managed COBOL

class-id HelloWorld as "Hello.Helloworld".

method-id main static.
local-storage section.
01 helloString string value "COBOL".
procedure division using by value args as string occurs any.

    if length of args > 0
        set helloString to args(1)
    end-if
    display "Hello, " & helloString & "!"

end method.

end class.

Program Structure in C#

namespace Hello
{
    public class HelloWorld
    {
        public static void Main(string[] args)
        {
            string helloString = "C#";

            if (args.Length > 1)
            {
                helloString = args[0];
            }
            System.Console.WriteLine("Hello, " + helloString + "!");
        }
    }
}
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Classes
Related information
Creative Commons License


Properties - in COBOL and C#

Properties in Managed COBOL

class-id MyClass.
working-storage section.
01 volume binary-long private.
property-id Volume binary-long.
  getter.
    set property-value to volume
  setter.
    if property-value < 0
      set volume to 0
    else
      set volume to property-value
    end-if
end property.
end class.
*> COBOL also allows you to expose fields as properties
class-id MyClass.
working-storage section.
01 llength  binary-long property as "Length".
01 width    binary-long property as "Width"   no get.
01 breadth  binary-long property as "Breadth" no set.
end class.
class-id a.
method-id main.
local-storage section.
01 foo type MyClass value new MyClass.
procedure division.
    add 1 to foo::Volume
    display foo::Volume
end method.
end class.

Properties in C#

private int _size;
private int _length;
private int _width;
private int _breadth;

public int Size
{
  get
  {
    return _size;
  }
  set
  {
    if (value < 0)
    {
      _size = 0;
    }
    else
    {
      _size = value;
    }
  }
}

public int Length
{
  get
  {
    return _length;
  }
  set
  {
    _length = value;
  }
}

public int Width
{
  set
  {
    _width = value;
  }
}

public int Breadth
{
  get
  {
    return _breadth;
  }
}
foo.Size++;

Properties in Java

private int _size = 0;
private int _length = 0;
private int _width = 0;
private int _breadth = 0;

public int getSize()
{
    return _size;
}
public void setSize(int value)
{
    if (value < 0)
    {
      _size = 0;
    }
    else
    {
      _size = value;
    }
}

public int getLength()
{
    return _length;
}
public void setLength(int value)
{
    _size = value;
}

public void setWidth(int value)
{
    _width = value;
}

public int getBreadth()
{
    return _breadth;
}

foo.Size++;

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Properties
Related information
Creative Commons License


Strings - in COBOL and C#

Strings in Managed COBOL

*> Escape sequences
x"0a"  *> line-feed
x"09"  *> tab
"\"    *> backslash
""     *> quote

*> String concatenation
01 school string value "Harding" & x"09".
   *> school is "Harding (tab) University"
   set school to school & "University"

*> Chars
01 letter character.
01 word character occurs any.
    set letter to school::Chars(0)         *> letter is H
    set letter to type Convert::ToChar(65) *> letter is A
    set letter to 65 as character          *> same thing
    set word to school::ToCharArray        *>word holds Harding

*> String literal
01 msg string value "File is c:\temp\x.dat".

*> String comparison
01 mascot string value "Beatles".
    if mascot = "Beatles"                    *> true
    if mascot::Equals("Beatles")             *> true
    if mascot::ToUpper::"Equals"("BEATLES")  *> true
    if mascot::CompareTo("Beatles") = 0      *> true

*> Substring
    set s to mascot::Substring(1, 3) *> s is "eat"

*> Replacement
    set s to mascot::Replace("Beatl" "Monke")  *> s is "Monkees"

*> Split
01 names string value "John,Paul,George,Ringo".
01 parts string occurs any.
    set parts to names::Split(",")

*> Date to string
01 dt type DateTime value new DateTime(1973, 10, 12).
01 s string.
    set s to dt::ToString("MMM dd, yyyy")  *> Oct 12, 1973

*> int to string
01 x string.
01 y binary-long value 2.
    set x to type x::ToString   *> x is "2"

*> string to int
01 x binary-long.
    set x to type Convert::ToInt32("-5")   *> x is -5

*> Mutable string
01 buffer type System.Text.StringBuilder
        value new System.Text.StringBuilder("two ").
    invoke buffer::Append("three ")
    invoke buffer::Insert(0, "one ")
    invoke buffer::Replace("two" "TWO"
    display buffer             *> Prints "one TWO three"

Strings in C#

// Escape sequences
\r    // carriage-return
\n    // line-feed
\t    // tab
\\    // backslash
\"    // quote

// String concatenation
string school = "Harding\t";
school = school + "University"; // school is "Harding (tab) University"

// Chars
char letter = school[0];              // letter is H
letter = Convert.ToChar(65);          // letter is A
letter = (char)65;                    // same thing
char[] word = school.ToCharArray();   // word holds Harding

// String literal
string msg = @"File is c:\temp\x.dat";
// same as
string msg = "File is c:\\temp\\x.dat";

// String comparison
string mascot = "Beatles";
if (mascot == "Beatles")                 // true
if (mascot.Equals("Beatles"))            // true
if (mascot.ToUpper().Equals("BEATLES"))  // true
if (mascot.CompareTo("Beatles") == 0)    // true

// Substring
s = mascot.Substring(1, 3))     // s is "eat"

// Replacement
s = mascot.Replace("Beatl", "Monke")) // s is "Monkees"

// Split
string names = "John,Paul,George,Ringo";
// One name in each slot
string[] parts = names.Split(",".ToCharArray());

// Date to string
DateTime dt = new DateTime(1973, 10, 12);
string s = dt.ToString("MMM dd, yyyy");     // Oct 12, 1973

// int to string
int x = 2;
string y = x.ToString();     // y is "2"

// string to int
int x = Convert.ToInt32("-5");     // x is -5

// Mutable string
System.Text.StringBuilder buffer =
    new System.Text.StringBuilder("two ");
buffer.Append("three ");
buffer.Insert(0, "one ");
buffer.Replace("two", "TWO");
Console.WriteLine(buffer);     // Prints "one TWO three"
Parent topic: Comparison of COBOL with Other Managed Languages
Related information
String Handling in Managed COBOL
Creative Commons License


Structures, Value Types - in COBOL and C#

Structures in Managed COBOL

COBOL uses the valuetype-id to define a value type.

valuetype-id StudentRecord.
01 aName string public.
01 gpa float-short public.
method-id new.
procedure division using by value nam as string,
                                  gpa as float-short.
    set aName to nam
    set self::"gpa" to gpa
end method.
end valuetype.

class-id a.
method-id main static.
local-storage section.
01 stu type StudentRecord value new StudentRecord("Bob", 3.5).
01 stu2 type StudentRecord.
procedure division.
    set stu2 to stu
    set stu2::name to "Sue"
    display stu::name   *> Prints Bob
    display stu2::name  *> Prints Sue
end method.
end class.

Structures in C#

C# uses struct to define a value type.

struct StudentRecord
{
  public string name;
  public float gpa;

  public StudentRecord(string name, float gpa)
  {
    this.name = name;
    this.gpa = gpa;
  }
}
StudentRecord stu = new StudentRecord("Bob", 3.5f);
StudentRecord stu2 = stu;

stu2.name = "Sue";
Console.WriteLine(stu.name);    // Prints Bob
Console.WriteLine(stu2.name);   // Prints Sue
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
ValueTypes
Related information
Creative Commons License


Synchronization - in COBOL and C#

Synchronization in Managed COBOL

*> Synchronize on an object's monitor, in this case
*> the current object
sync on self
   *> The code here is synchronized
end-sync

Synchronization in C#

// Synchronize on an object's monitor, in this case
// the current object
lock (this)
{
    // The code here is synchronised
}
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
SYNC Statement
Related information
Creative Commons License


MicroFocus.COBOL.RuntimeServices

MicroFocus.COBOL.RuntimeServices assembly provides the following classes:

  • CallableAttribute
  • CharsetAttribute
  • Interop
  • MarshallUtils
  • RunUnit
Restriction: MicroFocus.COBOL.RuntimeServices are supported for .NET managed COBOL only.

The Help is available in the file MicroFocus.COBOL.RuntimeServices.chm, which is installed in the Help folder of your installation. The default location is %ProgramFiles%\Micro Focus\Visual COBOL\Help.

To open the Help, double-click MicroFocus.COBOL.RuntimeServices.chm in Windows Explorer.

Parent topic: Managed COBOL
Related information
Developing an Application for Multiple Run Units in .NET


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
  • ENTRY Statement Restrictions
  • Filename Restrictions
  • Floating-point Numbers
  • Hardware or Operating System Limits
  • Maximum Number of Methods in a Class
  • Size of Names, Literals and PICTURE Character Strings
  • Nested Statement Restrictions
  • 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 | 4GB
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


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 length of the filename is limited to 261 characters. The length of the basename and extension together is 256 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
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.
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 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


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


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 | 4GB
Procedure Division | 816MB
Local-Storage Section | Platform specific
COBOL segment | 16MB
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 with Native COBOL
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 with Native COBOL
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 COM, Java or Web Services
    Any COBOL services, such as COM interfaces, Java interfaces and Web Services, that you created using the Service Interfaces feature or the Interface Mapping Toolkit can continue to run under COBOL Server.
  • Mixed-language Implications in Managed COBOL
    Managed COBOL programs can interoperate seamlessly with programs in other managed languages.
  • Object-Oriented (OO) COBOL Restrictions in Managed Code
    Applications that use the native Object-Oriented (OO) COBOL syntax will probably require significant work to migrate them to managed COBOL. We recommend that you contact Micro Focus support 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
Related information
Visual Studio and COBOL


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.

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.
  • Mainframe PERFORM statements (perform-type(osvs/vsc2)).

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.

Most Compiler directives are supported for managed COBOL, in addition to those directives designed specifically for compiling managed code.

The following Compiler directives are not supported in managed COBOL:

  • ACTUAL-PARAMS
  • BOUNDOPT
  • CHECK
  • COBIDY
  • FASTCALL
  • FASTLINK
  • FAULTFIND
  • FIXOPT
  • GNT
  • HOSTSIGNS
  • INT
  • INTLEVEL
  • KEEP-INT
  • LINKCHECK
  • LITLINK
  • LNKALIGN
  • OBJ
  • OMF
  • OPT
  • PARAMCOUNTCHECK
  • PERFORMOPT
  • RECURSECHECK
  • SCHEDULER
  • SEG
  • SOURCEASM
  • TRICKLE
  • WEBSERVER
Parent topic: Managed COBOL Restrictions
Related information
Compiler Directives
Managed COBOL Command Line Compiler Directives


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.

Managed COBOL supports virtually all file handling functionality.

The following file handling features are not supported in managed COBOL:

  • .lbr files
  • LPT[2-n] devices
  • Printer redirection
  • Timeout support within the support for LPT1
Parent topic: Managed COBOL Restrictions
Related information
File Handling


COBOL Services as COM, Java or Web Services

Any COBOL services, such as COM interfaces, Java interfaces and Web Services, that you created using the Service Interfaces feature or the Interface Mapping Toolkit can continue to run under COBOL Server.

COBOL Server can run any Java interfaces, COM interfaces or Web Services that you exposed using the Interface Mapping Toolkit.

However, the Interface Mapping Toolkit is not available in Visual COBOL, so you cannot create new interfaces or services like this.

Parent topic: Managed COBOL Restrictions
Related information
Java and COBOL
Web Application Projects


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.

Non-COBOL projects that call COBOL code require a reference to the MicroFocus.COBOL.Runtime assembly.

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


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 support for extra help with this.

Applications that use the native OO COBOL syntax will probably require significant work to migrate them to managed COBOL. We recommend that you contact Micro Focus support 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.

Managed COBOL provides extensive support for SQL.

The following 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.
  • CONNECT ... WITH PROMPT syntax is not supported with applications compiled with SQL(DBMAN=ADO)
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


Licensing

  • Licensing Concepts
  • Authorizing Your Product
  • Revoking Licenses
  • Licensing Error Messages
    Messages you might encounter when working with licensing.
Parent topic: General Reference


Licensing Concepts

  • Overview
  • To start the Micro Focus Licensing Administration tool
  • To view installed licenses
  • Trial Licenses
  • Usage Log
  • Using the Licensing Services
    Guidance on using the Sentinel RMS license server when developing COBOL projects.
Parent topic: Licensing


Overview

You manage your product licensing by using the Micro Focus Licensing 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 is administering licenses, you can also request licenses from a central license server.

Tip: You can prevent the license server being installed by creating an empty file called SKIP_SAFENET_INSTALL and saving it in the Sentinel installation folder ...\SafeNet Sentinel\Sentinel RMS License Manager\WINNT).

This stops licensing being interrupted while updates to the server are installing. When licensing needs to be updated, remove the file and install the server manually. You can also use this process on machines where you need to preserve the production environment.

Central License Server

If your site has multiple licenses and you want to use a central license server to manage them, install the Micro Focus License Manager that is supplied with your product. Individual workstations can then be configured to obtain a license from the license server machine.

License Management System Restrictions

The Sentinel RMS license management system supplied with your product does not acknowledge or manage Micro Focus product licenses you have previously installed and that use the Micro Focus License Management System.

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.

Uninstalling a Product that uses Sentinel RMS

Uninstalling a Micro Focus product that uses Sentinel RMS does not revoke 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 revoke the licenses that you have activated for it.

Parent topic: Licensing Concepts


To start the Micro Focus Licensing Administration tool

From the Windows Taskbar click Start > All Programs >Micro Focus License Manager > License Management System.

Parent topic: Licensing Concepts
Related information
To authorize your product using a local license server
To authorize your product manually
To set up a central license server and load licenses
To configure your workstation to use a central license server
To view installed licenses
To revoke licenses
To revoke licenses manually


To view installed licenses

  1. Start the Micro Focus Licensing Administration tool.
  2. Select the Licenses tab.
A list of installed licenses will be displayed and will show:
  • The name of the product licensed
  • The serial number of the license
  • The type of license
  • For limited licenses, the expiry date
  • Whether the license is hosted locally or a networked computer
Parent topic: Licensing Concepts
Related information
To start the Micro Focus Licensing Administration tool
To authorize your product using a local license server
To authorize your product manually
To set up a central license server and load licenses
To configure your workstation to use a central license server
To revoke licenses
To revoke licenses manually


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.

Parent topic: Licensing Concepts


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 10MB in size they are archived to lservrc.log.xxx where xxx is an incremental number for the archive file.

The files are located in C:\Documents and Settings\All Users\Application Data\Micro Focus or C:\Programdata\Micro Focus depending on which version of Windows you are using. As these files contain important and useful information, and, to maintain disk space, it is recommended that you manage these files accordingly.

Parent topic: Licensing Concepts


Using the Licensing Services

Guidance on using the Sentinel RMS license server when developing COBOL projects.

Developing COBOL projects requires that licenses are installed.

By default the Sentinel RMS license server is installed automatically in your Micro Focus product. It starts automatically and runs as a service.

Tip: You can prevent the license server being installed by creating an empty file called SKIP_SAFENET_INSTALL and saving it in the Sentinel installation folder ...\SafeNet Sentinel\Sentinel RMS License Manager\WINNT).

This stops licensing being interrupted while updates to the server are installing. When licensing needs to be updated, remove the file and install the server manually. You can also use this process on machines where you need to preserve the production environment.

  • To start the Sentinel RMS license server
    Steps to start the license server.
  • To stop the Sentinel RMS license server
    Steps to stop the license server.
  • To start the Micro Focus licensing service
Parent topic: Licensing Concepts


To start the Sentinel RMS license server

Steps to start the license server.

Note: Normally you don't need to start the license server as it starts automatically and runs as a service.
  1. Open the Microsoft Management Console Services snap-in.
  2. Right-click on Sentinel RMS License Manager and choose Start.
Parent topic: Using the Licensing Services


To stop the Sentinel RMS license server

Steps to stop the license server.

  1. Open the Microsoft Management Console Services snap-in.
  2. Right-click on Sentinel RMS License Manager and choose Stop.
Parent topic: Using the Licensing Services


To start the Micro Focus licensing service

The licensing service enables the Micro Focus licensing system to communicate with the Sentinel system. It starts automatically. If you need to restart it, do the following:

  1. Open Control Panel > Services.
  2. Start MF CES Daemon.
Parent topic: Using the Licensing Services


Authorizing Your Product

Depending on your system and requirements, you can either install Sentinel RMS license server on individual computers or on a single computer that will act as a central license server. A Sentinel RMS license server is installed automatically with your product, and you can choose any machine on which it is installed to act as the central server if required.

You need an appropriate type of authorization code in order to install your license or licenses. For example, if you have ordered 50 licenses then the authorization code installs either 1 license on each of 50 machines or 50 licenses on the central server. If you do not know which type of code you need, contact your system administrator.

  • To authorize your product using a local license server
  • To authorize your product manually
  • To configure your workstation to use a central license server
Parent topic: Licensing


To authorize your product using a local license server

The task steps below describe how to authorize your product if you are using the Sentinel RMS license server that is set up on your local machine. (The license server is automatically set up when you first install your product.)

Note: Internet connectivity is required to perform this task.
  1. Start the Micro Focus Licensing Administration tool.
  2. Click the Authorize tab.
  3. Enter your authorization code.
  4. Click Authorize.
Note: If authorization fails, the user interface will allow you to attempt manual authorization.
Parent topic: Authorizing Your Product
Related information
To start the Micro Focus Licensing Administration tool
To authorize your product manually
To set up a central license server and load licenses
To configure your workstation to use a central license server
To view installed licenses
To revoke licenses
To revoke licenses manually


To authorize your product manually

Manual authorization is necessary if your machine does not have Internet connectivity or if normal (automatic) authorization has failed. where normal authorization has failed, the user interface for manual authorization is displayed automatically. You can start this interface manually by choosing the Manual Activation option from the Options menu.

  1. Start the Micro Focus Licensing Administration tool if it is not already enabled.
  2. From the Options menu, select Manual Authorization.

Take the following steps for both methods of Manual Authorization:

  1. Either click the http link on the Manual Authorization Interface or paste the http link into an Internet browser. If you don't have an Internet connection, make a note of the address and perform this step on a machine with Internet access. When you have obtained the license strings you can then copy them onto the license server.

    The link will take you to the Micro Focus Safenet activation webpage.

  2. Enter your authorization code (a 16-character alphanumeric string)
  3. Enter your Machine ID. The Machine ID string is displayed on the Manual Authorization interface.
  4. Enter your e-mail address in the Email Address field.
  5. Click Generate.
  6. Copy the generated license string and paste it into License String on the Manual Authorization interface.

    Alternatively, wait until you have received an email message from Product Support containing your license string.

  7. Click Install Licenses.
Parent topic: Authorizing Your Product
Related information
To start the Micro Focus Licensing Administration tool
To authorize your product using a local license server
To set up a central license server and load licenses
To configure your workstation to use a central license server
To view installed licenses
To revoke licenses
To revoke licenses manually


To configure your workstation to use a central license server

You can set up a central Sentinel RMS license server if your authorization code grants multiple licenses. A license server is installed automatically when you install your Micro Focus product, and you can use any license server installation as your central license server without additional configuration.

CAUTION:
If you change the name of your license server after you have installed licenses it will stop working.

The task steps below describe how to authorize your workstation product if you want to obtain a license from a central Sentinel RMS license server. Internet connectivity is required.

You need the IP address or server name for the central license server you want to access. You should be able to get this from your License System Administrator.

Important: We recommend that other options on Advanced Configuration are modified only under guidance from Micro Focus SupportLine.
  1. Start the Micro Focus Licensing Administration tool.
  2. Select Options > Advanced Configuration
  3. Click Change against the License Server row.
  4. Enter the IP address or server name of the central license server.
  5. Click Save.
  6. Click Close.
Parent topic: Authorizing Your Product
Related information
To start the Micro Focus Licensing Administration tool
To authorize your product using a local license server
To authorize your product manually
To set up a central license server and load licenses
To view installed licenses
To revoke licenses
To revoke licenses manually


Revoking Licenses

  • To revoke licenses
  • To revoke licenses manually
    The manual revoke process should be followed when automatic revoke has failed.
  • To revoke licenses during product uninstall
  • To move your product license to a different computer
Parent topic: Licensing


To revoke licenses

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

Note: Internet connectivity is required to perform this task.
  1. Start the Micro Focus Licensing Administration tool.
  2. Select the Revoke tab.
  3. Select the product license you want to revoke.
  4. Click Revoke

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

  5. Input or select the number of licenses you want to revoke.
  6. Click Revoke.

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

Ensure that you keep the new authorization codes in a safe place. You will need them when you re-authorize your product.

Note: If there is a problem accessing the Micro Focus License Authorization Server and the revoke fails, the Revoke Product Licenses dialog box will enable options to allow manual revocation. At this point your licences 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.
Parent topic: Revoking Licenses
Related information
To start the Micro Focus Licensing Administration tool
To authorize your product using a local license server
To authorize your product manually
To set up a central license server and load licenses
To configure your workstation to use a central license server
To view installed licenses
To revoke licenses manually


To revoke licenses manually

The manual revoke process should be followed when automatic revoke has failed.

If automatic revocation fails, the Revoke Product Licenses dialog box will display options for manual revocation. Either:

  1. Copy all of the character string displayed in the text box at the bottom of the Revoke Product Licenses dialog box.

    This string contains the Sentinel RMS License Revoke Tickets that are required to issue a new authorization code.

  2. Click the HTTP link.

    The link will take you to the Micro Focus SafeNet License Revocation web page.

  3. Paste the copied string into the text box and click Generate.

    The new Authorization code will be displayed.

Or

  1. Copy all of the character string displayed in the text box at the bottom of the Revoke Product Licenses dialog box and send in an email to your SupportLine representative.
Important: Ensure that you keep the new authorization codes in a safe place. You will need them when you re-authorize your product.
Parent topic: Revoking Licenses
Related information
To start the Micro Focus Licensing Administration tool
To authorize your product using a local license server
To authorize your product manually
To set up a central license server and load licenses
To configure your workstation to use a central license server
To view installed licenses
To revoke licenses


To revoke licenses during product uninstall

When you uninstall a product, the Micro Focus License Manager software performs a check to see if any licenses for that product exist on your computer. If so, you will be prompted to revoke them. If you do revoke them, they will be removed and you will be given you a new authorization code. You use this new code to generate a license when you install the product on another machine.

If you are going to re-install your product on the same machine, you do not need to revoke the license. In this case, select Keep when you are prompted to revoke the license.

  1. Uninstall your product.

    A prompt will display to reallocate your licenses.

  2. Select Revoke if you want to revoke the licenses.

    The Micro Focus License System Administration tool is displayed at the Revoke tab.

  3. Select the product license you want to revoke.
  4. Click Revoke.

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

  5. Input or select the number of licenses you want to revoke.
  6. Click Revoke.

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

    Ensure that you keep the new authorization codes in a safe place. You will need them when you re-authorize your product(s) .

Note: If there is a problem accessing the Micro Focus License Authorization Server and the revoke fails, the Revoke Product Licenses dialog box will enable options to allow manual revocation. At this point your licences 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.
Parent topic: Revoking Licenses


To move your product license to a different computer

If you have been using a product that has had a license provided by the local license server, you can use the product on a different computer by performing these steps

  1. Start the Micro Focus Licensing Administration tool.
  2. Revoke the license, making note of the new authorization code that will be required when you re-authorize your product.
  3. Uninstall the product.
  4. Install the product on the new computer.
  5. Start the Micro Focus Licensing Administration tool.
  6. Authorize your product with the new authorization code.
Note: You can proceed with the product uninstall without taking steps to revoke the license first. In this case, you will be guided through the revoke process as part of the uninstall.
Parent topic: Revoking Licenses
Related tasks
To revoke licenses during product uninstall
Related information
To start the Micro Focus Licensing Administration tool
To authorize your product using a local license server
To configure your workstation to use a central license server


Licensing Error Messages

Messages you might encounter when working with licensing.

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


Initialization error - Initializing: Cannot communicate with licensing daemon

Check the licensing service is running.

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

Parent topic: Licensing Error Messages


Error - Initalizing: Cannot find initialization file

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


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

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


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

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


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

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


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

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


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

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


Unable to authorize (cause)

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


Run-time System Configuration

Restriction: The run-time switches and tunables are supported for native COBOL only.

You can configure the run-time system environment to ensure it behaves appropriately for the application, regardless of the configuration used by other COBOL applications. You can configure run-time behavior through environment variables, run-time tunables, and run-time switches.

  • Run-time Switches
  • Run-time Tunables
Parent topic: General Reference
Related information
Overview of Linking Native COBOL Applications and Run-time Systems


Run-time Switches

Restriction: These switches are supported for native COBOL only.

You can control the behavior of a program by setting run-time switches. For example, there is a switch to hide trailing spaces in DISPLAY ... UPON CONSOLE statements, and a switch to direct error messages to a log file or the console. Most switches affect specific COBOL features.

  • Introduction to Switches
  • Setting Run-time Switches
  • Syntax for Setting Switches
  • List of General Run-time Switches
Parent topic: Run-time System Configuration


Introduction to Switches

A switch is a parameter you pass to the run-time system to control the behavior of your program at run time. These switches fall into two categories:

Run-time switches
Run-time switches are acted on by the run-time system itself. Each consists of an upper-case or lower-case letter. These switches affect optional aspects of the behavior of certain COBOL features at run time.
Programmable switches
COBOL programmable switches are numbered from 0 to 8. Each can be set to "off" or "on" when your application is started. Their state can be read by your application at any time when it is running.

The switches must be defined using a condition name in the Special-Names paragraph. For example:

 special-names.
     switch-0 is job-origin on status is us-office
                            off status is uk-office
  ...
 procedure division.
     evaluate job-origin
      when us-office...
      when uk-office...
  ...
Parent topic: Run-time Switches


Setting Run-time Switches

Restriction: These switches are supported for native COBOL only.

You can specify switches:

  • In the project's application configuration file in the IDE. These switch settings are built into your application and are the defaults used for your application. These settings can be overridden when you run the application.
  • In the environment variables COBSW and OOSW (for switches for object-oriented programs). These switch settings take effect when you start the application. We recommend that for switches affecting file handling, you do not use COBSW, but edit the file handler configuration file Extfh instead.

    The following command sets the programmable switches 1 and 4 on, and all the others (2, 3, 5-8) are off by default:

    set COBSW=+1+4
  • On the command line. These switch settings take effect when you start the application. Switch settings on the command line take precedence over those in COBSW.

    For example, the following command loads the program myprog with programmable switches 5 and 7 on and switch 2 off, and all the others (0, 1, 3, 4, 6 and 8) are off by default. Note that switch 7 is turned on, since the last setting of it (that is +7) is the one used.

    myprog -2+5-7+7

    The following command loads the program myprog with switch T on and switch O off:

    myprog (+T-O)
Parent topic: Run-time Switches
Related information
To add a configuration file


Syntax for Setting Switches

To set switches on the command line, use the following command:

({ {+|-|/}s }...)

To set switches using COBSW use the following command:

SET COBSW={ {+|-|/}switch }...

where:

{ | } | Choose one of the items either side of the |.
{ }... | You can repeat this item.
switch | Either a programmable switch with a digit in the range 0 through 8, or a run-time switch with an upper-case or lower-case letter. A letter is equivalent to the same letter followed by the digit 0. For example B, B0, b, b0 all refer to the same switch.
+ | Sets the switch on.
- | Sets the switch off.

Notes

  • Switches can be separated by spaces (but this is not required); however, there must not be a space between the sign ("+" or "-") and its associated switch
  • Switches can be specified in any order, but each programmable or alphabetic switch must be preceded by a sign
  • Individual switches can be set more than once, but the last setting of any particular switch is the one accepted by the system
  • Switches remain set when COBOL subprograms are called
  • Switches set on the command line take precedence over those defined in the COBSW environment variable
  • Switches are case sensitive
Parent topic: Run-time Switches


List of General Run-time Switches

Restriction: These switches are supported for native COBOL only.
  • 0, 1, 2, 3, 4, 5, 6, 7 and 8 run-time switches
    Sets the corresponding COBOL switch when the program is entered.
  • A1 run-time switch
    Disables the display of trailing spaces by causing DISPLAY ... UPON CONSOLE statements to strip off any trailing spaces in the data item being displayed before outputting the data to the screen.
  • B, B1 run-time switches
    Causes the record pointer to be updated past any locked record encountered when using the READ NEXT statement.
  • C4 run-time switch
    Forces the screen in 43-line mode on an EGA or VGA monitor, or with the COBOL Text Window.
  • C5 run-time switch
    Forces the screen in 50-line mode on an EGA or VGA monitor, or with the COBOL Text Window.
  • D run-time switch
    Invokes the standard ANSI COBOL Debug module.
  • d run-time switch
    Specifies the amount of memory in bytes to be used for the run-time system dynamic paging buffers.
  • E run-time switch
    Enables the execution of intermediate code which contains S-level syntax-check errors.
  • F run-time switch
    Checks all numeric items for valid numeric data.
  • I2 run-time switch
    Redirects run-time system errors to STDERR.
  • l run-time switch
    Enables you to set the maximum amount of memory to be made available to the run-time system, or to cause the run-time system to perform physical cancels instead of logical cancels.
  • L1 run-time switch
    Disables the interactive popup window that appears when an exception error occurs.
  • L2 run-time switch
    Determines the character(s) to be used as the record terminator when reading a line sequential file.
  • N run-time switch
    Enables null insertion for all line sequential files in your program.
  • S5 run-time switch
    Enables redirectable console I/O.
  • T run-time switch
    Enables insertion of tab characters in all line sequential files.
  • List of Run-time Switches for OO Programs
  • Key to Run-time Switches
Parent topic: Run-time Switches


0, 1, 2, 3, 4, 5, 6, 7 and 8 run-time switches

Sets the corresponding COBOL switch when the program is entered.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | All off
Type: | General

Comments:

These switches enable the COBOL switches 0-8 that you defined in the Special-Names paragraph of your program. You can specify these switches in any order, but each individual switch must be preceded by a sign.

Parent topic: List of General Run-time Switches
Related concepts
Configuration Section
The Special-Names Paragraph
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


A1 run-time switch

Disables the display of trailing spaces by causing DISPLAY ... UPON CONSOLE statements to strip off any trailing spaces in the data item being displayed before outputting the data to the screen.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

This switch provides compatibility with earlier COBOL systems from Micro Focus. When this switch is off, the trailing spaces are included in the display, as required by the ANSI COBOL Standard.

Parent topic: List of General Run-time Switches
Related reference
The File Control Entry
Data Description Entry Skeleton
The USAGE Clause
Screen Section Entry Skeleton
The USAGE Clause in the Screen Section
The DISPLAY Statement
Related information
List of Run-time Switches for OO Programs
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


B, B1 run-time switches

Causes the record pointer to be updated past any locked record encountered when using the READ NEXT statement.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | File handling

Comments:

Set the B switch for indexed sequential files open INPUT or I-O. Set the B1 switch for indexed sequential files open INPUT. Setting either of these switches permits a file to be sequentially read, even if another process has records locked in that file.

A file status of "locked record" is returned when a locked record is read when the B switch is set; a file status of "00" is returned when a locked record is read when the B1 switch is set.

Note: This switch also affects relative and record sequential files when your program is compiled with the CALLFH directive set.
Parent topic: List of General Run-time Switches
Related reference
CALLFH
The OPEN Statement
The SORT Statement
The USE Statement
XML Syntax - OPEN Statement
The File Control Entry
The READ Statement
XML Syntax - READ Statement
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


C4 run-time switch

Forces the screen in 43-line mode on an EGA or VGA monitor, or with the COBOL Text Window.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

The original screen mode is restored upon return to the operating system.

Setting this switch causes the components to start in 43-line mode.

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


C5 run-time switch

Forces the screen in 50-line mode on an EGA or VGA monitor, or with the COBOL Text Window.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

The original screen mode is restored upon return to the operating system.

Setting this switch causes the components to start in 50-line mode.

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


D run-time switch

Invokes the standard ANSI COBOL Debug module.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

This switch must be set on the command line.

Example:

The following command loads the program Myprog with the standard ANSI COBOL Debug module invoked:

myprog (+D)
Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


d run-time switch

Specifies the amount of memory in bytes to be used for the run-time system dynamic paging buffers.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | -d245760 (240 K)
Type: | General

Comments:

Dynamic paging is used by programs such as the Compiler. By increasing the amount of memory you might be able to improve the performance of such programs. Once the amount of memory allocated for dynamic paging is exceeded, the run-time system pages any further requirements onto disk.

For example, when compiling a large COBOL program, the amount of memory for dynamic paging buffers might be exceeded due to the Compiler requiring a large amount of dictionary to store the symbol table it creates. When the dynamic paging buffer space is exhausted, the run-time system starts to page dynamic accesses to disk, which might have a performance overhead. By raising the amount of memory for dynamic buffering, paging to disk can be avoided (or at least reduced) and therefore better Compiler performance achieved.

Example:

To double the amount of memory (to 500k) the run-time system could use before paging to disk, you would set the COBSW environment variable as follows:

COBSW=-d500000
Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


E run-time switch

Enables the execution of intermediate code which contains S-level syntax-check errors.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

If you try to run intermediate code programs which contain S-level Compiler errors when this switch is set to off, you receive a run-time system error.

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


F run-time switch

Checks all numeric items for valid numeric data.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | On
Type: | General

Comments:

If the data is not valid, run-time system error 163 ("Illegal character in numeric field") is produced. Setting this switch to off suppresses this checking.

This checking is only done on generated code created with the CHECKNUM Compiler directive, and on intermediate code.

The run-time system and generated code try to optimize many types of numeric operations. These operations can cause invalid results if the numeric operands do not contain valid numeric data. By default, the run-time system gives the run-time system error 163 when a numeric operation is tried with invalid numeric data.

Invalid data is handled differently by intermediate and native code. We recommend that you enable numeric field checking while you are developing your program.

If you receive run-time error 163, we recommend that you adjust your code so that no invalid data is used. You can locate the invalid numeric data in your code by setting the +F switch on and then animating your program until run-time system error 163 is detected.

If you are not able to correct your code, you might want to use one or more of the following Compiler directives to resolve invalid data in numeric fields:

  • HOSTSIGNS - enables arithmetic with COMP-3 items that have illegal sign nibbles to produce the desired result.
  • HOSTNUMCOMPARE - controls the operation of comparisons between integer numeric data items of USAGE DISPLAY and alphanumeric literals or figurative constants. You can set the ZWB Compiler directive with HOST-NUMCOMPARE to affect comparisons involving signed and unsigned data items. These directives emulate mainframe behavior, so you do not need to change your data.
  • HOSTNUMMOVE - causes the Compiler to switch off checking for illegal characters in numeric fields during the execution of certain MOVE statements. (Use with care.)
  • SIGN-FIXUP - provides limited emulation of mainframe compiler options NUMPROC(NOPFD) and NUMPROC(PFD) for MOVE and COMPARE statements if you also set HOSTNUMCOMPARE or HOSTNUMMOVE.
  • SPZERO - causes space characters in numeric data items of USAGE DISPLAY to be treated as zeros.

Example:

working-storage section.
    01 item-a       pic 9.
procedure division.
    If item-a =  0.
        Display "zero"
    else
        display "nonzero"
    end-if.

The variable item-a is not initialized by a VALUE clause, and so contains a space character x"20". Running this program with the F switch set on causes the run-time system to check whether the numeric field contains a non-numeric value resulting in run-time error 163.

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


I2 run-time switch

Redirects run-time system errors to STDERR.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

The I2 switch is enabled only when used in conjunction with the +S5 switch.

If set off, run-time system error messages are sent to STDOUT (standard output). If set on, the error messages are sent to STDERR (standard error).

This switch has no effect when running under Windows.

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


l run-time switch

Enables you to set the maximum amount of memory to be made available to the run-time system, or to cause the run-time system to perform physical cancels instead of logical cancels.

Note: Restriction:

These switches are supported for native COBOL only.

Properties:

Default: | The maximum number of bytes available to the run-time system.
Type: | General

Comments:

This switch is lower-case "L", not upper-case "I".

The format of this switch is lnnnnnn, where nnnnnn is the amount of memory in bytes to be made available to the run-time system.

You can use this switch to limit the amount of memory the run-time system will use. This might be useful to enable you to tune your system.

By default the run-time system performs logical cancels unless all available memory has been used up. As far as your programs are concerned, the behavior of logical and physical cancels is identical, but logical cancels are faster. A logical cancel flushes all file buffers but does not release any memory. To force all cancels to be physical, you must specify this switch with parameter zero; for example:

+l0

By default, when the run-time system requires memory space it checks that the new request does not exceed the available memory. If it does, the memory that should have been freed by any cancels is freed and the run-time system repeats its request for memory. The run-time system loads programs that have been logically canceled in preference to reloading from disk.

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview
default_cancel_mode


L1 run-time switch

Disables the interactive popup window that appears when an exception error occurs.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

Instead of the interactive popup window, a general Windows error message is displayed and control is returned to the operating system without any user intervention.

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


L2 run-time switch

Determines the character(s) to be used as the record terminator when reading a line sequential file.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | File handling

Comments:

When off (-L2), x"0A" is taken as the record terminator.

When on (+L2), x"0D0A" is taken as the record terminator. This provides compatibility with earlier versions of this system, correctly reading files written using a WRITE ... AFTER ADVANCING statement.

This switch only affects read operations and not write operations.

Use of the +L2 switch is in many respects unnecessary for the majority of applications. The File Handler is able to recognize line sequential delimiters for data files created, irrespective of the platform on which the files are processed. Using this method to change the delimiters will not result in the user record area ever containing x'0D' characters (unless escaped using the INSERTNULL option) because these are discarded as noise characters by the File Handler. This is in contrast to OCDS behavior.

Parent topic: List of General Run-time Switches
Related reference
The WRITE Statement
XML Syntax - WRITE Statement
Related information
List of Run-time Switches for OO Programs
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


N run-time switch

Enables null insertion for all line sequential files in your program.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | On
Type: | File handling

Comments:

This switch is especially useful if the format of your files is incompatible with this COBOL system.

Setting this switch to on means that when a program writes records to a line sequential file with a record containing control characters (that is, all characters with ASCII codes less than or equal to x"1F"), the system adds a null character (x"00") before each control character. Similarly, on reading a record from a line sequential file, these null characters are stripped from the control characters.

Setting this switch affects only the physical storage of data in a line sequential file. Records written with one setting and read back with the same setting are returned in exactly the same way. However, if you try to read a file with one setting which was written with the other setting, the results are unpredictable.

Setting this switch off enables control characters to be written and read in the same way as other characters.

When the N switch is on:

  • Any character is allowed in the data record of a line sequential file.
  • Each record is examined before it is written. All characters whose value is less than or equal to x"1F" are written with a preceding null (x"00") to form two-byte pairs. On output to disk, trailing spaces are removed, and a record terminator of x"0D0A" is appended to terminate the record.
  • The file is read as records, some of which might contain two-byte pairs where the first byte is null. The records are terminated by a record terminator. The leading null of each two-byte pair is removed to give the final data record. Tabs (x"09") that do not form part of a two-byte pair are expanded.

The File Handler configuration option INSERTNULL takes precedence over the N run-time switch:

Note: Control characters depend on the operating system. Their hexadecimal values are always less than x"1F". CR (x"0D"), LF (x"0A"), TAB (x"09"), NUL (x"00"), and EOF (x"1A") are all recognized control characters on Windows.

When the N switch is off:

  • Data records in a line sequential file must contain only ASCII text characters (those with a value greater than x"1F").
  • Trailing spaces are removed on output to disk, and a record terminator of x"0D0A" is appended to terminate the record. Printer control characters might also be written to disk.
  • The file is read as data records with each record terminated by a record terminator. If the data contains either x"0D" or x"0A", results can be unpredictable. Tab characters (x"09") are expanded to spaces; otherwise the data record is returned intact.

Example:

The command:

a:myprog (-n)

loads the program Myprog from drive a:. It also specifies that, in line sequential files, all characters less than or equal to x"1F", except for Tab and the file control characters, are treated as data. Null is not inserted before data characters less than x"1F" on output.

Parent topic: List of General Run-time Switches
Related reference
EXPANDTAB
Related information
List of Run-time Switches for OO Programs
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


S5 run-time switch

Enables redirectable console I/O.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

This function is achieved by the run-time system forcing all ACCEPT FROM/DISPLAY UPON CONSOLE statements to be executed such that I/O to and from the screen and keyboard can be redirected by using the > and < operators on the operating system command line.

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview
Introduction to Run-time Switches
Run-time Switches for OO Programs
Key to Run-time Switches
Run-time Tunables
The ACCEPT Statement
ALTER and ACCEPT Statement Restrictions
The File Control Entry
Data Description Entry Skeleton
The USAGE Clause
Screen Section Entry Skeleton
The USAGE Clause in the Screen Section
The DISPLAY Statement
I2 run-time switch


T run-time switch

Enables insertion of tab characters in all line sequential files.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | File handling

Comments:

This switch is especially useful if the format of your files is incompatible with this COBOL system.

On output to disk, multiple spaces before a tab stop position are written as one tab character. The T switch does not affect any trailing spaces as these are not part of the line sequential record, and they are removed on output. Tab positions are every 8 character positions (for example, 9, 17, 25) and cannot be changed.

On input, tab characters are always expanded to spaces to the next position, regardless of the setting of the T switch.

With this switch set to off, all spaces in a line sequential file are written to disk as space characters.

Parent topic: List of General Run-time Switches
Related concepts
Trailing Blanks in Line Sequential Files
Related reference
EXPANDTAB
Related information
List of Run-time Switches for OO Programs
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


List of Run-time Switches for OO Programs

Restriction: These switches are supported for native COBOL only.

To set OO run-time switches, use the environment variable OOSW. For example, the following turns off the v switch and turns on the d switch:

set oosw=-v+d
  • d OO run-time switch
    Enables debugging by preventing reuse of object handles from finalized objects.
  • f OO run-time switch
    Enables you to name the message trace file.
  • g1 OO run-time switch
    Sets a guard page before Object-Storage sections
  • g2 OO run-time switch
    Sets a guard page after Object-Storage sections.
  • l OO run-time switch
    Sets the Class Library to be preloaded by the run-time system.
  • t OO run-time switch
    Generate a trace file showing every message sent by your application.
Parent topic: List of General Run-time Switches


d OO run-time switch

Enables debugging by preventing reuse of object handles from finalized objects.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | OO

Comments:

In normal operation, each time an object is finalized its object handle is available for reuse by the run-time system and can be assigned when a new object is created. Setting +d prevents the run-time system from reallocating object handles.

Do not use this switch for production applications – the run-time system can eventually run out of memory to allocate new handles.

Parent topic: List of Run-time Switches for OO Programs
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


f OO run-time switch

Enables you to name the message trace file.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | OO

Comments:

The format of the switch is:

ftrace.log

where trace.log is the name of the message trace file. The default trace filename is trace.log.

Parent topic: List of Run-time Switches for OO Programs
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


g1 OO run-time switch

Sets a guard page before Object-Storage sections

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | OO

Comments:

You can't set +g1+g2.

Parent topic: List of Run-time Switches for OO Programs
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


g2 OO run-time switch

Sets a guard page after Object-Storage sections.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | OO

Comments:

You can't set +g1+g2.

Parent topic: List of Run-time Switches for OO Programs
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


l OO run-time switch

Sets the Class Library to be preloaded by the run-time system.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | On
Type: | OO

Comments:

The format of this switch is:

lclass

where class is the name of the class that you want pre-loaded.

Set this switch off to disable loading of the Class Library. You should do this if you want to debug the class library.

If you have your own class library in a .lbr file, you can load that instead of the Micro Focus Class Library. Set:

+lfilename

where filename is the name of the .dll file.

You can load more than one class library with the +l switch; separate the names with semicolons (;). For example:

+lclass1;class2

Do not leave any spaces between the names.

Parent topic: List of Run-time Switches for OO Programs
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


t OO run-time switch

Generate a trace file showing every message sent by your application.

Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | OO

Comments:

The trace file is named trace.log by default. You can specify a name for the file with the f switch.

The trace file shows you the messages sent by your application and is useful for debugging. Do not set this switch when running production applications – trace slows down execution, and the log file grows in size continuously while the application runs.

Parent topic: List of Run-time Switches for OO Programs
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


Key to Run-time Switches

Restriction: These switches are supported for native COBOL only.

The following information is shown for each switch:

Function:

The function that the switch performs.

Properties:

Default: The default setting of the switch.
Type: Indicates how you set the switch. The type can be:
  • General. Set on the command line or using the environment variable COBSW.
  • OO. Set using the environment variable OOSW.
  • File handling. Set in the file handler configuration file extfh.cfg

Comments:

Additional information about the switch.

Parent topic: List of General Run-time Switches


Run-time Tunables

You can use run-time tunables to control the behavior of a program. Run-time tunables are stored in a run-time configuration file.

  • Run-time Configuration Tunables - Overview
  • Format of a Configuration File for Native COBOL
  • Format of a Configuration File for .NET COBOL
  • List of Run-time Tunables
Parent topic: Run-time System Configuration


Run-time Configuration Tunables - Overview

You normally configure your run-time system using a project's properties in the IDE. However, some run-time behavior cannot be configured using the IDE; this must be configured using run-time tunables, which are stored in a run-time configuration file.

When your run-time system or linked executable starts up, it attempts to read the run-time configuration file. The run-time configuration file specifies values for the run-time tunables .

If a setting specified in the IDE conflicts with a setting in the configuration file, the setting specified in the IDE takes precedence.

The run-time configuration file is shared by all users of the run-time system.

For native COBOL, you create or edit the run-time configuration file with a text editor, and then specify the location and name of the run-time configuration file using the COBCONFIG_ environment variable.

For example, if you want to use a configuration file called myconf.cfg , you set COBCONFIG_ as follows.

set COBCONFIG_=e:\mydir\myconf.cfg

For .NET COBOL, you add a configuration file (e.g. an application.configuration file or web.configuration file) in Visual Studio. There is no need to use an environment variable to specify its location, because the file is part of the application managed at run-time.

The use of a configuration file is optional - no error is issued if it does not exist.

Parent topic: Run-time Tunables
Related information
To add a configuration file


Format of a Configuration File for Native COBOL

The configuration file conforms to this format:

  • Each run-time tunable appears on a new line.
  • Blank lines are ignored.
  • A comment line starts with a # character. However, as the configuration file is processed at run-time, we advise that you limit the number of comments, in order to keep to a minimum the time taken to process the configuration file.
  • The maximum number of characters permitted in a comment line is 80, including any new-line or carriage return characters that might be placed at the end of the line by some editors.
  • Each space in the definition can be replaced with tabs or more than one space. For example:
    setenv dd_MYFILE /usr/mydir/myfile
set cobconfig_error_report=TRUE

The format of each tunable is:

set configurable_name=value
where:
configurable_name
The name of the run-time tunable .
value
The value to be assigned to the run-time tunable.

Where value is numeric, a leading zero indicates that the value should be treated as octal (that is, base 8). For example, 07 (octal) is 7 (decimal), while 010 (octal) is 8 (decimal); however, 08 (octal) and 09 (octal) are invalid octal values. Hexadecimal values can also be set by using numeric values that begin with with 0x.

Parent topic: Run-time Tunables


Format of a Configuration File for .NET COBOL

When a required option to configure the run-time behavior is not available in the IDE, use a .config file to set a run-time tunable in your .NET COBOL applications.

In Visual Studio, add the correct .config file for the type of application you are using; for example:
  • Add an application configuration file (exe.config) for a console application.
  • Add a web configuration file (web.config) for an ASP.NET application.
Note: You do not need to configure the COBCONFIG_ environment variable to point to this file, because the file is part of the application managed at run-time.

When you add the configuration to your .NET COBOL application, the Tunables section group is already declared. Add the section details, using the section details in bold below as an example.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
 <configSections>
  <sectionGroup name="MicroFocus.COBOL.Application">
   <section name="Switches" type="System.Configuration.NameValueSectionHandler" />
   <section name="Environment" type="System.Configuration.NameValueSectionHandler" />
   <sectionGroup name="Interop">
    <section name="PreLoad" type="System.Configuration.NameValueSectionHandler" />
   </sectionGroup>
  </sectionGroup>

  <sectionGroup name="MicroFocus.COBOL.Runtime">
   <section name="Tunables" type="System.Configuration.NameValueSectionHandler" />
   <section name="Switches" type="System.Configuration.NameValueSectionHandler" />
  </sectionGroup>
</configSections>

<MicroFocus.COBOL.Application>
 <Switches></Switches>
 <Environment></Environment>
 <Interop> <PreLoad> </PreLoad> </Interop>
</MicroFocus.COBOL.Application>

 <MicroFocus.COBOL.Runtime>
  <Tunables>
   <add key="printer_redirection" value="true" />
   <add key="printer_defaults" value="size=20;font=Courier New" />
  </Tunables>
  <Switches></Switches>
 </MicroFocus.COBOL.Runtime>
</configuration>
Parent topic: Run-time Tunables
Related concepts
printer_defaults
printer_redirection
Related information
To add a configuration file


List of Run-time Tunables

Restriction: These tunables are supported for native COBOL only.
  • acu_library
    Loads 'aculibs', the ACUCOBOL-GT compatibility module.
  • ansi_input_mode
    Specifies whether the run-time system uses ANSI or OEM character sets when inputting keystrokes from a console or Application Output window.
  • arguments_are_initial
    Affects the COBOL command line arguments returned from the syntax ACCEPT ... FROM ARGUMENT-NUMBER and ACCEPT ... FROM ARGUMENT-VALUE.
  • cobconfig_error_report
    Specifies whether any errors detected during the processing of the configuration file are reported.
  • command_line_accept
    Specifies whether the first ACCEPT or READ from STDIN takes the input from the command line.
  • command_line_linkage
    Enables you to call a program and pass the command line to the main program as a parameter to be accessed via the Linkage Section.
  • core_filename
    Specifies the name of the file that is generated when the core_on_error tunable is set to 3.
  • core_on_error
    Specifies in what circumstances a core file is produced.
  • current_day
    Specifies the day of the month required to be returned when the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function is used.
  • current_hour
    Specifies the hour of the day that is to be returned when the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function is used.
  • current_minute
    Specifies the minute of the hour that is to be returned when the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function is used.
  • current_month
    Specifies the month of the year required to be returned when the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function is used.
  • current_second
    Specifes the second of the minute that is to be returned when the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function is used.
  • current_year
    Specifies the year required to be returned when the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function is used.
  • datewarp_dynamic
    Specifies whether the day, month, and year values specified by the current_day, current_month, and current_year tunables return static or "rolling" values.
  • debug_on_error
    Specifies whether to enable just-in-time debugging.
  • default_cancel_mode
    Specifies whether logical or physical cancels are used.
  • device_name_detection
    Specifies whether programs can use filenames that are normally reserved for device-names.
  • entry_point_mapper
    Specifies whether entry point mapper support is to be enabled.
  • entry_point_mapper_alias_exists_error
    Specifies whether the Entry Point Mapping facility causes a run-time system error COBRT198 ("Load failure") when a program with the same name as an alias definition is found on disk, or whether the aliasing occurs without loading the program with the same name from disk.
  • entry_point_mapper_search_order
    Specifies whether to use entry point mapping to look for programs before or after searching for the programs on disk.
  • environment_mapper
    Specifies whether the External File Mapper is enabled. The External File Mapper allows you to assign values to environment variables in a file. If the External File Mapper is enabled the system searches for the file mfextmap.dat.
  • error_on_duplicate_entry_point
    Controls whether an RTS 119 error is generated when an attempt is made to load a program containing a duplicate entry-point.
  • faultfind_config
    Controls the inclusion of program memory data in the Faultfinder output file.
  • faultfind_level
    Specifies whether FaultFinder is enabled. FaultFinder enables you to get information on unexpected program termination at run time.
  • faultfind_outfile
    Specifies the file to which a FaultFinder report is written.
  • faultfind_recsize
    Specifies the internal cache size used to store FaultFinder trace operations.
  • lock_mode
    Selects the locking implementation to be used.
  • mainframe_floating_point
    Specifies whether mainframe floating-point emulation is required.
  • memory_free_check_size
    Specifies the number of freed memory blocks that are to be monitored for subsequent corruption.
  • memory_strategy
    Sets a memory management strategy.
  • mfpm_access_cancelled_data
    Specifies whether the Working-Storage Sections of AMODE programs that have been canceled continue to be addressable.
  • mfpm_external_data31
    Specifies whether external data items are registered with Mainframe Pointer Manager (MFPM) above or below the 16 Mb line.
  • mfpm_logging
    Specifies whether Mainframe Pointer Manager (MFPM) events are to be traced.
  • no_mfredir
    Enables you to reduce the time the run-time system takes to initialize if your project or application does not execute remote programs.
  • os_error_log
    Specifies whether an event is written to the Windows Application Event log whenever run-time system error COBRT199 occurs.
  • printer_defaults
    Sets certain default printer settings when printer redirection has been enabled.
  • printer_raw_redirection
    Redirects WRITE statements through the Windows print spooler as RAW data types.
  • printer_redirection
    Redirects WRITE statements through the Windows print spooler.
  • profile_behavior
    Specifies the behavior of the Profiler with regard to the counting of time spent in called programs.
  • screen_cols
    Specifies the initial width of the Application Output window or console.
  • screen_lines
    Specifies the initial height of the Application Output window or console.
  • shared_memory_segment_size
    Specifies the initial size of the shared memory block allocated by the run-time system.
  • signal_regime
    Specifies whether or not the run-time system is to use its own signal handlers.
  • subsystem_cancel_mode
    Specifies whether logical or physical cancels are used for CBL_SUBSYSTEM cancels.
  • timewarp_dynamic
    Specifies whether the hours, minutes, and seconds values specified by the current_hour, current_minute, and current_second tunables return static or "rolling" values.
Parent topic: Run-time Tunables


acu_library

Loads 'aculibs', the ACUCOBOL-GT compatibility module.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-------acu_library=--.-TRUE-.---------><
                       +-FALSE+

Aculibs provides certain functionality for ACUCOBOL-GT compatibility. It provides C$RERR, the library routine for obtaining extended error information from file operations, and a number of external variables (F-ERRNO, F-INT-ERRNO, F-INT2-ERRNO, F-ERRMSG) containing other error information.

Parameters:

TRUE | Aculibs functionality is enabled
FALSE | Aculibs functionality is not enabled

Properties:

Default: | FALSE
IDE equivalent: | None

Comments:

External variables can provide additional information in troubleshooting situations. For example, if a database returns an error that does not map to one of the standard COBOL errors (record locked, duplicate key, etc.), the external variables F-ERRNO, F-INT-ERRNO, F-INT2-ERRNO and F-ERRMSG will contain extra information. Typically, F-ERRNO will be E_INTERNAL (which has a value of 15). F-INT-ERRNO and F-INT2-ERRNO will be the error values returned by the database, and F-ERRMSG will point to a text message returned by the database.

Add the following external declarations to working-storage:

01 F-INT-ERRNO BINARY-LONG SIGNED EXTERNAL.
01 F-INT2-ERRNO BINARY-LONG SIGNED EXTERNAL.
01 F-ERRMSG POINTER EXTERNAL.
77 F-ERRNO BINARY-SHORT SIGNED EXTERNAL.
Note: Refer to the COBOL COPY file filesys.def for the error value definitions.
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


ansi_input_mode

Specifies whether the run-time system uses ANSI or OEM character sets when inputting keystrokes from a console or Application Output window.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set ansi_input_mode=----.-TRUE-.---------><
                               +-FALSE+

Parameters:

TRUE | Use the ANSI character set to input keystrokes
FALSE | Use the OEM character set to input keystrokes

Properties:

Default: | FALSE
IDE equivalent: | None

Comments:

Using ANSI enables characters such as the Euro symbol, which does not exist in the OEM character set, to be input and displayed.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


arguments_are_initial

Affects the COBOL command line arguments returned from the syntax ACCEPT ... FROM ARGUMENT-NUMBER and ACCEPT ... FROM ARGUMENT-VALUE.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set arguments_are_initial=---.-TRUE-.-------------><
                                    +-FALSE+

Parameters:

TRUE | The COBOL command line arguments are the same as the initial ones passed to the run-unit by the operating system. When using a trigger, such as run , argument 0 is the trigger name and argument 1 is the name of the main COBOL program.
FALSE | The COBOL command line arguments do not contain any trigger name. Instead, argument 0 is always the name of the main COBOL program. When set to FALSE this tunable gives consistent results no matter how your application is packaged.

Properties:

Default: | FALSE
IDE equivalent: | None

Comments:

See the Language Reference for more details of the ACCEPT ... FROM ARGUMENT-NUMBER and ACCEPT ... FROM ARGUMENT-VALUE syntax.

If you are using a system executable to start your application, argument 0 is always the name of the executable (which, by default, is also the name of the main COBOL program), irrespective of the setting of this tunable.

For example, the command line:

myapp arg1 arg2

always returns myapp as argument 0, whereas the command line:

run myapp arg1 arg2

returns myapp as argument 0 when this tunable is set to FALSE; when the tunable is set to TRUE the trigger name ( run ) is returned as argument 0 and myapp as argument 1.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


cobconfig_error_report

Specifies whether any errors detected during the processing of the configuration file are reported.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set cobconfig_error_report=----.-TRUE-.----><
                                      +-FALSE+

Parameters:

TRUE | Errors are reported and result in processing of the configuration file being terminated
FALSE | Errors are not reported

Properties:

Default: | TRUE
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


command_line_accept

Specifies whether the first ACCEPT or READ from STDIN takes the input from the command line.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set command_line_accept=---.-TRUE-.-------------><
                                  +-FALSE+

Parameters:

TRUE | The first ACCEPT or READ from STDIN takes the input from the command line.
FALSE | The first ACCEPT or READ from STDIN takes the input from the user. This provides direct ANSI conformance.

Properties:

Default: | FALSE
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
command_line_linkage


command_line_linkage

Enables you to call a program and pass the command line to the main program as a parameter to be accessed via the Linkage Section.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set command_line_linkage=---.-TRUE-.------><
                                   +-FALSE+

Parameters:

TRUE | The command line can be accessed via the Linkage Section
FALSE | The command line cannot be accessed via the Linkage Section

Properties:

Default: | FALSE
IDE equivalent: | None

Comments:

This run-time tunable is provided for backward compatibility only. It works only with linked executables.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
command_line_accept


current_day

Specifies the day of the month required to be returned when the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function is used.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set current_day=---integer------><

Parameters:

integer A value in the range 1 through 31, representing the required day of the month. The value you specify is returned when you use the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function.

Properties:

Default: | The current day specified by the system clock.
IDE equivalent: | None

Comments:

If the datewarp_dynamic tunable is set to TRUE, the day value specified is treated as the day the clock is started, and changes each time the system clock passes midnight.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
current_hour
current_minute
current_month
current_second
current_year
datewarp_dynamic
timewarp_dynamic


current_hour

Specifies the hour of the day that is to be returned when the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function is used.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set current_hour=---integer-------------><

Parameters:

integer A value from 0 - 23 indicating the required hour of the day. The value you specify is returned when you use the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function

Properties:

Default: | The current hour as returned by the system clock.
IDE equivalent: | None

Comments:

If the timewarp_dynamic tunable is set to TRUE, the hour value specified is treated as the hour at which the clock is started, and will change every 60 minutes.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
current_day
current_minute
current_month
current_second
current_year
datewarp_dynamic
timewarp_dynamic


current_minute

Specifies the minute of the hour that is to be returned when the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function is used.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set current_minute=---integer-------------><

Parameters:

integer A value from 0 - 59 indicating the required minute of the hour. The value you specify is returned when you use the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function.

Properties:

Default: | The current minute as returned by the system clock.
IDE equivalent: | None

Comments:

If the timewarp_dynamic tunable is set to TRUE, the minute value specified is treated as the minute at which the clock is started, and will change every 60 seconds.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
current_day
current_hour
current_month
current_second
current_year
datewarp_dynamic
timewarp_dynamic


current_month

Specifies the month of the year required to be returned when the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function is used.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set current_month=---integer------><

Parameters:

integer A value in the range 1 through 12, representing the required month of the year. The value you specify is returned when you use the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function.
Note: A leading 0 indicates to the system that the value should be treated as octal. As a result, month values of 08 and 09 generate an error. For the months of September and October, use 8 and 9 rather than 08 and 09.

Properties:

Default: | The current month specified by the system clock.
IDE equivalent: | None

Comments:

None

If the datewarp_dynamic tunable is set to TRUE, the month value specified is treated as the month the clock is started, and changes when the system clock passes midnight on the last day of each month.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
current_day
current_hour
current_minute
current_second
current_year
datewarp_dynamic
timewarp_dynamic


current_second

Specifes the second of the minute that is to be returned when the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function is used.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set current_second=---integer-------------><

Parameters:

integer A value from 0 - 59 indicating the required second of the minute. The value you specify is returned when you use the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function

Properties:

Default: | The current second as returned by the system clock.
IDE equivalent: | None

Comments:

If the timewarp_dynamic tunable is set to TRUE, the second value specified is treated as the second at which the clock is started, and will change as the system clock changes.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
current_day
current_hour
current_minute
current_month
current_year
datewarp_dynamic
timewarp_dynamic


current_year

Specifies the year required to be returned when the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function is used.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set current_year=---integer------><

Parameters:

integer A value representing the required year. The value you specify is returned when you use the ACCEPT identifier FROM DATE or ACCEPT identifier FROM DAY syntax or the CURRENT-DATE intrinsic function.

Properties:

Default: | The current year specified by the system clock.
IDE equivalent: | None

Comments:

If the datewarp_dynamic tunable is set to TRUE, the year value specified is treated as the year the clock is started and changes each time midnight passes on December 31st.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
current_day
current_hour
current_minute
current_month
current_second
datewarp_dynamic
timewarp_dynamic


datewarp_dynamic

Specifies whether the day, month, and year values specified by the current_day, current_month, and current_year tunables return static or "rolling" values.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set datewarp_dynamic=---.-TRUE-.-------------><
                               +-FALSE+

Parameters:

TRUE | The day, month, and year values specified for the current_day, current_month and current_year tunables are treated as the clock start values and will "roll" once they have been set.
FALSE | The day, month, and year values specified for the current_day, current_month, and current_year tunables are static values that will always be returned when the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function is used.

Properties:

Default: | FALSE
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
current_day
current_hour
current_minute
current_month
current_second
current_year
timewarp_dynamic


debug_on_error

Specifies whether to enable just-in-time debugging.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set debug_on_error=---.-0-.-----------><
                             +-1-+

Parameters:

0 | Disables just-in-time debugging.
1 | Enables just-in-time debugging: the Debugger starts if a running program terminates with a run-time system error.

Properties:

Default: | 0
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
core_on_error
signal_regime


default_cancel_mode

Specifies whether logical or physical cancels are used.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set default_cancel_mode---.-0-.-----------><
                                 +-1-+

Parameters:

0 | Physical cancels: any program canceled during run time will be freed from memory, making more memory available.
1 | Logical cancels: any program canceled during run time will not be freed from memory. The program is available to be reused and hence the performance of CALL/CANCEL statements is greatly increased.

As far as your program is concerned, the behavior of logical and real cancels is identical.

Properties:

Default: | 1
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


device_name_detection

Specifies whether programs can use filenames that are normally reserved for device-names.
Note: Restriction:

These tunables are supported for native COBOL only.

Syntax:

>>-----set device_name_detection=---.-TRUE-.------><
                                    +-FALSE+

Parameters:

TRUE | The run-time system treats certain predefined names (such as ERR) as device-names.
FALSE | No predefined device-names are used by the run-time system.

Properties:

Default: | TRUE
IDE equivalent: | None

Comments:

When you set device_name_detection=TRUE, the run-time system treats the following as device-names, so they cannot be used as filenames in your programs:

  • :BB
  • :CE
  • :CI
  • :CO
  • :LP
  • AUX
  • COM<n>
  • CON
  • ERR
  • LPT
  • LPT<n>
  • LST
  • NUL
  • PRN
  • PUN
  • RDR
  • STDERR
  • STDIN
  • STDOUT
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


entry_point_mapper

Specifies whether entry point mapper support is to be enabled.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set entry_point_mapper=---.-TRUE-.-------------><
                                 +-FALSE+

Parameters:

TRUE | Enable entry point mapper support.
FALSE | Disable entry point mapper support.

Properties:

Default: | FALSE
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related concepts
Entry Point Mapping for COBOL Programs
Related tasks
Run-time Configuration Tunables - Overview
Related reference
entry_point_mapper_alias_exists_error
entry_point_mapper_search_order


entry_point_mapper_alias_exists_error

Specifies whether the Entry Point Mapping facility causes a run-time system error COBRT198 ("Load failure") when a program with the same name as an alias definition is found on disk, or whether the aliasing occurs without loading the program with the same name from disk.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set entry_point_mapper_alias_exists_error=---.-TRUE-.-------------><
                                                    +-FALSE+

Parameters:

TRUE | Run-time system error COBRT198 occurs when a program with the same name as an alias definition occurs on disk.
FALSE | Aliasing occurs without loading the program with the same name from disk.

Properties:

Default: | TRUE
IDE equivalent: | None

Comments:

This tunable is only relevant if the entry_point_mapper_search_order tunable is set to 1; that is, pre-disk searching is enabled.

Parent topic: List of Run-time Tunables
Related concepts
Entry Point Mapping for COBOL Programs
Related tasks
Run-time Configuration Tunables - Overview
Related reference
entry_point_mapper
entry_point_mapper_search_order


entry_point_mapper_search_order

Specifies whether to use entry point mapping to look for programs before or after searching for the programs on disk.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set entry_point_mapper_search_order=---.-0-.-----------><
                                              +-1-+

Parameters:

0 | Programs are looked for on disk before using entry point mapping.
1 | Programs are looked for using entry point mapping before looking on disk.

Properties:

Default: | 0
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related concepts
Entry Point Mapping for COBOL Programs
Related tasks
Run-time Configuration Tunables - Overview
Related reference
entry_point_mapper
entry_point_mapper_alias_exists_error


environment_mapper

Specifies whether the External File Mapper is enabled. The External File Mapper allows you to assign values to environment variables in a file. If the External File Mapper is enabled the system searches for the file mfextmap.dat.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set environment_mapper=---.-TRUE-.-------><
                                 +-FALSE+

Parameters:

TRUE | The External File Mapper is enabled
FALSE | The External File Mapper is not enabled.

Properties:

Default: | FALSE
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


error_on_duplicate_entry_point

Controls whether an RTS 119 error is generated when an attempt is made to load a program containing a duplicate entry-point.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set error_on_duplicate_entry_point =---.-TRUE-.------><
                                              +-FALSE+

Parameters:

TRUE | Force an RTS 119 error to be generated when loading a duplicate entry point.
FALSE | Silently ignore duplicate entry-points.

Properties:

Default: | FALSE
Setting: | None

Example:

If program A is loaded and contains entry-point ENTA, and then program B is loaded which also contains entry-point ENTA, the RTS can either issue an RTS 119 error ("Symbol redefined") when it encounters ENTA in program B, or silently ignore it.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


faultfind_config

Controls the inclusion of program memory data in the Faultfinder output file.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set faultfind_config=----integer---------><

Parameters:

integer The action to perform and the type of memory as follows:

These values can be combined to suppress combinations of types of memory, for example, a value of 5 will suppress working storage and dynamically allocated memory from being included.

0 | Include all types of memory (default)
1 | Exclude working storage
2 | Exclude thread-local storage
4 | Exclude dynamically allocated memory
Default: | 0
IDE equivalent: | None

Properties:

Default: | 0
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
faultfind_level
faultfind_outfile
faultfind_recsize
Related information
FaultFinder Tunables


faultfind_level

Specifies whether FaultFinder is enabled. FaultFinder enables you to get information on unexpected program termination at run time.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set faultfind_level=----integer---------><

Parameters:

integer Any positive value up to 100,000. Specifying this tunable turns on FaultFinder. The last integer events are dumped to a FaultFinder report if abnormal application termination occurs. The greater the value of integer, the more memory is used.

Properties:

Default: | 0 (off)
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
faultfind_config
faultfind_outfile
faultfind_recsize
Related information
FaultFinder Tunables


faultfind_outfile

Specifies the file to which a FaultFinder report is written.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set faultfind_outfile--=----"[>>]filename"----><

Parameters:

filename The file to which a FaultFinder report is written. If you specify >>, the output is appended to filename, if it already exists, otherwise a new file named filename is created. If filename contains the string %p, this string is replaced by the process ID of the program that started FaultFinder.

Properties:

Default: | fltfnd_out.pid, in the current working directory, where pid is the process ID of the process that triggered the FaultFinder output.
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
faultfind_config
faultfind_level
faultfind_recsize
Related information
FaultFinder Tunables


faultfind_recsize

Specifies the internal cache size used to store FaultFinder trace operations.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set faultfind_recsize=---rec_size--------><

Parameters:

rec_size A numeric value, in bytes, that specifies the internal cache size used to store read/write data for the operation traceback log. All read/write data is stored and reported. By using this tunable you might improve performance. The maximum value is 1024.

Properties:

Default: | 64
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
faultfind_config
faultfind_level
faultfind_outfile
Related information
FaultFinder Tunables


lock_mode

Selects the locking implementation to be used.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set lock_mode=---.-0-.-----------><
                        +-1-+
                        +-2-+

Parameters:

0 | Uses the locking mechanism provided by Micro Focus COBOL V3.1 and earlier versions.
1 | Provides compatibility with DOS and OS/2 locking mechanisms.
2 | Provides interlanguage locking. This method causes record locks to lock the physical record.

Properties:

Default: | 1
IDE equivalent: | None

Comments:

This tunable is only applicable if the File Handler configuration option FILEMAXSIZE is set to 4.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


mainframe_floating_point

Specifies whether mainframe floating-point emulation is required.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set mainframe_floating_point=---.-TRUE-.-------------><
                                       +-FALSE+

Parameters:

TRUE | Mainframe floating-point emulation is required.
FALSE | Mainframe floating-point emulation is not required.

Properties:

Default: | FALSE
IDE equivalent: | None

Comments:

Specifying this tunable has the same effect as specifying the MAINFRAME_FLOATING_POINT environment variable. If both are specified, the setting of the MAINFRAME_FLOATING_POINT environment variable overrides the setting of the mainframe_floating_point tunable.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


memory_free_check_size

Specifies the number of freed memory blocks that are to be monitored for subsequent corruption.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set memory_free_check_size=---freed-memory-blocks------><

Parameters:

freed-memory-blocks A numeric value defining the number of freed memory blocks to monitor

Properties:

Default: | 100
IDE equivalent: | None

Comments:

You should use this tunable in conjunction with the check freed memory and reuse freed memory strategies offered by the memory_strategy tunable.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
memory_strategy


memory_strategy

Sets a memory management strategy.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set memory_strategy=---strategy-specification------><

Parameters:

strategy-specification A numeric value representing one or more of the following flags (see Comments for information about valid combinations):
0x00000001
Check bytes strategy: prepend and append check bytes to each memory allocation
0x00000002
Check freed memory strategy: monitor for subsequent corruption the last n memory blocks freed, where n is the current value set using the memory_free_check_size run-time tunable
0x00000004
Reuse strategy: allow freed memory being monitored for corruption to be used to satisfy allocation requests
0x40000000
Compatibility strategy: maintain compatibility with previous versions of the run-time system
0x80000000
Validate strategy: validate memory each time an allocation or free operation occurs

Properties:

Default: | 0x00000001
IDE equivalent: | None

Comments:

You can use this tunable to enable a process to be executed with one or more memory management strategies in place. For example, to specify that each memory allocation made by the run-time system is to have check bytes prepended and appended, and that each time an allocation or free operation takes place memory is to be validated, you would set the tunable as follows:

set memory_strategy=0x80000001

Only certain combinations of strategies are valid:

  • Check bytes, check freed memory, reuse and validate can be used together in any combination.
  • Compatibility can be used only with validate.

When the check bytes memory management strategy is in place, and the run-time system receives a request to free a memory block, the run-time system checks that the check bytes have not been corrupted, and then releases the memory. A corruption occurs when a program has written past the end of another memory block into the header of this one, or a program has written past the end of this memory block. If the run-time system detects a corruption, it issues run-time system error COBRT252 indicating the memory block address and type of memory that has been corrupted, for example:

Execution error: file 'MYFILE'
error code: 252, pc=0, call=1, seg=0
252 Memory corruption detected (addr=00376068, type=136/1)

When the check freed memory strategy is in place, and the run-time system receives a request to free a memory block, the run-time system does not release the memory, but instead:

  • Clears the contents of the memory block to a predefined check value
  • Stores a reference to the block. The run-time tunable memory_free_check_size defines how many blocks the run-time system handles. If the limit has been reached, the run-time system:
    1. Validates the contents of the memory pointed to by the oldest entry stored. If the validation fails (that is, the memory does not contain the expected check value), the run-time system issues run-time system error COBRT252.
    2. Frees the memory pointed to by the oldest entry stored.

You should use the check freed memory strategy strategy with caution as it can lead to memory fragmentation and a significantly larger memory footprint for the process than would normally be expected.

You can use the reuse memory management strategy in conjunction with the check freed memory strategy to allow freed memory to be used to satisfy new allocation requests. When the reuse strategy is in effect and the run-time system needs to allocate a new block of memory, it first checks whether an area of freed memory will satisfy the allocation request. An allocation request will be satisfied from freed memory only if the size and type of the freed memory exactly match the size and type of the allocation request. When an allocation request is satisfied from freed memory, the run-time system first validates the contents of the freed memory. If the validation fails (that is, the memory does not contain the expected check value), the run-time system issues run-time system error COBRT252.

The compatibility memory strategy is provided to give compatibility with the memory management provided in earlier versions of the run-time system. If this strategy is specified, all other strategies except validation are ignored. This strategy does not perform any memory validation or tracking, and silently ignores any memory chaining errors it encounters if an attempt is made to free a memory block more than once.

The validation memory management strategy causes all memory allocations previously made by the run-time system using the check bytes memory management strategy and all freed memory to be validated each time the run-time system is requested to perform a memory allocate or free operation. Additionally, if the operating system allows it, an operating-system memory heap validation check is performed. You should use this strategy with caution since it will lead to a major performance degradation in those applications that perform a large number of memory allocate and free operations.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
memory_free_check_size


mfpm_access_cancelled_data

Specifies whether the Working-Storage Sections of AMODE programs that have been canceled continue to be addressable.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set mfpm_access_cancelled_data=---.-TRUE-.-------------><
                                         +-FALSE+

Parameters:

TRUE | The Working-Storage Sections of AMODE programs are addressable after they have been canceled.
FALSE | The Working-Storage Sections of AMODE programs are not addressable after they have been canceled.

Properties:

Default: | FALSE
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
mfpm_external_data31
mfpm_logging


mfpm_external_data31

Specifies whether external data items are registered with Mainframe Pointer Manager (MFPM) above or below the 16 Mb line.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set mfpm_external_data31=---.-TRUE-.-------------><
                                   +-FALSE+

Parameters:

TRUE | External data items are registered with Mainframe Pointer Manager above the 16 Mb line, making them addressable to only AMODE(31) programs.
FALSE | External data items are registered with Mainframe Pointer Manager below the 16 Mb line, making them addressable to both AMODE(24) and AMODE(31) programs.

Properties:

Default: | FALSE
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
mfpm_access_cancelled_data
mfpm_logging


mfpm_logging

Specifies whether Mainframe Pointer Manager (MFPM) events are to be traced.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set mfpm_logging(option)=---.-TRUE-.-------><
                                   +-FALSE+

Parameters:

option
0
Mainframe Pointer Manager events and address map are traced.
1
Mainframe Pointer Manager events are traced.
2
Mainframe Pointer Manager address map is traced.
Default: | 0
IDE equivalent: | None

Properties:

Default: | 0
IDE equivalent: | None

Comments:

Mainframe Pointer Manager logging is performed using the Consolidated Tracing Facility (CTF). Setting this tunable implicitly sets the mf.rts#mfpm Consolidated Tracing Facility property, and the Consolidated Tracing Facility trace level to "info" if not already set.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
mfpm_access_cancelled_data
mfpm_external_data31


no_mfredir

Enables you to reduce the time the run-time system takes to initialize if your project or application does not execute remote programs.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set no_mfredir=---.-TRUE-.-------------><
                         +-FALSE+

Parameters:

TRUE | The run-time system initializes without searching for the optional module _MFREDIR.
FALSE | The run-time system searches for _MFREDIR when initializing.

Properties:

Default: | FALSE
IDE equivalent: | None

Comments:

The _MFREDIR module is only required to enable remote program execution. As most applications do not require remote program execution, _MFREDIR rarely exists resulting in many unnecessary lookups being made in the folders on the application and system search paths.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


os_error_log

Specifies whether an event is written to the Windows Application Event log whenever run-time system error COBRT199 occurs.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set os_error_log=---.-TRUE-.-------------><
                           +-FALSE+

Parameters:

TRUE | An event is written to the Windows Application Event log whenever run-time system error COBRT199 occurs. This was the behavior in previous versions of this COBOL system.
FALSE | An event is not written to the Windows Application Event log whenever run-time system error COBRT199 occurs.

Properties:

Default: | FALSE
IDE equivalent: | None

Comments:

Regardless of the setting of os_error_log, a Consolidated Tracing Facility warning event can be generated whenever run-time system error COBRT199 occurs. See the help for the COBRT199 message for information on configuring Consolidated Tracing Facility to enable this.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


printer_defaults

Sets certain default printer settings when printer redirection has been enabled.
Note: This tunable is supported for .NET COBOL only.

Set these details in a configuration file, in Visual Studio.

Syntax:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
 <configSections>

  <sectionGroup name="MicroFocus.COBOL.Runtime">
   <section name="Tunables" type="System.Configuration.NameValueSectionHandler" />
   <section name="Switches" type="System.Configuration.NameValueSectionHandler" />
  </sectionGroup>
</configSections>

 <MicroFocus.COBOL.Runtime>
  <Tunables>
   <add key="printer_redirection" value="true" />
   <add key="printer_defaults" value="size=20;font=Courier New" />
  </Tunables>
  <Switches></Switches>
 </MicroFocus.COBOL.Runtime>
</configuration>

Parameters:

Font
Name of the font
Size
Size of the font
Title
A name for the spooler job
Printer
The name of the printer to use

Properties:

Default: | Not set
IDE equivalent: | None

Comments:

This tunable is dependent on printer redirection being on, which you can do by setting the printer_redirection tunable or by calling the PC_PRINTER_REDIRECTION_PROC routine.

Parent topic: List of Run-time Tunables
Related concepts
Format of a Configuration File for .NET COBOL
printer_redirection
Related tasks
Run-time Configuration Tunables - Overview
Related information
To add a configuration file


printer_raw_redirection

Redirects WRITE statements through the Windows print spooler as RAW data types.
Restriction: This tunable is supported for .NET COBOL only.

Syntax:

>>-----printer_raw_redirection=----.-TRUE-.-------><
                                   +-FALSE+

Parameters:

TRUE | Redirect WRITE statements to files defined with the ASSIGN TO PRINTER syntax through the Windows print spooler and process them as RAW data types.
FALSE | Output is sent through the printer driver or directly to the printer port; see printer_redirection.

Properties:

Default: | FALSE
IDE equivalent: | None
Parent topic: List of Run-time Tunables


printer_redirection

Redirects WRITE statements through the Windows print spooler.

The following details are for native COBOL only; for details of .NET COBOL, refer to the Comments section.

Syntax:

>>-----printer_redirection=----.-TRUE-.-------><
                               +-FALSE+

Parameters:

TRUE | Redirect WRITE statements to files defined with the ASSIGN TO PRINTER syntax through the Windows print spooler, rather than sending the output directly to the printer port.
FALSE | Output is sent directly to the printer port.

Properties:

Default: | FALSE
IDE equivalent: | None

Comments:

To configure this tunable for .NET COBOL, add a reference to a .config file in Visual Studio. Refer to Format of a Configuration File for .NET COBOL for details of the required syntax.

You can also set printer redirection by calling the PC_PRINTER_REDIRECTION_PROC routine.

Parent topic: List of Run-time Tunables
Related concepts
Format of a Configuration File for .NET COBOL
printer_defaults
Related tasks
Run-time Configuration Tunables - Overview
Related information
To add a configuration file
The File Control Entry


profile_behavior

Specifies the behavior of the Profiler with regard to the counting of time spent in called programs.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set profile_behavior=---.-0-.-----------><
                               +-1-+

Parameters:

0 | Time spent in a called program is counted both in the called program and in the calling program.
1 | Time spent in a called program is counted only in the called program.

Properties:

Default: | 0
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related information
Introduction to Profiler


screen_cols

Specifies the initial width of the Application Output window or console.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set screen_cols=----integer--------------><

Parameters:

integer A value in the range 0 through 132 indicating the width of the Application Output window or console.

Properties:

Default: | For console windows, the current screen width as returned by the operating system; for the Application Output window, 80.
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


screen_lines

Specifies the initial height of the Application Output window or console.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set screen_lines=----integer------------><

Parameters:

integer A value in the range 0 through 60 indicating the height of the Application Output window or console.

Properties:

Default:
  • For console windows, the current screen height as returned by the operating system
  • 25 for the Application Output window
  • 43 if COBSW=C4 is set
  • 50 if COBSW=C5 is set
IDE equivalent: None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


shared_memory_segment_size

Specifies the initial size of the shared memory block allocated by the run-time system.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set shared_memory_segment_size=---integer-----------><

Parameters:

integer Specifies the initial size of the shared memory block allocated by the run-time system, in bytes. The minimum value you can specify is 8192 (8 K).

Properties:

Default: | 65536 (64 K)
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview


signal_regime

Specifies whether or not the run-time system is to use its own signal handlers.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set signal_regime(sig)=integer---------><

or

>>-----set signal_regime=1---------><

Parameters:

sig The number of the signal, between 1 and the maximum signal number on your operating system. See your operating system documentation for details on signal numbers.
integer The action the run-time system is to take for the signal sig. integer can take one of the following values:
0 - The signal sig is used if needed
By default, the run-time system sets up signal handlers for all signals whose operating system default action would cause termination. The run-time system can thus catch these signals and tidy up (for example, close any open files to prevent file corruption) before exiting.
1 - The signal sig is used only if a handler was not already posted for this signal
This is useful if the third-party software is invoked before your COBOL system and sets up a handler for signal sig. If this tunable is not set for this signal, the run-time system overwrites the third-party software's handler with its own; this leads to unpredictable behavior, such as run-time system error COBRT115 ("Unexpected signal") being produced.

If a handler was posted, the run-time system will not post any handlers for this signal and so any run-time system functionality which relies on this signal will not work.

2 - The signal sig is used
This is only of use if the third-party software is invoked after the run-time system and sets up a handler for signal sig. Use of this setting is strongly discouraged for any signal whose operating system default action is to cause termination; if this signal is received between the run-time system being invoked and the third-party software setting up its handler, the default action of the operating system occurs, and the process exits without the run-time system being able to tidy up. This could lead to problems such as file corruption.

Any run-time system functionality which relies on this signal will not work.

Properties:

Default: | 0 for all signals
IDE equivalent: | None

Comments:

If you use the alternative syntax (set signal_regime=1), the signal regime for all signals is set to 1.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
core_on_error
debug_on_error
cobpostsighandler
cobremovesighandler
Related information
Signal Handling Overview
Third Party Software that Uses Signals


subsystem_cancel_mode

Specifies whether logical or physical cancels are used for CBL_SUBSYSTEM cancels.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set subsystem_cancel_mode=--.-0-.-----------><
                                   +-1-+

Parameters:

0 | Physical cancels: any program canceled with a CBL_SUBSYSTEM cancel will be freed from memory, making more memory available.
1 | Logical cancels: any program canceled with a CBL_SUBSYSTEM cancel will not be freed from memory. The programs are available to be reused and hence the performance of CALL/CANCEL statements is greatly increased.

Properties:

Default: | 0
IDE equivalent: | None

Comments:

As far as your program is concerned, the behavior of logical and physical cancels is identical.

Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
CBL_SUBSYSTEM


timewarp_dynamic

Specifies whether the hours, minutes, and seconds values specified by the current_hour, current_minute, and current_second tunables return static or "rolling" values.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set timewarp_dynamic=---.-TRUE-.-------------><
                               +-FALSE+

Parameters:

TRUE | The hours, minutes, and seconds values specified for the current_hour, current_minute and current_second tunables are treated as clock start values and will "roll" once they have been set.
FALSE | The hours, minutes, and seconds values specified for the current_hour, current_minute and current_second tunables are static values that will always be returned when the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function is used.

Properties:

Default: | FALSE
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related tasks
Run-time Configuration Tunables - Overview
Related reference
current_day
current_hour
current_minute
current_month
current_second
current_year
datewarp_dynamic


Deployment

  • Deploying Native COBOL Applications
Parent topic: Micro Focus Visual COBOL for Visual Studio 2010


Copyright and Legal Information

  • Copyright and Trademarks
Parent topic: Micro Focus Visual COBOL for Visual Studio 2010


Copyright and Trademarks

Copyright © Micro Focus 1984-2012. All rights reserved. The software and information contained herein are proprietary to, and comprise valuable trade secrets of, Micro Focus, which intends to preserve as trade secrets such software and information. This software is an unpublished copyright of Micro Focus and may not be used, copied, transmitted, or stored in any manner. This software and information or any other copies thereof may not be provided or otherwise made available to any other person.

Micro Focus has made every effort to ensure that this book is correct and accurate, but reserves the right to make changes without notice at its sole discretion at any time. The software described in this document is supplied under a license and may be used or copied only in accordance with the terms of such license, and in particular any warranty of fitness of Micro Focus software products for any particular purpose is expressly excluded and in no event will Micro Focus be liable for any consequential loss.

Micro Focus, the Micro Focus Logo, Micro Focus Server, Micro Focus Studio, Net Express, Net Express Academic Edition, Net Express Personal Edition, Server Enterprise Edition, Server Express, Mainframe Express, Animator, Application Server, AppMaster Builder, APS, Data Express, Enterprise Server, Enterprise View, EnterpriseLink, Object COBOL Developer Suite, Revolve, Revolve Enterprise Edition, SOA Express, Visual COBOL, Unlocking the Value of Legacy, and XDB are trademarks or registered trademarks of Micro Focus IP Development Limited in the United Kingdom, the United States and other countries.

IBM®, z/OS®, CICS® and RACF® are registered trademarks, and IMS™ is a trademark, of International Business Machines Corporation.

License management is based on SentinelRMS © 1989-2006 SafeNet, Inc. All rights reserved. Sentinel is a registered trademark of SafeNet, Inc.

Portions of some programming examples were produced by Dr. Frank McCown, Harding University Computer Science Dept and are licensed under a Creative Commons License.

All other trademarks are the property of their respective owners.

Reference to third party companies, products and web sites is for information purposes only and constitutes neither an endorsement nor a recommendation. Micro Focus provides this information only as a convenience to users. Micro Focus makes no representation whatsoever regarding the content of any other web site or the use of any such third party products. Micro Focus shall not be liable in respect of your use or access to such third party products/web sites.

No part of this publication, with the exception of the software product user documentation contained on a CD-ROM, may be copied, photocopied, reproduced, transmitted, transcribed, or reduced to any electronic medium or machine-readable form without prior written consent of Micro Focus. Contact your Micro Focus representative if you require access to the modified Apache Software Foundation source files.

Licensees may duplicate the software product user documentation contained on a CD-ROM, but only to the extent necessary to support the users authorized access to the software under the license agreement. Any reproduction of the documentation, regardless of whether the documentation is reproduced in whole or in part, must be accompanied by this copyright statement in its entirety, without modification.

U.S. GOVERNMENT RESTRICTED RIGHTS. It is acknowledged that the Software and the Documentation were developed at private expense, that no part is in the public domain, and that the Software and Documentation are Commercial Computer Software provided with RESTRICTED RIGHTS under Federal Acquisition Regulations and agency supplements to them. Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software clause at DFAR 252.227-7013 et. seq. or subparagraphs (c)(1) and (2) of the Commercial Computer Software Restricted Rights at FAR 52.227-19, as applicable. Contractor is Micro Focus, One Irvington Center, 700 King Farm Boulevard, Suite 400, Rockville, Maryland 20850. Rights are reserved under copyright laws of the United States with respect to unpublished portions of the Software.

Parent topic: Copyright and Legal Information


Notations and Conventions

COBOL Conventions
  • PIC X is used rather than PIC 99 with the COMP-X and COMP-5 data types. Unlike PIC 99, PIC X shows the length of the data item and so demonstrates more clearly the use of COMP-X, which is to define a binary item of the specified number of bytes.
Command Line Format
  • Words printed in italics are generic terms representing names to be devised by you.
  • Words printed in nonitalic characters are the actual words you must enter. You must type them in upper or lower case as shown.
  • Material enclosed in square brackets [ ] is optional.
  • When material is enclosed in braces { }, you must choose from the options within them. If there is only one option in the braces, the braces indicate repetition.
  • The ellipsis (. . .) follows { } or [ ] and means you can repeat the material in the { } or [ ]. The number of repetitions allowed is unlimited unless otherwise stated. If the ellipsis is used with [ ] the material can be omitted altogether.
  • If a command line does not fit across the page, it is continued on the next line; the continuation line is indented.
  • Command line options can be specified as /option or -option.
Keyboard Keys
  • Key names and menu choices are emboldened within the text.
  • Enter refers to the carriage return or Enter key. Where commands to be typed are shown, the Enter key is not explicitly shown; it is treated as implicit that Enter must be pressed at the end of the line.
  • The keys described in this book are not available in all environments. When there is a reference to use of a key such as a status or function key, this refers to the logical press and release of this key, rather than physical keystroke. If your environment does not support the key given, please refer to your accompanying Read Me for the equivalent key.
Numbers
  • Hexadecimal numbers are enclosed in quotation marks and preceded by a lower-case "x" or "h"; for example, x"9D", h"03FF". The "x" is used when the hexadecimal number represents a character string; the "h" when it represents a numerical value.
Path Specifications
  • All path specifications are based on installation to the default installation directory. If you have installed Visual COBOL to a non-default installation directory, adjust the path specifications accordingly.
  • All path specifications show default paths for installation on the Windows 7 operating system. If you have installed on an alternative operating system, adjust the path specifications accordingly.
  • All path specifications show the physical directory name. This might be different than the paths shown by default in the Windows Explorer address field. For example, a folder listed as Computer > (OS)C: > Users > Public > Public Documents, or something similar, in the Explorer address field usually describes a physical location of c:\users\public\documents. To see the physical location, click the address field in Explorer. You also see the physical path at a command prompt.
  • Some path specifications use an environment variable to represent dynamic drive and directory names. For example, if your %PUBLIC% environment variable is set to c:\users\public, then substitute c:\users\public in place of a %PUBLIC% specification in the documented path.
  • Some path specifications use the %ProgramFiles% environment variable to represent the drive and directory containing your program files for both 32-bit and 64-bit machines. If you are running on a 64-bit machine, resolve this to the value of the %ProgramFiles(x86)% environment variable.
User Interface
  • Menu choices, and UI control and field names are emboldened within the text.
  • In some environments, you might notice that what appears on your screen differs in minor ways (for example, version numbers) from that illustrated in this Help. This does not affect the operation of your software.
Parent topic: Micro Focus Visual COBOL for Visual Studio 2010


Better Method Overload in Managed COBOL

Suppose we have an argument list A with a set of argument types (A1, A2,…An) and two applicable method overloads Mp and Mq with parameter types (P1…Pn) and (Q1,…Qn), where if necessary the parameters have been converted to expanded form (see above).

Then, Mp is said to be a better method overload than Mq if both the following are true:

  • For each argument, the implicit conversion from Ax to Px is not worse than the conversion from Ax to Qx (see below for definition of better conversion)
  • There is at least one argument for which the conversion from Ax to Px is better than the conversion from Ax to Qx

Suppose we have two conversions, from type S to types T1 and T2, then T1 is the better conversion when T1 and T2 are as follows:

T1 is: And T2 is one of:
same as S anything
binary-char
  • binary-char unsigned
  • binary-short unsigned
  • binary-long unsigned
  • binary-double unsigned
binary-short
  • binary-short unsigned
  • binary-long unsigned
  • binary-double unsigned
binary-long
  • binary-long unsigned
  • binary-double unsigned
binary-double
  • binary-double unsigned

Otherwise neither conversion is better.


Implicit Conversion in Method Overloading in Managed COBOL

An implicit conversion exists from type S to type T if it is possible to assign an object of type S to an object of type T, with the equivalent of the following statement:

SET obj-T TO obj-S

The following types of implicit conversion are available:

Identity conversions

This simply means that S is the same type as T

Implicit numeric conversions

COBOL generally allows any numeric item to be assigned to any other, with any loss of data being the responsibility of the user. However, when determining if a conversion exists for the purposes of method overloading, we distinguish between proper conversions and truncation conversions. Proper conversions are those for which no loss of data magnitude should result, though even in this case precision can be lost when converting between fixed point and floating point.

For managed COBOL types, proper implicit conversions include:

binary-char
  • binary-short
  • binary-long
  • binary-double
  • float-short
  • float-long
  • decimal
binary-char unsigned

The same as binary-char, plus:

  • binary-short unsigned
  • binary-long unsigned
  • binary-double unsigned
binary-short
  • binary-long
  • binary-double
  • float-short
  • float-long
  • decimal
binary-short unsigned

The same as binary-short, plus:

  • binary-long unsigned
  • binary-double unsigned
binary-long
  • binary-double
  • float-short
  • float-long
  • decimal
binary-long unsigned

The same as binary-long, plus:

  • binary-double unsigned
binary-double
  • float-short
  • float-long
  • decimal
binary-double unsigned

The same as binary-double

character
  • binary-short unsigned
  • binary-long
  • binary-long unsigned
  • binary-double
  • binary-double unsigned
  • float-short
  • float-long
  • decimal
float-short
  • float-long
Implicit enumeration conversions

The value 0 may be converted to any enum type

Implicit reference conversions

If S and T are reference types, S may be assigned to T when:

  • Type S is derived (directly or indirectly) from type T. This includes the case where T is System.Object, since all types derive from that
  • Type S implements interface type T
  • If S is an array type with element type E1 and T is an array type with element type E2, then S can be assigned to T provided:
    • S and T have the same number of dimensions
    • Both E1 and E2 are reference types
    • An implicit conversion exists from E1 to E2
  • Any array type may be assigned to type System.Array in .NET COBOL
  • Any delegate type may be assigned to type System.Delegate
  • Null may be assigned to any reference type
Boxing conversions

Any value type can be converted to a System.Object, type by a process known as boxing. As part of this process the value is copied onto the object heap and a reference is created

Implicit constant expression conversions

Any numeric constant can be converted to any type capable of containing the full value of that constant. For instance the value 1 can be converted both to BINARY-CHAR UNSIGNED and to BINARY-CHAR.

User defined implicit conversions

A user defined implicit conversion consists of an optional implicit numeric conversion from S to S1 followed by the execution of a user defined implicit conversion operator resulting in T1, followed by another optional implicit numeric conversion to T. User defined implicit conversion operators are defined in COBOL with OPERATOR-ID IMPLICIT and result in methods with the name op_Implicit.

Related information
Type Compatibility of Managed COBOL with Other Managed Languages


Method Overloading in Managed COBOL

In managed COBOL, it is permissible (and very common practice) for a given class or interface to have multiple methods with the same name, which are distinguished from each other by having different signatures. The signature of a method is determined by the:

  • Number of parameters
  • Type of each parameter
  • Passing mode (BY VALUE, BY REFERENCE, or BY OUTPUT) of each parameter
  • Return type , which in .NET COBOL, this type may be System.Void, which represents a method with no RETURNING item

When code written in COBOL, or any other language, attempts to invoke a method in some class or interface, and more than one method with the given name exists, then a choice of the available methods is made. The choice is based on the number of parameters and the ‘best’ type match for the parameters (the precise definition of ‘best’ is complex and is treated later). If no method with a suitable signature can be found, a ‘method not found’ error results. If there is no method that provides a better match than all the other possible methods with this name, an ‘ambiguous match’ error is given.

Although the type of the RETURNING item is a part of the method's signature, the choice of method to be invoked is never based on the RETURNING type. This is different from .NET and JVM, which allow a class to have multiple methods that differ only by returning type. This is not generally good practice, and COBOL produces an error if it finds such multiple methods within a single class. The only time when such multiple methods can arise from a COBOL program is in the case of the explicit and implicit operators.

Related reference
The Operator-ID Paragraph


Method Signatures Defined by Managed COBOL Programs

The type of a COBOL parameter may be specified by:

  • Referencing the type explicitly in the PROCEDURE DIVISION phrase using the AS syntax
  • Declaring a linkage section item with a given type and referencing that linkage section item in the PROCEDURE DIVISION USING phrase

For REFERENCE and OUTPUT parameters, managed types are exposed directly as managed pointers to the corresponding managed type. COBOL data types that do not correspond to managed types (such as PIC X fields, groups, numeric fields other than BINARY-LONG and so on) are exposed as COBOL pointers (objects of type MicroFocus.COBOL.Program.Reference, in .NET COBOL).

For VALUE parameters, and RETURNING items, types are exposed as follows:

COBOL types: are exposed as:
Managed types | objects of the corresponding type
Numeric items with more than 19 decimal digit positions | MicroFocus.COBOL.Program.BigDecimal
Numeric items with implied decimal point, such as PIC 9(9)v99, all sizes | - System.Decimal in .NET COBOL
Unsigned numeric items with no implied decimal point: In .NET COBOL:
  • < 3 numeric digits - unsigned int8
  • < 5 numeric digits - unsigned int16
  • < 10 numeric digits - unsigned int32
  • < 19 numeric digits - unsigned int64

In JVM COBOL, they are exposed the same as signed numeric items.

Signed numeric items with no implied decimal point:
  • < 3 numeric digits - int8
  • < 5 numeric digits - int16
  • < 10 numeric digits - int32
  • < 19 numeric digits - int64
All other types PIC X, group and so on | string
Related information
Type Compatibility of Managed COBOL with Other Managed Languages


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

 device\library-name.lbr\filename.ext

Example

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

Related concepts
Filename Mapping
Related information
Defining Input and Output Files


General Open PL/I Issues

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. You should read the topic Open PL/I 8.1 for Windows before starting to use this feature.

Related information
PL/I Programming


Tour of the Visual Studio IDE for Visual COBOL

Guides you though the main features offered by Visual COBOL for Visual Studio.

Visual COBOL is integrated into Microsoft Visual Studio. You use the Microsoft Visual Studio IDE to develop, build and debug COBOL applications, as either native COBOL or .NET managed COBOL.

COBOL Applications

Visual COBOL provides a number of templates for creating both managed and native COBOL applications, COBOL Web sites and Web applications, WCF Service applications, SQL Database projects.

Solutions and Projects

A solution is a container holding one or more projects that work together to create an application. The solution has the extension .sln. A COBOL project has the extension .cblproj and a C# project has the extension .csproj.

Solution Explorer shows the solution that is open and its projects, as follows:

Add Existing File

There are several options that enable you to import existing COBOL source code into the IDE and start editing it as Visual COBOL projects. These are the Create Project from Existing Code wizard available from the File menu or the Add Existing COBOL Items command in Solution Explorer which helps you add files to a project. You can use the Create Project command in Solution Explorer to subdivide a project and create a new one from selected files.

You can convert Net Express projects into Visual Studio solutions and use the new IDE to develop and modernize the applications. Choose File > New > Solution from Net Express Project and follow the wizard instructions:

You can use the Project Details window to display a list of the files in your project or solution with files details like file type and location, COBOL dialect, the number of errors generated by the file:

COBOL Editor

The COBOL Editor provides help such as column cut and paste, and background checking, which underlines errors with red wavy lines (also known as "squigglies"), which you can then hover over to display details of the syntax.

When you are editing, you can insert code snippets and navigate forward and backward quickly, as shown below:

COBOL Editor Goto GoBack

You can customize the editor to display line numbers, adjust colorization, tabs, margins and you can specify the extensions you want to use for copybooks, from the Text Editor > COBOL (Text) Editor page in Tools > Options.

You can search for files, variables and section names in your solution with the help of the Navigate To option:

The Find All References option enables you to search for references of any COBOL data items, section and paragraph names in the solution:

In managed code, the editor provides help when you need to type more complicated constructs such as the code to override the members that a class inherits from a base class or the code for implementing an interface.

The Override Class Members option helps you select the members of the base class to override and adds the overriding methods to the inheriting class:

The Smart Tag for implementing an interface appears underneath at the beginning of the declaration of any interface that is not fully implemented. Implement the interface is as simple as clicking the tag:

Compiling, Project Properties and Copybooks

The project's properties define how to compile the project, including items such as the required Compiler directives, and the location of the output files, as shown below:

COBOL Project Properties

The project properties also define the location of any copybooks, as shown below:

Copypaths Project Properties

Each file can have its own properties with its own compilation requirements, or it can be not compiled at all as shown below:

Build Tools, the Output Pane and the Error List

Build configurations define how to build a project or solution, such as on which platform. There are default configurations of Debug and Release for each project type, and you can create your own specific configurations.

Build Configuration Manager

The Output window shows the results of your build together with errors. You can double-click an error and navigate directly to the appropriate line in the source code. You can do the same from the Error List.

Debugging

When you debug the application, you can step through the code, hover over a data item to see its value, and watch data item values in a variety of ways.

Debug Step Hover Watch

You can specify breakpoints on a range of conditions, such as when an expression is true or changes, or when a line is hit a specified number of times, as follows:

In native code, you can set COBOL watchpoints on data items and watch for changes in the area of memory associated with the watchpoints. When the memory changes, the debugger breaks on the line that follows the line on which the data change occurred.

Also in native code, you can use the Memory window to watch the contents of the memory that is associated with data items or expressions:

You can debug COBOL applications that are running on a remote machine. You set up the two machines and configure them for remote debugging. Then you build the source files on your local machine and debug the application that is running on the remote machine.

Parent topic: Welcome


To add Simple-JNDI to a user library

  1. Add the Simple-JNDI.jar to your user library.
  2. Do one of the following:
    • Compress the jndi.properties configuration file into a .zip file, and add the directory containing the .zip file using Add External JARs
    • Add the directory containing the jndi.properties file using Add External Class Folder
Related tasks
To create a user library for JDBC dependencies


Deployment Licensing

Related concepts
Overview of Deploying Native COBOL Applications


COBOL Debugging Settings

You can set additional options for debugging Micro Focus COBOL in the Visual Studio IDE, in Tools > Options > Debugging > COBOL Debugging Settings.
Step over inline PERFORM statements steps into them
By default, Step Over (F10) skips inline PERFORM statements.
Check this option to enable stepping into inline PERFORM statements when you use Step Over. Works with native code only.
Parent topic: General Debugging Options


To create a user library for JDBC dependencies

  1. In Eclipse, create a new workspace; then add a new COBOL JVM project to it.
  2. Right-click the project name and select Properties.
  3. Under Micro Focus COBOL, 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 New and type in a name for the library. For example, JDBC Dependencies.
  8. Check System Library; then click OK. Automatically adds to all libraries in the workspace.
  9. Click Add JARs and add .jar and .zip files to the library as necessary. See To add Simple-JNDI to a user library for more information.
  10. When you are finished adding all dependencies, click OK.
  11. Check the box next to the new library; then click Finish.
Related tasks
To add Simple-JNDI to a user library


IMS Properties

The IMS page in your project properties enables you to specify output folders for the generated files, or DBD, PSB or MFS build settings.

You can specify the following IMS properties:

Output Folders
Generated files
Click this to browse your computer to choose the folder to be used for files created when genning any files from the current project.
MFS Output
Specifies the folder where the generated control blocks from the MFS generation program will be saved.
IMS Databases
Click this to browse your computer to choose the folder to use when looking for IMS databases for the current project.
Clean also removes all DBD/PSB generated files
Check this to delete all DBD/PSB generated files when cleaning the project.
DBD Build Settings
Message level
Choose the level of error message reporting when generating DBDs.

Levels are cumulative, that is, if you select Severe, you only see Severe errors, while if you select Error, you see messages at Severe and Error level, and if you select Warning, you see all messages.

Generate listing file
Check this to generate a list file containing the original DBD source statements with any warning or error messages included.
Generate Map for DBD
Check this to cause the DBDMAP utility to be run.
Additional directives
Specify any DBDGEN directives to be used when genning DBD files in the current project. Separate directives with a space.
PSB Build Settings
Message level
Choose the level of error message reporting for PSBGEN.

Levels are cumulative, that is, if you select Severe, you only see Severe errors, while if you select Error, you see messages at Severe and Error level, and if you select Warning, you see all messages.

Generate listing file
Check this to generate a list file containing the original PSB source statements with any warning or error messages included.
Validate PSB against DBDGENs
Check this to validate the genned PSB against the current DBDGEN library.

If Generate listing file is checked the validation report will appear in the listing after the PSB source statements.

Additional directives
Specify any PSBGEN directives to be used when genning PSB files in the current project. Separate directives with a space.
MFS Build Settings
Message level
Choose the level of error message reporting for MFSGEN.

Levels are cumulative, that is, if you select Severe, you only see Severe errors, while if you select Error, you see messages at Severe and Error level, and if you select Warning, you see all messages.

Generate listing file
Check this to generate a list file containing the original MFS source statements with any warning or error messages included.
STACK handling
Choose a method of processing STACK and UNSTACK statements. The STACK and UNSTACK statements are often used to define different device types for one format. With Mainframe Transaction Option, only one device type can be 'active' at a time, thus, the STACKs for the other device types are not needed and would slow the processing of the MFSGEN.
Ignore after DEV statement
The default property.
Ignore always
Expand always


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 Copybook Paths tab, 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.

Each COPY statement in your program identifies a copybook to be copied. If the filename in the COPY statement is incomplete, because it lacks either an extension or a path, the Compiler searches for it as follows:

  1. In the directory given by the COPY library-name. Note that if the name of the copybook is a qualified filename, that is, it includes the path or directory, the Compiler searches that directory only.
  2. In the directory containing the main source program being compiled.
  3. In any directories listed in the COBCPY environment variable, in the order specified.

If the COPY statement does not give the extension of the copybook's filename, the Compiler searches for files with extensions given by the directive COPYEXT.


To compile a single file

  1. To change the Compiler directives:
    1. In Solution Explorer, right-click the file you want to compile.
    2. Click Properties.
    3. Go to the COBOL page.
    4. In Additional Directives, type the directives to set. Separate each directive with a space.
    5. Click OK.
  2. In Solution Explorer, right-click the file you want to compile.
  3. Click Compile.

    This option is not available when a build is already in progress.

These directives override any that are specified for the whole project.

Next time you rebuild or compile this your file, the directives you specified are used.

Related information
Compiling from the Command Line
Compiler Directives
Setting Directives Outside the IDE


To set up a central license server and load licenses

You can set up a central Sentinel RMS license server if your authorization code grants multiple licenses. A license server is installed automatically when you install your Micro Focus product, and you can use any license server installation as your central license server without additional configuration.

Important: Internet connectivity is required to authorize your product and obtain licenses

After you have installed your product:

  1. Start the Micro Focus Licensing Administration tool.
  2. Click the Authorize tab.
  3. Enter your authorization code (a 16-character alphanumeric string)
  4. Click Authorize.
CAUTION:
If you change the name of your license server after you have installed licenses it will stop working.
Related information
To start the Micro Focus Licensing Administration tool
To authorize your product using a local license server
To authorize your product manually
To configure your workstation to use a central license server
To view installed licenses
To revoke licenses
To revoke licenses manually


Creating Debug Files

If you encounter an error when compiling a program that requires you to contact Micro Focus technical support, your support representative might request that you provide additional debug files (as well as source and data files) to help us determine the cause of the problem. If so, they will advise you how to create them.

Parent topic: Contacting Micro Focus