RM COBOL Win 70 Manual

RM/COBOL®
User’s Guide
®
Version 7.0 for 32-Bit Windows
This manual is a user’s guide for Liant Software Corporation’s RM/COBOL language.
It is assumed that the reader is familiar with programming concepts and with the COBOL
language in general.
The information contained herein applies to systems running under Microsoft

Windows 95, Microsoft Windows 98, Microsoft Windows NT, and UNIX-based
operating systems.
The information in this document is subject to change without prior notice. Liant
Software Corporation assumes no responsibility for any errors that may appear in this
document. Liant reserves the right to make improvements and/or changes in the products
and programs described in this guide at any time without notice. Companies, names, and
data used in examples herein are fictitious unless otherwise noted.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted,

in any form or by any means, electronic, mechanical, photocopied, recorded, or
otherwise, without prior written permission of Liant Software Corporation.
The software described in this document is furnished to the user under a license for a
specific number of uses and may be copied (with inclusion of the copyright notice) only
in accordance with the terms of such license.
Copyright © 1985, 1986-1999 by Liant Software Corporation. All rights reserved.

Printed in the United States of America.
_____________________
RM, RM/COBOL, RM/COBOL-85, Relativity, Enterprise CodeBench, RM/InfoExpress, RM/Panels,

RM/plusDB, VanGui Interface Builder, CodeWatch, CodeBridge, Liant, and the Liant logo are trademarks
or registered trademarks of Liant Software Corporation.
Borland is a registered trademark of Borland International, Inc.
Btrieve is a registered trademark of Pervasive Software.
Cobol-WOW, Cobol-RPC, and Cobol-CGI are trademarks of England Technical Services, Inc.
IBM and Macro Assembler/2 are trademarks or registered trademarks of International Business Machines
Corporation.
Microsoft, CodeView, MS, MS-DOS, Visual Basic, Windows 95, Windows 98, and Windows NT are
trademarks or registered trademarks of Microsoft Corporation in the USA and other countries.
Novell and NetWare are trademarks or registered trademarks of Novell, Incorporated.
TrueType is a registered trademark of Apple Computer, Incorporated.
UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open
Company Ltd.
All other products, brand, or trade names used in this publication are the trademarks or registered trademarks of
their respective trademark holders, and are used only for explanation purposes.
Document Number 401190-0499
Preface
Welcome to RM/COBOL Version 7.0

RM/COBOL version 7.0 for 32-bit Windows is a significantly enhanced version of
Liant’s widely used RM/COBOL compilers, designed for new program development and
execution of programs created with earlier versions of RM/COBOL. Although modeled
on the American National Standard COBOL X3.23-1985, there are areas where
RM/COBOL varies from the standard. A complete list of these variances is included in
Appendix I, Extension, Obsolete, and Subset Language Elements.
The RM/COBOL operating procedures described in this manual are for use on Microsoft
32-bit Windows and UNIX-based systems that support remote file access using Novell
NetWare (version 3.11 and above), Client for Microsoft Networks, or Btrieve software.
Note 1 Beginning with version 6.5, the -85 suffix is no longer a part of the RM/COBOL
product name. The -85 suffix was used to reflect current technology and to avoid
confusion with an earlier product named RM/COBOL, which referred to the 1974 ANSI
standard version. Support for RM/COBOL (74) ceased on December 31, 1994.
Note 2 The term “Windows” in this document refers to Windows 95, Windows 98, or
Windows NT, unless specifically stated otherwise.
What's New
The following section summarizes the major enhancements available in RM/COBOL
version 7.0 for Windows. This summary describes the main features of each
enhancement. The RM/COBOL Language Reference Manual and this user’s guide
contain the details regarding these features.
Note For information on the significant enhancements in previous releases of

RM/COBOL, see the information beginning page xli.
RM/COBOL User's Guide for 32-Bit Windows xxv

Welcome to RM/COBOL Version 7.0
CodeWatch Debugger Introduced
This release includes CodeWatch, a standalone, source-level debugger for Windows.
CodeWatch supports the debugging of any applications without requiring that they be
built under the RM/CodeBench or Enterprise CodeBench development environments.
CodeWatch uses true 32-bit Windows “look-and-feel” and common Windows controls
such as native toolbars, tree lists, progress indicators, and spin buttons. For more
information, see the CodeWatch manual, which is included in the RM/COBOL
development system documentation set for this release. CodeWatch uses the enhanced
debugging information that is available when the new debugging options are specified
during compilation of a source program. For additional information on the new
debugging options, refer to the paragraph Enhanced Debugging Options on page xxx in
the “Compiler New Features” section.
CodeBridge Cross-Language Call System Introduced

A new facility that simplifies communication between COBOL programs and non-
COBOL subprograms (such as those written in C or C++) is included in RM/COBOL
version 7.0 for Windows. Known as CodeBridge, this facility allows COBOL
programmers to call external APIs or custom-developed subprograms without introducing
“foreign” language and data dependencies into their programs. This means that
developers can write C functions using C data types as usual, without worrying about the
complex ArgEntry structure or COBOL data types. After the function declaration has
been augmented for use as a template, the CodeBridge utility automatically produces a C
source file for a bridge DLL. This file contains all the logic to interface to the calling
COBOL program, the developer's C functions, and the needed calls to a CodeBridge data
conversion library. The developer then compiles this source file, along with the C
functions to be called, and links everything together with the conversion library to form
the completed non-COBOL DLL. In a similar manner, pre-existing DLL libraries also
can be called from RM/COBOL applications.
Refer to the CodeBridge manual, included in the RM/COBOL development system

documentation set for this release.
Enhanced Windows Printing

The RM/COBOL version 7.0 for Windows runtime contains enhancements to provide
more capabilities and flexibility when printing with Windows printer drivers. A new
predefined printer device, “PRINTER?”, has been added to the runtime (see the
“Windows Printers” section under DEFINE-DEVICE configuration record in
Chapter 10, Configuration). When this device is opened, a standard Windows Print
Setup dialog box is presented to the user to allow dynamic selection of the
Windows printer.
xxvi Preface
What's New
A library of P$ subprograms (described in Appendix E, Windows Printing) and two
Windows registry properties, Printer Dialog Always and Printer Dialog Never (see
Chapter 3, Installation and System Considerations for Microsoft Windows), have been
added to allow developer control of this dialog box. The RM/COBOL for Windows
compiler can use this capability to select the printer for the listing file.
The RM/COBOL for Windows runtime also has been enhanced to support raw mode
printing, which is useful when printing with escape sequences to a Windows NT network
printer. Limited support for Windows printers via escape sequences is provided as well
(see also Appendix E).
Additions to the RM/COBOL Subprogram Library

The RM/COBOL subprogram library now includes the following C$ subprograms (for
more detail, see Appendix F, Subprogram Library):
• C$ClearDevelopmentMode disables expanded error information reporting (known

as “development mode”) in many of the C$ and P$ subprograms.
• C$Delay relinquishes the CPU for a specified length of time (in seconds).
• C$GetEnv and C$SetEnv retrieve and set, respectively, environment variables.
• C$GetLastFileName retrieves the last file-name and pathname used in a COBOL

I/O statement.
• C$GetLastFileOp retrieves information about the last COBOL I/O file

operation performed.
• C$GetRMInfo retrieves information about the RM/COBOL runtime system.
• C$GetSyn and C$SetSyn retrieve and set, respectively, the values of RM/COBOL
synonyms used in the Windows registry file.
• C$GetSysInfo retrieves information about the operating system on which the

RM/COBOL runtime system is running.
• C$MemoryAllocate allocates dynamic memory.
• C$MemoryDeallocate deallocates (frees) dynamically allocated memory.
• C$PlaySound plays Windows predefined sound events or sound files.
RM/COBOL User's Guide for 32-Bit Windows xxvii

What's New
• C$SetDevelopmentMode enables expanded error information reporting (known as
“development mode”) in many of the C$ and P$ subprograms.
• C$Show sets the show state of the main RM/COBOL window (rmguife.exe).
• C$ShowArgs displays a list of the arguments used to call a subprogram.
Ability to Use Btrieve Interface

An additional subprogram, C$BTRV, makes raw Btrieve functions, including
transactions, accessible from RM/COBOL using Btrieve's normal interface.
Runtime New Features

In addition to the new C$ and P$ subprogram libraries supplied in the runtime,
RM/COBOL version 7.0 for Windows runtime system includes the following features:
• Support for Large Files. The runtime system allows RM/COBOL 7.0 files to grow
past limits imposed in previous versions. On Windows 95 and Windows 98, files up
to 4 GB (gigabytes) are supported. Windows NT supports multiple terabyte files on
the NT file system. Only files on FAT32 (Windows 95 and Windows 98 file system
format) or NTFS (Windows NT file system) may be larger than 2 GB.
• Enhanced Runtime Performance. The RM/COBOL version 7.0 for Windows

runtime typically runs computational tasks 20 to 30 percent faster than RM/COBOL
version 6.51 for Windows.
• Termination Log Added. On Windows, a log of termination error messages,

including traceback information, can be used to collect information about errors
not trapped by declaratives. The ENABLE-LOGGING=TERMINATION and
LOG-PATH keywords have been added to the RUN-OPTION configuration record
to allow error messages to be collected for later analysis. See Chapter 10,
Configuration, for more information.
• New Runtime Behavior. When the RM/COBOL runtime loads a non-COBOL

subprogram library using CodeBridge, it builds a table of entry points into that
library. If the sequence “RMDLL” is found at the beginning of any entry name, it is
removed. See the CodeBridge documentation for more information.
xxviii Preface
What's New
• Runtime Registration. The RM/COBOL version 7.0 for Windows runtime now
consists of two components: a client (runcobol.exe) and a server (rmcblrun.dll).
The client component is completely compatible with previous versions of the
runcobol.exe program—no command line changes are required. The server DLL,
however, must be registered with Windows before RM/COBOL programs can be run.
This is automatically performed during program installation and is an issue only if
the runtime is moved to a different directory without being installed again. In this
case, the client can be used to reregister the server. See the installation procedures in
Chapter 3, Installation and System Considerations for Microsoft Windows.
• More Flexible Filenames. Two new options have been added to the
RUN-FILES-ATTR configuration record. The ALLOW-EXTENDED-CHARS-IN-
FILENAMES keyword allows extended characters in filenames. The ENABLE-
OLD-DOS-FILENAME-HANDLING keyword supports the way in which filenames
are handled in the old DOS-style 8.3 format. See Chapter 10 for further details.
• LINAGE Configuration Options. The PRINT-ATTR configuration record now

includes two new configuration keywords to assist in configuring LINAGE for page
printers, such as laser printers and ink jet printers. (See Chapter 10.)
The new LINAGE-INITIAL-FORM-POSITION keyword defines where the form is

positioned in the printer when the file is opened. The RM/COBOL implementation
of LINAGE has required in the past that the form be aligned in the printer such that
the first line printed is line one of the page body of the first logical page. This was
a reasonable requirement when COBOL was mainly used with line printers and
continuous forms. However, this requirement is not reasonable for page printers.
For page printers, the value TOP-OF-FORM would be specified for this new
keyword. The value PAGE-BODY-LINE-1 (the default value) would be
specified for line printers when the operator adjusts the form to the first line of the
logical page.
The new LINAGE-PAGES-PER-PHYSICAL-PAGE keyword in the PRINT-ATTR

configuration record defines the number of logical pages per physical page.
LINAGE specifies logical pages, not physical pages. Therefore, the RM/COBOL
implementation of LINAGE did not use form feed characters when printing
LINAGE files since form feed characters advance the printer to the next physical
page. For a page printer, a form feed character is sometimes necessary to advance
to the next physical page. When LINAGE-PAGES-PER-PHYSICAL-PAGE is
set to a nonzero value, then a physical page break (normally a form feed character)
is printed each time that number of logical pages has been printed. When
LINAGE-PAGES-PER-PHYSICAL-PAGE is set to 0 (the default value), then
physical page breaks are not generated for LINAGE files.
RM/COBOL User's Guide for 32-Bit Windows xxix

What's New
Compiler New Features
While RM/COBOL 6.61 contained numerous changes to the compiler, version 7 features
even more capabilities, including the following:
• Increased Compiler Capacity. RM/COBOL version 7.0 for Windows compiler

allows 65535 identifiers to be defined in a single program (up from the 8192 allowed
in version 6.61). The maximum space for user-defined words has been increased
such that all 65535 identifiers could have unique names 30-characters in length (up
from the 21-character average limit for version 6.61). The changes that support the
increased capacity also eliminate the problem that limited consecutive comment lines
to around 800. The limit is now about 18,000 consecutive comment lines.
• New Reserved Words. To support some of the features described in the following
paragraphs, the reserved words list has been extended with the following new words:
ADDRESS, CENTURY-DATE, CENTURY-DAY, COUNT-MAX, COUNT-MIN,
DATE-AND-TIME, DAY-AND-TIME, NULL, NULLS, and RETURNING.
Note that if you use these reserved words as user-defined words, you must either
change the spelling of these user-defined words or use the DERESERVE keyword in
the COMPILER-OPTIONS configuration record.
• ACCEPT Statement Enhancements. A number of changes have been made

to the ACCEPT statement related to improving the way dates and times are handled.
These changes provide additional ways of writing Y2K-compliant COBOL.
New phrases include CENTURY-DATE, CENTURY-DAY, DATE-AND-TIME,
DATE-COMPILED, and DAY-AND-TIME. See the RM/COBOL Language
Reference Manual for more information.
• Constant-Names. Compile-time constants can now be defined with constant-names

declared in level-number 78 data description entries. Once defined, a constant-name
can be used in almost all contexts where a literal or integer is required in the
language syntax. When properly used, constant-names greatly simplify the
maintenance of COBOL programs.
xxx Preface
What's New
• POINTER Data Types. The POINTER data type has been added. Pointer data
items can be used to point to other data items in the program or in allocated memory.
Support for pointer data items includes the NULL and NULLS figurative constants,
which are pointer literals with a null pointer value. There are two new formats of the
SET statement to manipulate pointer data items and an ADDRESS OF special
register for obtaining the address of a data item as a pointer value. A non-null
pointer refers to an area of memory that may be accessed in COBOL by setting the
base address of a level-number 01 or 77 data item described in the Linkage Section
of the program to the pointer value. Dynamic memory allocation is supported by two
new subprograms in the provided library, C$MemoryAllocate and
C$MemoryDeallocate.
• Binary Allocation Configuration. New configuration options allow binary numeric

data items to be allocated in the minimum size necessary to support the specified
PICTURE character-string consistent with the configured sizes. RM/COBOL has
traditionally allocated binary numeric data items as two, four, eight, or sixteen bytes.
The new configuration options allow binary numeric data items described with one or
two digits to be allocated as a single byte. For more details on binary numeric data
item allocation configuration, see the description of the BINARY-ALLOCATION
and BINARY-ALLOCATION-SIGNED keywords in the COMPILER-OPTIONS
configuration record section of Chapter 10, Configuration.
• Binary Allocation Override. In addition to binary allocation configuration, the

compiler now supports a binary allocation override specification in the USAGE
clause. The binary allocation override specification is an integer, enclosed in
parentheses, that follows a binary usage type (COMPUTATIONAL-4, COMP-4, or
BINARY). The integer specifies the number of bytes to allocate, overriding the
number of bytes that would have been allocated based on the current compiler
configuration. The override specification may specify fewer bytes than would be
required to support the decimal precision indicated by the PICTURE character-string.
• COUNT, COUNT-MAX, and COUNT-MIN Special Registers. The compiler

now supports three new special registers, COUNT OF data-name-1, COUNT-MIN
OF data-name-1, and COUNT-MAX OF data-name-1, that may be used to obtain
the number of occurrences of a table data item. For a fixed occurrence table,
COUNT, COUNT-MAX, and COUNT-MIN all return the fixed number of
occurrences specified in the OCCURS clause. For a variable occurrence table,
COUNT-MIN returns the minimum number of occurrences specified in the OCCURS
clause, COUNT returns the current number of occurrences (that is, the current value
of the DEPENDING data item specified in the OCCURS clause), and COUNT-MAX
returns the maximum number of occurrences specified in the OCCURS clause.
RM/COBOL User's Guide for 32-Bit Windows xxxi

What's New
• LENGTH Special Register. The compiler now supports a new special register,
LENGTH OF identifier-1, that may be used to obtain the length in bytes of any data
item. The length for most data items is a constant, but the length is a variable for
variable size groups and for identifiers that specify reference modification.
• PROGRAM-ID Special Register. The compiler now supports a new special

register, PROGRAM-ID, which may be used to obtain the program-name of any
program that specifies this special register.
• In-Line Comments. The compiler now supports the *> symbol as an in-line
comment introducer. Any characters on the same source record following *> will be
treated as commentary. The *> symbol must be preceded by a space separator.
• OMITTED Arguments. The compiler now supports the keyword OMITTED in the
USING list of a CALL statement. Since arguments are positional, this feature allows
an argument to be omitted from other than the end of the USING list.
• GIVING/RETURNING Phrase. The compiler now supports the

GIVING/RETURNING phrase in the Procedure Division header and in a CALL
statement. This phrase specifies an additional argument intended as the output
argument of a called program.
• Formal Arguments (USING/GIVING). The compiler now handles as a special

case the specification of a formal argument as an actual argument in a CALL
statement or in a reference modified identifier reference. In these two cases, the
reference is evaluated according to the description of the actual argument
corresponding to the formal argument rather than using the Linkage Section
description of the formal argument. This means that a program that is just an
intermediary between two programs need not have a Linkage Section data
description entry that accurately describes the size of the actual argument being
passed through it. For example, calling C$CARG with a formal argument, which is
described as longer than the corresponding actual argument, will no longer result in a
data reference error. Instead, C$CARG will return the correct length of the actual
argument, and because of the reference modification change described here, this
length may be successfully used to reference modify the formal argument.
This also means that a program can call the supplied subprogram C$CARG with an
argument that the calling program omitted without getting a data reference error. In
this case, the call to C$CARG will succeed and return an argument descriptor that
includes a type of OMITTED and a length of zero. In the case of reference
modification, an omitted actual argument would cause a data reference error, but for
an argument that is not omitted, the reference modification can use any offset and
length combination that is consistent with the actual argument. Previous to this
enhancement, reference modification that used variables implied a reference to the
item as described in the Linkage Section for the formal argument data item and this
xxxii Preface
What's New
implied reference, if larger than the corresponding actual argument, would cause a
data reference error before the reference modification was applied.
• New Listing Date Formats. The compilation listing date format can now be
configured to include four-digit years with the new format values DDMMYYYY,
MMDDYYYY, YYYYMMDD, and YYYYDDD. The default listing date format
has been changed to MMDDYYYY so that a four-digit year will be used by default.
This change also included making the DATE-COMPILED paragraph use the same
date format as the compilation listing header.
• Enhanced Debugging Options. The Y Compile Command Option has two new
variations that direct the compiler to embed additional debugging information in the
program object file. The additional debugging information allows CodeWatch to
display the program source during execution without requiring that the program be
compiled under Enterprise CodeBench. See the description of the Y compiler
command line option in Chapter 6, Compiling, and the DEBUG-TABLE-OUTPUT
keyword in the COMPILER-OPTIONS configuration record, as detailed in
Chapter 10, Configuration.
Enhanced File Recovery Performance

For large files, the Indexed File Recovery utility (recover1) runs at least twice as fast as
previous versions. The -m option has been added to allow the user to specify a larger
amount of memory to be used for the recovery. Allocating more memory generally
results in much faster recovery. For more information, see Appendix G, Utilities.
New Rmpgmcom Utility Option

A new option in the rmpgmcom utility, STRIP, can remove COBOL symbol table and
debug line table information produced by the Y compilation option from object files. See
Appendix G, Utilities, for more information.
Who Should Use This Book

This book is intended for commercial application developers who are familiar with
programming concepts and with the COBOL language in general, and by persons running
COBOL programs developed with RM/COBOL.
RM/COBOL User's Guide for 32-Bit Windows xxxiii

Who Should Use This Book
Organization of Information
This user’s guide is divided into the following parts:
Chapter 1—Introduction describes the general concepts of the RM/COBOL compiler

and runtime system and how they are used, lists the add-on development tools that are
available to support RM/COBOL programs, and explains file naming conventions.
Chapter 2—Installation and System Considerations for UNIX explains the

installation procedures for RM/COBOL and presents information about the
implementation on UNIX-based operating systems.
Chapter 3—Installation and System Considerations for Microsoft Windows explains

the installation procedures for RM/COBOL and presents information about the
implementation on Microsoft Windows 95, Windows 98, or Windows NT operating
systems.
Chapter 4—System Considerations for Btrieve presents information about the

implementation of RM/COBOL for systems using Btrieve. This chapter also describes
the limitations of RM/COBOL indexed files and the Btrieve MicroKernel Database
Engine (MKDE).
Chapter 5—System Verification describes the suite of verification programs provided

with RM/COBOL.
Chapter 6—Compiling describes RM/COBOL files, details the RM/COBOL Compile

Command, rmcobol, and its options, defines the types of errors that can be encountered
during program compilation and the messages generated as a result, illustrates and defines
each section of the program listing, and presents information on RM/COBOL error
recovery.
Chapter 7—Running details the RM/COBOL Runtime Command, runcobol, and its
options, and defines the types of errors that can be encountered during program
execution. It also lists the messages generated as a result.
Chapter 8—RM/COBOL Features presents information about the implementation of

RM/COBOL with respect to specific COBOL statements.
Chapter 9—Debugging presents general debug concepts and a detailed discussion of the
Debug commands.
Chapter 10—Configuration details the methods available for modifying the

RM/COBOL default configuration.
xxxiv Preface
Chapter 11—Instrumentation details the data-gathering Instrumentation facility. It
also describes a sample data analysis program—provided with Instrumentation—called
analysis.
Appendix A—Runtime Messages lists and defines the messages that may be generated
during program execution.
Appendix B—Limits and Ranges describes RM/COBOL limits and ranges.
Appendix C—Internal Data Formats describes and illustrates the internal

representation of the data types.
Appendix D—Customizing RM/COBOL for UNIX provides information on how to

customize the runtime system portion of RM/COBOL and how to add C subprograms to
the runtime system.
Appendix E—Windows Printing describes the subprograms supplied with the

RM/COBOL Windows runtime system that allow access to Windows printing features.
Appendix F—Subprogram Library describes a set of supplied subprograms that can be

called by any RM/COBOL program.
Appendix G—Utilities describes the full range of file conversion, management, and
manipulation facilities.
Appendix H—Object Versions lists the new object features that are incompatible with
earlier releases of RM/COBOL.
Appendix I—Extension, Obsolete, and Subset Language Elements lists the

RM/COBOL extensions to and variances from ANSI COBOL 1985. It also lists obsolete
and subset language elements.
Appendix J—Code-Set Translation Tables lists each ASCII and EBCDIC hexadecimal
value and its corresponding numeric, alphabetic or control character.
The RM/COBOL User’s Guide for 32-Bit Windows also includes an index.
RM/COBOL User's Guide for 32-Bit Windows xxxv

Related Publications
For additional information, refer to the following publications that are available from
Liant Software Corporation:
CodeBridge—Calling Non-COBOL Subprograms
CodeWatch User's Guide
RM/COBOL for DOS User’s Guide Supplement
RM/COBOL Open File Manager User’s Guide
RM/COBOL Language Reference Manual
RM/COBOL Syntax Summary
RM/CodeBench User’s Guide
Enterprise CodeBench Getting Started Manual
RM/InfoExpress for TCP/IP User's Guide
RM/InfoExpress for SPX/IPX User’s Guide
RM/Panels Reference Manual
Relativity Client/Server Installation Guide
Relativity Data Manager Installation Guide
Relativity DBA Installation Guide
Relativity Designer Installation Guide
Theory of Relativity, A Primer
VanGui Interface Builder User's Guides (Delphi and Visual Basic)
Contact the appropriate vendor for other publications:
Btrieve products are available from Pervasive Software, Inc. (formerly

Btrieve Technologies, Inc.).
NetWare products are available from Novell, Incorporated.
Microsoft products are available from Microsoft Corporation.
xxxvi Preface
Related Publications
Conventions and Symbols
The following conventions and symbols are used or followed throughout this guide.
1. Words in all capital letters indicate COBOL reserved words, such as statements,
phrases, and clauses; acronyms; configuration keywords; environment variables; and
RM/COBOL Compiler and Runtime Command line options.
2. Bold lowercase letters represent names of files, directories, programs, commands,

and utilities. RM/COBOL accepts uppercase and lowercase filenames. Within this
document, the lowercase version is used. Remember, however, that under UNIX
filenames are case sensitive (for example, TEST4 and test4 represent different files).
Bold type style is also used for emphasis on some types of lists.
3. Text that is displayed in a monospaced font indicates user input or system output
(according to context as it appears on the screen). This type style is also used for
sample command lines, program code and file listing examples, and sample sessions.
4. Italic type identifies the titles of other books and the names of chapters in this guide,
and it occasionally is used for emphasis.
In syntax, italic type denotes a placeholder or variable for information you supply, as
described in the following item.
5. The symbols found in the syntax charts are used as follows:
italicized words indicate items for which you substitute a specific value
UPPERCASE WORDS indicate items that you enter exactly as shown (although
not necessarily in uppercase)
... indicate indefinite repetition of the last item
| separate alternatives
[ ] surround optional items
{ } surround a set of alternatives, one of which is required
{| |} surround a set of unique alternatives, one or more of
which is required, but each alternative may be specified
only once; when multiple alternatives are specified, they
may be specified in any order.
RM/COBOL User's Guide for 32-Bit Windows xxxvii

6. All punctuation must appear exactly as shown.
7. The term “NetWare” refers to the Novell NetWare operating system.
8. The term “window” refers to a delineated area of the screen, normally smaller than
the full screen. The term “Windows” refers to the Microsoft Windows 95,
Windows 98, or Windows NT operating systems.
9. Examples for UNIX-based systems in this document assume the use of the Bourne
Shell (sh) command interpreter.
10. Throughout this document, references to a printer refer to the device assigned to
PRINTER, in accordance with operating system conventions.
11. RM/COBOL Compile and Runtime Command line options may be specified either
with or without a leading hyphen. Examples in this guide do not show a leading
hyphen. If any option on a command line is preceded by a hyphen, then a leading
hyphen is required for all options. When assigning a value to an option, the equal
sign is optional if leading hyphens are used.
Command line options may be specified in either uppercase or lowercase characters.
Examples in this guide are shown in uppercase.
These capabilities are provided to support the command line syntax of previous
versions of RM/COBOL.
12. Any text that applies only to a specific operating system is specified in a Note
format.
13. Key combinations with a plus sign between key names indicate to press and hold
down the first key while pressing the second key. For example, “Press Alt + Esc”
means to press and hold down the Alt key and press the Escape key. Then release
both keys. A comma between key names means to press and release the keys one
after the other.
xxxviii Preface
Registration
Please take a moment to fill out and mail (or fax) the registration card you received with
RM/COBOL. You can also complete this process by registering your Liant product
online at: http://www.liant.com.
Registering your product entitles you to the following benefits:
• Customer support. Free 30-day telephone support, including direct access to

support personnel and 24-hour message service.
• Special upgrades. Free media updates and upgrades within 60 days of purchase.
• Product information. Notification of upgrades or revisions to RM/COBOL as soon

as they are released.
You can also receive up-to-date information about Liant and all its products via our web
site. Check back often for updated content.
Technical Support
Liant Software Corporation is dedicated to helping you achieve the highest possible
performance from the RM/COBOL family of products. The technical support staff is
committed to providing you prompt and professional service when you have problems or
questions about your Liant products.
These technical support services are subject to Liant’s prices, terms, and conditions in
place at the time the service is requested.
While it is not possible to maintain and support specific releases of all software
indefinitely, we offer priority support for the most current release of each product. For
customers who elect not to upgrade to the most current release of the products, support is
provided on a “limited" basis, as time and resources allow.
Support Guidelines
When you need assistance, you can expedite your call by having the following
information available for the technical support representative:
1. Company name, support contract, partner, ADR, or distributor number.
2. Liant product serial number (found on the media label, registration card, or product
banner message).
RM/COBOL User's Guide for 32-Bit Windows xxxix

Registration
3. Product version number.
4. Operating system and version number.
5. Hardware, related equipment, and terminal type.
6. Exact message appearing on screen.
7. Concise explanation of the problem and process involved when the problem
occurred.
Test Cases
You may be asked for an example (test case) that demonstrates the problem. Please
remember the following guidelines when submitting a test case:
• The smaller the test case is, the faster we will be able to isolate the cause of the
problem.
• Do not send full applications.
• Reduce the test case to one or two programs and as few data files as possible.
• If you have very large data files, write a small program to read in your current data
files and to create new data files with as few records as necessary to reproduce the
problem.
• Test the test case before sending it to us to ensure that you have included all the
necessary components to recompile and run the test case. You may need to include
an RM/COBOL configuration file.
When submitting your test case, please include the following items:
1. README text file that explains the problems. This file must include information
regarding the hardware, operating system, versions of all relevant software (including
the operating system and all Liant products). It must also include step-by-step
instructions to reproduce the behavior.
2. Program source files. We require source for any program that is called during the
course of the test case. Be sure to include any copy files necessary for recompilation.
3. Data files required by the programs. These files should be as small as possible to
reproduce the problem described in the test case.
xl Preface
Technical Support
Version 6.6 Enhancements
Increased Compiler Capacity

The ability to compile large programs has been improved by allowing more identifiers
and user-defined words during compilation. The maximum number of identifiers has
been increased from 3612 to 8192, while the maximum space available for user-defined
words has been doubled. The new user-defined word limit allows for 8192 user-defined
words that average 21 characters in length, but these cannot all be identifiers since
procedure-names must also fit in this space. The cross reference capability of the
compiler was also improved to correctly cross reference source programs up to 65535
lines in length, up from the 16384 lines supported in prior versions.
Improved Compiler Performance for Large Programs

The compiler performance has been improved for large programs by adjustments to the
memory allocation algorithms.
New Statistics in Compilation Listing File

The compiler now provides additional statistics regarding how much identifier table space
and user-defined word space has been consumed to compile a source program. The
messages are intended to help project managers avoid surprises in suddenly having a
source program exceed one of the limits. The messages are now part of the Program
Summary Statistics portion of the listing. Here is an example of the messages:
Source program used 4489 (55%) of 8192 available identifiers

(T28 limit).
Source program used 33004 (50%) of 65536 available user-defined

word space (T48 limit).
The new compiler also offers additional statistics regarding the use of memory during
compilation. The message helps the user establish a proper setting of the workspace size
compiler option (W command line option and WORKSPACE-SIZE keyword of the
COMPILER-OPTIONS configuration record). The message is now part of the Program
Summary Statistics portion of the listing. Here is an example of the message:
Maximum compilation memory used was 487K bytes (2 presses and 0

increases required).
RM/COBOL User's Guide for 32-Bit Windows xli

Memory presses and increases occur in the compiler to help minimize the amount of
memory used, but at the cost of compilation speed. Minimizing the number of
presses by increasing the workspace size setting yields the fastest compilation. A
small number of presses does not affect compiler speed.
Double-Byte Character Set (DBCS) Support

Double-byte character set (DBCS) characters are now supported by RM/COBOL when
running on those versions of UNIX that allow their use. See the description of the
DBCS-CHARACTERS keyword in the TERM-ATTR configuration record in
Chapter 10, Configuration, for more information.
Enhanced Indexed File Recovery Program

The Indexed File Recovery utility (recover1) has been enhanced to improve its ability to
repair damaged indexed files. recover1 is now able to repair not only those problems
that, in previous versions, required the use of the recover2 utility, but other problems as
well. The enhancements to recover1 have made the recovery and recover2 utilities
obsolete. However, recovery and recover2 are still included on the distribution media
for backward compatibility. See Appendix G, Utilities, for more information on the
recover1 program.
Masked Input and Output

The RM/COBOL runtime now allows dynamic input based on a template supplied with a
new keyword, MASK, that can be specified in the CONTROL phrase in ACCEPT and
DISPLAY statements. This capability applies to UNIX only. (For more details, see
Chapter 8, RM/COBOL Features.)
Support For Large Files

When running under operating systems that support files larger than 2 GB (gigabytes),
the runtime system will now allow RM/COBOL files to grow past limits imposed in
previous versions. This support is provided by the LARGE-FILE-LOCK-LIMIT
keyword of the RUN-FILES-ATTR configuration record. In order to use this new limit
on relative or sequential files, you must use the USE-LARGE-FILE-LOCK-LIMIT
keyword in a RUN-REL-FILES or RUN-SEQ-FILES configuration record. For more
information, see Chapter 10, Configuration. In order to use this new limit on indexed
files, you must use an indexed file version of 3 (see Chapter 8, RM/COBOL Features, for
more information).
xlii Preface
The following section summarizes the major enhancements available in version 6 of
RM/COBOL. This summary describes the main features of each enhancement. The
RM/COBOL Language Reference Manual and this user’s guide contain the details
regarding these features.
Full 32-bit Implementation

RM/COBOL is now implemented in 32-bit code across all platforms (UNIX and
Windows). One common RM/COBOL runtime system or compiler will execute under
either Windows 95 or Windows NT. On Windows 95, the COBOL programs can make
calls to non-COBOL subprograms in either 16-bit or 32-bit dynamic link libraries
(DLLs). On Windows NT, COBOL programs can make calls only to non-COBOL
subprograms in 32-bit DLLs.
Windows Registry Support

RM/COBOL for Windows makes use of the Windows registry to maintain program
properties. This feature eliminates the need for initialization (.ini) files. The tabs in the
Properties dialog box for the COBOL object program can be used to set values in the
registry. See “Windows Registry” in Chapter 3, Installation and System Considerations
for Microsoft Windows, for more information. A new utility, RM/COBOL Configuration,
rmconfig.exe, also can be used to set these properties by displaying the Properties dialog
box. For more details, see Appendix G, Utilities.
Note The Initialization File to Windows Registry utility (ini2reg.exe), available only in
Windows, converts an RM/COBOL for Windows initialization file and places its contents
into the registry database.
Windows 95 and Windows NT Extensions

RM/COBOL for Windows now supports extensions to Windows 95 and Windows NT.
These extensions include long filenames and 3D controls.
RM/COBOL User's Guide for 32-Bit Windows xliii

Automated System Installation and Removal
An automated system installation and removal capability is now a part of RM/COBOL for
Windows. This feature greatly simplifies the loading and unloading of RM/COBOL. It is
especially useful in ensuring that the appropriate programs are included or removed when
upgrading to new versions. See the “System Installation” and “System Removal” sections
in Chapter 3, Installation and System Considerations for Microsoft Windows, for more
information.
Right Mouse Button Pop-Up Menu

RM/COBOL now provides the ability to define a pop-up menu that displays when the
right mouse button is clicked in the client area of the RM/COBOL window. For more
information about setting pop-up menu properties, see the section “Setting Pop-up Menu
Properties” in Chapter 3, Installation and System Considerations for Microsoft Windows.
A new subprogram, C$RBMenu, also can be used to define such a pop-up menu
temporarily. For details, see Appendix F, Subprogram Library.
New Subprograms for Windows

Several other new subprograms, which are supported only under Windows, have been
added in version 6.5. The C$GUICFG subprogram temporarily changes the RM/COBOL
graphical user interface. C$TBarEn enables and disables the toolbar buttons in the
RM/COBOL window. C$TBarSeq sets the bitmap sequence of a toolbar button in the
RM/COBOL window. For further details on these subprograms, see Appendix F,
Subprogram Library.
Window Style and the SYSTEM Non-COBOL Subprogram

The Windows version of RM/COBOL now allows you to set the style of the window
created when you use the SYSTEM non-COBOL subprogram. For more information, see
the SYSTEM Window Type property in Chapter 3, Installation and System
Considerations for Microsoft Windows.
Btrieve Adapter Enhancements

RM/COBOL version 6.5 for Windows 95 and Windows NT includes an rmbtrv32.dll,
which is the 32-bit version of the 16-bit rbadaptr.dll that was shipped with RM/COBOL
version 6.08 for Windows 3.1.
xliv Preface
rmbtrv32 supports the following RM/COBOL version 6 features: split keys, duplicate
prime keys, multiple record locks, record lock timeouts, and START with FIRST or
LAST. In addition, rmbtrv32 supports the RUN-INDEX-FILES DATA-COMPRESSION
and BLOCK-SIZE keywords, and rmbtrv32 returns expanded error codes for better error
reporting. rmbtrv32 also supports selected features of Btrieve version 6 and 6.1 files as
well as Btrieve version 6.15 MicroKernel Database Engines. rmbtrv32 supports the
Btrieve maximum of 119 key segments, repeating duplicates, and the no currency change
(NCC) option on insert and update operations.
Using repeating duplicates along with the NCC option should eliminate the possible
position-lost errors that could occur when a second user deleted records as the first user
was reading through them.
rmbtrv32 allows pre-created Btrieve files that have multiple alternate collating sequences
(ACS) defined, although all Btrieve keys that map to RM/COBOL keys must use ACS
number zero since COBOL defines one ACS per file.
Setting RUN-INDEX-FILES DATA-COMPRESSION=NO allows the user to have

rmbtrv32 create uncompressed Btrieve files (earlier versions of rbadaptr
always created compressed Btrieve files, which forced some users to pre-create
uncompressed files).
See Chapter 4, System Considerations for Btrieve, for further information on these
features.
Attached Configuration Files on Windows

The Attach Configuration utility (rmattach.exe) now allows configuration files to be
physically attached to rmcobol.exe, runcobol.exe, and recover1.exe under Windows.
When attached, a configuration file will be processed prior to any configuration file
specified with a command line option. For more information, see “Attach Configuration
Utility (rmattach)” in Appendix G, Utilities.
Built-In Configuration File under UNIX

The UNIX version of RM/COBOL allows a configuration file to be linked in to the
runtime system and compiler system. For more information, see “Built-In and Attached
Configuration Files” in Chapter 10, Configuration.
RM/COBOL User's Guide for 32-Bit Windows xlv

Year 2000 Subprogram
In order to facilitate updating RM/COBOL programs to handle the year 2000 issue, this
release provides a non-COBOL subprogram called C$Century. This subprogram
retrieves the first two digits of the current year. For example, for the year 1999, it will
return 19; for the year 2000, it will return 20. See Appendix F, Subprogram Library, for
more details.
C$RERR Eleven-Character Extended Status

The C$RERR subprogram has been enhanced to return an eleven-character extended
status when called with an eleven-character data item. The four-character extended status
returned in a four-character data item remains unchanged from previous versions of
RM/COBOL. See Appendix F, Subprogram Library, for details.
Improved recover1 Utility Program

The Indexed File Recovery utility program (recover1.exe) has several new
enhancements, including:
• Displaying information on why recovery may be required.
• The ability to display the last 98 or 30 error received when accessing the file, and the
date and time it occurred.
• Several options to control the amount of user interaction required.
• An option that allows the Open For Modify Count to be reset without performing a
full recovery.
For more information, see Appendix G, Utilities.
Enhanced rmmapinx Utility Program

The Map Indexed File utility program (rmmapinx.exe) includes two significant
improvements. It now displays the Open for Modify Count for an indexed file, and it
also displays the value of the last 98 or 30 error received while accessing the file. The
date and time that the error occurred is also available. In addition, this utility reports split
keys correctly.
xlvi Preface
Dynamically Configurable Prompt Character
ACCEPT statements may now specify a prompt character in the CONTROL phrase. The
specified character is used for that ACCEPT statement only; the default prompt character
is not changed. The PROMPT keyword is described under “CONTROL Phrase” in
Chapter 8, RM/COBOL Features.
Building Custom Products Using the customiz Shell Script

The User Makefile that was included in previous versions of the RM/COBOL
development system for UNIX has been replaced with a UNIX Bourne Shell script.
When executed, this script interactively obtains information about the product to be built
from the user and generates the appropriate Makefile. The user can then use this
Makefile to build the product. See Appendix D, Customizing RM/COBOL for UNIX, for
more information.
Indexed File Block Sizes After OPEN OUTPUT

The manner in which a block size is chosen for an indexed file when OPEN OUTPUT is
performed may differ from previous releases. See the description of the BLOCK
CONTAINS clause under “Indexed Files” in Chapter 8, RM/COBOL Features, for more
information.
DELETE FILE under UNIX

The DELETE FILE operation will now fail if the user does not have write permission for
both the file to be deleted and the directory containing the file.
Resolution of Program Names

The method used to resolve program names from environment variables has been changed
to the method used in earlier versions. The environment is now searched for a matching
name only after appending the extensions. This procedure is described in steps 5 through
7 in the section entitled “Subprogram Loading” in Chapter 8, RM/COBOL Features.
Compiler Support for External Access Methods

The RM/COBOL compiler now supports the use of external access methods (such as
RM/InfoExpress) to locate source files and copy files. See “EXTERNAL-ACCESS-
METHOD Record” in Chapter 10, Configuration.
RM/COBOL User's Guide for 32-Bit Windows xlvii

Deficiencies
When this user’s guide was printed, RM/COBOL for UNIX, Windows 95, Windows 98,
and Windows NT had the following deficiencies:
• RM/COBOL implements file and record locks through region locks. The algorithm
for computing the region to be locked is unique to RM/COBOL. This means that the
OPEN and READ statements only lock out other RM/COBOL applications; an
application not using the RM/COBOL file system can still access data in locked files.
This may cause inconsistent data when a file is shared between RM/COBOL
applications and other applications.
• RM/COBOL implements the WITH LOCK phrase of the OPEN statement and the
WITH NO LOCK phrase of the READ statement by applying region locks to
segments of the file. To ensure consistent results and to improve performance when
the WITH LOCK phrase is specified, the runtime system must recognize when two
distinct filenames identify the same file. This is accomplished under Windows by
resolving the user filename into a fully specified filename, including the remote
machine name when the file is remote. If a remote file resides on a UNIX server
accessed by Network File System (NFS), however, two very different filenames can
be associated with a single file through the ln command. This can cause a Windows
client program to read invalid data from the file or to diagnose file integrity errors.
Deficiencies that are version-specific or are discovered after printing are described in the
README files contained on the delivered media.
xlviii Preface
Deficiencies
Chapter 1: Introduction
This introductory section of the RM/COBOL User’s Guide provides an overview of the
RM/COBOL product. It explains the general concepts of the RM/COBOL compiler and
runtime system and how they are used, lists the additional add-on development tools that
are available to support RM/COBOL programs, describes how to rename program
executables, and explains file naming conventions.
RM/COBOL Software
RM/COBOL, delivered on appropriate media, contains a large number of individual
files and programs. The actual number of files and programs depends on the specific
version of the product you purchased and whether you purchased a development or a
runtime-only system. The delivered media contains one or more README files, which
list the actual files and programs delivered. Please check these README files after you
have installed the product to make sure that you have received all of the appropriate files
and programs.
RM/COBOL Compiler
The RM/COBOL compiler reads COBOL source code and produces object files that can
be executed using the runtime system. These object files are portable, and they can be
executed by an RM/COBOL runtime system on many computer configurations—even
computer configurations that are different from the one used to compile the object files.
For more information on compiling COBOL programs, see Chapter 6, Compiling.
RM/COBOL Runtime System

The RM/COBOL runtime system is used to execute compiled COBOL programs. Liant
Software Corporation provides a different runtime system for each supported computer,
and they help to insulate the COBOL programmer from the differences between
computers. The runtime system also includes a debugger to assist in developing COBOL
programs. For more information on running COBOL programs, see Chapter 7, Running.
RM/COBOL User's Guide for 32-Bit Windows 1-1

RM/COBOL Software
CodeWatch
CodeWatch is a standalone, source-level debugger for Windows that is included with the
RM/COBOL development system. CodeWatch supports easy debugging of any
applications without requiring that they be built under the RM/CodeBench or Enterprise
CodeBench development environments. CodeWatch uses true 32-bit Windows “look-
and-feel” and common Windows controls such as native toolbars, tree lists, progress
indicators, and spin buttons. For more information, see the CodeWatch manual.
CodeBridge
CodeBridge is a cross-language call system included with the RM/COBOL development
system. This facility simplifies communication between COBOL programs and non-
COBOL subprograms (such as those written in C or C++). CodeBridge allows COBOL
programmers to call external APIs or custom-developed subprograms without introducing
“foreign” language and data dependencies into their programs. For more information, see
the CodeBridge manual.
Internal Libraries and Utility Programs

The RM/COBOL runtime system also includes several built-in library routines to perform
functions not described in the COBOL standard. Among other things, these routines can
be used to determine information about program arguments, control the display screen,
and execute other (non-COBOL) programs. For more information, see Appendix F,
Subprogram Library.
There are several utility programs delivered with RM/COBOL. These utility programs
are used to manage and manipulate both data files and RM/COBOL object files. For
more information on the utility programs, see Appendix G, Utilities.
1-2 Introduction
CodeWatch
Add-On Packages
Several add-on packages are available from Liant Software Corporation to support
RM/COBOL programs. They include the following:
• Relativity. An integrated tool set that provides relational database functionality

for COBOL data without any application modifications or data conversions. It
also provides a full-featured, Microsoft Windows Open Database Connectivity
(ODBC)-compliant relational database engine that allows SQL-based access to
COBOL application data.
• Enterprise CodeBench. An integrated, graphical development environment for

developing RM/COBOL applications on UNIX within the Windows 95 and
Windows 98 environment.
• RM/InfoExpress. A file management system designed to optimize RM/COBOL

data file access on various local area networks (LANs) and wide area networks
(WANs). Implementations are available for TCP/IP (Transmission Control
Protocol/Internet Protocol) and Novell SPX/IPX (Sequenced Packet
Exchange/Internetwork Packet Exchange).
• VanGui Interface Builder. An interface builder that allows Visual Basic and
Delphi to serve as graphical user interface (GUI) front-ends to COBOL programs
running across a network.
• RM/Panels. A portable screen I/O package that allows WYSIWYG development of

RM/COBOL displays.
• Cobol-WOW (Windows Object Workshop). A visual tool for developing full-

featured Windows applications completely in RM/COBOL.
• Cobol-RPC (Remote Procedure Call). A tool for building distributed RM/COBOL

applications for LANs, WANs, and the Internet.
• Cobol-CGI (Common Gateway Interface). A tool for integrating RM/COBOL

applications with the Internet’s World Wide Web.

Add-On Packages
Renaming Executables
Some users may wish to rename one of the RM/COBOL executable programs (runcobol,
rmcobol, and recover1) after they have been installed. Some error and warning
messages for these executables are stored in corresponding message files. The default
names for these files are RUN.MSG, RMC.MSG, and REC.MSG, respectively.
In order to more gracefully handle renamed executables, the message filename may be the
same as the root name of the executable or the default name. In a standard installation,
for example, the RM/COBOL runtime will first search for a runcobol.msg file. If one
can not be found, the runtime system will search for a RUN.MSG file. If the runtime
executable were renamed to myapp (myapp.exe for DOS and Windows), the
RM/COBOL runtime would first search for myapp.msg.
File Naming Conventions

On those operating systems that support case-sensitive filenames, RM/COBOL filenames
can contain any combination of uppercase and lowercase letters, and numerals.
The Windows version of RM/COBOL, like Windows 95, Windows 98, and
Windows NT, supports long filenames and filenames containing embedded spaces.
RM/COBOL filenames can be enclosed in quotation marks (ASCII code 22 hex).
RM/COBOL filenames containing embedding spaces must be enclosed in quotation
marks to avoid having the embedded spaces interpreted as separators. For example:
"c:\My Source Directory\My COBOL Program.cbl"
Note Although Windows 95, Windows 98, and Windows NT store long filenames with
case preserved, filenames are always compared and searched for in a case-insensitive
manner (that is, filenames that differ only in whether letters are uppercase or lowercase
refer to the same physical file).
RM/COBOL uses the extensions .cbl, .cob, and .lst to designate the source, object and
listing files of a program. This allows all three files to reside in the same directory.
These extension names may be changed with the EXTENSION-NAMES configuration
record (see page 10-19).
Source files do not need to have an extension of .cbl; in fact, they do not need an
extension at all. If the compiler cannot locate the source file with the name given and the
name does not have an extension, it will try to locate the file again, using first .cbl as an
extension to the filename and then .CBL.
1-4 Introduction
Renaming Executables
The RM/COBOL compiler always creates object and listing files with extensions. It will
either replace the current extension of the source file, or append an extension if the source
filename does not have one. The case of the extension will match the case of the first
character of the source file’s extension, or the first character in the source file’s name if
there is no extension. If there is no extension and the first character of the source
filename is not a letter, the extension will be lowercase.
The RM/COBOL runtime system does not require object files to have an extension of
.cob. However, since the compiler generates objects with the .cob extension, the
runtime system will try to locate object files by adding first .cob and then .COB, but
only if the original filename does not already have an extension. Table 1-1 contains
sample filenames.
Table 1-1 Sample Filenames
Source Filename Resulting Object Filename

TESTFILE TESTFILE.COB
Testfile Testfile.COB
Test Test.COB
Test.Cbl Test.COB
Test.cbl Test.cob
test.xyz test.cob
test.XYZ test.COB
tESTFILE tESTFILE.cob
test test.cob
test.CBL test.COB
test.cbl test.cob
2TESTFIL 2TESTFIL.cob

1-6 Introduction
Chapter 2: Installation and
System Considerations for UNIX
This chapter lists the hardware and software required to install the RM/COBOL product,
describes how to install RM/COBOL, and provides information specific to using
RM/COBOL for UNIX-based operating systems.
Your computer configuration is the assembled set of hardware and software that makes up
your system. Before you can develop or run RM/COBOL programs, your configuration
must meet or exceed the requirements set forth in this chapter.
System Requirements
The version of RM/COBOL that you have purchased is for a particular combination of
hardware and operating system. Several items listed below vary depending on the actual
version of the product that you have purchased.
Required Hardware
• Memory. The amount of memory depends on the specific version of the product that
you have purchased.
• Hard Disk. A hard disk drive is required for installing this product. The amount of
space required is version-specific. The average minimum disk space required to
install this product is 3 megabytes (3 MB) for a development system and 2.5
megabytes (2.5 MB) for a runtime system.
• Removable Media. Some form of removable media (magnetic tape or floppy disk)
is required for installing this product. The type of media is version-specific.
• Terminal. A terminal with a minimum capacity of 80 columns.

System Requirements
System Installation
RM/COBOL is delivered on media suitable for your configuration. In order to use this
product, you must install the contents of the distribution media onto your hard disk.
The delivered media contains compressed files. This allows Liant to use fewer floppies in
a distribution set and also speeds up the install time. The files are compressed or
decompressed using the GNU gzip and gunzip programs. A copy of these programs or
the source is available from the Free Software Foundation (FSF), which can be accessed
from CompuServe (using GO UNIXFORUM) or from the Internet (using “anonymous
ftp” from prep.ai.mit.edu). The COPYING.gnu file is a copy of the GNU General Public
License. Use the cat or pg commands to review the file contents. If you do not have
access to these online services, FSF provides a copy of the source for a minimum media
handling charge. A copy of the source also may be obtained from Liant Software
Corporation.
Note Installation information specific to your UNIX system can be found on the media
label.
To install RM/COBOL on your operating system, take the following steps.
1. Log in as root.
2. The amount of disk space required to install this product is noted on the media
envelope label. You can check the availability of space on your system by executing
the following command:
df
3. Create an empty directory in which you want to install RM/COBOL. For example:
mkdir /usr/rmcobol
cd /usr/rmcobol
4. Copy the contents of the distribution media (all volumes) onto your hard disk. Use
the cpio command on the distribution media to copy the files.
5. Issue the following command to install RM/COBOL. This command performs the
necessary steps to copy the proper files into the system command directory (/usr/bin)
and to decompress the data files.
./rminstall
2-2 Installation and System Considerations for UNIX

System Installation
During the execution of this command, you are asked whether you want to install the
termcap or terminfo version of runcobol and recover1 (see “Terminal Interfaces” on
page 2-9 for more information). Messages appear periodically indicating the status
of the installation.
RM/COBOL is distributed with a default configuration that will satisfy your system
requirements. Configuration options for your system are found in Chapter 10,
Configuration.
Locating RM/COBOL Files
File Locations Within Operating System Pathnames

File locations are determined by the pathname of the file, according to operating system
rules and conventions. A fully qualified pathname consists of an optional directory path
with slash separators followed by a filename. The directory path may begin with a
leading slash, tilde (~), or period (.) character. A directory path with a leading slash or
tilde is fully specified and identifies a filename relative to the root file system. A
directory path without a leading slash or tilde character specifies a filename relative to the
current directory.
If a pathname is specified without a directory path, RM/COBOL searches the current

directory.
Specifying a directory path with a leading slash or tilde indicates to RM/COBOL that an
exact filename has been specified. If RM/COBOL cannot find the file in the specified
location, it will not look elsewhere. If you do not specify a directory path, and
RM/COBOL cannot find the file relative to the current directory, it will search for the file
according to the directory search sequence. If a directory path is specified, but there is no
leading slash or tilde, then the EXPANDED-PATH-SEARCH keyword of the
RUN-FILES-ATTR configuration record determines whether the directory search
sequence will be used. When the configuration keyword is set to its default value of NO,
the directory search sequence will not be used (see page 10-27). If the value is set to
YES, then the entire name, including the directory path, will be appended to each entry in
the directory search sequence in an attempt to locate the file.
The tilde (~) character at the beginning of a pathname is used to refer to home directories.
Standing alone, it expands to the user’s home directory as reflected in the environment
variable HOME. When followed by a name consisting of letter and digit characters, the
name identifies the user whose home directory should be used.

Directory Search Sequences
You can direct RM/COBOL to search for a file not found in the current working directory
by using a predefined directory search sequence. There are two directory search
sequences: one for the compiler and one for the runtime system.
To direct the RM/COBOL compiler to use the directory search sequence, set the
environment variable RMPATH as follows:
RMPATH=path[:path] ... ; export RMPATH
To direct the RM/COBOL runtime system to use the directory search sequence, set the
environment variable RUNPATH as follows:
RUNPATH=path[:path] ... ; export RUNPATH
In both commands, path indicates the directory that is to be searched for the file and has
the form:
[/]directory[/directory ] ...
directory is the name of an existing directory.
If multiple paths are specified, they must be separated with colons. If the file is not
located in the current directory or the explicitly defined paths and if the file should be
created, then the file is created in the current directory. Figure 2-1 and Figure 2-2
illustrate the compiler and runtime system search sequences, respectively.
Figure 2-1 Compiler Search Sequence
Look first in this directory:
RMPATH=WAGE/HOURLY/OVERTIME:/usr/local/cobol
Then look in this directory:
Figure 2-2 Runtime System Search Sequence
Look first in this directory:
RUNPATH=usr/local/cobol:~
Then look in this directory:

The compiler and runtime system may be executed from a directory other than the current
directory if a complete pathname is specified in the command line, or if the PATH
directory search feature is used. If a complete pathname is not specified, the list of
directories specified by PATH are searched. Note that the current directory is not
implicitly searched with the PATH environment variable.
The compiler, runtime system, and recovery utility (recover1.exe) require access to other
files in order to operate. These include the message files (RMC.MSG, RUN.MSG, and
REC.MSG), and, for the compiler, the compiler overlay file rmcobol.ovy. RM/COBOL
looks for these files first in the directory containing the executable file, then in the current
directory, and finally in the directories specified in the PATH environment variable.
The compiler overlay file is located by the compiler, not by the operating system. The
compiler will attempt to locate the overlay file first in the directory containing the
compiler executable, then in the current directory, and finally in the directories specified
in the PATH environment variable. After locating the overlay file, the compiler will use
the compiler directory search sequence to locate all other files.
Note On some versions of UNIX, it is impossible to determine the directory that

contains the executable file when that directory is specified on the command line.
File Access Names

The file access name you specify in the COBOL source program specifies the physical
file or device to which input or output is directed. For information on specifying the
file access name in a COBOL source program, see the discussion of the ASSIGN
clause (file control entry) in Chapter 3, Environment Division, and the discussion of the
VALUE OF clause in Chapter 4, Data Division, of the RM/COBOL Language Reference
Manual.
To establish synonymity between a file access name specified in your source program and
another name specified when the program is run, use environment variables that are set
before starting the runtime system.
If you specified a generic file access name for program input-output and wish to direct it
to a specific device or file, enter:
file-access-name = file-access-name-2;
export file-access-name-1

A generic file access name is one that does not specify a directory path. Since the format
of physical pathnames, including conventions of directory names, varies from one
operating system to another, for maximum portability it is recommended that source
programs specify generic file access names, preferably with eight or fewer letters. This
recommendation applies only when the file access name is hard coded into the program as
a literal.
For example, if the file control entry specifies:
SELECT REPORT-FILE ASSIGN TO PRINT, "report"
and no environment variable named “report” exists, RM/COBOL will create a file named
report in the current directory.
If, prior to running the program, you enter the command:
REPORT=/dev/lp; export report
all program output written to REPORT-FILE will be written to /dev/lp.
If—again prior to execution—you enter the command:
REPORT=/output/audit.lst; export report
RM/COBOL will create a file audit.lst in the directory /output without any need to
modify or recompile the source program.
The RESOLVE-LEADING-NAME and RESOLVE-SUBSEQUENT-NAMES keywords

of the RUN-FILES-ATTR configuration record can be used to force resolution of one or
more of the directory names from the environment. For more information, see the
discussion of the RUN-FILES-ATTR record beginning on page 10-26.
When environment variables are not used, the file access name in the COBOL program
specifies the UNIX filename. The effect of a prior environment variable assignment may
be canceled by the command:
unset file-access-name
Whether or not an environment variable is used to modify the file access name, if the
resulting file access name does not include a directory path, RUNPATH will be used by
the runtime system to obtain the fully qualified pathname (see “File Locations Within
Operating System Pathnames” on page 2-3 for additional information).

When the resulting file access name is PRINTER or PRINTER1, then the default
configuration writes the file to the print spooler. See “Printer Support” on page 8-46 for
additional information on printing.
When the resulting file access name is TAPE, then the default configuration writes the file
to the default tape device. See “Tape Support” on page 8-47 for additional information
on tape devices.
The DEFINE-DEVICE configuration record may define other file access names that are
to be treated as devices and also may change the default treatment of PRINTER and
TAPE. See “DEFINE-DEVICE Record” on page 10-16 for additional information on
configuring file access names that are to be treated as devices.
The resulting file access name should follow the operating system rules for valid
filenames and pathnames.
Other System Considerations
Memory Available for a COBOL Run Unit

The memory available for a run unit in the operating system environment is
implementation specific. If the total memory required by a run unit exceeds the amount
of available memory, runtime system errors will occur. These errors indicate the inability
to obtain enough memory to perform a desired operation. The RM/COBOL runtime
system does not provide a virtual memory scheme, although your system may.
Segmentation and subprograms should be used to manage the dynamic memory

requirements of very large run units.
Most modern UNIX systems (for example, BSD, System V, Sun OS) are supplied with
built-in virtual memory systems. These systems make it appear as though there is always
sufficient memory for the runtime system, regardless of how much physical RAM is
installed in the machine.
A small number of UNIX machines (for example, the NCR Tower systems), are
configured by the manufacturer to limit the maximum size of a program to less than
10 MB (2 MB in the case of the NCR Tower range). This limitation is enforced
regardless of the availability of physical RAM. Execution of the runtime system on such
machines can lead to unpredictable results. Moreover, it is not uncommon for the runtime
system to terminate with the following message:
Segmentation fault: core dumped

There is no known solution to this problem except to adjust the UNIX kernel parameter
MAXUMEM to a more reasonable value (for example, 16 MB or 32 MB) and then
rebuild the kernel. The method of performing this task varies among different UNIX
systems. Contact your UNIX system supplier for details.
Number of Files
The operating system determines the number of files a run unit is allowed to open. The
maximum number of files that may be opened is three fewer than the maximum number of
open files per process. Most UNIX systems allow this maximum to be changed by
reconfiguring the kernel.
Number of Region Locks

The runtime system uses the operating system region lock facility to provide file level
locking and to control file sharing, as well as to support record locking. To implement
file locking, the runtime system applies one region lock to each open file in addition to
the locks applied for record locks. During an I/O statement, one or two additional region
locks may be applied to a single file. If the program employs multiple record locking,
these region locks remain until the program unlocks the records.
Network File Access

It is possible to receive a 98,27 error when accessing an indexed file through the network
file system (NFS) when logged in as super-user (or root). If the file permissions do not
include write permission for “other”, an open operation may inadvertently succeed for
modes other than input mode. This is misleading because writes to the file will appear to
succeed, even though the data is not updated. This problem is undetectable and will
appear as a 98,27 error on the next access of the file after writing or deleting a record.

Terminal Input and Output
This section describes how terminal input and output is handled by the RM/COBOL
runtime system.
Terminal Interfaces
The runtime system uses one of two terminal interface mechanisms, termcap or terminfo,
to control cursor positioning, video display attributes, and function key mapping.
The termcap version of the runtime system uses the older termcap database, which has
a description of the user’s terminal in it. See “Termcap Database” on page 2-10 for
more information.
The terminfo version of the runtime system uses the terminal description in the terminfo
database for both input and output control of the terminal. See “Terminfo Database” on
page 2-11 for more information.
Both the termcap and terminfo versions of the runtime system are present on the
distribution media. During the installation process you will be asked which version to
install. To switch to the other interface, you must either install RM/COBOL again or use
the customiz utility as described in Appendix D, Customizing RM/COBOL for UNIX.
Cursor Types
The termcap and terminfo versions of the runtime system support two types of cursors,
each of which indicates a different edit mode during ACCEPT operations.
1. The attribute cursor_normal (or cursor-on) indicates that standard overtype mode is
active.
2. The attribute cursor_visible (or cursor-blink) indicates that insert mode is active.
Terminal Attributes
Some terminals under UNIX require that special characters appear on the screen just
before the start of an attribute and right after the end of it. Characters in between these
special characters take on the specified attribute. To accommodate these terminals, the
oV capability for termcap specifies the number of screen positions to be used by the nM,
nB, nR, nS, aL, aB, aR, aS and rS capabilities. The xmc capability is used for the
terminfo runtime system. RM/COBOL places the attribute characters at the position
specified by the ACCEPT or DISPLAY operation, and moves the actual start of the field
by the number of positions specified by oV or xmc. If you want, you can use the keyword
MOVE-ATTR with the TERM-UNIT configuration record to specify moving the

attributes back the number of positions specified by oV or xmc. However, if
MOVE-ATTR causes the attribute character to move back to the next line, and such a
move is prohibited by the lA (do not cross lines) capability described in the next
paragraph, the attribute will appear on the same line that is being displayed or accepted.
The lA is a Boolean termcap capability and is used with terminals that require screen
positions to implement attributes, as described in the preceding paragraph. The standard
RM/COBOL model is to keep an attribute in effect—without regard to the number of
screen lines to which it applies—until it encounters the special character that signals the
end of the attribute. Some terminals, however, recognize the end of a line as the end of
the attribute, without regard to the presence or absence of the ending special character. In
this case, the presence of lA will tell RM/COBOL that a new attribute character must be
placed at the start of every new line in a multiline ACCEPT or DISPLAY operation.
The sA is a Boolean termcap capability that is also used with terminals that require screen
positions to implement attributes. The RM/COBOL model is to assume that attributes
will not wrap from the bottom to the top of the screen. If your terminal behaves
differently, and if you have specified the MOVE-ATTR configuration keyword, use sA.
This allows fields placed at the home position (line 1, position 1) to have their attributes
placed at the last line of the screen.
Termcap Database
The runtime system locates the termcap database by first looking for the environment
variable TERMCAP. If the TERMCAP environment variable is found and contains a
valid pathname, that value is used as the pathname to the database. If the environment
variable is found but it contains a valid termcap entry, that entry will be used as the
terminal description. Otherwise, the filename /etc/termcap will be used as the name of
the database.
The TERMCAP environment variable can be set as follows:
TERMCAP=p a t h n a m e ; export TERMCAP
pathname is a pathname of the termcap file.
For example:
TERMCAP=/usr/sales/mytermcapfile; export TERMCAP

Terminfo Database
The runtime system locates the terminfo database by first looking for the environment
variable TERMINFO. If the TERMINFO environment variable is found, that value is
used as the pathname to the database subdirectories. Otherwise, the path /usr/lib/terminfo
will be used.
The TERMINFO environment variable can be set as follows:
TERMINFO=p a t h n a m e ; export TERMINFO
pathname is a pathname of the terminfo file.
For example:
TERMINFO=/usr/sales/myterminfo; export TERMINFO
Termcap and Terminfo
The name of the database entry that describes the behavior of your terminal is obtained
from the environment variable TERM. This variable should be set to the appropriate
terminal name before invoking the runtime system. The TERM environment variable can
be set as follows:
TERM=t e r m - n a m e ; export TERM
term-name is the name of your terminal as it appears in the termcap or terminfo

database. The termcap or terminfo capabilities used by the runtime system (if
present) are listed in the tables that follow.
Table 2-1 describes the information from the terminfo and termcap databases that the
runtime system uses.

Table 2-1 Terminfo and Termcap Names for the Runtime System
Terminfo Termcap
Name Name Description
Booleans
am am Terminal has automatic margins.
bce be Screen erased with background color.
xenl xn Newline ignored after 80 columns. Also used to
signify that the terminal’s cursor will not
automatically advance to the next line after column 80
is reached, but will instead wait for the next character.
Numbers
cols co Number of columns in a line.
lines li Number of lines on screen or page.
pb pb Lowest baud where padding is needed.
xmc sg Number of blank characters left by smso or rmso.
Output Strings
acsc ac Graphic charset pairs.
batt1 Attributes for box characters—primary set (AIX
systems only).
batt2 Attributes for box characters—alternate set (AIX
systems only).
box1 Box characters—primary set (AIX systems only).
box2 Box characters—alternate set (AIX systems only).
bel bl Audible signal (bell).
blink Turn on blinking.
civis vi Make cursor invisible.
clear cl Clear screen and home cursor.
cnorm ve Make cursor appear normal (undo vs/vi).
cr cr Carriage return.

Table 2-1 Terminfo and Termcap Names for the Runtime System (Cont.)
Terminfo Termcap
Output Strings
cub1 le Move cursor left one space.
cud1 do Down one line.
cuf1 nd Nondestructive space (cursor right).
cup cm Cursor motion.
cuu1 up Upline (cursor up).
cvvis vs Make cursor very visible—insert mode.
dim Turn on half-bright mode.
ed cd Clear to end of display.
el ce Clear to end of line.
enacs eA Enable alternate character set.
home ho Home cursor.
ko Termcap entries for other non-function keys.
ind sf Scroll text up.
pad pc Pad character (rather than null).
op op Set all colors to the original color pairs.
rev Turn on reverse video mode.
rmacs ae End alternate character set.
rmcup te String to end programs that use cup.
rmso se End of standout mode (if no nM or sgr0).
is Terminal initialization string.
rs1 r1 Terminal reset/initialization string 1.
setb Sb Set current background color.
setf Sf Set current foreground color.
sgr Define video attributes, 1 through 9.
sgr0 me Turn off all attributes.
smacs as Start alternate character set.
smcup ti String to begin programs that use cup.
tc Entry of similar terminal.
xenl xn Newline ignored after 80 columns.

Table 2-2 describes the input sequences that may be handled by the terminfo package.
For convenience, the corresponding termcap name is also given. These terminfo names
are also the only names that will be recognized when using the TERM-INPUT
configuration feature of the runtime system. Termcap names other than the ones listed in
the table can be used.
Table 2-2 Input Sequences for Terminfo and Termcap
Terminfo Termcap
Input Strings
ka1 K1 Upper-left of keypad.
Ka3 K3 Upper-right of keypad.
Kb2 K2 Center of keypad.
Kbeg @1 Sent by beginning key.
Kbs kb Sent by backspace key.
Kc1 K4 Lower-left of keypad.
Kc3 K5 Lower-right of keypad.
Kcan @2 Sent by cancel key.
Kclo @3 Sent by close key.
Kclr kC Sent by clear screen or erase key.
Kcmd @4 Sent by command key.
Kcpy @5 Sent by copy key.
Kcrt @6 Sent by create key.
Kctab kt Sent by clear-tab key.
Kcub1 kl Sent by terminal left arrow key.
Kcud1 kd Sent by terminal down arrow key.
Kcuf1 kr Sent by terminal right arrow key.
Kcuu1 ku Sent by terminal up arrow key.
Kdch1 kD Sent by delete character key.
Kdl1 kL Sent by delete line key.
Ked kS Sent by clear-to-end-of-screen key.
Kel kE Sent by clear-to-end-of-line key.
Kend @7 Sent by end key.
Kent @8 Sent by enter/send key.
Kext @9 Sent by exit key.
Kf0 k0 Sent by function key f0.
Kf2 k2 Sent by function key f2
kf3 k3 Sent by function key f3.

Table 2-2 Input Sequences for Terminfo and Termcap (Cont.)
Terminfo Termcap
Input Strings
kf10 k; Sent by function key f10.
kf11 F1 Sent by function key f11.
kf20 FA Sent by function key f20.
kf21 FB Sent by function key f21.
kf22 FC Sent by function key f22.
kf23 FD Sent by function key f23.
kf24 FE Sent by function key f24.
kf25 FF Sent by function key f25.
kf26 FG Sent by function key f26.
kf27 FH Sent by function key f27.
kf28 FI Sent by function key f28.
kf29 FJ Sent by function key f29.
kf30 FK Sent by function key f30.
kf31 FL Sent by function key f31.
kf32 FM Sent by function key f32.
kf33 FN Sent by function key f33.
kf34 FO Sent by function key f34.
kf35 FP Sent by function key f35.
kf36 FQ Sent by function key f36.
kf37 FR Sent by function key f37.
kf38 FS Sent by function key f38.

Terminfo Termcap
Input Strings
kf39 FT Sent by function key f39.
kf40 FU Sent by function key f40.
kf41 FV Sent by function key f41.
kf42 FW Sent by function key f42.
kf43 FX Sent by function key f43.
kf44 FY Sent by function key f44.
kf45 FZ Sent by function key f45.
kf46 Fa Sent by function key f46.
kf47 Fb Sent by function key f47.
kf48 Fc Sent by function key f48.
kf49 Fd Sent by function key f49.
kf50 Fe Sent by function key f50.
kf51 Ff Sent by function key f51.
kf52 Fg Sent by function key f52.
kf53 Fh Sent by function key f53.
kf54 Fi Sent by function key f54.
kf55 Fj Sent by function key f55.
kf56 Fk Sent by function key f56.
kf57 Fl Sent by function key f57.
kf58 Fm Sent by function key f58.
kf59 Fn Sent by function key f59.
kf60 Fo Sent by function key f60.
kf61 Fp Sent by function key f61.
kf62 Fq Sent by function key f62.
kf63 Fr Sent by function key f63.
kfnd @0 Sent by find key.
khlp %1 Sent by help key.
khome kh Sent by home key.
khts kT Sent by set-tab key.
kich1 kI Sent by insert character/enter insert mode key.
kil1 kA Sent by insert line.
kind kF Sent by scroll-forward/down key.
kll kH Sent by home-down key.
kmov %4 Sent by move key.
kmrk %2 Sent by mark key.

Terminfo Termcap
Input Strings
kmsg %3 Sent by message key.
knp kN Sent by next-page key.
knxt %5 Sent by next-object key.
kopn %6 Sent by open key.
kopt %7 Sent by options key.
kpp kP Sent by previous-page key.
kprt %9 Sent by print key.
kprv %8 Sent by previous-object key.
krdo %0 Sent by redo key.
kref &1 Sent by reference key.
kres &5 Sent by resume key.
krfr &2 Sent by refresh key.
kri kR Sent by scroll-backward/up key.
krmir kM Sent by exit insert mode key.
krpl &3 Sent by replace key.
krst &4 Sent by restart key.
ksav &6 Sent by save key.
kslt *6 Sent by select key.
kspd &7 Sent by suspend key.
ktbc ka Sent by clear-all-tabs key.
kund &8 Sent by undo key.
kBEG &9 Sent by shifted beginning key.
kCAN &0 Sent by shifted cancel key.
kCMD *1 Sent by shifted command key.
kCPY *2 Sent by shifted copy key.
kCRT *3 Sent by shifted create key.
kDC *4 Sent by shifted delete-char key.
kDL *5 Sent by shifted delete-line key.
kEND *7 Sent by shifted end key.
kEOL *8 Sent by shifted clear-line key.
kEXT *9 Sent by shifted exit key.
kFND *0 Sent by shifted find key.
kHLP #1 Sent by shifted help key.
kHOM #2 Sent by shifted home key.
kIC #3 Sent by shifted input key.

Terminfo Termcap
Input Strings
kLFT #4 Sent by shifted left arrow key.
kSAV !1 Sent by shifted save key.
kSPD !2 Sent by shifted suspend key.
kUND !3 Sent by shifted undo key.
kMSG %a Sent by shifted message key.
kMOV %b Sent by shifted move key.
kNXT %c Sent by shifted next key.
kOPT %d Sent by shifted options key.
kPRV %e Sent by shifted prev key.
kPRT %f Sent by shifted print key.
kRDO %g Sent by shifted redo key.
kRPL %h Sent by shifted replace key.
kRIT %i Sent by shifted right arrow key.
kRES %j Sent by shifted resume key.
lf0 l0 Labels on function key f0 if not f0.
lf10 la Labels on function key f10 if not f10.
nel nw Sent by newline key.

Table 2-3 describes the additional Boolean capabilities used by RM/COBOL when
accessing the termcap database.
Table 2-3 Additional Boolean Capabilities
Termcap
Name Description
lA Attributes will not wrap lines.
sA Attributes will wrap screen.
Table 2-4 describes the additional output string capabilities used by RM/COBOL when
Table 2-4 Additional Output String Capabilities
Termcap
Name Description
aB Low intensity blink.
Ab Low intensity underline and blink.
aL Low intensity.
Al Low intensity underline.
aR Low intensity reverse.
aS Low intensity blink and reverse.
nB High intensity blink.
Nb High intensity underline and blink.
nM High intensity.
Nm High intensity underline.
nR High intensity reverse.
nS High intensity blink and reverse.
vr End of field.

Table 2-5 describes the additional numeric capabilities used by RM/COBOL when
Table 2-5 Additional Numeric Capabilities
Termcap
Name Description
oV Number of blank characters left by additional RM/COBOL attribute
capabilities.
The Boolean capabilities sA and lA cannot be added to the terminfo database since it is a
closed system; these capabilities are not used by the terminfo runtime system. Under
runtime systems that use terminfo for output, the xmc numeric capability determines the
width of attribute characters and the starting position of fields. Specifying xmc#0
indicates a physical attribute terminal for which the attributes do not occupy a screen
position but still must be written at the physical start and end of each field.
Runtime systems that use the terminfo database directly for output sequences will use the
set_attributes or sgr string for all field attributes, if it is available. The terminfo
set_attributes string has nine parameters or attributes that can be set. RM/COBOL makes
use of six of these parameters. The second parameter is set if the underline attribute is
requested. The third parameter is set if the reverse attribute is requested. The fourth
parameter is set if the blinking attribute is requested. The fifth parameter is set if the
low-intensity attribute is used. The sixth parameter is set if the high-intensity attribute is
used. The ninth parameter may be used when line draw characters are requested for
pop-up window borders. The only exception to requesting line draw characters in this
manner is in terminals where xmc and sgr are specified (for example, physical attribute
terminals). On these terminals the alternate character set attribute can either be a field
attribute or a single character attribute. Because the terminfo database does not indicate
how to determine this behavior for a terminal, RM/COBOL will infer that the terminal has
the alternate character set as a single character attribute, if the smac definition is in the
terminfo database for the terminal. In this case, the smacs and rmacs sequence will be
used for the writing of graphics or alternate character set data and the ninth parameter will
always be specified as off.
Each of the sgr parameters is set to one if an ACCEPT or DISPLAY requests the
corresponding attribute. Otherwise, a zero is set for the parameter. A zero is also set for
all other parameters.
Attributes are reset by using the sgr0 string if it is defined. Otherwise, they are reset
using all zeroes as parameters to the set_attributes string.

If the set_attributes string is not available, the standard terminfo strings listed in
Table 2-6 will be used.
Table 2-6 Standard Terminfo Strings
Terminfo
Name Description
blink High intensity blink.
dim Low intensity.
rev High intensity reverse video.
rmacs End alternate character set.
rmso Reset attributes (also used for high intensity if no sgr0).
sgr0 High intensity.
smacs Start alternate character set.
smso High intensity (if no sgr0 or rmso).
If color keywords are specified in the CONTROL phrase, the terminfo setf or setb
sequence will be used to set the foreground or background color. These sequences accept
a single numeric parameter indicating the desired color. If these sequences are not
already defined for your terminal and you wish to define them, the association of colors to
color numbers is normally defined in the C include file, curses.h.
If line draw characters are requested for either pop-up window borders, or because the
GRAPHICS keyword in the CONTROL phrase was specified in an ACCEPT or
DISPLAY statement, the terminfo database is examined for the acsc sequence or the box1
and box2 sequences. UNIX systems provide the acsc string to map generic (vt100) line
draw characters to the correct characters for your terminal. These characters are then
enabled through the ninth sgr parameter (see page 2-20). To support double-line draw
characters, RM/COBOL has extended the acsc string to include six more mappings.
These mappings extend the generic (vt100) characters by describing the double-line
graphic characters with the corresponding uppercase letters, as shown in Table 2-7.
AIX systems describe line draw graphic characters through the box1 and box2 sequences
in the terminfo file. In addition, if the first character of batt1 or batt2 is f, the ninth sgr
parameter will be set when writing the box1 or box2 line draw characters, respectively.

Table 2-7 vt100 Line Graphic Characters
Description Single-Line Character Double-Line Character

lower-right corner j (») J (Î)
upper-right corner k (¹) K (È)
upper-left corner l (¸) L (Å)
lower-left corner m (º) M (Ë)
horizontal line q (¶) Q (Á)
vertical line x (·) X (Â)
Redirection of Input and Output

RM/COBOL supports standard piping and standard redirection of input and output.
The use of the redirection and piping operators (>, >> , < and | ) on the Runtime
Command line affects the operation of ACCEPT and DISPLAY statements in several
ways. Piping is a means of chaining the standard output (DISPLAY statements) of one
run unit to the standard input (ACCEPT statements) of a second run unit; therefore,
piping appears identical to redirection at the program level. Note that a Format 1
ACCEPT or DISPLAY statement that includes the FROM/UPON CONSOLE phrase or
FROM/UPON mnemonic-name phrase where mnemonic-name is defined as CONSOLE
IS mnemonic-name, is not redirected or piped unless it is configured to come from
standard input or go to standard output. If this is not the case, you must use either 2> or
2>> for redirection. Note also that if an ACCEPT or DISPLAY statement contains a
UNIT phrase, it will not be redirected.
Standard Input
The standard input device is defined by default to be the keyboard of the terminal that
started the run unit. Standard input may be redirected to a file or other device by the
operating system conventions for standard input redirection and piping on the command
line that starts the run unit.

For example:
runcobol getdata <inputfile
redirects standard input to the file inputfile and
runcobol putdata | runcobol getdata
pipes the standard output from program putdata to the standard input of program
getdata.
ACCEPT statements that do not specify the FROM CONSOLE phrase read from the
standard input device.
When standard input is redirected, the ACCEPT statement (Formats 1 and 3) operation is
modified. Only the SIZE, CURSOR, ECHO, CONVERT and ON EXCEPTION phrases
of Format 3 are used; all other phrases are ignored. Note that Format 1 ACCEPT
statements with numeric operands are treated as Format 3 ACCEPT statements unless the
program containing the ACCEPT statements was compiled with the M Compile
Command Option (see page 6-11).
At the beginning of each ACCEPT statement, the next record is read from standard input
into the ACCEPT buffer. The following operations take place for each of the receiving
data items in the ACCEPT statement:
1. If there are no characters in the ACCEPT buffer, the next record is read from
standard input into the ACCEPT buffer.
2. If the number of characters in the ACCEPT buffer does not exceed the size of the
current receiving item, those characters are transferred to the receiving item in the
appropriate format (that is, left justified, space fill for all Format 1 and for
alphanumeric Format 3, and with appropriate conversion for numeric Format 3).
3. If the number of characters in the ACCEPT buffer exceeds the size of the current
receiving item, only the leftmost “size” characters are transferred, as described in the
previous operation. The characters that remain in the ACCEPT buffer are used for
the next receiving item or are discarded if the current receiving item is the last
receiving item in the ACCEPT statement.
Note Where numeric sending and receiving data items are used with piping,
the use of the CONVERT phrase with DISPLAY and ACCEPT statements is
strongly recommended.

The M Runtime Command Option (see page 7-4) modifies the operation of Format 1
ACCEPT statements to conform to Level 2 ANSI semantics. The actions described
above are modified as follows:
1. If the number of characters in the ACCEPT buffer does not equal or exceed the size
of the current receiving item, one or more records are read from standard input and
are concatenated until there are enough characters.
2. The leftmost “size” characters are transferred as described in steps 2 and 3 on the
preceding page. The characters that remain in the ACCEPT buffer are discarded.
Note that the use of the M Runtime Command Option requires close matching of
ACCEPT and DISPLAY statements when used with piping.
Also note that the M Runtime Command Option affects the operation of Format 1
ACCEPT statements which are not redirected; the console operator is required to enter
enough characters to fill the receiving item. If the Enter key is pressed before enough
characters have been entered, the request will be reissued until the concatenation of the
characters entered is sufficient to fill the receiving item.
The M Runtime Command Option does not affect the operation of Format 3 ACCEPT
statements.
An end-of-file condition is reported to Format 3 ACCEPT statements as an exception

variable of 64 (Send). If an end-of-file condition occurs and there is no ON
EXCEPTION phrase, a runtime system error is reported and execution ends.
Standard Output
The standard output device is defined by default to be the monitor of the terminal that
started the run unit. Standard output may be redirected to a file or other device by the
operating system conventions for standard output redirection and piping on the command
line that starts the run unit.
For example:
runcobol putdata >outputfile
redirects standard output to the file outputfile and
runcobol putdata | runcobol getdata
pipes the standard output from program putdata to the standard input of
program getdata.

DISPLAY statements that do not specify the UPON or UPON CONSOLE phrase write to
the standard output device.
When standard output is redirected, all phrases, except SIZE and CONVERT, of the
Format 2 DISPLAY statement are ignored. All sending operands are concatenated
(within the limits of the ACCEPT/DISPLAY buffer as described in the following
paragraphs) and are transferred to standard output as one or more records.
A Format 1 DISPLAY statement generates one record and may generate more than one
record, depending on the presence or absence of the M Runtime Command Option (see
page 7-4). If the M Option is not present in the Runtime Command, all sending operands
are concatenated, the resulting operand is truncated to the DISPLAY buffer size, and a
single record is written. If the M Option is present, all sending operands are concatenated
and the resulting operand is split into zero or more records equal in length to the
DISPLAY buffer size, along with a final record no longer than the DISPLAY buffer size.
If a Format 2 DISPLAY statement is redirected, one or more records are generated,

depending on the size of the discrete sending items. If the size of the sending operand
does not exceed the space remaining in the DISPLAY buffer, the sending operand is
appended to the current buffer and the DISPLAY buffer is written if the sending operand
is the last operand. If the size of the sending operand exceeds the space remaining in the
DISPLAY buffer, the current DISPLAY buffer is written and the sending operand is
truncated to the size of the DISPLAY buffer. The new DISPLAY buffer contents are
written if the sending operand is the last operand.
Standard Error
The standard error device is defined by default to be the monitor and keyboard.
Interactive debug input and output, STOP literal statements, and runtime system
messages are directed to the standard error device. These operations can be redirected by
a configuration option; see the discussion of the ERROR-MESSAGE-DESTINATION
keyword that begins on page 10-25.
These operations also can be redirected using the operating system standard-error
redirection convention on the command line that starts the run unit.
For example:
runcobol putdata 2>error.out
To direct standard output and standard error to the same destination, specify:
runcobol putdata >all.out 2>&1

Chapter 3: Installation and
System Considerations for
Microsoft Windows
This chapter lists the hardware and software required to install the RM/COBOL
product, describes how to install RM/COBOL, and provides information specific to
using RM/COBOL with Microsoft Windows 95, Windows 98, and Windows NT
operating systems.
Your computer configuration is the assembled set of hardware and software that makes up
your system. Before you can develop or run RM/COBOL programs, your configuration
must meet or exceed the requirements set forth in this chapter.
System Requirements
RM/COBOL runs on the IBM PC and full compatibles. Appropriately licensed versions
run in conjunction with Client for Microsoft Networks or Novell NetWare software to
provide support for multiuser file access.
Required Hardware
• IBM PC or compatible machine with an 80486-class processor or higher.
• A mouse or other pointing device.
• Eight megabytes of random-access memory (RAM). (Sixteen megabytes are

recommended.)
• VGA (640x480) or compatible display. (An 800x600 or better super-VGA display is

recommended.)
• A double-sided, high-density 3.5-inch floppy disk drive for program installation.
• Network adapter (for multiuser configurations)

System Requirements
Required Software
One of the following operating systems is required:
• Microsoft Windows 95
• Microsoft Windows 98
• Microsoft Windows NT version 4.0
Local Area Network (LAN) Software
To provide multiuser access, one or both of the following network programs is required:
• Novell NetWare version 3.11 or later
• Client for Microsoft Networks for Windows 95, Windows 98, or Windows NT
version 4.0
Btrieve Software
To access local Btrieve files, the following software is required:

• Btrieve for Windows NT/Windows 95/Windows 98 version 6.15 or later
To access remote Btrieve files, both of the following software components are required:
• Btrieve MicroKernel Database Engine for NetWare or Windows NT Servers version
6.15 or later
• Btrieve Requester for Windows 95/Windows 98/Windows NT version 6.15 or later
Note Btrieve components are available from Pervasive Software Inc.
3-2 Installation and System Considerations for Microsoft Windows

System Requirements
System Installation
To install RM/COBOL, take the following steps:
1. Start the Windows 95, Windows 98, or Windows NT operating system.
2. Insert your RM/COBOL for 32-bit Windows diskette into a disk drive.
3. Click on the Start button and select the Run command.
4. In the Open text box in the Run dialog box, type the following:
A:setup
where “A” is the letter assigned to the drive where you inserted the diskette.
5. Click the OK command button and follow the prompts on your screen to complete
the installation process.
After installation is complete, you can display the RM/COBOL Program Folder, which is
illustrated in Figure 3-1. The programs are described in Table 3-1.
Figure 3-1 RM/COBOL Program Folder
Note Depending upon which RM/COBOL package you purchased, not all of the
program icons in Figure 3-1 will appear on your system.

System Installation
Table 3-1 RM/COBOL Program Icons
Program Icon Name Description

CodeWatch Starts CodeWatch, a standalone, source-level debugger for
Windows.
Compiler Starts the RM/COBOL compiler and prompts for a source
(rmcobol) filename.
doverify Starts the RM/COBOL verification suite.
INI to Registry Takes a Windows initialization (.ini) file and inserts its entries
(ini2reg.exe) into the Windows registry used by RM/COBOL.
ixverify Starts the RM/InfoExpress verification suite.
Read Me Starts notepad with the README file.
Recover1 Starts the Indexed File Recovery utility program (recover1.exe).
This program is used to recover damaged indexed files.
Registry Configuration Sets the runtime system, compiler, and Indexed File Recovery
(rmconfig.exe) utility program (recover1.exe) options for RM/COBOL
programs and data files.
rmdefinx Starts the Define Indexed File utility program (rmdefinx.cob).
rmmapinx Starts the Map Indexed File utility program (rmmapinx.cob).
rmmappgm Starts the Map Program File utility (rmmappgm.cob) program.
rmpgmcom Starts the Combine Program File utility program
(rmpgmcom.cob).
Runtime Starts the RM/COBOL runtime system and prompts for a
(runcobol) program name.
Toolbar Editor Starts the toolbar button editor.

System Installation
Registering the RM/COBOL Runtime
The RM/COBOL version 7.0 for Windows runtime system consists of two components:
• A client, called runcobol.exe
• A server, called rmcblrun.dll
The runtime server DLL, which must be registered with Windows before RM/COBOL
programs can be run, is automatically registered by the Setup program when the runtime
system is installed. If the runtime is moved to a directory other than the installation
directory without a re-installation, the error message shown in Figure 3-2 is displayed
indicating that there is a registration problem.
Figure 3-2 RM/COBOL Runtime Server Error Message
There are two ways to resolve this problem. You can do either of the following:
• Repeat the installation.
• Use the /REGSERVER command line option.
To register the Windows runtime in a directory other than the installation directory, first
make sure that runcobol.exe and rmcblrun.dll are in the same directory. Then, click the
Windows Start button and select Run from the menu, or open a DOS window. Enter the
following command:
path\RUNCOBOL /REGSERVER
where path is the drive and directory or the UNC location of these two files.
For example:
"c:\program files\rmcobol v7\runcobol" /regserver
Note The quotes are necessary only if the pathname contains spaces.

System Installation
If the registration process is successful, the message box illustrated in Figure 3-3
is displayed.
Figure 3-3 Successful RM/COBOL Server Registration Message
Once registration is complete, the runcobol.exe program is no longer required to be in

the same directory as the rmcblrun.dll server.
The RM/COBOL runtime also provides the /UNREGSERVER command line option to
unregister the runtime from Windows. Although the uninstallation program automatically
unregisters the runtime, this can be done manually with the following command:
path\RUNCOBOL /UNREGSERVER
It is not necessary to unregister the runtime before re-registering the runtime from a
different location.
Finally, the following option will display the location of the currently registered runtime
server:
path\RUNCOBOL /SHOWSERVER
Figure 3-4 illustrates the message box that is displayed when the server has been properly
registered:
Figure 3-4 RM/COBOL Show Server Registration Message
Otherwise, a detailed error message is displayed. Note that “Class not registered” in the
this error message indicates that the server is not registered.

System Installation
System Removal
To remove RM/COBOL from your system, take the following steps:
1. Click Start button, point to Settings, and then click Control Panel.
2. Double-click Add/Remove Programs.
3. From the Install/Uninstall tab in the Add/Remove Programs Properties dialog box,
select “RM/COBOL” from the list of installed program packages.
4. Click the Add/Remove button.
5. Follow the prompts on your screen to complete the removal process.
All installed RM/COBOL system programs, files, shortcuts, and Windows registry entries
are now removed. Customer files are not affected.
System Configuration
As mentioned, RM/COBOL supports IBM PCs, full PC compatibles, and Windows
systems. This section sets forth information required to configure RM/COBOL with each
type of system.
Creating a Windows Shortcut

When you create a shortcut in Windows, you must also specify the properties of the item.
Properties include a description of the item (the application name) and the working
directory where the application files are stored.
To create a shortcut for an application under Windows, take the following steps:
1. Open the folder to which you want the item added. (Note that you can also add an
item directly to the desktop.)
2. Click the right mouse button to open a pop-up menu. Point to the New option and
click Shortcut. The Create Shortcut dialog box opens.

System Removal
3. In the Target text box, type in a runtime system command, as described in Chapter 7,
Running. Click the Next button.
4. When prompted to name the shortcut, choose a name that uniquely identifies the
application program. This name becomes the label that appears under the shortcut
icon.
5. After Windows creates the shortcut, you must modify the properties of the shortcut in
order for it to work properly. Right-click the shortcut icon and choose Properties.
The Shortcut Properties dialog box opens.
6. Select the Shortcut tab in the dialog box. (Figure 3-5 illustrates the Shortcut
Properties Tab used in this example.) In the Start in text box, enter the name of the
directory where the program files for this application are located and where new files
will be placed. The directory you specify here becomes the current directory while
the application program is running.
Figure 3-5 Shortcut Properties Tab

Using Associations With Filename Extensions
During installation, RM/COBOL for Windows automatically sets up filename extension
associations for .cbl and .cob files. These associations allow the user to compile or run
source or object files by double-clicking these files when running the Windows File
Manager or Windows Explorer.
Normally, you cannot pass command line options to Windows programs executed using a
filename extension association. However, using the Windows registry (described on
page 3-16), it is possible to inform the RM/COBOL compiler or runtime system of
command line options for all programs or for specific programs. (See page 3-20 for a
discussion of the Command Line Options property in the RM/COBOL configuration.)
Under Windows, it is also possible to drag and drop .cbl and .cob files to the
RM/COBOL compiler or runtime system for execution. Dropping a .cbl file on a printer
icon will print that source file.
Prompting for a Filename

If the command line specified for the compiler or the runtime system has a ? character for
the source or object filename, the Select an RM/COBOL Object File dialog box appears,
as shown in Figure 3-6.
Figure 3-6 Select an RM/COBOL Object File Dialog Box
When the user selects the file from the list available in the space below the Look in
drop-down list box, the filename in the File name text box replaces the ? character on the
command line. To open (or start) the source or runtime system file, click the Open
button. Double-clicking the name of the file also opens (or starts) the selected object file.

File Locations Within Operating System Pathnames

File locations are determined by the pathname of the file, according to operating system
rules and conventions. A fully qualified pathname contains the drive specifier, a directory
path, the filename, and the filename extension. A filename that begins with a universal
naming convention (UNC) specifier (\\server) is also treated as a fully qualified
pathname.
Note Novell NetWare syntax (server\volume:filename) is no longer supported. Use of

UNC filename is now required (\\server\volume\filename).
If a pathname appears without a drive specifier, the current drive is assumed. If a

pathname is specified without a directory path, RM/COBOL searches the current
directory of the specified or assumed drive.
Specifying a directory path with a leading slash, a drive letter, or a volume name indicates
to RM/COBOL that an exact filename has been specified. If
RM/COBOL cannot find the file in the specified location, it will not look elsewhere. If
you do not specify a directory path, and RM/COBOL cannot find the file in the assumed
location, it will search for the file according to the directory search sequence. If a
directory path is specified, but there is no leading slash, drive letter, or volume name, then
the EXPANDED-PATH-SEARCH keyword of the RUN-FILES-ATTR configuration
record determines whether the directory search sequence will be used (see page 10-27).
When the configuration keyword is set to its default value of NO, the directory search
sequence will not be used. If the value is set to YES, then the entire name, including the
directory path, will be appended to each entry in the directory search sequence in an
attempt to locate the file.

Directory Search Sequences
You can direct RM/COBOL to search for a file not found in the current working directory
by using a predefined directory search sequence. There are two directory search
sequences: one for the compiler and one for the runtime system.
To direct the RM/COBOL compiler to use the directory search sequence, set the
RMPATH synonym. You do this by using the RM/COBOL Configuration utility
(rmconfig.exe), as explained in Appendix G, Utilities. Alternatively, you can right-click
the mouse button on a .cbl file, select the Synonyms Properties tab, and set the RMPATH
synonym with the following syntax (see page 3-29 for a discussion of setting synonyms):
path [;path] ...
To direct the RM/COBOL runtime system to use the directory search sequence, set the
RUNPATH synonym. To do this, use the RM/COBOL Configuration utility
(rmconfig.exe), as discussed in Appendix G. You may also right-click the mouse button
on a .cob file, select the Synonyms Properties tab, and set the RUNPATH synonym with
the following syntax (see page 3-29 for a discussion of setting synonyms):
path [;path] ...
In both commands, path indicates the directory that is to be searched for the file, and has
the form:
[d:] [\] directory [\directory] ...
d is the drive specifier.
directory is the location of an existing file, or the location of a file that will
be created.

If multiple paths are specified, they must be separated with semicolons. Figure 3-7 and
Figure 3-8 illustrate the compiler and runtime system search sequences, respectively.
Figure 3-7 Compiler Search Sequence
Look first in this directory on drive A:
A:wage\hourly\overtime;B:
Then look in the current directory on drive B:
Figure 3-8 Runtime System Search Sequence
Look first in the current directory on drive A:,

then drive B:
A:;B:;C:\
Then look in the root directory on drive C:
Files made to appear in the current directory by using Novell search directories when the
Novell Search Mode is set to a value other than 2 will not be accessed. If a file to be
accessed resides in a directory other than the current directory, that directory must be
included in the RMPATH or RUNPATH directory list. This requirement also applies to
files located in Novell search directories when the Novell Search Mode is set to a value
other than 2.
The compiler, runtime system, and Indexed File Recovery utility program require access
to other files in order to operate. These include the message files (RMC.MSG,
RUN.MSG, and REC.MSG), dynamic link library files (with an extension of .dll), and,
for the compiler, the compiler overlay file, rmcobol.ovy. RM/COBOL looks for these
files first in the directory containing the executable file, then in the current directory, and
finally in the directories specified in the PATH environment variable. For the dynamic
link library files, the default Windows system directory and then the default Windows
directory will be searched prior to searching the directories specified in the PATH
environment variable.
The compiler and runtime system may be executed from a directory other than the current
directory if a complete pathname is specified in the command line, or if either the search
directory of Novell NetWare or the DOS PATH directory search feature is used. If a
complete pathname is not specified and the compiler or runtime system is not located in
the current directory, the directories specified by PATH are searched.

Novell NetWare Search Paths
Novell NetWare defines a search path for locating command files. RM/COBOL defines a
search path for locating compiler files (RMPATH) and for locating runtime system files
(RUNPATH). Both Novell NetWare and RM/COBOL search paths consist of a list of
directories from which attempts are made to open files.
With RM/COBOL search paths, if any one of the directories in a user’s path does not
have search permission for the user, then the searching sequence stops for all remaining
directories and a security violation is reported. This security violation indicates that the
runtime system has been prevented from examining the directory for a file. If a security
violation occurs, and the file is located in a directory for which the user has permission,
examine the permissions for other directories in the RUNPATH sequence.
To prevent this security violation, take one of the following actions:
• Give the user search permission for all directories in RUNPATH, RMPATH, and the
Novell NetWare search path.
• Alternatively, remove the directory from the search path.
Note This same security violation can occur when creating a new file, even if it is with
OPEN OUTPUT. The RM/COBOL runtime system still searches RUNPATH to locate a
file that needs to be replaced.
File Access Names

The file access name you specify in the COBOL source program specifies the physical
file or device to which input or output is directed. For information on specifying the file
access name in a COBOL source program, see the discussion of the ASSIGN clause (file
control entry) in Chapter 3, Environment Division, and the discussion of the VALUE OF
clause in Chapter 4, Data Division, of the RM/COBOL Language Reference Manual.
To establish synonymity between a file access name specified in your source program and
another name specified when the program is run, use the Synonyms tab of the Properties
dialog box, as illustrated in Figure 3-9. The Synonyms Properties tab is described on
page 3-29.

Figure 3-9 Synonyms Tab of the Properties Dialog Box
For example, let us say that you specified a generic file access name for program
input-output and wish to direct it to a specific device or file. A generic file access name is
one that does not specify a directory path or drive letter. Since the format of physical
pathnames, including conventions of specifying drive letters and directory names, varies
from one operating system to another, for maximum portability it is recommended that
source programs specify generic file access names, preferably with eight or fewer letters.
This recommendation only applies when the file access name is hard coded into the
program as a literal.
For example, if the file control entry specifies:
SELECT REPORT-FILE ASSIGN TO PRINT, "report"
and no synonym is assigned, RM/COBOL will create a file named report in the current
directory on the current drive.
If, prior to running the program, you set the synonym "report" to a value of LPT1, all
program output written to REPORT-FILE will be written to LPT1.
If—again prior to execution—you set the synonym "report" to a value of

"A:\output\audit.lst", RM/COBOL will create a file named audit.lst in the subdirectory
\output on drive A without any need to modify or recompile the source program.

When a synonym is not set, the file access name in the COBOL program specifies the
actual filename. Synonym values can be canceled by highlighting the entry on the
Synonyms tab of the Properties dialog box, clicking the Remove button, and restarting
runcobol.exe.
Whether or not a synonym is used to modify the file access name, if the resulting file
access name does not include either a drive letter or a directory path, RUNPATH will be
used by the runtime system to obtain the fully qualified pathname (see “File Locations
Within Operating System Pathnames” on page 3-10 for additional information).
The RESOLVE-LEADING-NAME and RESOLVE-SUBSEQUENT-NAMES keywords

of the RUN-FILES-ATTR configuration record can be used to force resolution of one or
more of the directory names from the environment. For more information, see the
discussion of the RUN-FILES-ATTR record beginning on page 10-26.
The resulting file access name should follow the operating system rules for valid
filenames and pathnames.
Windows System Print Jobs

When the resulting file access name is PRINTER or PRINTERn, where n is a decimal
digit from 1 to 9, RM/COBOL refers to the Windows printer device attached to LPT1: or
LPTn: respectively, provided that LPT1: or LPTn: has a Windows printer attached to it.
This method causes the Windows printer device driver to be used, which does not allow
the use of raw escape sequences.
When the resulting file access name is "PRINTER?" (see 10-19), RM/COBOL displays
the standard Windows Print dialog box when the file is opened. This allows the user to
select the destination Windows printer in a dynamic manner (that is, at execution). Once
the "PRINTER?" device has been opened, the selected printer is remembered by the
runtime, and subsequent opens do not display the standard Windows Print dialog box.
The program may call the P$EnableDialog subprogram (see page E-16) to force a
standard Windows Print dialog box on the next open of "PRINTER?". The user may also
set the Printer Dialog Always registry property to TRUE (see page 3-25) to force the
dialog box on every open of "PRINTER?". The program may also call P$DisplayDialog
(see page E-16) at any time, to force the standard Windows Print dialog box to be
displayed.
In order to send raw escape sequences to a printer, the printer must be opened directly by
using the name “LPT1”. The name “LPTn”, where n is a decimal digit, also can be used.
The DEFINE-DEVICE configuration record may define other file access names that are
to be treated as devices and also change the default treatment of PRINTER and
PRINTERn. See “DEFINE-DEVICE Record” on page 10-16 for additional information
on configuring file access names that are to be treated as devices.

Windows Registry
RM/COBOL version 6.5 and later stores configuration information for the runtime
system, compiler, and Indexed File Recovery utility program in the Windows registry.
The registry is a hierarchical database of configuration information maintained by
Windows.
Previous versions of RM/COBOL for Windows stored configuration information in

separate initialization files located in the main Windows directory. These initialization
files are no longer used. However, when distributing configuration information to
end-users, initialization files can still be shipped with your product. To merge your
program’s configuration information into the Windows registry, include a call to the
supplied Initialization File to Windows Registry Conversion utility (ini2reg.exe),
described on page G-40, in your application’s installation procedure.
The Windows registry is organized much like a disk drive’s directory structure. All of
RM/COBOL’s configuration information is stored under the “directory” path
“HKEY_LOCAL_MACHINE\SOFTWARE\Liant Software Corporation\RM/COBOL\CurrentVersion”.
Three subdirectories underneath that path (rmcobol, runcobol, and recover1) correspond
with information previously stored in the separate initialization files rmcobol.ini,
runcobol.ini, and recover1.ini.
You are not required to know the inner details of the Windows registry structure in order
to change the properties of your programs. RM/COBOL for Windows includes Windows
shell extensions that allow the manipulation of configuration information for default
values as well as individual program settings without having to navigate through the
Windows registry editor. Configuration information for a specific COBOL program may
be edited by right-clicking a source or object file and choosing Properties. If a source file
is chosen, the properties used when compiling that program can be modified. If an object
file is chosen, the properties used when running that program can be modified. The
configuration options available in the Properties dialog box are described in the following
section “Setting Properties.” Configuration information for programs and generic default
values may also be edited by running the supplied RM/COBOL Configuration utility
(rmconfig.exe), as described on page G-41.
Users may migrate the complete RM/COBOL registry information from one machine to
another by using the regedit.exe utility supplied with Windows. This utility allows entire
sections of the Windows registry to be exported to a .reg text file, which can then be
imported into the Windows registry of another machine. Consult the Microsoft Windows
help documentation for more information on regedit.exe.

Windows Registry
Setting Properties
This section describes the configuration options that can be set using the Properties dialog
box.
The following definitions explain terms used throughout this section.

Term Meaning
Boolean Indicates a value of TRUE or FALSE. A value of 1 or 0
may also be used to indicate TRUE or FALSE.
number Indicates a positive integer value. Valid example: “12”.
Invalid example: “=5”.
string Indicates alphanumeric characters.
filename Indicates the operating system filename.
Selecting a File to Configure

The Select File tab, illustrated in Figure 3-10, allows you to select the source file or
object file that you want to configure.
Note If you have opened the Properties dialog box by right-clicking the mouse button on
an RM/COBOL source or object file and then selecting Properties, this tab will not be
available. You are only able to configure options for the current file.
Figure 3-10 Select File Tab

Setting Properties
The Select File tab contains the following options:
• Default Properties. When selected, the Default Properties option enables the other
Properties tabs (Miscellaneous, Synonyms, Colors, Toolbar, Menu Bar, and Pop-up
Menu) to set system defaults for all files.
• Individual File. When selected, the Individual File option enables the other
Properties tabs to change the properties for the selected file.
• Configure for. The three options provided in this area determine the activity for
which the Properties tabs will configure a file.
− Running. If this option is selected, the settings for the .cob file will be shown
and used when running the file.
− Compiling. If this option is selected, the settings for the .cbl file are affected.
− Recovery. If this option is selected, the settings used for recovering a data file
with the Indexed File Recovery utility program (recover1.exe) are affected.
• Browse. Use this button to open a dialog box that allows you to look for a file for
which you want to set properties.
• Use Defaults. The behavior of the Use Defaults button is dependent upon whether
the Default Properties or the Individual File option is in effect.
If the Default Properties option is selected, choosing the Use Defaults button causes
the system defaults to be reset to the values that were in place when the product was
originally installed. Note, however, that any property values set for an individual file
will not be reset.
If the Individual File option is selected, choosing the Use Defaults button causes
property values that have been overridden for the selected file to be reset to use the
system defaults.

Setting Properties
Setting Miscellaneous Properties
The Miscellaneous Properties tab, illustrated in Figure 3-11, allows you to set various
properties for the file that was specified using the Select File tab.
Figure 3-11 Miscellaneous Properties Tab
The Miscellaneous Properties tab contains the following options:
• Property. This list box presents an alphabetical listing of the properties that are used
to configure the physical appearance of the RM/COBOL program. (Each of these
properties is discussed below.)
• Use Default Settings. Select this button to use the selected property’s default value.
That default value will be shown in the Value area (described below). See the
Default Properties option on the Select File tab for information on configuring
default values (for more information, see the discussion of “Selecting a File to
Configure” that begins on page 3-17).
• Use Custom Settings. Select this button to override the default value for the
selected property.
• Value. This area displays the value associated with the property selected in the
Property list box and allows you to change it. Note that this area is disabled unless
the Use Custom Settings button is selected.
The following properties can be set or modified.

Setting Properties
Auto Paste
The Auto Paste property specifies a Boolean value that enables or disables the
Auto Paste function. Setting Auto Paste to TRUE enables the Auto Paste feature and
double-clicking the mouse button transfers the marked data to a pending ACCEPT field.
If Auto Paste is set to FALSE, double-clicking the mouse button marks a word of text.
The default value is TRUE.
The C$GUICFG subprogram (see page F-16) can be used to temporarily change the Auto
Paste property in order to manipulate the graphical user interface.
Auto Scale
The Auto Scale property specifies a Boolean value that determines whether to implement
auto scaling of fonts when the window is resized. Setting Auto Scale to TRUE
automatically changes the font size when the window is resized. Setting Auto Scale to
FALSE turns off this capability. The default value is TRUE. See also the Sizing Priority
property on page 3-27.
The C$GUICFG subprogram (see page F-16) can be used to temporarily change the Auto
Scale property in order to manipulate the graphical user interface.
Command Line Options
The Command Line Options property defines a series of command line options to be
passed to the runtime system. Processing of options on the actual command line occurs
last and replaces any options specified using this property.
Enable Close
The Enable Close property specifies a Boolean value that enables or disables the Close
menu item on the Control menu as well as the Close button in the upper-right corner of
the window. Setting Enable Close to TRUE enables the Close menu item and the Close
button. Setting Enable Close to FALSE dims and disables the Close menu item and the
Close button. The default value is TRUE.
The C$GUICFG subprogram (see page F-16) can be used to temporarily change the
Enable Close property in order to manipulate the graphical user interface.
Enable Properties Dialog
The Enable Properties Dialog property specifies a Boolean value that enables or disables
the Properties menu item on the Control menu. Setting Enable Properties Dialog to

Setting Properties
TRUE enables the Properties menu item. Setting Enable Properties Dialog to FALSE
dims and disables the Properties menu item. The default is TRUE.
Enable Properties Dialog property in order to manipulate the graphical user interface.
Font
The Font property specifies the typeface to use as well as point size and style. The
typeface must be a fixed-width (or monospaced) font, such as Courier. Clicking the
Select Fonts button opens the Fonts dialog box, which provides a list of available fonts,
styles, and sizes.
Full OEM To ANSI Conversions
The Full OEM To ANSI Conversions property specifies a Boolean value that determines
whether or not to convert a character from OEM to ANSI or from ANSI to OEM. This
property affects titles, menus, and other Windows objects. Because Windows uses the
ANSI character set, the default setting (TRUE) causes all output to be converted from the
OEM character set to the ANSI character set and all input from these controls to be
converted from ANSI to OEM. If, however, the user wants to avoid these conversions,
this property should be set to FALSE in order to suppress the conversion. Setting this
value to FALSE causes the runtime system to behave as it did prior to the RM/COBOL
6.5 release.
Note The European “Latin-1” character set is the same as the Windows native ANSI
character set.
The C$GUICFG subprogram (see page F-16) can be used to temporarily change the Full
OEM to ANSI Conversions property in order to manipulate the graphical user interface.
Icon File
The Icon File property specifies the icon filename from which to load icons for the
toolbar (see the Name option of the Toolbar Properties tab, described beginning on
page 3-32). This property is used only if the Toolbar property is set to TRUE (see
page 3-28). The default value is rmtbar.vrf (see Table 3-3 on page 3-38 for more
information).
The C$GUICFG subprogram (see page F-16) can be used to temporarily change the Icon
File property in order to manipulate the graphical user interface.

Setting Properties
Load Registry On CALL
The Load Registry On CALL property specifies a Boolean value that enables or
disables additional processing of the Windows registry file. If set to TRUE, the registry
is re-examined whenever a COBOL subprogram is called. The subprogram name is
treated as if it were a filename and causes corresponding registry entries to be processed.
If set to FALSE, the registry is not re-examined. The default value is FALSE.
Note Use caution when setting the value of the Load Registry On CALL property to
TRUE as a system default. Doing so can affect the performance of your application.
This behavior can occur when using RM/Panels because an RM/Panels application uses
many subprogram calls. Alternatively, you can use the C$TBar (see page F-37), C$MBar
(see page F-17), or C$GUICFG (see page F-16) subprograms to manipulate the toolbar
and menu bar instead of using the Windows registry file and the Load Registry on CALL
property.
Load Registry On RETURN
The Load Registry On RETURN property specifies a Boolean value that enables or
disables additional processing of the Windows registry file. If set to TRUE, the registry is
re-examined whenever a COBOL subprogram is exited. The calling program’s name is
treated as if it were a filename and causes corresponding registry entries to be processed.
If set to FALSE, the registry is not re-examined. The default value is FALSE.
Note Use caution when setting the value of the Load Registry On RETURN property to
TRUE as a system default. Doing so can affect the performance of your application.
This behavior can occur when using RM/Panels because an RM/Panels application uses
many subprogram calls. Alternatively, you can use the C$TBar (see page F-37), C$MBar
(see page F-17), or C$GUICFG (see page F-16) subprograms to manipulate the toolbar
and menu bar instead of using the Windows registry file and the Load Registry on
RETURN property.
Logo Bitmap
The Logo Bitmap property specifies a Boolean value that determines whether a Logo
Bitmap is displayed. If set to TRUE, the file specified by the Logo Bitmap File property
(described below) is displayed. If set to FALSE, it is not displayed. The default value
is TRUE.

Setting Properties
Logo Bitmap File
The Logo Bitmap File property specifies the bitmap (.bmp) filename that may be
displayed in the COBOL window when an application is started. The bitmap is centered
in the main window until an erase screen operation is encountered (DISPLAY ERASE).
You can build a simple COBOL program that displays a bitmap, responds to keyboard
sequences (such as function keys that could be generated from the menus or toolbar), and
dispatches the appropriate code. The default value is run.bmp, rmc.bmp, or rec.bmp
for the runtime system, compiler, and Indexed File Recovery utility program,
respectively. If the bitmap file is not found, or if Logo Bitmap (described above) is set
to FALSE, this property is ignored.
Main Window Type
The Main Window Type property determines the style of the Main window (the window
that is activated when the COBOL application begins execution).
The following values are valid:

Value Meaning
HIDDEN The window is not activated and is hidden.
MINIMIZED The window is activated and is displayed as an icon.
MAXIMIZED The window is activated and is displayed in its maximized
state.
SHOW The window is activated and is displayed in its current
size and position.
Mark Alphanumeric
The Mark Alphanumeric property specifies a Boolean value that determines the
terminating conditions for selecting a word from the application window. If Mark
Alphanumeric is set to TRUE, double-clicking the mouse button to mark a word selects
characters until a non-alphanumeric character is encountered. If Mark Alphanumeric is
set to FALSE, selection occurs when a blank is encountered. The default value is TRUE.
The C$GUICFG subprogram (see page F-16) can be used to temporarily change the Mark
Alphanumeric property in order to manipulate the graphical user interface.
Offset X
The Offset X property specifies a number that identifies the leftmost location (as a
pixel offset from the left edge of the screen) of the COBOL window. The default
value is 0.

Setting Properties
Offset Y
The Offset Y property specifies a number that identifies the uppermost location (as a
pixel offset from the top edge of the screen) of the COBOL window. The default value
is 0.
Panels Controls 3D
The Panels Controls 3D property specifies a Boolean value that causes certain
RM/Panels for Windows controls (date, time, alpha, and numeric fields) to take on a
three-dimensional appearance. This capability was not available in prior versions of
RM/Panels for Windows. The default value, FALSE, causes existing applications to
appear the same as they did under previous versions of RM/COBOL.
Panels Static Controls Border
The Panels Static Controls Border property specifies a Boolean value that cause the Static
Text Control (a new Panels control type) to have a border. The default value, FALSE,
causes these controls to be drawn without a border.
Paste Termination
The Paste Termination property specifies a Boolean value that affects automatic
termination of fields pasted into a pending ACCEPT statement, using either the Paste (see
page 3-44) or Auto Paste (see page 3-20) function. If Paste Termination is set to TRUE,
data transfer will continue until the data is exhausted, including all tabs and carriage
returns. If Paste Termination is set to FALSE, data transfer stops when a tab or carriage
return is encountered. There is a carriage return at the end of each line of text in the
Windows Clipboard. The default value is TRUE.
The C$GUICFG subprogram (see page F-16) can be used to temporarily change the Paste
Termination property in order to manipulate the graphical user interface.
Persistent
The Persistent property specifies a Boolean value that affects the behavior of the
RM/COBOL window when the COBOL program, compiler, or Indexed File Recovery
utility program terminates. If Persistent is set to TRUE, the window will not close until
dismissed by the user. If Persistent is set to FALSE, the window will close immediately
upon completion. The default value is FALSE.

Setting Properties
If any RM/COBOL window disappears upon completion before the user is able to read
the final text displayed in that window, then set Persistent to TRUE and close the window
manually after reading the final text.
Persistent property in order to manipulate the graphical user interface.
Printer Dialog Always
The Printer Dialog Always property specifies a Boolean value that affects the behavior of
the RM/COBOL runtime when opening the "PRINTER?" (dynamic printer selection)
device (see page 10-19). If Printer Dialog Always is set to TRUE, the standard Windows
Print dialog box will appear when the dynamic printer device is opened. If Printer Dialog
Always is set to FALSE, the dialog box will appear only the first time the dynamic printer
is opened. The P$EnableDialog subprogram (see page E-16) may be called to cause the
dialog to appear on the next open of the dynamic printer). The default value is FALSE.
Printer Dialog Always property.
Printer Dialog Never
The Printer Dialog Never property specifies a Boolean value that affects the behavior of
the RM/COBOL runtime when opening the "PRINTER?" (dynamic printer selection)
device (see page 10-19). If Printer Dialog Never is set to TRUE, the standard Windows
Print dialog box will never appear when the dynamic printer device is opened. In this
case, the "PRINTER?" device behaves like the Printer (default) printer device. If Printer
Dialog Never is set to FALSE, the appearance of the dialog box is controlled by the
setting of the Printer Dialog Always property. The default value is FALSE.
Printer Dialog Never property.
Note If the Printer Dialog Never property is set to TRUE, the standard Windows Print
dialog box will never appear, regardless of the state of the Printer Dialog Always
property.
Printer Enable Escape Sequences
The Printer Enable Escape Sequences property specifies a Boolean value that determines
whether printing will allow embedded RM/COBOL-specific escape sequences. See
“RM/COBOL-Specific Escape Sequences" in Appendix E, Windows Printing, for a more
complete description. If the value is set to TRUE, the RM/COBOL runtime system will

Setting Properties
recognize the sequences. If the value is set to FALSE, the runtime system will ignore
those escape sequences. The default value is FALSE.
Note Setting the Printer Enable Escape Sequences property to TRUE affects
all Windows printers that the COBOL program uses. To allow embedded
RM/COBOL-specific escape sequences for only specific printers, use the
P$EnableEscapeSequences subprogram (see page E-38).
Printer Enable Raw Mode
The Printer Enable Raw Mode property specifies a Boolean value that determines
whether or not Windows printers will be opened in raw mode. If the value is set to
TRUE, the runtime system will open printers in raw mode. This allows certain Windows
NT networked printers to respond to embedded escape sequences. See P$SetRawMode
subprogram on page E-43 for a more complete description of raw mode. Most P$
subprograms are not available if RAW mode is used. If the value is set to FALSE, the
runtime system will treat the printer as a normal Windows printer. The default value is
FALSE.
Note Setting the Printer Enable Raw Mode property to TRUE affects all Windows
printers that the COBOL program uses. To allow raw mode printing for only
specific printers, use the P$SetRawMode subprogram. For more information, refer
to Appendix E.
Remove Trailing Blanks
The Remove Trailing Blanks property defines a Boolean value that specifies whether
trailing blanks will be removed from the Toolbar (see page 3-32) and Menu Bar strings
(see page 3-34) before they are sent to the COBOL program’s ACCEPT statement for
processing. The default value is TRUE.
Remove Trailing Blanks property in order to manipulate the graphical user interface.
Scroll Buffer Size
The Scroll Buffer Size property specifies a number that affects the virtual size of the
RM/COBOL window. The number of rows initially displayed in the window is
determined by the ROWS keyword in the TERM-ATTR configuration record (see
page 10-39). The Scroll Buffer Size property determines the number of rows that can be
scrolled off the screen using the vertical scroll bar. Setting the Scroll Buffer Size to a
non-zero value overrides the Auto Scale property (described on page 3-20) and
automatically turns on the vertical scroll bar. The default value is 0.

Setting Properties
Show Return Code Dialog
The Show Return Code Dialog property specifies a Boolean value that determines
whether the Return Code message box (see page 3-44) indicating the program exit code,
described on page 7-8, should be displayed when an error occurs. Automated systems,
which handle such errors and do not require operator assistance, may wish to suppress the
message box and continue processing. The default value is TRUE, which causes the
message box to be displayed.
Show Through Borders

The Show Through Borders property specifies a Boolean value that determines whether
the border of an overlayed pop-up window is shown when overlayed by a pop-up window
without a FILL character. When Show Through Borders is set to TRUE, the border is
visible. When Show Through Borders is set to FALSE, the border is not visible. The
default value is FALSE.
Sizing Priority
The Sizing Priority property specifies whether to make the width or height a priority when
auto scaling fonts. If the user resizes the window and auto scaling is on, the system will
select a font to match the new size of the window. The new size will be based on the
width or height of the window. The default value is WIDTH. (See also the Auto Scale
property on page 3-20.)
Sizing Priority property in order to manipulate the graphical user interface.
Status Bar
The Status Bar property specifies a Boolean value that determines whether the status bar
is initially visible. Setting Status Bar to TRUE turns on the status bar. Setting Status Bar
to FALSE turns off the status bar. The default value is FALSE.
Status Bar property in order to manipulate the graphical user interface.
Status Bar Text

The Status Bar Text property specifies the initial string of text to be placed in the status
bar. The default value is an empty string. This text is displayed in the status bar
whenever the mouse is in the client area of the window.
Note The C$SBar subprogram (see page F-25) also can be used to display a status bar in
the RM/COBOL window.

Setting Properties
SYSTEM Window Type
The SYSTEM Window Type property determines the style of the window shown by a
program run using the SYSTEM non-COBOL subprogram (see page F-41).
The following values are valid:

Value Meaning
HIDDEN The window is not activated and is hidden.
MINIMIZED The window is activated and is displayed as an icon.
MAXIMIZED The window is activated and is displayed in its maximized
state.
SHOW The window is activated and is displayed in its current
size and position.
Title Text
The Title Text property specifies the string of text to be placed in the main window of the
COBOL program that is currently running. The default title is “RM/COBOL” if no
program name is specified on the runcobol command line. Otherwise, it is the initial
program name.
Note The C$Title subprogram (see page F-39) also can be used to specify the text to be
placed in the RM/COBOL window.
Toolbar
The Toolbar property specifies a Boolean value that determines whether the toolbar is
visible initially. Setting Toolbar to TRUE turns on the toolbar. Setting Toolbar to
FALSE turns off the toolbar. The default value is FALSE.
Toolbar property in order to manipulate the graphical user interface.
Update Timeout
The Update Timeout property specifies a number that represents a delay before a screen
refresh occurs. The value of number is specified in milliseconds. A larger number causes
DISPLAY statements to occur less frequently, potentially improving screen display
performance (especially when multiple DISPLAY statements of short records occur in a
short period of time). This property may also be used to force DISPLAY statements to
occur more frequently. The default value is 500 milliseconds (half of a second).
Update Timeout property in order to manipulate the graphical user interface.

Setting Properties
Use Windows Colors
The Use Windows Colors property defines a Boolean value that specifies whether the
standard Windows colors, as set in the Windows Control Panel (Display Properties dialog
box, Appearance tab), are used as the RM/COBOL default foreground and background
colors. If Use Windows Colors is set to TRUE, the standard Windows colors will be
used. If Use Windows Colors is set to FALSE, BLACK will be used for the background
and WHITE for the foreground. A value of FALSE allows the same behavior as that
found in versions of RM/COBOL prior to 6.0. The default value is TRUE.
Setting Synonym Properties

The Synonyms Properties tab, illustrated in Figure 3-12, allows you to establish synonym
name(s) and their values for the file that was specified using the Select File tab (see
page 3-17). The name is a string that is the name of a variable placed in the program’s
environment. The value is a string that is the value of name in the environment. A
synonym can be used to specify the actual file access name for a COBOL program, or to
specify other environment variables such as the RMPATH and RUNPATH directory
search sequences (see page 3-11).
Figure 3-12 Synonyms Properties Tab

Setting Properties
The Synonyms Properties tab contains the following options:
• Name. The value entered in this list box is the name of the synonym to which you
are assigning a value.
• Value. The value in this text box is the value assigned to the synonym selected in the
Name list box.
• Remove. Use this button to clear the value for the currently selected synonym name
and remove it from the list.
• Remove All. Use this button to clear all synonym values for the currently selected
program.
These synonyms override any environment variables established with the DOS SET
command. As a result, these synonyms may be used to establish a connection between the
open name of the file, literal-1 or data-name-1 (see “Input-Output Section” in Chapter 3,
Environment Division, of the RM/COBOL Language Reference Manual for more
information), and the actual file access name.
If either the Load Registry On CALL property or Load Registry On RETURN property
(see page 3-22) is set to TRUE, synonyms will be reprocessed whenever a subprogram is
called or exited. Synonym assignments are cumulative. For example, if a synonym is
assigned for a called subprogram, its value is unchanged when the subprogram exits
unless Load Registry On RETURN is set to TRUE and the synonym is defined for the
calling program.

Setting Properties
Setting Color Properties
The Colors Properties tab, illustrated in Figure 3-13, allows you to control color mapping
for the file that was specified using the Select File tab (as described beginning on
page 3-17).
Figure 3-13 Colors Properties Tab
The Colors Properties tab contains the following options:
• Color. Use this list box to select the color you want to change. The first eight colors
in this list box correspond to the color-names for the keywords (FCOLOR and
BCOLOR) allowed in a CONTROL phrase of an ACCEPT or DISPLAY statement
(see page 8-11). These colors are displayed if low intensity is selected. The
remaining eight colors correspond to the same color-names if high intensity is
selected. Note that GRAY is “HIGH BLACK” and YELLOW is “HIGH BROWN.”
The current color setting is displayed to the right of each name.
Note An asterisk (*) after the name indicates that the default color should not be
overridden. If the Change button (see the following item) is used to override the
default, the overriding color is displayed on the right.
• Change. Use this button to display a Color Selection dialog box that allows you to
select a color to override the selected color name.
• Use Default. Use this button to clear the overriding color for the currently selected
color name, thereby using the default color.

Setting Properties
Setting Toolbar Properties
The Toolbar Properties tab, illustrated in Figure 3-14, allows you to define the string that
is to be sent to the program through the COBOL ACCEPT statement when the
corresponding toolbar button is pressed.
The C$TBar subprogram (see page F-37) also can be used to display a toolbar in the
RM/COBOL window.
Figure 3-14 Toolbar Properties Tab
The Toolbar Properties tab contains the following options:
• Name. The value entered in this text box is the name of the icon stored in the
filename specified by the Icon File property (see page 3-21).
• Prompt. The value entered in this text box is an optional text string that is displayed
whenever the cursor is placed on the toolbar icon that is specified by the icon name.
• String. Although the value entered in this text box is an ASCII text string, it also can
contain special characters for the Return, Tab, Escape, or Function keys. If the first
character is a greater than character (>), the characters that follow are executed as a
command. The special characters are described in Table 3-2. (These characters are
interpreted by the COBOL ACCEPT statement, as described in Table 8-2 beginning
on page 8-6.)

Setting Properties
Table 3-2 Special Characters for the Button Character-String
Special Character Description

>commandline execute commandline:
\a Alt
\b Backspace
\\ Backslash character
\c Control
\d Delete
\e Escape
\f0 Function key 10
\f1 Function key 1
\f2 Function key 2
\f3 Function key 3
\f4 Function key 4
\f5 Function key 5
\f6 Function key 6
\f7 Function key 7
\f8 Function key 8
\f9 Function key 9
\fa Function key 10
\fb Function key 11
\fc Function key 12
\i Insert
\n Newline
\s Shift
\t Tab
\x Exit program
\zb Begin
\zc Clear
\zd Down Arrow
\ze End
\zh Home
\zl Left Arrow
\zn Next (Page Down)
\zp Prior (Page Up)
\zr Right Arrow
\zu Up Arrow

Setting Properties
• Move Up and Move Down. Use these buttons to control the order of the buttons
shown in the toolbar. This order is determined by the order of the names in the Name
list box. When you choose Move Up, the currently selected name moves up one
position in the list. Choosing the Move Down button moves the selected name down
one position.
• Remove. Use this button to clear the value for the currently selected toolbar button
name and remove it from the list.
• Remove All. Use this button to clear all toolbar button values for the currently
selected program.
Setting Menu Bar Properties

The Menu Bar Properties tab, illustrated in Figure 3-15, allows you to identify a list of
pulldown menu names and their associated values for the file that was specified using the
Select File tab (as described beginning on page 3-17).
The C$MBar subprogram (see page F-17) also can be used to display a menu bar in the
RM/COBOL window.
Figure 3-15 Menu Bar Properties Tab

Setting Properties
The Menu Bar Properties tab contains the following options:
• Name. The value entered in this text box is the string that appears in the menu bar.
If the first character is a tilde (~), the name is disabled. An ampersand (&) character
causes the next character to be underlined and used as an accelerator.
when the cursor is placed on the menu bar item.
• String. The value entered in this text box defines the items in the pulldown menu
along with the strings that are returned to the COBOL program when an item is
selected. Using the following syntax, it can specify either a value to be returned or
additional sub-menu items:
pulldownname["prompt"]=menu
pulldownname is the string that appears in the menu bar.
prompt is an optional text string that is displayed on the status bar when the cursor is
placed on the menu bar item specified by pulldownname.
menu defines the items in the pulldown menu along with the strings that are returned
to the COBOL program when an item is selected. The syntax for menu is shown as
follows:
menu -> [(]items[)]

items -> item name=[string | (menu)][,items]
item name -> pulldownname["menu prompt"]
string -> string to be sent (see the Toolbar Properties tab)
If the first character of pulldownname is a ~ (tilde), the menu is disabled. An &

(ampersand) in pulldownname causes the next character to be underlined and used as
an accelerator.
• Move Up and Move Down. Use these buttons to control the order of the pulldown
menu names shown in the menu bar. This order is determined by the order of the
names in the Name list box. When you choose Move Up, the currently selected name
moves up one position in the list. Choosing the Move Down button moves the
selected name down one position.
• Remove. Use this button to clear the value for the currently selected pulldown menu
• Remove All. Use this button to clear all pulldown menu values for the currently
selected program.

Setting Properties
Setting Pop-Up Menu Properties
The Pop-up Menu Properties tab, illustrated in Figure 3-16, allows you to identify a list of
pop-up menu names and their associated values that will be displayed when right-clicking
the mouse button on an RM/COBOL program in the client area of the screen.
The C$RBMenu subprogram (see page F-22) also can be used to display a pop-up menu
in the RM/COBOL window when the right mouse button is pressed.
Note If you are using RM/Panels, a pop-up menu defined by RM/Panels will override a
pop-up menu defined by setting mouse menu properties.
Figure 3-16 Pop-up Menu Properties Tab
The Pop-up Menu Properties tab contains the following options:
• Name. The value entered in this text box is the string that appears in the pop-up
menu. If the first character is a tilde (~), the name is disabled. An ampersand (&)
causes the next character to be underlined and used as an accelerator.
when the cursor is placed on the pop-up menu item.

Setting Properties
• String. The value entered in this text box defines the items in the pop-up menu along
with the strings that are returned to the COBOL program when an item is selected. It
can specify either a value to be returned or additional sub-menu items by using the
following syntax:
pop-upname["prompt"]=menu
pop-upname is the string that appears in the pop-up menu.
prompt is an optional text string that is displayed on the status bar when the cursor is
placed on the pop-up menu item specified by pop-upname.
menu defines the items in the pop-up menu along with the strings that are returned to
the COBOL program when an item is selected. The syntax for menu is shown as
follows:
menu -> [(]items[)]

items -> item name=[string | (menu)][,items]
item name -> pop-upname["menu prompt"]
string -> string to be sent (see the Toolbar Properties tab)
If the first character of pop-upname is a ~ (tilde), the menu is disabled. An &

(ampersand) in pop-upname causes the next character to be underlined and used as
an accelerator.
• Move Up and Move Down. Use these buttons to control the order of the names
shown in the pop-up menu. This order is determined by the order of the names in the
Name list box. When you choose Move Up, the currently selected name moves up
one position in the list. Choosing the Move Down button moves the selected name
down one position.
• Remove. Use this button to clear the value for the currently selected pop-up menu
• Remove All. Use this button to clear all pop-up menu values for the currently
selected program.
Toolbar Editor
RM/COBOL provides a default toolbar in the file, rmtbar.vrf. This toolbar is the
default value specified in the Icon File property (see page 3-21). The buttons provided in
the default toolbar are documented in Table 3-3. A bitmap editor (rmtbedit.exe),
provided with your RM/COBOL runtime system, allows you to create or edit the buttons
on the toolbar.

Toolbar Editor
Table 3-3 Default rmtbar.vrf File Button Icons
Button Description
A–Z Letters A through Z (useful for menu picks)
1 – 20 Numbers 1 through 20 (useful for menu picks)
AF1 – AF12 Alt Function keys 1 through 12
AP Accounts Payable
AR Accounts Receivable
BREAK Hammer smashing object (Break key)
CF1 – CF12 Control Function keys 1 through 12
COMPANION Two buddies (Companion for RM/COBOL)
DISK Hard disk drive
DISKETTE Floppy disk
DOWN Down Arrow key
END Curtains closing (End key)
ENTER Enter key
ESCAPE Escape key
EXIT Door with exit sign
F1 – F12 Function keys 1 through 12
FILE File cabinet
GL General Ledger
GO GO sign
GRAPH Three-dimensional graph (Grafsman)
GREEN Green traffic light
HELP Question mark
HOME Little house (Home key)
INFO Italic lowercase i
LEFT Left Arrow key
LINELEFT Left Arrow key pointing at margin bar (Tab left)
LINERIGHT Right Arrow key pointing at margin bar (Tab right)
MAIL Bundle of letters
MENU Menu

Toolbar Editor
Table 3-3 Default rmtbar.vrf File Button Icons (Cont.)
Button Description
PAGEDOWN Down Arrow key pointing at margin bar
PAGEUP Up Arrow key pointing at margin bar
PHONE Telephone
PR Payroll
PRINTER Printer
RED Red traffic light
REPORT Text on computer paper
RIGHT Right Arrow key
SAFE Archive (Safe)
SEARCH Flashlight
SF1 – SF12 Shift Function keys 1 through 12
STOP Stop sign
TERMINAL Display and keyboard (Data terminal or PC)
UP Up Arrow key
WRITE Pencil writing on paper
YELLOW Yellow traffic light
YIELD Yield sign
Running the Toolbar Editor

To run the Toolbar editor, choose the Toolbar Editor icon. The application presents you
with a menu bar. Under the File menu, you can open a toolbar file or create a new one.
(The file created by the Toolbar editor is a resource file that is composed of bitmap
buttons, each of which has a name. It is that name that you reference in the Toolbar
Properties tab when defining character actions, as described on page 3-32.) A Resource
dialog box then displays the bitmap buttons available in the toolbar file.
When the Resource dialog box is active, a Resource menu is available. You can edit,
delete, copy, and save the bitmap buttons presented in the Resource dialog box. Opening
or creating a bitmap Resource dialog box opens a bitmap editor.

Toolbar Editor
Editing a Bitmap
When you start the bitmap editor, you are in draw mode. When you move the cursor into
the editor’s grid area, it changes to a pen. You can use the left and right mouse buttons to
modify your bitmap. Each button can hold in memory a color that you choose from the
color palette. For example, if you click red with the left mouse button and blue with the
right mouse button, these colors are stored until you click on another color. By default,
when you start the bitmap editor, the left button is black and the right button is gray until
you change the color.
In the bottom portion of the color palette, the center square contains the mouse’s left
button color and the background color is in the mouse’s right button color. For example,
the color palette in Figure 3-17 shows the center square to be black (indicating that the
color stored in the left mouse button is black) and the background is gray (indicating that
the color stored in the right mouse button is gray).
Figure 3-17 Color Palette Showing Right and Left Mouse Colors
Buttons are shown in a pair of frames. The first frame represents the up image of the
button. The second frame in the sequence represents the down image of the button.
Testing the Bitmap

To test a button, choose the Bitmap->Test Button command from the menu bar.
A dialog box appears that shows the bitmap as a button.
Transferring the Image Up

The bitmap that you create can be duplicated to the down image of the button. Select
Bitmap->Transfer Up Image command from the menu bar. At the prompt, choose the
Yes button to transfer the image or choose the No button to terminate the transfer.

Toolbar Editor
Importing and Exporting Bitmaps
You may import a bitmap by choosing the Resource->Import command from the menu
bar. This command opens the Import Bitmap dialog box. Enter the name of the .bmp file
you want to import and choose the OK button.
You may export a bitmap by choosing the Resource->Export command from the menu
bar. This command opens the Save Bitmap As dialog. Enter the name of the file you
want to export and choose the OK button.

This section describes special system considerations for using RM/COBOL under the
Windows operating system.
Memory Available for a COBOL Run Unit

The memory available for a run unit depends on the configuration of your PC. If the total
memory required by a run unit exceeds the amount of available memory, runtime system
errors will occur. These errors indicate an inability to obtain enough memory to perform
a desired operation. This is unlikely to occur under Windows because Windows 95,
Windows 98, and Windows NT provide virtual memory. However, it is still possible to
use segmentation and subprograms to manage the dynamic memory requirements of very
large run units.
Portable Line Draw Characters

The GRAPHICS keyword of the ACCEPT and/or DISPLAY CONTROL phrase
translates the characters described in Table 8-5 on page 8-13 to system-specific line draw
characters. Characters that are not listed in this table are output unchanged.
It is not required that the current font contain line draw characters because the runtime
system dynamically creates these characters as required.
Blinking Attribute
The blinking attribute (see page 10-24) is not supported in the Windows environment.

Runtime System Screen
Figure 3-18 illustrates a sample screen of an RM/COBOL program running under
Windows.
Figure 3-18 Sample Screen of an RM/COBOL Program Running Under Windows
Title bar
Menu bar
Control menu button
Toolbar
Pop-up menu
Status bar Client area
The runtime system screen is a typical Windows operating system window with the
following areas:
• Client area. Used by the RM/COBOL program input and output.
• Menu bar. Configurable by the developer. Menu bar can be different for each
program. COBOL programs can also display a menu bar by using the C$MBar
subprogram (see page F-17 for more information).
• Status bar. Displays prompt text when the user moves the mouse in the client area,
through a menu pick or over a toolbar button. It is configurable by the developer.
Status bar can be different for each program. COBOL programs can also display text
in the status bar by using the C$SBar subprogram (see page F-25 for more
information). It can be turned on or off by the user.
• Control menu button. Opens the Control menu.

• Title bar. Identifies the program name currently running the COBOL program and
displays the Minimize, Maximize, and Close buttons. It is configurable by the
developer. Title bar can be different for each program. COBOL programs can also
display a title by using the C$Title subprogram (see page F-39 for more information).
• Toolbar. Configurable by the developer. Toolbar can be different for each program.
It can be turned on or off by the user. COBOL programs can also display a toolbar
by using the C$TBar subprogram (see page F-37 for more information).
• Pop-up menu. Configurable by the developer. Pop-up menu can be different for
each program. RM/COBOL programs can also change the contents of a pop-up
menu by using the C$RBMenu subprogram (see page F-22 for more information).
Cursor Types
Under default conditions, there are three types of cursors, each of which indicates a
different edit mode during ACCEPT operations.
_ The underscore cursor indicates that standard overtype mode is active.
à The full-height cursor indicates that you have typed to the end of the field and
that the TAB phrase has been specified in the ACCEPT statement. A backspace
key or field termination key are the only valid keystrokes in this mode.
ß The half-height cursor indicates that insert mode is active.
Control Menu Icon

The upper-left corner of the title bar has a button that enables the Control menu
(sometimes referred to as System menu). Although the Control menu is standard in the
Windows operating system, RM/COBOL for Windows has added functions to this menu.
Figure 3-19 illustrates the RM/COBOL for Windows Control menu.
Figure 3-19 RM/COBOL for Windows Control Menu

The Restore, Move, Size, Minimize, Maximize, and Close commands are standard
Control menu functions for the Windows operating system. (For more information, see
the Microsoft Windows documentation that accompanied the operating system.) The
Copy, Copy table, Paste, and Properties commands have been added to the Control menu
by RM/COBOL for Windows. Each of these commands is described in the following
sections.
Copy
Choosing the Copy command from the Control menu copies the text selected in the
client area of the window to the Windows Clipboard. To select text, hold down the
mouse button and drag the mouse to the target area. Double-clicking the mouse button
selects text in the same manner, as described in the Mark Alphanumeric property (see
page 3-23).
Copy table
Choosing the Copy table command from the Control menu copies the text selected in the
client area of the window to the Windows Clipboard, and also replaces multiple spaces
with a tab. This feature is useful in copying a table of numbers to a spreadsheet, since
spreadsheets require that number fields be separated by the tab character.
Paste
Choosing the Paste command from the Control menu copies the text in the Windows
Clipboard to the currently running RM/COBOL program through the COBOL ACCEPT
statement. If more data is pasted than can be accepted by the ACCEPT command, the
data is buffered.
Properties
Choosing the Properties command from the Control menu opens the Properties dialog
box, which is illustrated in Figure 3-11 on page 3-19.
Return Code Message Box

When runcobol.exe terminates with an exit code other than 0, a Return Code message
box appears displaying the status code, as shown in Figure 3-20. (See page 7-8 for more
information on program exit codes.) If a COBOL error occurred, that error message is
displayed as well. The Show Return Code Dialog property can be used to suppress the
display of this message box (see page 3-27).

The message box contains two command buttons. The OK button dismisses the message
box and closes the application. The Cancel button dismisses the message box only. The
application window remains open until you select the Close option from the Control
menu. To close the message box, you can click the Close button in the upper-right corner
of the window.
Figure 3-20 Return Code Message Box
CALL “SYSTEM”
When using the SYSTEM non-COBOL subprogram (CALL “SYSTEM”) with DOS
programs and batch files (see page F-41), you can customize how these programs run by
modifying the MS-DOS Prompt properties. This can be done by right-clicking the mouse
on the MS-DOS Prompt icon and selecting Properties from the pop-up menu.
Performance
For increased file system performance in single-user mode, set the RUN-FILES-ATTR
configuration record option to FORCE-USER-MODE=SINGLE (see page 10-28).

Chapter 4: System
Considerations for Btrieve
This chapter describes special considerations for using RM/COBOL to access Btrieve
files. Btrieve files are an alternative indexed file format to the RM/COBOL indexed file
format. Btrieve files can reside on the local machine, in which case they are accessed via
client-based Btrieve, or they can reside on a remote machine, in which case they are
accessed via server-based Btrieve. The RM/COBOL-to-Btrieve Adapter program
(rmbtrv32) provides the communication between the RM/COBOL runtime and Btrieve
runtime, translating COBOL requests to Btrieve requests.
RM/COBOL-to-Btrieve Adapter Program

(rmbtrv32) Concepts
The RM/COBOL-to-Btrieve Adapter program, rmbtrv32, improves performance by
providing a mechanism to reduce the overhead required to transmit requests for records in
an indexed file across a local area network (LAN).
The goal of the rmbtrv32 program is to use the local area network for passing general
requests to other machines and for receiving completed requests back from the other
machines. As a result, significant increases may occur in the performance of the
application program, the cost-effectiveness of the local area network, and the productivity
of the user.
Note See “RM/COBOL versus Btrieve Indexed File Performance” on page 4-8 for a
situation in which the performance of Btrieve index files may not exceed that of
RM/COBOL indexed files.
Indexed Files
The application program can request a specific record of information in an indexed file.
The location of the specified record within the indexed file is determined by means of an
identifier known as a key. Indexed files use a much more efficient method of locating the
record than simply searching through all the records in the file until the requested record
is found. Instead, indexed files build overhead tables into the file that are similar to
indexes in a book. These overhead tables enable the indexed files to quickly look up the

RM/COBOL-to-Btrieve Adapter Program (rmbtrv32) Concepts
desired location and then read the desired data. Figure 4-1 illustrates this process on a
single-user system.
Note In Figure 4-1, Figure 4-2, and Figure 4-3, each line represents a separate event that
happens at a separate time. The lighter lines represent a small transfer of information, and
the heavier lines represent a large transfer.
Figure 4-1 Indexed File Requests on a Single-User System
Request for Overhead Table
Overhead Table Data
Request for Actual Data

Disk Drive
Actual Data
Computer
When this process happens over a network, the situation is very similar, as shown in
Figure 4-2.
Figure 4-2 Indexed File Requests on a Local Area Network
Local Area Network Cable
Disk Drive
Computer 1 Computer 2
(Client) (Server)
In Figure 4-2, Computer 2 acts as a conduit, called a server, through which the requests of
Computer 1, called a client, are routed. (The server routes requests for more than one
client computer, which is an advantage of local area networks.) A more effective way to
route requests, however, is shown in Figure 4-3.
4-2 System Considerations for Btrieve

Figure 4-3 Indexed File Requests on a Local Area Network by the Btrieve
MicroKernel Database Engine (MKDE)
Requests for Key Cable
Data for Key Disk Drive
Computer 1 Computer 2
(Client) (Server)
Figure 4-3 illustrates the way in which a Btrieve requester (running on the client,
Computer 1) and a Btrieve MicroKernel Database Engine (running on the server,
Computer 2), makes the processing of messages even more efficient. (Note that the
Btrieve MicroKernel Database Engine is a key external component of the rmbtrv32
program.) Although the interactions between Computer 2 and the disk drive are exactly
the same as shown in Figure 4-2, the interactions between Computer 1 and Computer 2
are significantly different. Instead of Computer 1 giving Computer 2 many small
instructions to carry out, Computer 1 now gives Computer 2 a single, general request.
Computer 2 searches the overhead table for the indexed files to locate the desired record
and then returns only the requested record.
There are several advantages to this method, but the following two are the most
significant:
1. The overall operation may be quicker because the number of transfers between the
two computers is reduced.
2. Because there are fewer transfers between the Computer 1 and Computer 2, the local
area network can use the time that it is not performing transfers between the two
computers to make transfers between other computers on the network. It allows the
network to handle more computers, which makes it more cost effective.

Required Software Components
The following components, described in the following sections, are required when using
RM/COBOL to access Btrieve files:
• Novell NetWare version 3.11 or later
• Btrieve MicroKernel Database Engine (MKDE) for NetWare Server, version 6.15
or later
• Btrieve Requester for Windows 95/Windows 98/Windows NT
• RM/COBOL compiler (development system) for Windows
• RM/COBOL runtime system for Windows
• RM/COBOL-to-Btrieve Adapter program (rmbtrv32) for Windows
Note NetWare products are available from Novell, Incorporated. Btrieve products
are available from Pervasive Software, Inc. (formerly Btrieve Technologies, Inc.).
Novell NetWare
NetWare is the software that communicates between computers on the local area network.
These NetWare products are responsible for handling the actual hardware connections,
recovering from transmission errors detected by the hardware, and routing the messages
from one program executing on one computer to another program executing on another
computer.
NetWare augments the operating system by providing access to files on file servers.
Btrieve MicroKernel Database Engine (MKDE)

The MKDE component consists of two types. The first type, a client-based Btrieve
MKDE, provides access to files that are located on the same machine as the application
program. The second type, NetWare Btrieve MKDE, provides access to files that are
located on a remote machine in a multiuser environment.
The NetWare Btrieve MKDE is a record management system similar to the indexed files
built into the RM/COBOL runtime system. Because the NetWare Btrieve MKDE is not
built into the RM/COBOL runtime system, it can run on a separate computer using
NetWare, thus providing access to files in the manner illustrated in Figure 4-3 (see
page 4-3).

There are also versions of the Btrieve MKDE that run on other types of networks and on a
single machine (client-based Btrieve MKDE), without network support. The client-based
Btrieve MKDE, however, no longer has the speed advantage over the RM/COBOL file
management system, since both systems have the same access to the disk drive.
Btrieve Requester for Windows NT, Windows 98, and

Windows 95
The Windows NT, Windows 98, or Windows 95 requester, a dynamic link library (DLL)
program, runs on the client computer and communicates with either the server-based or
the client-based Btrieve MKDE.
RM/COBOL Compiler for Windows

The RM/COBOL compiler (development system) is a GSA-certified high implementation
of the American National Standard COBOL X3.23-1985 with extensions and support for
most optional features of the language.
RM/COBOL Runtime System for Windows

The RM/COBOL runtime system executes the application program and carries out its
instructions. The runtime system has an internal file management system that accepts
input from the user, processes data, produces data in the form of output to the user, and,
most importantly, generates requests for records to be written to and read from files.
The runtime system has been designed so that any existing RM/COBOL application may
be run in many different environments without changes either to the source of the
program or to the actual executable object. Furthermore, any existing RM/COBOL
runtime system that executes on Windows can also use the RM/COBOL-to-Btrieve
Adapter (rmbtrv32) program.
RM/COBOL-to-Btrieve Adapter (rmbtrv32) Program for

Windows
The rmbtrv32 program acts as an interpreter between either of the two types of Btrieve
MKDEs (described on page 4-4) and COBOL application programs. In order to
understand how this transparent interface is achieved, it is necessary to briefly describe
the different ways in which the Btrieve MKDE and the COBOL language provide access
to indexed files.
The Btrieve MKDE lets an application program access records stored in indexed files,
and provides the necessary functions for storing, retrieving, and updating the information.

The Btrieve MKDE’s method of accessing indexed files is an efficient system that
provides significant increases in functionality to the user in certain cases. However,
because the Btrieve MKDE does not use COBOL language features that provide access to
indexed files, a COBOL application program cannot communicate directly with the
Btrieve MKDE.
A COBOL application program uses American National Standard COBOL 1985 language
features, such as OPEN, READ, WRITE, REWRITE, and CLOSE, to access indexed
files. The RM/COBOL runtime system contains a file management system that provides
the runtime system with support for these features. The RM/COBOL runtime system
communicates with the file management system by means of requests and responses that
are called messages. These messages are processed outside of the file management
system by any one of a variety of external file access methods.
The rmbtrv32 program, in effect, is one such external file access method for the
RM/COBOL runtime system. rmbtrv32 receives messages from the RM/COBOL file
management system. Then, acting as an application program for the Btrieve MKDE,
rmbtrv32 translates the messages into Btrieve requests, enabling the Btrieve MKDE to
carry out the action originally requested by the COBOL application program. The
Btrieve MKDE performs the action either on the user’s computer system or acts with
NetWare on a remote system using the local area network. (The drive letter in the
pathname of the file indicates the machine on which the file resides.) After the Btrieve
MKDE has completed the requests, rmbtrv32 constructs an appropriate response
message, which is sent to the RM/COBOL file management system, and, finally, back to
the COBOL application program. Figure 4-4 illustrates this process.
Figure 4-4 RM/COBOL-to-Btrieve Adapter Program (rmbtrv32) Acting as an

External File Access Method
COBOL application RM/COBOL file The rmbtrv32 program

program requests management system translates COBOL request
record. sends request to the into Btrieve request and
rmbtrv32 program sends it to the Btrieve
for processing. MKDE.
RM/COBOL file rmbtrv32 translates The Btrieve MKDE carries

management system Btrieve response into out the request and sends
sends response to COBOL response the Btrieve response to the
the COBOL and sends it to the rmbtrv32 program.
application program. RM/COBOL file
management system.
See page 4-9 for the RM/COBOL-to-Btrieve Adapter program (rmbtrv32) options.

Configuration for Btrieve
The installation and configuration of client-based Btrieve (also called Workstation
Btrieve) for Windows 95, Windows 98, and Windows NT are fully described in the
Btrieve for Windows NT/Windows 95/Windows 98 Installation and Operation manual
supplied by Pervasive Software with your Btrieve system. The client-based Btrieve is the
MicroKernel Database Engine (MKDE) that is used to access local files (that is, Btrieve
files residing on the computer where the RM/COBOL runtime system is run). A number
of configuration settings can be modified using the Btrieve Setup utility. After
configuring Btrieve, use the Btrieve File Manager utility (or other Btrieve software) to
verify that Btrieve is working properly before using Btrieve with RM/COBOL.
Similarly, the installation and configuration of server-based Btrieve (for NetWare or for
the Windows NT Server) are fully described in the Btrieve for NetWare Installation and
Operation manual or the Btrieve for Windows NT Server Edition Installation and
Operation manual, whichever is appropriate, that was supplied by Pervasive Software
with your Btrieve system. These manuals also describe the installation and configuration
of the requesters used to communicate with server-based Btrieve. The server-based
Btrieve is the MKDE that is used to access remote files (that is, Btrieve files residing on
the NetWare or Windows NT Server computer). A number of configuration settings for
both the MKDE and the requesters can be modified by using the appropriate Btrieve
Setup utility.
The Btrieve Programmer’s Guide, supplied by Pervasive Software with your Btrieve
Developer Kit, is an excellent source of information for help in setting the Btrieve
configuration options properly. In addition, several books on Btrieve are available
commercially, and the Btrieve Developer’s Journal is published quarterly by
Smithware, Inc.
System Considerations for Btrieve Files

The RM/COBOL-to-Btrieve Adapter program (rmbtrv32) creates Btrieve files when
necessary or if requested. Btrieve files created by rmbtrv32 have a computed page size
based on one of the following methods that produces the largest value:
1. The size of the block requested by the COBOL application.
2. The size necessary for the length of the longest key, times eight.
3. The size of the largest record requested by the application, plus eight times the
number of linked duplicate keys, plus six (for overhead information), plus four if the
file specifies variable-length records (again for overhead information). See
“Variable-Length Records” on page 4-23 for more information.

Furthermore, if the record size is greater than the maximum page size and the keys of the
file all fit into that maximum, the rmbtrv32 program creates a variable-length file. (The
Btrieve MKDE restricts the fixed-length part of records to less than the page size.)
Finally, rmbtrv32 creates the file with the following characteristics:
• Data compression
• Blank truncation
• Five-percent, free-space threshold
• No page preallocation
To create Btrieve files with characteristics other than those previously listed, use the
Btrieve File Manager utility, the filename, and the Btrieve description-file that contains
the characteristics for the new file. For more information, see the chapter about using the
File Manager utility in the appropriate Btrieve installation and operation manual.
Characteristics established using the Btrieve File Manager utility can have a direct impact
on performance, including the following:
• The page preallocation value can be used to reserve pages for use by the file. This
has the advantage of ensuring, in advance, that the file has the disk space it needs. It
can also improve performance by concentrating the location of the file on the disk
media (assuming that the disk space is not already fragmented).
• The free-space threshold value can be set to 10, 20, or 30 percent to allow for growth
of variable-length records.
• Keys can be created that are binary or have any of the extended key types.
• Null keys can be created.
• More keys can be defined than can be used by the COBOL program. These keys
must be defined either at starting locations that are different from the COBOL keys
or after the COBOL key description for the same location. Such keys can have any
Btrieve attribute and can be split.
RM/COBOL versus Btrieve Indexed File Performance

In general, when used across the network, Btrieve indexed files have better performance
than RM/COBOL indexed files because less network activity has to occur to access a
record.
However, there is a case in which this may not be true. When a COBOL program opens
an indexed file WITH LOCK, the COBOL program then has exclusive access to that file.

This has an important consequence for RM/COBOL indexed files. In this case, the
RM/COBOL runtime system knows that no other user is able to change the indexed file
overhead tables on the server, and it keeps the overhead tables on the local machine. This
results in fewer requests across the network for the overhead tables and may result in
better performance than the same program using Btrieve indexed files.
This effect is most pronounced when the indexed file is being read sequentially (for
example, producing a report).
RM/COBOL-to-Btrieve Adapter Program

(rmbtrv32) Options
The rmbtrv32 program has options that are specified on the
EXTERNAL-ACCESS-METHOD or on the RUN-INDEX-FILES configuration
record in the RM/COBOL configuration file. (See pages 10-20 and 10-31, respectively.)
These configuration file options, described in the following sections, give rmbtrv32
information that the Btrieve MKDE requires, but which is not contained in RM/COBOL
file management system messages.
Note Typically when configuring the Btrieve MKDE, it is often sufficient to specify
only the “Largest Compressed Record Size” Btrieve configuration option if you are using
compression (see the appropriate Btrieve installation and operation manual for more
details).
EXTERNAL-ACCESS-METHOD Configuration Record Options

Most of the information that the rmbtrv32 program needs to operate can be
obtained through requests received from the RM/COBOL file management system.
However, when rmbtrv32 needs information required by the Btrieve MKDE, which
the RM/COBOL file management system cannot supply, it is possible to provide
this information directly to rmbtrv32 with the following options in the
EXTERNAL-ACCESS-METHOD configuration record:
• B (rmbtrv32 Btrieve MKDE page size option)
• Create option
• D (Duplicates option)
• I (Initial display option)
• L (Lock option)

RM/COBOL-to-Btrieve Adapter Program (rmbtrv32) Options
• M (Mode option)
• O (Owner option)
• P (rmbtrv32 page size option)
• T (Diagnostic trace filename)
These options are described in the following sections.
Note The create option is specified by the CREATE-FILES keyword in the

EXTERNAL-ACCESS-METHOD configuration record. The other options
(B, D, I, L, M, O, P, and T) are specified by the OPTIONS keyword in the
EXTERNAL-ACCESS-METHOD configuration record. (For more information,
see page 10-20.)
B (rmbtrv32 Btrieve MKDE Page Size Option)
This option is obsolete and should not be specified. The “Maximum Page Size” is no
longer a configurable parameter of the Btrieve engine, which always assumes the Btrieve
limit of 4096 bytes. If this value is inadvertently specified as an amount smaller than
4096, rmbtrv32 may create a Btrieve file with variable-length records when such records
would not be needed.
Create Option
The create option, for creating a new file, has the following values:
• Yes Create new files as Btrieve indexed files (the default).
• No Do not create new files.
See the description of the CREATE-FILES keyword in the

EXTERNAL-ACCESS-METHOD configuration record on page 10-20.
The create option is the determinant parameter supplied to the rmbtrv32 program,
because it determines the system that will be responsible for creating a new indexed file.
Depending on the value specified in this parameter, the new file can be created by
rmbtrv32, by another external file access method, or by the RM/COBOL file
management system. In order to understand how this process works, it is helpful to know
more about the way in which the RM/COBOL file management system searches for a file.
Before an application program creates a file, the RM/COBOL file management system
first tries to locate an existing file having the same name as the one specified in the
create attempt. The file management system searches the current directory first, and
then all the other directories located in the environment variable, RUNPATH. (See

“Directory Search Sequences” on page 3-11 for more information on setting the
RUNPATH variable.)
In addition to the rmbtrv32 program, other external file access methods can be running
on the computer or network at the same time. In searching for a file, the RM/COBOL file
management system also communicates with all other known external file access methods.
The search for the filename occurs in the following sequence:

1. Any external file access methods currently running (including rmbtrv32) search the
current directory.
2. The RM/COBOL file management system searches the current directory.
3. The external file access methods search the first directory in the RUNPATH list.
4. The RM/COBOL file management system searches the first directory in the
RUNPATH list.
The search continues until all pertinent directories have been checked. If a file having the
same name as the one specified in the create attempt is found, it will be opened. If such a
file cannot be found, and the application program wants to create one, then a designated
external file access method can create the file.
The rmbtrv32 program create option value is a yes or no indicator that specifies whether
you want rmbtrv32 to create any new indexed files as Btrieve files. Regardless of the
value specified, any new file is created in the first directory possible, usually the current
directory. Valid values are Yes and No. The default value is Yes.
A value of Yes causes any new indexed files to be created as Btrieve files:
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 CREATE-FILES=YES
A value of No causes rmbtrv32 not to create the file and enables another external file
access method or the RM/COBOL file management system to create new indexed files:
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 CREATE-FILES=NO
D (Duplicates Option)
The duplicates option is used to specify whether linked or repeating duplicatable keys are
used for files created by rmbtrv32.
The duplicates option has the following values:
• L Create linked duplicatable keys. Linked duplicates mean that only one copy of
the duplicated key value is stored in index pages. The data records with the
duplicated key value are linked together with pointers in a doubly-linked list.

• R Create repeating duplicatable keys. Repeating duplicates mean that the
duplicated key value is repeated in the index pages for each data record with
that value. The data records are not linked together. Using repeating
duplicates uses more space in index pages, but saves space in data pages and
also helps avoid position lost errors when files are shared.
The default value is L. Refer to the Btrieve Programmer’s Guide for more information.
The following example tells rmbtrv32 to create files with repeating duplicatable keys:
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 OPTIONS='D=R'
I (Initial Display Option)
The initial display option is used to specify whether or not rmbtrv32 should display an
initial message box when it is first invoked.
The initial display option has the following values:
• Y (Yes) Display the message box. The message box shows the rmbtrv32
version number and the OPTIONS parameter string that was passed to it from
the EXTERNAL-ACCESS-METHOD configuration record. The user must
click the OK button to acknowledge and continue. This option is most useful
the first time the user attempts to use rmbtrv32 with RM/COBOL and
Btrieve.
Note I=Y should not be used in a production environment.
• N (No) Do not display the message box.
The default value is N.
Example
The following example tells rmbtrv32 to display the informative message box:
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 OPTIONS='I=Y'

L (Lock Option)
The lock option is used to specify the manner in which the rmbtrv32 program is to
handle the WITH LOCK phrase on OPEN statements.
The lock option has the following values:
• I Ignore the WITH LOCK phrase. Use the Btrieve MKDE open mode indicated
with the M option (see page 4-14).
• D Deny the WITH LOCK phrase.
• A Accept the WITH LOCK phrase. If OPEN WITH LOCK is requested by

the application, ignore the open mode indicated with the M (mode) option
described on page 4-14.
The default value is A.
Examples
The following example tells rmbtrv32 to ignore the WITH LOCK phrase on OPEN
statements:
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 OPTIONS='L=I'
The following example tells rmbtrv32 to deny the WITH LOCK phrase on OPEN
statements:
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 OPTIONS='L=D'
The following example tells rmbtrv32 to accept the WITH LOCK phrase on OPEN
statements:
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 OPTIONS='L=A'

M (Mode Option)
The mode option is used to specify a value to rmbtrv32 at the time a Btrieve file is
opened. The following values are used only if the file is not OPENed WITH LOCK. See
the L (lock) option, described previously. The mode option has the following values:
• N Normal
• A Accelerated
• R Read-only
• V Verify
• E Exclusive
The default value is N.
Note The ability of rmbtrv32 to specify a mode value is dependent on whether the
application program requests the WITH LOCK phrase on OPEN statements. See the lock
option on page 4-13 for more information.
Examples
In normal mode, the Btrieve MKDE behaves as it normally does with its recovery option
enabled, allowing update requests and performing normal writes to the disk drive. The
following example specifies a value of normal when the file is opened:
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 OPTIONS='M=N'
In accelerated mode, the data recovery capability of the Btrieve MKDE is disabled to
increase the speed at which records are updated. The following example specifies a value
of accelerated when the file is opened:
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 OPTIONS='M=A'
In read-only mode, no updates can be performed. The following example specifies a

value of read-only when the file is opened:
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 OPTIONS='M=R'
Verify mode is now disregarded and the MKDE assumes normal mode instead.
In exclusive mode, the user has exclusive access to the file until the user closes it. This is
the same as specifying EXCLUSIVE or WITH LOCK on the OPEN statement in the
COBOL program.
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 OPTIONS='M=E'

O (Owner Option)
The owner option specifies the “owner” ID (actually a security password) for new files
and open requests for existing files. The value is a string of up to a maximum of eight
characters delimited by a trailing space. The value cannot contain spaces. The following
example specifies an owner ID of YELLOW:
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 OPTIONS='O=YELLOW'
P (rmbtrv32 Page Size Option)
The rmbtrv32 page size option is the default minimum page size for the files created
by rmbtrv32. Btrieve files are physically accessed in fixed-length pieces called pages.
When rmbtrv32 creates a new file, the Btrieve MKDE requires the specification of a
page size. The size of a page is determined from either the page size option or a
computation based on the size of the record. See “Variable-Length Records” on
page 4-23 for more information. A larger page size transfers more data in a single disk
request, requires more time to transfer, and requires more memory to contain the pages.
A smaller page size allows more blocks in memory for a fixed amount of memory, but
requires more time to randomly access a record by increasing the tree depth of each index
for the file.
If specified, the value must be a multiple of 512 in the range of 512 to 4096, inclusive.
When creating a file, the page size used will be the smallest multiple of 512 sufficient to
hold the file overhead, eight keys, the fixed part of the record, or, if specified, the default
page size, whichever is greater.
The following example sets the value of the page size option to 1024:
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 OPTIONS='P=1024'
T (Diagnostic Trace Filename Option)
This option is used to specify the pathname of a file to which rmbtrv32 will write a trace
of open requests. This feature is used when there is a problem with a Btrieve file not
being successfully opened by a COBOL program. It is not to be used in a production
environment, because it degrades performance and the trace file can become quite large,
which might exhaust disk space. To turn on the trace feature, edit the RM/COBOL
configuration file for the COBOL program in question and add a T=trace-file-name
parameter to the OPTIONS keyword in the EXTERNAL-ACCESS-METHOD
configuration record (see page 10-20). For example, the following record writes trace
information to the file c:\test\trace.fil:
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 OPTIONS='T=C:\test\trace.fil'

The trace file contains a “Begin open” and “End open” pair of records for every open
request that rmbtrv32 receives. This includes all opens that runcobol does for files, such
as its message file and the COBOL program file, as well as every OPEN statement
executed by the COBOL program. The “End open” line shows the COBOL status code
returned to the RM/COBOL file management system. Between the “Begin” and “End”
lines, zero or more “BTRV Create” or “BTRV Open” lines show the full pathname of the
file, the exact Btrieve status code returned by the name of the file, and the exact Btrieve
status code returned by the Windows Btrieve DLLs. The following is a sample trace file:
Trace Initialized
Begin open, Not indexed
End open, Code=35
End open, Code=35
End open, Code=35
Begin open, Flags=0x4900 (file must exist)
UFN=INX1
BTRV Open status 0 on file C:\TEST\INX1
End open, Code=0
Begin open, Flags=0xe100 (file must exist)
UFN=INX2
End open, Code=35
Begin open, Flags=0xe000
UFN=INX2
BTRV Create status 0 on file C:\TEST\INX2
End open, Code=0
When you are finished diagnosing the problem, be sure to edit the configuration file again
and remove the T=trace-file-name parameter from the OPTIONS keyword in the
EXTERNAL-ACCESS-METHOD configuration record.
RUN-INDEX-FILES Configuration Record Options

In addition to the options specified on the EXTERNAL-ACCESS-METHOD, two
RUN-INDEX-FILES keywords have meaning for rmbtrv32: DATA-COMPRESSION
and BLOCK-SIZE. (For more information, see page 10-31.)
Specifying DATA-COMPRESSION=NO causes rmbtrv32 to create uncompressed

Btrieve files. The default is to create compressed Btrieve files. (Note that Btrieve does
not support key compression.)

Specifying BLOCK-SIZE=nnnn causes rmbtrv32 to create files with a page size of nnnn.
rmbtrv32 first computes the minimum allowable page size for the file based on the
record size, number of key segments, type of duplicates, and so forth. It then uses the
first value greater than or equal to the computed minimum value in the following order:
1. From the BLOCK CONTAINS clause in the program’s file description entry.
2. From the P=<page size> option parameter on the OPTIONS keyword in the
EXTERNAL-ACCESS-METHOD record (see page 10-20).
3. From the RUN-INDEX-FILES BLOCK-SIZE=<size> configuration record.
If none of these three values is present or acceptable, rmbtrv32 uses the computed
minimum value.
Example
The following example represents a typical command line invoking runcobol using
rmbtrv32:
runcobol userprog x=config.cfg
where the config.cfg file contains the following records:
RUN-INDEX-FILES DATA-COMPRESSION=NO
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32
& CREATE-FILES=YES
& OPTIONS='P=1024, D=R, O=XyZzY'
The ampersand (&), which begins the third and fourth lines in this example, is the
configuration file record continuation character. Note that different RM/COBOL
applications can specify different rmbtrv32 option parameters by using different
RM/COBOL configuration files.

Starting the RM/COBOL-to-Btrieve Adapter
Program (rmbtrv32) for Windows
The RM/COBOL-to-Btrieve Adapter (rmbtrv32) program and either the client-based
Btrieve MKDE or the Windows 95/Windows 98/Windows NT Btrieve requester
programs are all started automatically. This process is initiated by the user placing the
following configuration record in the RM/COBOL configuration file and starting the
RM/COBOL runtime system:
EXTERNAL-ACCESS-METHOD NAME=RMBTRV32
The only requirement is that Windows must be able to locate the various executable files
that are required.
Note The server-based Btrieve MKDE (running on a NetWare server or on a Windows

NT Server) must be started separately. Refer to the appropriate Btrieve installation and
operation manual for information on starting server-based Btrieve.
The rmbtrv32 program, rmbtrv32.dll, is a dynamic link library (DLL) that can be
loaded by the Windows 95, Windows 98, and Windows NT version of RM/COBOL.
rmbtrv32.dll communicates directly with wbtrv32.dll, which is the Btrieve interface
DLL supplied with your Btrieve system. The wbtrv32.dll file is normally installed, along
with a number of other DLL, EXE, and other Btrieve files, in a separate Btrieve
executable subdirectory.
Since RM/COBOL and Btrieve are separate products supplied by separate vendors, the
executable files required by each are normally installed in the separate directory
structures. Therefore, the recommended way of ensuring that Windows can locate the
files is to place the directory names containing the files into the Windows PATH
environment variable. For RM/COBOL, this is the directory containing rmbtrv32.dll
(and also containing runcobol.exe, and so forth). For Btrieve, this is the directory
containing wbtrv32.dll (and other DLLs and EXEs). Add these two directory names to
your Windows PATH (which is often done in the autoexec.bat file).
Although it is not the recommended method, Windows will find the executable files if
they reside in any combination of the following:
1. The directory that contains the runcobol.exe that is started.
2. The current directory.
3. The Windows system directory (normally c:\windows\system).

Starting the RM/COBOL-to-Btrieve Adapter Program (rmbtrv32) for Windows
4. The main Windows directory (normally c:\windows).
5. Any directory in the PATH environment variable
Note Both the Btrieve MKDEs and rmbtrv32.dll have keywords that can be passed to
them when they are started. If no parameters are specified, the programs use default
values.
For information on specifying keywords in the EXTERNAL-ACCESS-METHOD

configuration record, see page 10-20. For more information on rmbtrv32 options, see
page 4-9.
The rmbtrv32 program, the Windows 95/Windows 98/Windows NT Btrieve requester,

and the client-based Btrieve MKDE all terminate automatically when the final
RM/COBOL runtime system using them terminates. Server-based Btrieve (running on a
NetWare or Windows NT Server) must be terminated separately; however, server-based
Btrieve normally remains running as long as the server computer remains running.
RM/COBOL Indexed Files and Btrieve

MicroKernel Database Engine (MKDE)
Limitations
This section describes the limitations of the Btrieve MicroKernel Database Engine
(MKDE), and the way in which these limitations affect RM/COBOL indexed files.
Although these two systems perform the same functions, they do not operate in the same
manner.
Note For more information on the RM/COBOL limits and ranges, see Appendix B,
Limits and Ranges.
Current Record Position Limitations

A COBOL application program can sequentially read through all the records in an
indexed file. The manner in which a requested record is presented to the application
program for the READ operation varies, depending on how the file was created. The
Btrieve MicroKernel Database Engine (MKDE) behaves according to ANSI COBOL
1985 for simple READ statements.
However, for READ NEXT statements, the behavior of the Btrieve MKDE can vary from
ANSI COBOL 1985. According to ANSI COBOL 1985, the determination of the next
record to be read is not affected by subsequent non-READ operations. As long as the

RM/COBOL Indexed Files and Btrieve MicroKernel Database Engine (MKDE) Limitations
COBOL application program does not perform any non-READ operations to the indexed
file, the Btrieve MKDE behaves according to ANSI COBOL 1985. If non-READ
operations are performed to the file, however, the Btrieve MKDE defines the next record
as being the one after the non-READ operation.
The RM/COBOL-to-Btrieve Adapter program, rmbtrv32, compensates for this variation

by remembering the location of the record that was last read, and the surrounding records,
in order to set the position indicator back to the correct place following the non-READ
operation. This compensation works completely when a single-user is accessing the file,
but can fail in a shared file environment.
In a Btrieve shared file environment, rmbtrv32 can become lost when reading records via
a key containing duplicate key values. If the COBOL application program performs a
non-READ operation between a READ and a READ NEXT statement, and an application
program running on the same or another computer deletes the current record and the
records around it (and all these records contain duplicate key values), then rmbtrv32
becomes lost and returns an error message 46,02 to the application program (see
page A-20 for more information).
This position-lost problem can be avoided when the shared Btrieve file is accessed via a
version 6.1 or later Btrieve MKDE. rmbtrv32 sets the new No Currency Change (NCC)
option on Insert and Update operations so that Btrieve will not change the current record
position. In addition, the user can specify the use of repeating duplicatable keys (see the
D (Duplicates Option) on page 4-11 of this guide and the discussion of Linked versus
Repeating Duplicatable keys in the Btrieve Programmer’s Guide). Using both of these
features avoids the position lost problem and retrieves the correct record.
File Position Indicator Limitations

The file position indicator specifies the next record to access within a file during certain
sequences of input-output operations.
If the COBOL program executes a START LESS THAN statement and there are multiple
records in the file that contain duplicate keys (for example, multiple records having the
same key value that satisfy the START LESS THAN condition), then the file position
indicator will be positioned to the last record in the sequence of duplicate key values.
The same result occurs if you execute a START LESS THAN OR EQUAL statement
where the equal condition is not met.
If no new records containing duplicates for a key value are added to the file, then
rmbtrv32 behaves identically to the RM/COBOL file management system for the
succeeding READ NEXT or READ PREVIOUS statements. The RM/COBOL file
management system does not move the file position indicator from the record originally

located by the START statement. This position is the record returned for succeeding
READ NEXT or READ PREVIOUS statements.
The Btrieve MKDE does not allow rmbtrv32 to emulate this behavior if new records are
added that contain duplicates for a key value. rmbtrv32 moves the file position indicator
to the last record added at the time of the succeeding READ NEXT or READ
PREVIOUS statement.
Note Once the READ statement has been executed, the position is known, and the
RM/COBOL file management system and the Btrieve MKDE again behave the same.
Permission Error Detection Limitations

When you attempt to open an RM/COBOL indexed file and rmbtrv32 is active,
rmbtrv32 may open the file before the RM/COBOL file management system opens the
file. If the indexed file is already opened by the RM/COBOL file management system on
another computer, the Btrieve MKDE returns a Permission Error to rmbtrv32 instead of
a Not a Btrieve File error. rmbtrv32 assumes that the file is an already-opened
RM/COBOL indexed file and reports an Invalid Organization error to the file
management system, which then attempts to open the file. If the file is an RM/COBOL
indexed file, the open succeeds. If the problem was one with permissions, then the
RM/COBOL file management system encounters it also and returns the correct error
code.
Using Existing Btrieve Files with RM/COBOL

RM/COBOL and ANSI COBOL 1985 define some limitations on indexed files that are
not imposed by the Btrieve MKDE.
rmbtrv32 creates new Btrieve files that are compatible with the COBOL concept of
indexed files. Existing Btrieve files can be used also, providing they have the following
characteristics:
• The primary key cannot have a null value.
• Alternate keys can be modified, can use either the native or alternate collating
sequence (ACS), can be binary, and can have a null value.
• Keys cannot have the following Btrieve key flags: descending, supplemental, and
any-segment null. Keys must use ACS number zero, if any.

• Keys do not have to be created in the file in any particular order. However, within
the file, there must be at least one key residing at the correct position for each
COBOL key. That key must be of the correct length, contain the correct duplicates
flag, and cannot contain any of the restrictions on keys as described above.
Furthermore, this key must be defined within the Btrieve file before any other keys
that start at the same position. Subsequent keys may have forbidden characteristics.
• There can be more keys in the Btrieve file than in the COBOL description and they
can have characteristics that are not legal for COBOL keys. However, they must
either have a starting position that does not match the starting position for any
COBOL key, or they must occur in the Btrieve definition after the COBOL key
description for that position.
• Within the record there should not be any multiple-byte integer data fields.
rmbtrv32 will not reject any files with fields of this type. Because of byte ordering,
however, there are no COBOL data types that can directly manipulate the integer
data in the field.
If an OPEN OUTPUT is performed on an existing Btrieve file, all characteristics of the

original file are preserved. This includes any compression (or lack of it) and any extra
keys. The file is simply made empty.
Btrieve MicroKernel Database Engine (MKDE) Limitations

Affecting RM/COBOL Applications
The Btrieve MKDE has limitations that may affect existing COBOL applications:
• Version 5 Btrieve files have a maximum record size of 55296 bytes. Version 6
Btrieve files support record sizes of 64 KB or more using “chunk” operations.
rmbtrv32 does not use any Btrieve “chunk” operations; therefore, the maximum
record size is limited by the communication environment in which Btrieve runs.
When accessing server-based Btrieve (remote files), the maximum record size is
57000 bytes. When accessing client-based Btrieve (local files), the maximum record
size is 64512 bytes. The largest possible record size without using variable-length
records is 4088 bytes. RM/COBOL files have a maximum record size of 65280
bytes.
• Btrieve files have a minimum record length of four bytes. RM/COBOL files have a
minimum record length of one byte. rmbtrv32 supports files whose record size is
less than four bytes by using a zero-filled, four-byte record.
• Btrieve files must have all keys located within the first 4096 bytes of a record.
RM/COBOL files may have keys located anywhere within the record.

• Btrieve files have a limit of 119 key segments. RM/COBOL files have a limit of 255
key segments.
• Btrieve files have a maximum key size of 255 bytes. The RM/COBOL runtime
system (including rmbtrv32), however, supports a maximum key size of 254 bytes.
Variable-Length Records
RM/COBOL will support variable-length records using the Btrieve MKDE’s
variable-length record files. The size of the Btrieve data page will be either the minimum
record length or the maximum Btrieve MKDE page size, whichever is smaller.
For more details, refer to the discussion of variable-length records, logical and physical
record lengths, and page sizes in the Btrieve Programmer’s Guide.
Key Placement
The Btrieve MKDE restricts placement of keys within the first data page of a record. If a
file has variable-length records, the keys must fit within the minimum record length of the
file or the maximum Btrieve MKDE page size, whichever is smaller.
Automatic Creation of Variable-Length Record Files

If a COBOL program creates a file with a record size greater than the maximum Btrieve
page size, and the keys of that file fit within the maximum Btrieve page size, then the file
will be created with a record size equal to the maximum Btrieve page size, with the
remainder of the record in the variable-length portion of the Btrieve record. (The Btrieve
MKDE allows the portion of the record past the fixed length to be considerably longer.)
Verification of Maximum Record and Block Length

Btrieve files do not have a mechanism for storing the maximum record length and
maximum block length for a file. If a Btrieve file is opened with a maximum length for
its RECORD CONTAINS or BLOCK CONTAINS clause that does not match the
maximum length at the time the file was created, the mismatch will not be detected.
Support for RM/COBOL Internal Data Formats

The Btrieve MKDE internally stores integers in Intel binary integer format, with the most
significant byte at the highest address and the least significant byte at the lowest address.
Therefore, applications that access Btrieve files written outside of RM/COBOL cannot
directly access the following three RM/COBOL internal data formats since they store

numbers in the opposite manner (as binary integers with the most significant byte at the
lowest address and the least significant byte at the highest address):
• BINARY data
• COMPUTATIONAL-1 data
• COMPUTATIONAL-4 data
For more information about RM/COBOL internal data formats, refer to Appendix C,
Internal Data Formats.
Support for Btrieve Internal Data Formats

RM/COBOL programs can directly access the following Btrieve internal data formats:
• Decimal
• Money
• Numeric Signed ASCII
• Numeric Signed Trailing Separate
• String
All other Btrieve internal data formats can be interpreted by an RM/COBOL program on
a byte-by-byte basis. For more information about Btrieve internal data formats, refer to
“Extended Key Types” in the Btrieve Programmer’s Guide.
Input/Output Errors
Input/output errors that you would expect to occur for an RM/COBOL indexed file may
not occur for a Btrieve file. Because of its file structure and organization, information in
Btrieve files is stored differently than in RM/COBOL indexed files, or it is not recorded
at all. Thus, the RM/COBOL runtime system is unable to check or verify certain values
in these files.
For example, the error message 39,01, which normally occurs if an error is encountered
when the runtime system is trying to open an RM/COBOL indexed file, may not occur if
the file is a Btrieve file. Appendix A, Runtime Messages, provides more information on
this and other specific input/output error codes where this behavior can occur.

Chapter 5: System Verification
A suite of verification programs is provided with RM/COBOL. These programs ensure
that your delivered diskettes are undamaged and that you have installed the required
software correctly.
System Verification for UNIX

To invoke compilation and execution of the verification suite, enter:
doverify
For runtime-only systems, the compilation step is ignored.
The verification suite is designed to be self-explanatory. Follow the prompts on the

screen for instructions on selecting and running individual tests.
Note 1 If a problem occurs with the display features of the verification suite, make
sure you have properly set and exported the environment variable TERM for your
terminal type. If you have done this and a problem exists, verify that your terminal type
has an entry in the system terminal database (termcap or terminfo) and check the accuracy
of the cursor motion sequence. This can be accomplished by running the system visual
editor (vi).
Note 2 If any of the menu selections within the terminal configuration test work
incorrectly, refer to Chapter 8, RM/COBOL Features, for details on the terminal attributes
required by the runtime system for complete ACCEPT and DISPLAY functionality.
Single-User Tests
Six sets of tests are provided in the verification suite for single-user versions. They are as
follows:
1. Terminal Configuration Test. This consists of individual tests that verify the
functionality of ACCEPT and DISPLAY statements and defaults, screen editing
functions and color functions (for appropriately configured terminals).
2. File System Test. This tests the sequential, relative, and indexed file system. It
reads and writes records to each of the three file types.
3. Nucleus Test. This tests the modules of the RM/COBOL nucleus.

4. Printer Test. This tests that the printer configuration is correct and that
communication from RM/COBOL to the printer is successful. If no printer is
attached, preserve the test result in the prntst.out file by entering:
PRINTER=prntst.out; export PRINTER
before running this test.
5. Sort-Merge Test. This tests the sort-merge function of RM/COBOL.
6. Pop-Up Window Manager Test. This test ensures that the RM/COBOL
Pop-Up Window Manager feature is installed correctly. The program displays a
self-explanatory menu that allows you to test the various features of the Pop-Up
Window Manager system. If the runtime system has been linked to not include the
Pop-Up Window Manager, the program displays an appropriate message (see
Appendix D, Customizing RM/COBOL for UNIX).
Multiuser Test
An additional verification program is provided with an appropriately licensed, multiuser
version of RM/COBOL. This test ensures that RM/COBOL is interacting correctly with
the file protection mechanisms employed by your system.
The program pacetest needs to be run simultaneously from at least two terminals that use
the RM/COBOL runtime system on the computer. This test creates and uses two indexed
files: pinx and pinxfl. pinx is a file that contains a single control record which contains
the next available record in pinxfl. pinxfl is the working data file.
pacetest reads the control record, saves it, increments the control record, and writes it
back to pinx. The original number read is used as the primary key for the record written
to the growing pinxfl file. This scenario is repeated 100 times for each user running the
test. With two users running, 200 records would be written to pinxfl. The directions for
running pacetest are as follows:
1. Invoke pacetest at each terminal as follows:
runcobol pacetest
2. At one terminal only, choose function 1 to create the initial files. Wait for this
operation to complete.
3. At each terminal, choose function 2 to do simultaneous write operations. You will be
required to enter a unique station ID (1, 2, and so forth). Then, all stations should try
to press the Enter key simultaneously.
5-2 System Verification

4. At any of the terminals, choose function 3 to read the file. Make sure all the records
are shown in order and are all there (100 records are written by each station).
If pacetest encounters any errors while reading the file, it will sound an alarm and display
an error message next to the record in question. Should this occur, double-check your
software installation. If everything appears to be set up correctly and you are still having
problems, contact Liant technical support services.
System Verification for Windows

To invoke compilation and execution of the verification suite, choose the icon named
doverify. The doverify program allows the user to select compilation and/or execution.
For runtime-only systems, the program detects that the compiler is not present and
informs the user. The user may still select the execution option.
The verification suite is designed to be self-explanatory. Follow the prompts on the

screen for instructions on selecting and running individual tests.
Single-User Tests
Six sets of tests are provided in the verification suite for single-user versions. They are as
follows:
1. Terminal Configuration Test. This consists of individual tests that verify the
functionality of ACCEPT and DISPLAY statements and defaults, screen editing
functions and color functions (for appropriately configured terminals).
2. File System Test. This tests the sequential, relative and indexed file system. It reads
and writes records to each of the three file types.
3. Nucleus Test. This tests the modules of the RM/COBOL nucleus.
4. Printer Test. This tests that the printer configuration is correct and that
communication from RM/COBOL to the printer is successful. If no printer is
attached, preserve the test result in the prntst.out file by setting a synonym before
running this test. Using the Synonyms Properties tab (see page 3-29 for more
information), type PRINTER in the Name text box and type prntst.out in the Value
text box.
5. Sort-Merge Test. This tests the sort-merge function of RM/COBOL.
6. The Pop-Up Window Manager Test. This program displays a self-explanatory
menu that allows you to test the various features of the Pop-Up Window Manager.

Multiuser Test
An additional verification program is provided with an appropriately licensed, multiuser
version of RM/COBOL. This test ensures that RM/COBOL is interacting correctly with
the Novell NetWare software. Before using RM/COBOL on the network, you need to
install the Novell NetWare software and be familiar with its operation.
The program pacetest needs to be run simultaneously from each computer that uses the
RM/COBOL runtime system on the network. This test creates and uses two indexed files:
pinx and pinxfl. pinx is a file that contains a single control record which contains the
next available record in pinxfl. pinxfl is the working data file.
pacetest reads the control record, saves it, increments the control record, and rewrites it
back to pinx. The original number read is used as the primary key for the record written
to the growing pinxfl file. This scenario is repeated 100 times for each user running the
test. With two users running, 200 records would be written to pinxfl. The directions for
running pacetest are as follows:
1. Compile pacetest by choosing the RMCOBOL icon and selecting pacetest.cbl as the
source file.
2. Invoke pacetest at each computer by choosing the RUNCOBOL icon and selecting
pacetest.cob as the object file.
3. At one computer only, choose function 1 to create the initial files. Wait for this to
complete.
4. At each computer, choose function 2 to do simultaneous write operations. You will
be required to enter a unique station ID (1, 2, and so forth). Then, all stations should
try to press the Enter key simultaneously.
5. At any of the computers, choose function 3 to read the file. Make sure all the records
are shown in order and are all there (100 records are written by each station).
If pacetest encounters any errors while reading the file, it will sound an alarm and display
an error message next to the record in question. Should this occur, double check your
network installation. If everything appears to be set up correctly and you are still having
problems, contact Liant technical support services.
5-4 System Verification

Chapter 6: Compiling
RM/COBOL programs are compiled with a single pass of the RM/COBOL compiler.
Specifically, the compiler performs the following actions on the contents of the source
programs:
• Verifies syntactic accuracy.
• Creates object programs for execution with the RM/COBOL runtime system. Liant’s
use of this technique provides compactness and machine-independence.
• Creates program listings, the contents of which are chosen by entering the
appropriate Compile Command options.
This chapter presents complete information about the RM/COBOL compiler.
Compilation Process
The RM/COBOL compiler is invoked when you enter the Compile Command, rmcobol.
Once invoked, the compiler makes one pass through the specified source file. During this
pass, both object files and listing files are generated. The object file contains the
machine-independent object code, executed at runtime, for the RM/COBOL program.
The listing file contains a source image, which may be printed at the end of each
compilation. Using the available Compile Command options, you can alter, augment, and
suppress portions of the information contained in the listing.
RM/COBOL provides standard COBOL subprogram structure, but no intermediate

linkage process stands between program compilation and execution. It is also possible to
define sections of code within your program as overlay segments to the fixed permanent
segment, as explained in the discussion of segmentation in Chapter 5, Procedure
Division, of the RM/COBOL Language Reference Manual.
Note By default, the RM/COBOL compiler window disappears immediately when a

successful compilation completes. If you want the window to remain visible, set the
Persistent property to TRUE (see page 3-24).

Compilation Process
System Files
RM/COBOL takes its input from a source file, and creates an object file and a listing file.
Source Files
RM/COBOL source files contain the RM/COBOL source code. Source lines are made
up of variable-length records. Source text is ASCII, with either a line feed (LF) character
or a carriage return (CR) and line feed (LF) character paired as the line separator.
Embedded tab characters are expanded to one or more spaces, according to the default
tab column position, which is every fourth column, starting with column 8 and
ending with column 72, or according to the value of the TAB-STOPS keyword in the
RUN-SEQ-FILES configuration record (see page 10-35).
Object Files
An object file is created on disk as a purely binary file. Its filename is identical to the
filename of the source file, with the filename extension .cob or .COB (or the extension
specified in the EXTENSION-NAMES configuration record described on page 10-19).
You can direct the object file to a directory other than the one on which the source file
resides. To do this, use the O Compile Command Option. The object file may be
suppressed by the use of the N Option.
Listing Files
The contents of RM/COBOL listings are detailed later in this chapter, beginning on
page 6-18. Listings can be directed to a disk file, the printer, the screen, or any
combination thereof, depending on the options selected in the Compile Command.
Listing files are given the filename of the source program, with the filename extension .lst
or .LST (or the extension specified in the EXTENSION-NAMES configuration record
described on page 10-19). The listing file is a printer file and therefore may be
configured using the PRINT-ATTR configuration record (see page 10-20).
6-2 Compiling
System Files
Libraries
A source file can contain more than one source program. Files containing a sequence of
two or more programs are referred to in this manual as libraries. With libraries, the
generated object file contains a distinct object module for each source program in the
source file, excluding contained programs. The object for a contained program is
considered part of the object of the program that contains it. The listing file contains a
complete listing of each source program in the source file.
Each noncontained program in a source file or library is compiled strictly independent of

the other programs: there need be no relationship between them. However, this
capability to concatenate multiple source programs into a single library is used most
effectively when there is some logical relationship among the programs. This might be a
main program and the called subprograms, or all the programs that include a specific copy
file or group of copy files. In the latter case, recompilation of all the source programs
affected by a change in one of the copy files can be accomplished with a single invocation
of the Compile Command.
Note RM/COBOL versions 1 and 2 did not require END PROGRAM headers to
separate a sequence of source programs. Versions 3 and later support nested programs,
which makes END PROGRAM headers necessary. If you have a source file with a
sequence of programs and no END PROGRAM headers, you can either add the headers
or specify the Z=2 Compile Command Option (described on page 6-14).
Use the Combine Program utility (rmpgmcom), detailed in the discussion that begins on
page G-9, to combine multiple object files into a single library when the source modules
are contained in separate files.
Compile Command
Use the Compile Command (rmcobol) to request program compilation and to specify
options.
Under UNIX, the Compile Command is entered at a shell prompt. After typing the
desired command and options, press Enter to begin compilation.
Under Windows, the Compile Command can be entered in the Command Line text box of
the Shortcut dialog box. See page 3-7 for instructions on creating a Shortcut. Choose the
RMCOBOL icon to begin compilation. Programs also may be executed by dragging the
.cbl source file to the RMCOBOL object or by double-clicking the source file.

Libraries
The format of the Compile Command is as follows:
rmcobol filename [[(] [[~]option ] … [)c o m m e n t ]]
filename is the name of the source file to be compiled. It may be any valid operating
system pathname, and may by partially or fully qualified. Specifying an extension is
optional, but that extension must not be the same as the object file extension (.cob or
.COB unless configured otherwise). If you do not enter a filename extension with
the pathname, the compiler begins its search for the source file by looking first for
the file exactly as specified. If it cannot find such a file, it looks for a file with the
supplied name and an extension .cbl. If the file is still not found when running under
UNIX, it looks for a file with an extension of .CBL. For all attempts to open the
source file, if neither a drive designator nor a directory path is specified, the directory
search sequence is used. If a directory path is specified, a directory search sequence
may be used if configured properly. See the discussions that begin on page 2-4 for
UNIX and page 3-11 for Windows, and the EXPANDED-PATH-SEARCH
configuration keyword discussed on page 10-27.
~ (tilde) can be used as a negation character. Its purpose is to negate the presence of
attributes in a COMPILER-OPTIONS configuration record (see page 10-6). Its use
is fully described in Step 2 on page 6-5.
option specifies the RM/COBOL compiler options, described in the next section.
Spaces or commas must separate options. Options may be entered in either
uppercase or lowercase letters. If an option is repeated in a command, the last
occurrence of the option is used. Each option may be preceded by a hyphen. If any
option is preceded by a hyphen, then a leading hyphen must precede all options.
When a value is assigned to an option, the equal sign is optional if leading hyphens
are used.
comment is used to annotate the command. The comment is ignored by the compiler
and has no effect on the compilation. The left parenthesis is always optional. The
right parenthesis is a required separator if comments are entered.
Up to 83 characters of the Compile Command—including the pathname—are copied into

the option list field within the listing header, so that they are reproduced at the top of each
listing page.
6-4 Compiling
Compile Command
Compile Command Options
Compile Command options can be specified in the following two ways:
1. They can be placed into a configuration file, which is processed by the

RM/COBOL compiler when the appropriate command line option is specified. (See
the discussion of the COMPILER-OPTIONS configuration record that begins on
page 10-6.)
2. They can be specified in the Compile Command itself.
Options read from the configuration file are processed before options in the Compile
Command. This means that options specified in a Compile Command will always
override conflicting or contradictory options in a configuration file. The configured
options, together with the options that appear in a Compile Command, apply to every
source program in the source file referred to in that Compile Command.
You can override specific options in a configuration file by negating the option in the
Compile Command. To do this, enter a tilde (~) and the option in the Compile
Command. For example, the following configuration file, possibly named config.cfg:
COMPILER-OPTIONS FLAGGING=HIGH,COM2,OBSOLETE
& OBJECT-VERSION=2
& LISTING-PATHNAME=LISTINGS
directs RM/COBOL to flag HIGH, COM2 and OBSOLETE language elements, to restrict
the object version level to 2, and to write the listing file to the directory named
LISTINGS.
For a particular compilation, you may want to suppress some or all configured options.
For example, to suppress the flagging of COM2 elements and the creation of the listing
file (here, assuming the program name is PAYROLL), enter the following Compile
Command:
rmcobol payroll G=config.cfg F=~COM2 ~L
This negates the flagging of COM2 elements and suppresses the creation of the listing file
(L option) for the compilation. The next time you use this configuration file in a
compilation, the configured options will be in effect again.
To disable all flagging, and to write the listing to the current directory, enter the following
Compile Command:
rmcobol payroll G=config.cfg ~F, L=.

Compile Command
This negates the flagging of HIGH, COM2 and OBSOLETE elements, and writes
the listing to the current directory instead of to LISTINGS as specified in the
configuration file.
A negated option calls up the default value for that option; that is, it behaves exactly as if
no option were configured.
There are six groups of Compile Command options:
1. Compiler configuration options
2. Data item options
3. File type options
4. Listing options
5. Object program options
6. Source program options
The following sections contain a complete description of the Compile Command options.
Compiler Configuration Options
The following compiler options designate a file to be used as the complete compiler
configuration or as a supplement to it and allow suppression of the compiler banner
message.
G Use the G Option to designate a file to be used as the compiler configuration. The
G Option has the following format:
G=path
See the discussion of the COMPILER-OPTIONS configuration record that begins on

page 10-6. See also the H Compile Command Option.
By default, a configuration file is not designated.
H Use the H Option to designate a file as a supplement to the compiler configuration.

The H Option has the following format:
H=path
If no configuration exists (specified with the G Option), the specified file serves as
the complete configuration. See Chapter 10, Configuration.
By default, a supplemental file is not designated.
6-6 Compiling
Compile Command
K Use the K Option to suppress the banner message and the terminal error listing. This
is useful when you are running under batch files or shell scripts.
By default, this information is displayed on the standard output device.
W Use the W Option to specify the amount of memory (in kilobytes) that the compiler
should use for its internal table storage. The W Option has the following format:
W=n
n is a decimal number from 32 to 16384.
The default value is 1024 kilobytes (1024 KB).
Data Item Options
The following compiler options direct the compiler to assume a certain usage for data
items.
S Use the S Option to direct the compiler to assume a separate sign when the SIGN
clause is not specified for a DISPLAY usage, signed numeric data item (that is, for a
data item whose PICTURE character-string clause begins with S) . The S Option
also allows a BLANK WHEN ZERO clause to be specified in the data description
entry of a signed numeric data item for compatibility with RM/COBOL 2.n. In such
cases, a trailing fixed insertion plus symbol (+) is assumed for the PICTURE
character-string.
Note This option should be used only when compiling existing source programs
written with an earlier version of RM/COBOL, and then only with caution. The use
of this option creates inconsistencies between RM/COBOL and ANSI COBOL 1974
and 1985.
The default is to assume a trailing combined (zoned) sign unless the SIGN clause is
present and to disallow the BLANK WHEN ZERO clause for signed numeric data
items. For more information about trailing combined (zoned) signs, see Table C-1 on
page C-2.
U Use the U Option to direct the compiler to assume an alternative usage for data items
described as COMP or COMPUTATIONAL. The U Option has the following
format:
U[=B|D|P]
The U Option specified alone or as U=B directs the compiler to assume BINARY
usage for data items described as COMP or COMPUTATIONAL. This option
causes COMP data items to be compatible with IBM OS/VS COBOL COMP data
items and may result in improved computational speed at runtime.

Compile Command
The U=D Option directs the compiler to assume DISPLAY usage for items described
as COMP or COMPUTATIONAL.
The U=P Option directs the compiler to assume PACKED-DECIMAL usage for
items described as COMP or COMPUTATIONAL.
The U[=B] and 2 Options are mutually exclusive; they may not appear in the same
Compile Command.
The default is to assume unpacked decimal format for data items described as COMP
or COMPUTATIONAL.
File Type Options
The following compiler options determine whether a sequential file is declared as a binary
sequential or a line sequential file.
B Use the B Option to define as binary sequential those sequential files not explicitly
declared to be line sequential in their file control entries. (See page 8-40 for a
discussion of file types and structure.)
V Use the V Option to direct that any sequential file not declared to be binary
sequential be considered line sequential.
Note The B and V Options are mutually exclusive; they may not appear in the same
Compile Command. If neither the B nor the V Option is used, the decision on whether
the file is binary sequential or line sequential is deferred to program execution. The
choice is then controlled by the configured DEFAULT-TYPE keyword (see page 10-35).
Listing Options
The following compiler options generate a listing and control the destination and contents
of the listing.
Note The L, P, and T Options direct the listing to different destinations; any or all of
these options may appear in the same Compile Command. If neither the T nor the K
Option is selected, an error-only listing is written to standard output.
6-8 Compiling
Compile Command
A Use the A Option to direct the compiler to generate the allocation map in the listing
(see the discussion that begins on page 6-22).
This is useful during program development for use with the RM/COBOL Interactive
Debugger.
The A Option may not be specified if none of the L, P, T, or Y=3 Options are
specified or configured.
By default, the allocation map is not created as part of the listing or debugging
information in the object file.
C Use the C Option to suppress the inclusion of copied text in the listing.
Copied text is source text brought into the program as a result of encountering a
COPY statement. (The COPY statement is described in more detail in the discussion
that begins on page 8-31 of this user’s guide, and in Chapter 1, Language Structure,
of the RM/COBOL Language Reference Manual.)
The C Option suppresses only the inclusion of the copied text in the listing; the
copied text is always compiled. Even though the C Option is selected, erroneous
lines encountered in the copied text during compilation are written to the listing along
with the associated diagnostic message.
Text to the right of the COPY statement in the source line that contains that statement
appears on a line by itself, immediately following the copied text.
The C Option may not be specified if none of the L, P, T, Y=2, or Y=3 Options are
By default, copied text is included in the source listing. Copied text immediately
follows the line that contains the COPY statement.
E Use the E Option to suppress the inclusion of the source program component in the
listing. However, if errors are encountered during compilation, the listing will
include the erroneous lines and their associated diagnostic messages.
The E Option may not be specified if none of the L, P, or T Options are specified or
configured. The E Option is ignored if the Y=2 or Y=3 Options are specified.
By default, the source program component is included in the listing.
L Use the L Option to direct that a listing file be written to disk. The L Option has
the following format:
L[=path]
The L Option specified above directs the compiler to write the listing to the
default directory.

Compile Command
path specifies a directory into which the listing file is to be written.
The listing file will always have the same name as the source file; its extension will
be the listing file extension (.lst or .LST unless configured otherwise). On those
operating systems that have case-sensitive filenames, the case of the extension will
match the case of the first character of the source file’s extension, or the first
character in the source file’s name if there is no extension. If there is no extension
and the first character of the source filename is not a letter, then the extension .lst
will be used. (See Table 1-1 on page 1-5 for examples of valid filenames.)
The default directory, when path is not specified, depends on whether the source
filename was specified with a drive or directory in its value.
If the source filename was specified with a drive or directory in its value, the default
directory is the one containing the source file.
Otherwise, the default directory is determined by using the compiler directory search
sequence. If an existing file with the same name as the source file and the listing file
extension is found using the compiler directory search sequence (see page 2-4 for
UNIX and page 3-11 for Windows), the default directory is the one in which that file
is found. If such a file is not found using the compiler directory search sequence, the
default directory is the current directory.
If a file already exists with the specified name and extension in the specified or
default directory, it is overwritten.
By default, the listing is not written to disk.
P Use the P Option to direct the compiler to write a copy of the listing to the printer.
Without a print spooler, the P Option cannot be used when the printer is busy.
By default, a copy of the listing is not written to the printer. See the discussion of the
listing that begins on page 6-18.
R Use the R Option to direct the compiler to generate a sequential number in the first
six columns of source records as they appear on the listing. The source file itself is
not affected.
If selected, this option numbers records beginning with 1 for each source or copy
input file. The number can be helpful when editing the source file. This line number
cannot be used with the RM/COBOL Interactive Debugger.
The default is to print the source record exactly as read, including any commentary
information present in columns 1 through 6.
6-10 Compiling
Compile Command
T Use the T Option to direct the compiler to write a copy of the listing to the standard
output device. Generally, the standard output device is the screen, but this can be
controlled through redirection.
By default, a copy of the listing is not written to the standard output device.
However, the last two lines of the summary listing—as well as all erroneous lines and
associated diagnostic messages—are written to the standard output device regardless
of the T Option. This display can be suppressed with the K Option (see page 6-7).
X Use the X Option to direct the compiler to generate a cross reference map in the
listing. The cross reference map contains an alphabetic list of all user-defined words
that appear in the source program. For each user-defined word, the line number of
each appearance is listed. Each line number is marked to indicate that the word is
being used as a declaration, a source operand or a possible destination operand. (See
Figure 6-10 on page 6-28 for a sample of the cross reference map.)
The X Option may not be specified if none of the L, P, T, or Y=3 Options are
By default, the cross reference map is not included in the listing or in the debugging
information in the object file.
Object Program Options
The following compiler options generate or suppress an object program and control the
destination and features of the object program.
M Use the M Option to direct the compiler to suppress automatic conversions in certain
ACCEPT and DISPLAY statements. In Format 1 and 3 ACCEPT statements, this
option suppresses automatic input conversion for numeric operands and suppresses
right justification for justified operands. For Format 3 DISPLAY statements
(DISPLAY screen-name), this option suppresses automatic output conversion for
numeric fields within the screen description entry.
Note This option must be used if Format 1 ACCEPT statements with numeric
operands are to be treated in compliance with ANSI COBOL 1985 and 1974.
The default is to provide input conversion for numeric operands of Format 1 and 3
ACCEPT statements, right justification for justified operands of Format 1 and 3
ACCEPT statements, and output conversion for numeric fields of Format 3
DISPLAY statements.
N Use the N Option to suppress the generation of an object program.
The default is to generate object code according to the rules for the O Option,
described in the following section.

Compile Command
O Use the O Option to specify the directory pathname where the object file will be
placed. The O Option has the following format:
O=path
path specifies a directory into which the object file is to be written.
The object file will always have the same name as the source file. Its extension will
be the object file extension (.cob or .COB unless configured otherwise). On those
operating systems that have case-sensitive filenames, the case of the extension will
match the case of the first character of the source file’s extension, or the first
character in the source file’s name if there is no extension. If there is no extension
and the first character of the source filename is not a letter, then the extension .cob
will be used. (See Table 1-1 on page 1-5 for examples of valid filenames.)
The O and N Options may appear together in a single compilation. For example, the
OBJECT-PATHNAME keyword in the COMPILER-OPTIONS configuration record
(see page 10-14) specifies the directory for the object file. Entering the N Option on
the Compile Command suppresses the generation of the object file (and as a result
negates the OBJECT-PATHNAME keyword in the configuration file).
The default directory depends on whether or not the source filename was specified
with a drive or directory in its value.
If the source filename was specified with a drive or directory in its value, the default
directory is the one containing the source file.
Otherwise, the default directory is determined by using the directory search sequence.
If an existing file with the same name as the source file and the object file extension
is found using the compiler directory search sequence, the default directory is the one
in which that file is found. If such a file is not found using the compiler directory
search sequence (see the appropriate installation and systems considerations chapter
in this user’s guide for your specific operating system), the default directory is the
current directory.
If a file already exists with the specified name and extension in the specified or
default directory, it is overwritten.
6-12 Compiling
Compile Command
Q Use the Q Option to direct the compiler to eliminate debugging information from
generated object programs. Programs compiled with this option will appear invisible
to the Interactive Debugger and Instrumentation. A statement address consisting of
an optional segment number and segment offset will be substituted for line numbers
in Normal Termination, Error Termination and Traceback runtime system messages.
A segment number and segment offset replace line number references when this
option is selected.
Note This option may be used to both reduce the memory requirements and increase
the execution speed of most programs.
The default is to generate debugging information in object programs.
Y Use the Y Option to direct the compiler to output debugging information in the
object file. The Y Option has the following variations:
Option Action
Y=0 or ~Y Omits the symbol and debug line table from the object program
file. This is also the default behavior if Y is not specified.
Y=1 or Y Places the symbol table but not the debug line table in the object
file. When the symbol table is included in the object program
file, the source program data-names and index-names may be
used in Debug commands during execution (see Chapter 9,
Debugging).
Y=2 Places both the symbol table and the debug line table in the
object file. The line table is used by CodeWatch to display the
source program.
Y=3 Same as Y=2, except that the debug line table also includes
allocation map and cross-reference information if the A and/or X
option are also specified. This information can then be viewed
within CodeWatch, but may lead to large object program files.
Object program files created with Y=2 and Y=3 are fully compatible with all
versions of the RM/COBOL runtime (note that previous versions will ignore these
tables). This option does increase the size of the object program files, but has no
effect on runtime performance or memory requirements.
Note A new option in the rmpgmcom utility (see Appendix G, Utilities), STRIP,
may be used to remove symbol table and debug line table information from object
files that were created with Y=1 or Y=2. For source code security, object program
files that contain line table information should be reduced in size with this option or
recompiled without the Y option before they are redistributed.

Compile Command
Z Use the Z Option to indicate the highest allowed object version of the generated
code. The Z Option has the following format:
Z=version
version must be an integer in the range 1 through 8.
Statements that require a higher object version level than the value specified will
be flagged in error (see page 6-33 and the description of the COMPUTATIONAL-
VERSION keyword for the COMPILER-OPTIONS configuration record that begins
on page 10-10). This option forces the generation of code accepted by earlier
versions of the RM/COBOL runtime system.
Appendix H, Object Versions, lists the changes between object versions.
The default is to use the current object version number (8).
For source programs created with versions 1 or 2 that contain a sequence of programs
without an END PROGRAM header, this option can prevent the compiler from
treating the second or subsequent programs as contained programs. Since version 3
is the first version supporting nested source programs, setting Z=1 or Z=2 forces the
compiler to treat the source file as a sequence of programs even in the absence of an
END PROGRAM header.
7 Use the 7 Option to specify the semantic rules under which the program is to be
compiled.
7 specifies that the source program is to be compiled with ANSI COBOL 1974
semantics. ANSI COBOL 1974 semantics affect the I-O status values,
PERFORM . . . VARYING statements, ALPHABETIC class conditions, and
alphabetic-edited data items. A more specific discussion of these semantic
differences can be obtained by contacting Liant technical support services.
The 7 Option is implied if the 2 Option is specified.
The default is to compile the source program using ANSI COBOL 1985 semantics.
6-14 Compiling
Compile Command
Source Program Options
The following compiler options affect the analysis of the source program and cause
flagging of certain source features.
D Use the D Option to direct RM/COBOL to compile all source programs as if the
WITH DEBUGGING MODE clause appeared in each compiled program. This
option causes all source lines with the letter D in the indicator area to be compiled as
if they had a space in the indicator area.
This option is independent of the RM/COBOL Interactive Debugger, described in

Chapter 9, Debugging.
The default is to treat source lines with the letter D in the indicator area as
commentary information unless the WITH DEBUGGING MODE clause is specified
in the source program.
F Use the F Option to direct the compiler to flag occurrences of these language
elements:
COM1 INTERMEDIATE
COM2 OBSOLETE
EXTENSION SEG1
HIGH SEG2
The F Option has the following format:
 F=(keyword −list)
 F=keyword 
 
keyword-list specifies multiple elements to be flagged. Enclose the list in

parentheses, and if the keyword-list contains more than one item, separate them with
a space or comma. If leading hyphens are being used, the parentheses are optional.
You can negate an individual keyword by preceding it with a tilde (~).
keyword specifies a single element to be flagged.
The names of elements can be abbreviated, as long as they remain unique. If the
abbreviation is not unique, the keyword that occurs first alphabetically is chosen. For
example, C, CO and COM are valid abbreviations of COM1 but not of COM2.
Certain keywords cause more than one element of the language to be flagged:
1. Selecting INTERMEDIATE flags both HIGH and INTERMEDIATE elements.
2. Selecting COM1 flags both COM1 and COM2 elements.
3. Selecting SEG1 flags both SEG1 and SEG2 elements.

Compile Command
See Appendix I, Extension, Obsolete, and Subset Language Elements, for a complete
list of elements flagged.
By default, no elements of the language are flagged.
2 Use the 2 Option to direct the compiler to accept source programs created for the
RM/COBOL (74) 2.n compiler.
If the programs were compiled (or designed to be compiled) without the RM/COBOL
(74)2.n compiler ANSI Option, the separate sign (S) and line sequential (V) Options
(described on pages 6-7 and 6-8, respectively) may also need to be selected.
The 2 Option removes certain words from the list of RM/COBOL reserved words.
The removed words are those that are RM/COBOL additions to RM/COBOL (74)
2.n; thus, all words used in the earlier version as user-defined words are still valid.
Note carefully that if RM/COBOL language features are added to the program, the 2
Option can no longer be used, and the program must be changed accordingly. There
is also a technique for removing individual words from the list of reserved words.
See the discussion of the COMPILER-OPTIONS configuration record on page 10-6.
The 2 Option directs that COMP-3 data items always be signed, irrespective of the
presence or absence of an S in the associated PICTURE character-string.
The 2 Option directs that COMP-1 data items behave as in RM/COBOL (74) 2.n.
This causes the number of digits in the PICTURE character-string describing a
COMP-1 item to be ignored in three situations: when the item is the receiving item
in a MOVE statement, in an arithmetic statement that specifies ON SIZE ERROR,
and in an ACCEPT statement that specifies, explicitly or implicitly, input conversion.
In these situations, the COMP-1 item may contain any value in the range –32768
through 32767.
The 2 Option directs that OPEN EXTEND create a new file when the file is not
present, even when OPTIONAL was not specified in the file control entry.
The 2 Option directs that equality and inequality relation conditions, where the
subject and object are similar signed packed-decimal (COMP-3 or PACKED-
DECIMAL usage) or signed unpacked-decimal (COMP usage) operands, should not
be optimized to use string comparison operations. The string comparison
optimization prevents detection of equality when the only difference between the
subject and object of the relation results from the change in positive sign convention
for such items.
The 2 Option directs that the size of index data items be two bytes in length.
The 2 Option directs that the implied EXIT PROGRAM required by ANSI COBOL
1985 at the end of the Procedure Division be omitted. RM/COBOL (74) 2.n had
only an implied STOP RUN at the end of the Procedure Division.
6-16 Compiling
Compile Command
The 2 and U[=B] Options are mutually exclusive; they may not appear in the same
Compile Command.
The 2 Option implies the 7 Option.
The default is to recognize all RM/COBOL reserved words, treat COMP-3 data
items without an S in their PICTURE character-string as unsigned data items, treat
COMP-1 data items the same as two-byte COMP-4 data items, return a file not
present error for OPEN EXTEND of a nonexistent file not described with the
OPTIONAL phrase in its file control entry, use the string comparison optimization
for conditional relations of similar signed COMP-3 and COMP data items, use a size
of four bytes for index data items, and include the implied EXIT PROGRAM at the
end of the Procedure Division.
Sample Compile Commands

Here are examples of valid and invalid RM/COBOL Compile Commands.
Valid Compile Commands

rmcobol payroll.con P, V R
This command compiles the program named payroll.con; it directs the listing to the
system printer (the P Option); declares all sequential files not defined as binary sequential
in the source program to be line sequential files (the V Option); and sequentially numbers
the printed listing, starting with 1 for each copy level, in the first six columns of the listing
(the R Option).
rmcobol demo.prg (D,L=COBOL,S X) 3RD COMPILE
This command compiles the program demo.prg; the program is compiled as if the WITH
DEBUGGING clause were present (the D Option); the listing is written to the directory
named COBOL (the L Option); a separate sign is assumed in the absence of a SIGN
clause (the S Option); and the cross reference map is generated (the X Option). A
comment—3RD COMPILE—is reproduced in the listing header, but is ignored by the
compiler.
Note Under UNIX, the parenthesis must be preceded with a backslash (\) character in
order to be protected from the shell.

Sample Compile Commands
Invalid Compile Command
rmcobol payroll.cob B V
Here, the extension to the filename (.cob) is illegal, since .cob is the default extension for
the object file. The B and V Options are entered together: B treats all sequential files not
specified as either binary sequential or line sequential in the file control entry as binary
sequential, but V treats all such files as line sequential.
Listing
Depending on the options specified in the Compile Command, the compiler generates a
detailed listing. The T Option (see page 6-11) directs the listing to standard output. The
listing can be directed to the printer with the P Option (see page 6-10) and to a file with
the L Option (see page 6-9). All three of these options—or any combination thereof—
may be specified. However, keep in mind that in certain circumstances the listing may
contain lines as long as 118 characters. If the device to which the listing is sent cannot
accommodate lines of that width, characters at the right end of the long lines will be
truncated.
Note Error lines are always listed to standard output unless suppressed by the K Option
(see page 6-7).
The components of the listing (in order of appearance) are as follows:
1. Program listing, which contains the source image of the program.
2. Allocation map, which defines and locates each identifier used in the program.
3. Called program summary, which lists the names of all programs called or canceled
by the program being compiled.
4. Cross reference listing, which lists the names of all identifiers used in the program,
along with the source line numbers at which they are declared and used.
5. Summary listing, which provides status information on the compilation itself.
When the listing is written to a printer (either because the P Option is selected or because
a disk file that was generated as a result of the L Option is printed), each component starts
a new page.
6-18 Compiling
Listing
Program Listing
At the top of each page of the program listing, a header appears, a sample of which
appears in Figure 6-1.
Figure 6-1 Program Listing Header
z RM/COBOL (Version 7.0n.00) for operating-system 03/15/1999 08:52:03 Page 1 z

O Source file: ALLOCMAP Options: L A X O
Note The date and time formats are configurable (see the discussion of the
COMPILER-OPTIONS configuration record that begins on page 10-6).
Each page of the program listing also contains a subheader, illustrated in Figure 6-2.
Figure 6-2 Program Listing Subheader
z LINE DEBUG PG/LN -A 1 B..+....2....+....3....+....4....+....5....+....6....7..IDENTFCN

z
O O
This subheader sets a scale against which material on each page can be measured. The
column of numbers under the “LINE” heading contains sequential line numbers assigned
by the compiler to each line read from the source file or from a copy file; these line
numbers are used in the cross reference listing and in Debug. The numbers under the
“DEBUG” heading are used with the Interactive Debugger or for interpreting error
messages when the compiler Q Option is used; this column is used only when listing the
Procedure Division. The remaining headings locate the regions of the source line images:
the internal six-column line number field, area A, area B, the main body of the source
image (subdivided into ten-column subregions) and the eight-column identification field.
If the R Option was present in the Compile Command, the program listing contains a
compiler-generated line number in the PG/LN column.
The subheading is sometimes useful in determining when the text of a source line has
inadvertently extended beyond column 72, and is therefore not seen by the compiler.
The program listing itself contains the sequential line number, statement address, copy
level indicator (described in the next paragraph) and the source record. If errors were
detected during compilation, the appropriate error message diagnostic appears. The error
message marker and diagnostics are detailed on page 6-31.

Listing
The copy level indicator is a character-string of the following form:
+ n +
n is a decimal digit in the range 1 through 9. The copy level indicator appears
between the sentence address (DEBUG heading) and source record in the listing
whenever the source record has been copied at level n.
A sample of a program listing is shown in Figure 6-3.
Statement addresses are listed in decimal notation. For overlay segments, the segment
number is printed as part of the statement address. A slash separates the segment number
from the offset within the segment. For example:
50/000100
refers to location 100 within segment 50. Segment numbers and the slash are suppressed
for the fixed permanent segment.
The generation of the program listing may be suppressed by specifying the E Option
(page 6-9) in the Compile Command. Copied source text can be suppressed with the C
Option (page 6-9). Error messages (if any) and their associated undermarks and source
text are not suppressed, even when the C or E Option has been selected.
6-20 Compiling
Listing
Figure 6-3 Sample Program Listing
z 12 IDENTIFICATION DIVISION.
PROGRAM-ID. ALLOCMAP. z
3 ENVIRONMENT DIVISION.
O 4 CONFIGURATION SECTION. O
z 5
6
SOURCE-COMPUTER. IBM-PC-XT.
OBJECT-COMPUTER. IBM-PC-XT, z
7 PROGRAM COLLATING SEQUENCE EBCDIC-CODE.
O 8 SPECIAL-NAMES. O
z 9
10
SWITCH-1 IS REPORT-MODE,
ON STATUS IS REPORT-LIST, z
11 OFF STATUS IS REPORT-NOLIST;
O 12 SWITCH-3 IS DISPLAY-MODE, O
z 13
14
ON STATUS IS DISPLAY-LIST,
OFF STATUS IS DISPLAY-NOLIST; z
15 CO1 IS TOP-OF-FORM;
O 16 CO5 IS AMOUNT-LINE; O
z 17
18
CONSOLE IS PC-DISPLAY;
SYSIN IS STANDARD-IN; z
19 SYSIN IS STANDARD-OUT;
O 20 ALPHABET ASCII-1 IS STANDARD-1; O
z 21
22
ALPHABET ASCII-2 IS STANDARD-2;
ALPHABET NATIVE-1 IS NATIVE; z
23 ALPHABET EBCDIC-CODE IS EBCDIC;
O 24 ALPHABET BACKWARDS IS "ZYXWVUTSRQPONMLKJIHGFEDCBA"; O
z 25
26
SYMBOLIC CHARACTERS QUESTION-MARK, ASTERISK ARE 64, 43;
CLASS PUNCTUATION IS ";", ",", ".", "!", "?". z
27 INPUT-OUTPUT SECTION.
O 28 FILE-CONTROL. O
z 29
30
SELECT REPORT-FILE1 ASSIGN TO PRINTER;
ORGANIZATION IS SEQUENTIAL; z
31 ACCESS IS SEQUENTIAL.
O 32 SELECT LOOKUP-FILE1 ASSIGN TO DISC; O
z 33
34
ORGANIZATION IS RELATIVE;
ACCESS IS SEQUENTIAL. z
.
O . O
z 151 .
PROCEDURE DIVISION USING ARG1-GROUP, ARG2-GROUP. z
152 000002 A.
O 153 000005 CALL "CHRRTN" USING NW5-MDATE, NW5-MTIME. O
z 154
155
000016 CALL MATHRTN USING NBS-1, NBU-1, NCS-1, NCU-1,
NLC-1, NPS-1. z
156 000035 STOP RUN.
O 157 END PROGRAM ALLOCMAP. O

Listing
Allocation Map
The allocation map provides information on each user-defined word from the source
program, listed in the order declared. The type of user-defined word (described in the
following section) determines the allocation map format. The allocation map is generated
in the listing when the A Option is specified in the Compile Command (see page 6-9) or
the LISTING-ATTRIBUTES keyword is configured with the ALLOCATION-MAP value
(see page 10-12).
Alphabet-Names, Symbolic-Characters, Mnemonic-Names and

Class-Names
User-defined words declared in the SPECIAL-NAMES paragraph are listed in the

allocation map with the following information:
1. Association, which is the value for a figurative or symbolic-character; the code-name

for an alphabet-name; the switch-name for a mnemonic-name or condition-name
associated with a switch-name; the channel-name for a mnemonic-name associated
with a channel-name; the low-volume-I-O-name for a mnemonic-name associated
with a low-volume-I-O-name; or blank for a class-name. The value of a figurative or
symbolic-character is listed as the hexadecimal value in the native character set. If
that value represents a printable character, the printable character is listed in
quotation marks.
2. Status, which is On or Off for a condition-name associated with a switch-name. The

letters PCS appear with an alphabet-name declared as the program collating
sequence. Otherwise, the column is blank.
3. Type, which indicates whether the user-defined word is: an alphabet-name;

a mnemonic-name associated with a switch-name; a condition-name; a
mnemonic-name associated with a channel-name; a mnemonic-name associated
with a low-volume-I-O-name; a class-name; or a symbolic-character.
4. Name, which is the actual user-defined word declared with the indicated attributes or
the figurative constant LOW-VALUE or HIGH-VALUE. These particular figurative
constants are listed since their value depends on the program collating sequence
declared in the source program.
Figure 6-4 is an example of this part of the allocation map.
6-22 Compiling
Listing
Figure 6-4 Allocation Map (Part 1 of 5)
z Special-Names
Association Status Type Name z
X"00" Figurative constant LOW-VALUE
O X"FF" Figurative constant HIGH-VALUE O
z SWITCH-1
SWITCH-1 On
Switch-name
Condition-name
REPORT-MODE
REPORT-LIST z
SWITCH-1 Off Condition-name REPORT-NOLIST
O SWITCH-3 Switch-name REPORT-MODE O
z SWITCH-3
SWITCH-3
On
Off
Condition-name
Condition-name
REPORT-LIST
REPORT-NOLIST z
C01 Channel-name TOP-OF-FORM
O C05 Channel-name AMOUNT-LINE O
z CONSOLE
SYSIN
Low-volume-I-O-name
Low-volume-I-O-name
PC-DISPLAY
STANDARD-IN z
SYSOUT Low-volume-I-O-name STANDARD-OUT
O STANDARD-1 Alphabet-name ASCII-1 O
z STANDARD-2
NATIVE
Alphabet-name
Alphabet-name
ASCII-2
NATIVE-1 z
EBCDIC PCS Alphabet-name EBCDIC-CODE
O Literal Alphabet-name BACKWARDS O
z X"3F" = "?"
X"2A" = "*"
Symbolic-character
Symbolic-character
QUESTION-MARK
ASTERISK z
Class-name PUNCTUATION
O O
alphabet-names, symbolic-characters, mnemonic-names, and class-names
Split Key Names

User-defined words, declared as part of a RECORD KEY clause in an indexed file
control entry of the Environment Division that defines a split key, are listed in the
1. File-Name is the name of the file from the indexed file control entry.
2. Key-Number specifies the number of the key that has a split key defined. A value of
zero indicates the prime record key. Alternate keys are numbered from 1 to 254.
3. Type indicates that the entry is a split-key-name.
4. Name is the name associated with the split key.
Figure 6-5 illustrates a section of the allocation map for a file that defines split keys for
the primary key and the second alternate key in the file control entry.
z Split Key Names for program SPLITKEY

File-Name Key-Number Type Name z
FILE-1 0 Split-key-name KEY-1
O 2 Split-key-name KEY-2 O
split-key-names

Listing
Data-Names, Condition-Names, File-Names and Cd-Names
User-defined words declared in the Data Division, other than index-names, are listed in
the allocation map with the following information:
1. Address, which is the decimal address for data-names. The “Address” column is
blank for file-names, cd-names and condition-names.
For data items declared with the external attribute in the File Section or
Working-Storage Section, the compiler-generated external number is printed on
a line preceding the file or level 01 item description.
For data-names declared in the Linkage Section, each level 01 or 77 item is preceded
by an indication of how it is addressable:
• If it is listed in the USING phrase of the Procedure Division header, “Un:” and
“Using argument n” are printed to indicate the formal argument umber is n
within the USING argument list.
• If it is listed in the GIVING (RETURNING) phrase of the Procedure Division

header, “G:” and Giving argument” are printed to indicate that the item is the
formal GIVING argument.
• If it is a based linkage record and is not a formal argument, “Bn:” and “Based
linkage record n” are printed to indicate that the compiler assigned based linkage
record number is n.
• If none of the preceding descriptions apply, “Not addressable” is printed to

indicate that the Linkage Section data item is not available to the program.
2. Size, which is the decimal number of character positions required to store the value
of a data-name, or the maximum block size—in characters or records—for a file-
name declared with a non-zero block size. The “Size” column is blank for cd-names
and condition-names.
3. Debug, which contains an abbreviated type indicator used in the Interactive

Debugger to describe the format of the data item. The “Debug” column contains
“Fixed” or “Variable” for file-names to indicate that records of the file are fixed or
variable length, respectively. The “Debug” column is blank for cd-names and
condition-names.
Note These first three columns (Address, Size, and Debug) are used with the
Interactive Debugger to display and modify the values of data-names. See
6-24 Compiling
Listing
4. Order, which indicates the number of subscripts required when referencing the
data-name or condition-name. The “Order” column is blank for data-names not
requiring subscripting and also for file-names and cd-names. When one or more
subscripts are required, the order is indicated with a decimal number enclosed in
parentheses.
5. Type, which is a brief description of the item associated with the user-defined word.
For files, the organization and access are listed, in that order, separated by a slash.
6. Name, which is the actual user-defined word declared with the listed attributes. The
name is indented one column to the right for each increase in level-number.
z File Section for program ALLOCMAP

Address Size Debug Order Type Name z
Variable File Seq/Seq REPORT-FILE1
O 8 80 ANS Alphanumeric REPORT-RECORD-1 O
z 8 40
.
ANS Alphanumeric REPORT-RECORD-2
z
.
O . O
z Working-Storage Section for program ALLOCMAP
Address Size Debug Order Type Name z
532 112 GRP Group G1
O 532 8 ABS Alphabetic ABS-1 O
z 540
548
8
8
ANSE
ABS
Alphanumeric edited
Alphabetic, just
ANSE-1
ABSR-1 z
.
O . O
z .
Linkage Section for program ALLOCMAP z
Address Size Debug Order Type Name
O U1: Using argument 1 O
z 0
0
44
4
GRP
NSU
Group
Numeric unsigned
ARG-GROUP
ARG-COUNT z
4 8 ANS (1) Alphanumeric ARG-AREA
O . O
z .
. z
Communication Section for program ALLOCMAP
O Address Size Debug Order Type Name O
z 734 12 ANS
Cd for Input
Alphanumeric
NET-WORK-1
NW1-SYM-Q z
746 12 ANS Alphanumeric NW1-SQ1
O 758 12 ANS Alphanumeric NW1-SQ2 O
z 770
782
12
6
ANS
NSU
Alphanumeric
Numeric unsigned
NW1-SQ3
NW1-MDATE z
data-names, condition-names, file-names and cd-names

Listing
Index-Names
User-defined words declared as index-names in the Data Division are listed in the
1. Address, which is the decimal address of the index-name within the

index-name table for the program. For index-names with the external attribute,
the compiler-generated external number is printed on a line preceding the
index-name description.
2. Span, which is the decimal number of character positions of the table entry
associated with the index-name. This value is needed in order to convert index-name
values to occurrence number values and vice versa.
3. Debug, which contains an abbreviated type indicator used in the Interactive

Debugger to describe the format of the index-name. For all index-names, the type
indicator is IXN.
Note These first three columns (Address, Span, and Debug) are used with the
Interactive Debugger to display and modify the values of index-names. See
4. Type, which is a description of the item associated with the user-defined word. It is
Index-name for all index-names.
5. Name, which is the actual user-defined word declared as the index-name.
z Index-names
Address
for program ALLOCMAP
Span Debug Type Name z
0 5 IXN Index-name G2-I1
O 4 5 IXN Index-name G2-I2 O
z 8
12
13
13
IXN
IXN
Index-name
Index-name
NW3-I1
NW3-I2 z
index-names
6-26 Compiling
Listing
Constant-Names
User-defined words declared as constant-names in the Data Division are listed in the
1. Constant Value, which is the value associated with the constant-name. If the
constant-name value was specified with a constant-expression, then the result value is
shown. Otherwise, the literal associated with the constant-name is shown.
2. Type, which is a brief description of the type of the value associated with the
constant-name. If the constant-name value was specified with a constant-expression,
then the type is always Numeric unsigned. Otherwise, the type is the type of the
literal specified as the value for the constant-name.
3. Name, which is the actual user-defined word declared as the constant-name.
z Constant-names for program ALLOCMAP

Constant Value Type Name z
2 Numeric unsigned TWO
O "STRING1" Alphanumeric STRING1 O
z QUOTE (QUOTES)
-256.357
Alphanumeric
Numeric signed
MY-QUOTES
CONSTANT1 z
X"454647" Alphanumeric HEX1
O ALL "ABC" Alphanumeric STRING2 O
z ZERO (ZEROS, ZEROES)
SPACE (SPACES)
Numeric unsigned
Alphabetic
MY-ZEROS
MY-SPACES z
constant-names
Called Program Summary

The called program summary lists the names of all called and canceled programs and the
using count associated with each. Figure 6-9 illustrates this listing.
Figure 6-9 Called Program Summary
z Called Program Summary

Program-name required Using count z
MATHRTN 6
O "CHARRTN" 2 O
The program-name appears without quotation marks for dynamic (identifier) references
and inside quotation marks for static (literal) references. The “Using count” field
lists the maximum number of arguments used in any CALL reference to the listed literal
or identifier.

Listing
Cross Reference Listing
The cross reference alphabetically lists all user-defined words used in the program, and
provides the line number of each declaration, source and possible destination reference.
The line number is enclosed in slashes if the reference is a declaration or in asterisks if the
reference is a possible receiving item. The line number is not marked for sending items.
Procedure-names specified as the first operand of an ALTER statement and data-names
that are specified as receiving operands of Procedure Division statements are considered
destination references and are thus marked with asterisks in the cross reference listing.
The cross reference is generated in the listing when the X Option is specified in the
Compile Command (see page 6-11) or the LISTING-ATTRIBUTES keyword is
configured with the CROSS-REFERENCE value (see page 10-12). Figure 6-10
illustrates the cross reference listing.
Note The method used to mark possible destination references with surrounding
asterisks errs on the conservative side, particularly in arithmetic statements. The compiler
marks the second operand of an arithmetic statement as a possible destination even
though it may be followed by the GIVING phrase, which causes the second operand to be
only a sending item. The operands in the USING phrase of a CALL statement are always
considered to be possible destination references unless they are subject to a BY
CONTENT phrase.
Figure 6-10 Cross Reference Listing
z Cross
A
reference
/0152/
/Declaration/ *Destination*
z
ABSE-1 /0082/
O ABSR-1 /0083/ O
z ABS-1
AMOUNT-LINE
/0081/
/0016/ z
ANSE-1 /0085
O ANSR-1 /0086/ O
z ANS-1
ARG1-AREA
/0084/
/0113/ z
ARG1-COUNT /0112/
O ARG1-GROUP /0111/ 0151 O
z ARG2-AREA
ARG2-COUNT
/0116/
/0115/ z
ARG2-GROUP /0114/ 0151
O ARG3-AREA /0119/ O
z ARG3-COUNT
ARG3-GROUP
/0118/
/0117/ z
ASCII-1 /0020/
O ASCII-2 /0021/ O
z ASTERISK
BACKWARDS
/0025/
/0024/ z
DB1-DATA /0070/
O DB1-KEY 0047 /0069/ O
6-28 Compiling
Listing
Summary Listing
The summary listing shows the sizes of the regions of the generated object program.
Figure 6-11 illustrates this listing.
Figure 6-11 Summary Listing
z Program Summary Statistics

Read only size: 266 (X"0000010A") bytes z
Read/write size: 532 (X"00000214") bytes
O Overlayable segment size: 0 (X"00000000") bytes O
z Total generated object size:
Maximum EXTERNAL size:
798 (X"0000031E") bytes
88 (X"00000058") bytes z
Total EXTERNAL size: 92 (X"0000005C") bytes
O Errors: 1, Warnings: 0, Lines: 157 for program ALLOCMAP O
z Source program used 4489 (7%) of 65534 available identifiers
(T1C limit). z
Source program used 33004 (6%) of 588800 available user-defined
O word space (T2B limit). O
z Maximum compilation memory used was 487K bytes (2 presses and 0
increases required). z
Previous diagnostic message occurred at line 151.
O Object version level = 3 O
z Options in effect:
A - Allocation map listing z
X - Cross reference listing
O O
The line labeled “Read only size” lists the size of that region of the object program that
contains values that do not change during program execution. It consists primarily of the
instructions generated for the resident (or fixed) portion of the Procedure Division,
representations of the literals mentioned in the Procedure Division, and descriptors of the
operands referred to in the Procedure Division.
The line labeled “Read/write size” lists the size of that region of the object program that
contains values that might change during the course of execution. It consists primarily of
a current record area and a control block for each of the files specified, an area for the
Working-Storage Section and other internal control information.
The line labeled “Overlayable segment size” lists the size of the region of the object
program that is reserved for the independent and fixed overlayable segments of the
Procedure Division. Its length is the length of the longest independent or fixed
overlayable segment. All such segments are loaded into this common region on an
as-needed basis.
The line labeled “Total generated object size” lists the sum of the preceding values, and is
therefore the amount of memory needed to load the object program. It is not the total size
needed to execute that program. To execute the program there must be memory available
to accommodate not only the total size (as shown on the fourth line) but the operating
system, the runtime system, any external data items and the I/O buffers as well. Although
you have no control over the size of the operating system or runtime system, you can
exercise some control over the memory requirement for the I/O buffers by use of the

Listing
RESERVE and BLOCK CONTAINS clauses, described in detail in Chapter 8,
RM/COBOL Features.
The line labeled “Maximum EXTERNAL size” indicates the size of the single largest
record area with the external attribute declared in the source program. This number is
useful because the maximum allowed value varies depending on the environment in which
the program is run. See the section “Memory Available for a COBOL Run Unit” on
page 2-7 for these limitations.
The line labeled “Total EXTERNAL size” indicates the sum of the sizes of all record
areas with the external attribute declared in the source program. This number provides
information needed in estimating the runtime system memory requirements of the
program, but is not a direct measure since the memory requirements depend on the use of
matching external records in other programs of the run unit.
Note The two lines regarding EXTERNAL size are omitted in the listing file when the
program does not specify the EXTERNAL clause for any item.
The line labeled "Source program used ... of 65534 available identifiers ..." indicates the
amount of the identifier table limit consumed. Identifiers are the individual items
(classes, symbolic-characters, data items, conditions, and so forth) declared in the
program. Each data item and condition defined in the program requires its own identifier
entry even if the data-name or condition-name for the data item or condition is the same,
since qualification can be used to distinguish between the data items or conditions. The
T1C in the message refers to the compiler limit listed in Table 6-1 beginning on
page 6-36.
The line labeled "Source program used ... of 588800 available user-defined word space
..." indicates the amount of the user-defined word space consumed. User-defined words
are the unique spellings of words used as alphabet-names, cd-names, class-names,
condition-names, data-names, file-names, index-names, key-names, mnemonic-names,
paragraph-names, section-names, and symbolic-characters in the source program. Any
particular spelling consumes space only once in the user-defined word table. The T2B in
the message refers to the compiler limit listed in Table 6-1 beginning on page 6-36. The
limit of 98133 shown in that table assumes 30-character names, which use six words each
in the user-defined word space. If names averaged 24-characters in length (5 words
average use of word space), the limit would be 117760 names.
The line labeled "Maximum compilation memory ..." indicates the amount of memory
required to compile the source program. Setting the workspace size for the compiler to a
value at least this size or slightly larger results in the best compilation speed with the
minimum amount of memory consumption. The workspace size can be set using the W
command line option or the WORKSPACE-SIZE keyword of the COMPILER-OPTIONS
configuration record (see page 10-6). The number of presses indicates how many times
the compiler attempted to recover unused memory. Minimizing the number of presses by
6-30 Compiling
Listing
increasing the workspace size provides improved compilation speed. If the number of
presses is zero, then the compilation speed cannot be improved by increasing the
workspace size. The number of increases indicates the number of times the compiler had
to request more memory because the original workspace size was too small.
The lines labeled “Errors: . . .” and “Previous diagnostic message . . .” summarize the
number of diagnostic messages issued during compilation and the location of the last
diagnostic message, respectively.
The line labeled “Object version level” indicates the object version level of the object
program associated with the program being compiled. See Appendix H, Object Versions,
for complete information on the object version levels accepted by RM/COBOL.
The line labeled “Options in effect” and the lines that follow list the options selected for
the compilation. The listed options may have been specified in the Compile Command or
be part of a configuration file (see the discussion of the COMPILER-OPTIONS record
that begins on page 10-6). Those options that have no direct affect on the compilation
(such as list directing options) are not listed; if no options were specified, these lines will
not appear.
Error Marker and Diagnostics

Violations of syntactical or semantic rules are detected during the compiler’s pass
through the source program. If an error is detected, it is undermarked by a dollar sign.
Figure 6-12 illustrates the RM/COBOL diagnostic message format.
Figure 6-12 Error Marker and Diagnostics
z 1
2
IDENTIFICATION DIVISION.
PROGRAM-ID. ALLOCMAP. z
3 ENVIRONMENT DIVISION
O 4 CONFIGURATION SECTION. O
z *****
$
1) 0319: E Period space separator expected. z
5 SOURCE-COMPUTER. RMCOBOL.
O 6 OBJECT-COMPUTER. same. O
z *****
$
1) 0382: E Computer-name must be user-defined word instead of z
reserved word. (scan suppressed).
O *****Previous diagnostic message occurred at line 4. O
z 7 PROGRAM COLLATING SEQUENCE EBCDIC-CODE.
$ z
***** 1) 0005: I Scan resumed.
O *****Previous diagnostic message occurred at line 6. O
z 8
9
SPECIAL-NAMES.
SWITCH-1 IS REPORT-MODE, z
The first number on the line following the line with the undermark refers to the undermark
number. Multiple errors on the same line are numbered in ascending order, reading left to
right. The next number is the error number. This corresponds to the appropriate message

Listing
listed in Appendix B, Compiler Messages, of the RM/COBOL Language Reference
Manual.
Following the error number is a single letter that indicates the severity of the error. There
are three classes:
1. I indicates the message is informational only.
2. E indicates a severe error.
3. W indicates a warning.
Error Recovery
The RM/COBOL compiler may display a recovery message along with the error
diagnostic. This recovery message is generated if—as often happens—a compilation
error interrupts scanning. In this case, the source text is ignored until the compiler finds a
recovery point. This minimizes the amount of code you need to examine if an error
occurs. See Figure 6-13 for an illustration.
Figure 6-13 Error Recovery Display
z 10
11
ON STATUS IS REPORT-LIST,
OFF STATUS IS REPORT-NOLIST; z
12 C21 IS TOP-OF-FORM;
O $ O
z ***** 1) 0088: E Wrong code-name in ALPHABET clause. (scan suppressed).
*****Previous diagnostic message occurred at line 7. z
13 CONSOLE IS CRT-DISPLAY;
O 14 PROCEDURE DIVISION. O
z $
***** 1) 0005: I Scan resumed. z
The undermark indicates that the compiler did not recognize the alphabet code-name
given.
When the compiler encounters an error, it first attempts to make an assumption about
what was actually meant. When it can do so, it continues compiling from the point of
error, without displaying the “(scan suppressed)” portion of the message.
If it cannot do so, the compiler suppresses scanning until it finds a point where it can
begin again. In this case, an undermark indicates where it restarted scanning, and the
informational “Scan resumed” message is written. No source text between the undermark
associated with the “(scan suppressed)” message and the “Scan resumed” message is
compiled. This may result in data-names being undefined if the message occurs in the
Data Division.
6-32 Compiling
Listing
The diagnostic information described previously is always contained in the listing
regardless of the setting of the compiler options. If the L, P, and T Options are all absent
(meaning that the listing is not being written to any device), the diagnostic information is
written to the standard output device.
Error Threading
RM/COBOL provides error-threading facilities. By reading the “Previous diagnostic
message occurred at line” message, you can trace back through every error encountered
during compilation. This message may also appear after the summary listing, to point to
the last error in the program.
Compilation always proceeds to the end of the program regardless of the number of errors
found, unless an error causes abnormal termination. Global errors, such as undefined
paragraph names and illegal control transfers, are listed at the end of the listing file
allocation map.
Compile Command Messages

The banner appears when you first invoke the compiler:
RM/COBOL Compiler - Version 7.0nn.nn for operating system
Copyright(c) 1985, 1986-1999 by Liant Software Corp. All rights reserved.
Configured Options: option list
Registration Number: xx-nnnn-nnnnn-nnnn
The third line of the compiler banner appears only when options have been specified in a
configuration file or in the Compile Command. Options displayed as a single character
appear first. If flagging is configured, the configured keywords appear next; long
keywords are abbreviated. If an object pathname or a listing pathname is configured, it
appears in the form O=pathname or L=pathname. If the object version level number is
configured, it appears in the form Z=nnnn (where nnnn is a four-digit decimal number).
If you enter an invalid Compile Command, you will see:

Usage: RMCOBOL name [options]
Options: [(] [A] [B] [C] [D] [E] [F=(keyword list)] [G=configfile]
[H=configmod] [K] [L[=path]] [M] [N] [O=path] [P] [Q] [R] [S] [T]
[U[=B|D|P]] [V] [W=workspace] [X] [Y[=n]] [Z=version] [2] [7]
[)comments]

Compile Command Messages
In addition, the following may appear:
Command line error: file name is missing from command line.
Conflict error: COMPUTATIONAL-VERSION conflicts with OBJECT-VERSION.
Conflict error: option U conflicts with 2.
Conflict error: option V conflicts with B.
Mismatch error: options A and X require option L, P, T, or Y=3.
Mismatch error: option C requires option L, P, T, Y=2, or Y=3.
Mismatch error: option E requires option L, P, or T.
Syntax error: flag keyword is incorrect.
Syntax error: option characters must be followed by space or comma.
Syntax error: option O requires path specification.
Syntax error: option G or H requires path specification.
Syntax error: option U specifies invalid type character.
Syntax error: option Z requires numeric version specification.
Syntax error: symbol n is incorrect option letter.
Syntax error: option W requires numeric workspace specification.
Syntax error: option U describes incorrect type character.
Syntax error: option Y specifies an invalid numeric debug level.
Version error: value must be non-zero and less than or equal to 8.
Error invoking unauthorized copy of compiler.
Compiler Status Messages

The RM/COBOL compiler displays messages that tell you it has completed normally, or
that it has terminated abnormally.
One of these messages—Compilation complete—appears every time the compilation is

finished, regardless of the number of errors that appear. This message has the following
form:
Compilation complete--Programs: p, Errors: e, Warnings: w
p is the number of programs in the source file, excluding contained programs.
e is the number of errors found.
w is the number of warnings issued.
6-34 Compiling
The other messages appear under specific circumstances. They are listed in Appendix B,
Compiler Messages, of the RM/COBOL Language Reference Manual.
During initialization, the compiler locates and reads its message file. If it cannot find its
message file or the message file is corrupt, one of the following messages appears:
Unable to find the system message file

Unable to format the system message file
Unable to read the system message file
The compiler compares its version number and product code with those in the message
file. If they do not match, one or both of the following messages appears:
RM/COBOL: Message file version mismatch, expected 7.0n.nn, found n.nn.nn

RM/COBOL: Message file product mismatch, expected XX, found YY
When any of the above messages appear, the compilation terminates with the following
message:
Error invoking mismatched compiler and message file.
The compiler message file may have the wrong name or be in the wrong directory. The
compiler message file must have the name rmc.msg (RMC.MSG under UNIX). The
compiler attempts to find the message file in the directory that contains the rmcobol
executable file, the current directory, or through the PATH directory search sequence (see
page 2-4 for UNIX or page 3-11 for Windows).
Note On some versions of UNIX, it is impossible to determine which directory contains

the executable file when that directory is specified on the command line.
If a compilation error results in an abnormal termination, a message appears in the

following general form:
Compiler error n: text
n is a compiler error number.
text is any of the first sentences in the following definitions.
The numbers and their definitions are listed in Table 6-1.
In addition to these errors, unnumbered error messages may appear as a result of

configuration or I/O errors. These unnumbered error messages are described beginning
on page 6-41.

Table 6-1 Abnormal Termination Messages
Error
Number Message Text
1 Compiler limit exceeded, Tnn message.
The program has exceeded an internal compiler limit. This can be remedied by dividing
the program into a main program with multiple subprograms. The table number and
table usage are included in the message to provide additional information to help keep
the program in conformance with compiler limits. If this error continues to occur even
in a small program, it suggests an internal compiler malfunction. Provide a source copy
and the table number as it appears in this message to Liant technical support services.
The values of nn are listed as table numbers, and the values for message are listed as
table usage in the following table. Limits are provided only where meaningful; all
compiler tables are listed since error number 2 also displays this information.
Table
Number Table Usage Limit
T00 Source (input source records, contiguous comments) 28000
T01 AliasID (aliased identifiers) 65534
T02 Alter (ALTER statements) 65534
T03 BackPatchPsect (object back patches)
T04 Cfd (COBOL file definers) 65534
T05 Code (object code buffer)
T06 Condition (condition-names) 65534
T07 Corresponding (CORRESPONDING items for MOVE,
ADD, or SUBTRACT)
T08 CrossRef (cross reference entries) 290000
T09 DataParameter (forward data references, for example, FILE 65534
STATUS)
T0A DataRecord (DATA RECORDS clause references)
T0B DeclarativeRefError (declarative reference errors)
T0C DeferredScript (deferred subscripting in Screen Section) 65534
T0D DimensionTemp (table dimensions in subscripting)
T0E Dsect (data descriptions for data references) 65534
T0F ErrorID (identifier errors discovered after the definition)
T10 ErrorMessage (diagnostic messages for current line)
T11 ErrorProcedure (procedure errors)
T12 Error (diagnostic message entries)
T13 ErrorTemp (diagnostic message temporaries)
6-36 Compiling
Table 6-1 Abnormal Termination Messages (Cont.)
Error
Number Message Text
Table
T14 Exit (stacked internal exit locations)
T15 External (external data items or files)
T16 Fail (stacked recovery information for parsing errors)
T17 FileArea (file areas for SAME [RECORD] AREA clauses) 65534
T18 FileAreaTemp (file area temporaries)
T19 Fsect (file references) 65534
T1A Global (global data items or files) 65534
T1B Group (group data items stack for a record)
T1C ID (identifier definitions) 65534
T1D IndexTempHold (held index temporaries)
T1E IndexTemp (index temporaries)
T1F InspectTempHold (held INSPECT temporaries)
T20 InspectTemp (INSPECT temporaries)
T21 IntegerConstant (integer constants) 65534
T22 Jsect (procedure references) 65534
T23 Label (made intra-statement labels) 65534
T24 LiteralCharacter (literal characters) 65534
T25 LiteralRef (literal references) 65534
T26 Literal (literal descriptors) 65534
T27 LiteralTemp (literal temporaries)
T28 LiteralValue (literal values) 65534
T29 LocalSymbol (local symbol information for object symbol
table)
T2A NameLink (user-defined word links) 98133
T2B Name (user-defined words) 98133
T2C NextSentenceLabel (NEXT SENTENCE labels)
T2D NumericTemp (numeric temporaries) 65534
T2E Operand (statement operands)
T2F PackTemp (character packing temporaries)

Error
Number Message Text
Table
T30 ParameterText (diagnostic message parameter text)
T31 Partial (partial segments) 65534
T32 Perform (PERFORM statements) 65534
T33 PictureTemp (PICTURE character-string temporaries)
T34 PointerTemp (pointer temporaries stack)
T35 PointerTempHold (pointer temporaries save)
T36 Polish (expression evaluation Polish)
T37 PolishTemp (expression evaluation Polish temporary)
T38 PrecomputeRef (precomputed subscripting or reference 65534
modification)
T39 Preset (initial VALUE clause values)
T3A ProcedureRef (procedure references) 65534
T3B Procedure (procedure definitions) 65534
T3C ProgramName (program-names)
T3D ProgramNest (contained programs)
T3E Program (programs referenced by CALL statements) 65534
T3F Qualifier (qualifiers in identifiers)
T40 QualifierTemp (qualifier temporaries)
T41 RecordKey (record keys) 65534
T42 RecordKeyTemp (record key temporaries)
T43 RefMod (reference modifiers) 65534
T44 ReplaceKey (REPLACE statement keys) 65534
T45 ReplaceText (REPLACE statement text) 65534
T46 ReplacingKey (REPLACING phrase keys in COPY 65534
statements)
T47 ReplacingText (REPLACING phrase text in COPY 65534
statements)
T48 SameSortArea (SAME SORT AREA list)
T49 ScreenAttributes (Screen Section data item attributes) 65534
T4A ScreenGroup (Screen Section groups)
6-38 Compiling
Error
Number Message Text
Table
T4B ScriptPlex (subscripted reference entries) 65534
T4C ScriptRef (subscripted references) 65534
T4D ScriptTemp (subscript temporaries)
T4E Segment (Procedure Division segments) 65534
T4F SortMergeBlock (SORT and MERGE statements)
T50 SourceTemp (input source character temporaries)
T51 SpecialRegister (special register references) 65534
T52 Symbol (user-defined word temporaries)
T53 SystemNames (implementor-names) 65534
T54 TableIndex (INDEXED BY phrases of OCCURS clauses)
T55 TableKey (KEY phrases of OCCURS clauses) 65534
T56 Table (OCCURS clauses) 65534
T57 UndefinedProcedure (undefined procedure references)
T58 UsingID (Procedure Division header USING list) 256
T59 Work (compiler data stack) 65534
2 Table memory overflow, Tnn message.
The program has exceeded the available workspace when adding information to
the indicated compiler table. Increase the amount of user space available to the
compiler with the W Option, reduce the program size by dividing the program into
a main program with multiple subprograms or by using segmentation, or use shorter
data-names.
The values of nn are listed as table numbers, and the values for message are listed as
table usage in the table provided above for error number 1. Note that the table listed is
not necessarily one of the tables causing the problem; it may simply be the table being
increased in size when the operating system refuses to provide more memory to the
compiler.
3 Program data or code overflow.
The program exceeded an internal compiler limit. The listing file shows whether a data
or procedure overflow occurred.
One of the object sections has run out of space. Segmenting the program or dividing it
into a main program with multiple subprograms may solve a procedure overflow.
Reducing the size of data items described in the Data Division may solve a data
overflow condition.

Error
Number Message Text
4 Internal logic error, <error location information>
An internal compiler error has been encountered. If this problem arises, call Liant
technical support services for assistance. The <error location information> included in
this message may help determine the cause of this malfunction and should be recorded
for reference.
5 Fatal syntax error.
The compiler has encountered a syntax error from which it cannot recover. Fix the
syntax error in the source program and then compile the program again.
6 Object file overflow.
The object file has become too large for the compiler to produce a correct object file.
Break the program into two or more smaller programs that communicate using the
CALL statement.
An internal compiler error has been encountered: an invalid compiler table number
(roll) has been referenced. If this problem arises, call Liant technical support services
for assistance. The <error location information> included in this message may help
determine the cause of this malfunction and should be recorded for reference.
An internal compiler error has been encountered: an erroneous compiler table entry
number (group) has been referenced. If this problem arises, call Liant technical support
services for assistance. The <error location information> included in this message may
help determine the cause of this malfunction and should be recorded for reference.
An internal compiler error has been encountered: an erroneous compiler table entry
offset (rung) has been referenced. If this problem arises, call Liant technical support
services for assistance. The <error location information> included in this message may
help determine the cause of this malfunction and should be recorded for reference.
n Unknown error number.
The value of n was not 1 through 9, inclusive. If this occurs, call Liant technical
support services for assistance.
6-40 Compiling
In the unnumbered error messages described below, pathname may be one of the
following: a valid pathname, PRINTER if the P Option is used, or the standard output
device if the T Option is used.
Open error for file pathname
This message may occur for overlay files, program listings or object files. There are a
number of reasons this message may appear:
• A write-protected file was opened for output.
• The system is out of disk space.
• An invalid pathname was specified.
• A file exists, but RM/COBOL could not locate it because the directory search
sequence was not specified or was specified incorrectly.
• The system has reached its limit for the number of files that can be open at one time.
If the open error occurs on the compiler overlay file, the file may have the wrong name or
be in the wrong directory. The compiler overlay file must have the name rmcobol.ovy.
The compiler attempts to find the overlay file in the current directory and then in the same
directory as the compiler executable file. If unable to find the file there, the compiler
finds the overlay file through the PATH directory search sequence (see page 2-4 for
UNIX or page 3-11 for Windows).
Note On some versions of UNIX, it is impossible to determine the directory that

Write error for file pathname
This message can occur for both listing and object files. Generally, it means space is not
available to perform the write operation.
Read error for file pathname
This message can occur for source, overlay, and object files. Generally, it indicates a
corrupted file. The error will also occur on source files that contain a NULL character.
Restore the file from its backup copy, or, for object files, restart the compilation.

Load error for file pathname
This message can occur only for overlay files. It indicates that the overlay file is not the
same version as the resident compiler which loaded it. The overlay file may be corrupted,
in which case the problem can be corrected by restoring it from its backup. The problem
can also be caused by multiple versions of the compiler existing on the disk and an
incorrect establishment of the search sequence for overlay files. Such cases can be
corrected either by deleting the undesired version of the compiler or by resetting the
PATH environment variable such that the overlays associated with the resident compiler
will be found.
Compiler Configuration Errors

Compiler configuration errors include all errors that occur because of an error in the
configuration. The formats are as follows:
Error code at record number in file.
Error code in configuration.
code is the compiler configuration error number listed in Table 6-2 (see also the
“Configuration Errors” section that begins on page A-37), or it is an input/output
error (see the “Input/Output Errors” section beginning on page A-11).
number is the logical record in the configuration file where the error occurred. When
using number to determine which record is in error, count lines combined with their
continuation lines as one record, and do not count comment lines or blank lines.
file identifies one of the following sources of configuration records:
1. Attached configuration file
2. Overriding configuration file
3. Supplemental configuration file
6-42 Compiling
The format with the record number and filename appears if an error is detected during the
processing of a configuration record. The text of the configuration record in error follows
the message. The other format is used if an error is detected after all configuration
records have been processed or if an error is detected without an associated record.
Table 6-2 Compiler Configuration Errors
Code Description
E002 An invalid delimiter was found.
E004 A keyword has not been provided where one was expected or the
keyword is invalid.
E007 Syntax error.
E009 A value has not been provided where one was expected or the value is
invalid.
E00B A logical configuration record exceeds the maximum length.
E00C Token requested to dereserve was not found.
Compiler Initialization Errors

If the compiler encounters difficulties initializing the RM/COBOL file management
system, the following error message will appear:
Error initializing file manager.
This error generally occurs because a buffer pool has been configured that is too large to
be allocated. See the BUFFER-POOL-SIZE keyword of the RUN-FILES-ATTR
configuration record (page 10-26) for instructions on changing the buffer pool size.

Compiler Exit Codes
Compiler exit codes indicate the status of the compilation (either successful or
unsuccessful). These codes and their associated definitions are listed in Table 6-3.
Under UNIX, the exit code can be interrogated from the shell. See shell (sh) in your
UNIX documentation for details.
Under Windows, a non-zero exit code is displayed in a message box titled “Return Code”.
Selecting the OK button closes the compiler window. The message box also will contain
the COBOL error code, if one occurred. Display of the Return Code message box may be
disabled by setting the RM/COBOL Windows registry value “Show Return Code Dialog”
to FALSE. For more information, see the section “Setting Miscellaneous Properties” in
If the compiler was invoked from a COBOL program using the SYSTEM non-COBOL
subprogram (CALL “SYSTEM”), the exit code can be retrieved by passing an exit code
variable in the USING list. See page F-41 for more information on the SYSTEM
subprogram.
Table 6-3 Compiler Exit Codes
Code Description
0 Normal termination.
249 Warnings in program.
250 System initialization error.
251 Incorrect Compile Command.
252 Errors in program.
253 Reserved.
254 Compilation canceled (by pressing the CTRL and BREAK keys or the
system Interrupt key).
255 Compiler error.
6-44 Compiling
Compiler Exit Codes
Chapter 7: Running
One of the immediate results of compilation is the creation of the object file. Object files
contain the object version of the program that can be executed with the runtime command.
To execute the object program, use the RM/COBOL Runtime Command described in the
following section.
If your program uses segmentation, the segments are loaded and executed—as they are
referenced—by the RM/COBOL runtime system. The runtime system also allocates
memory for file buffers, external data items, and called RM/COBOL and non-COBOL
subprograms.
This chapter contains information on the RM/COBOL Runtime Command, runcobol, and
its options, examples of valid and invalid runtime commands, runtime messages, and
program exit codes.
Runtime Command
The RM/COBOL Runtime Command (runcobol) loads and executes RM/COBOL
programs.
Under UNIX, the Runtime Command is entered at a shell prompt. After typing the
desired command and options, press Enter to begin execution.
Under Windows, the Runtime Command can be entered in the Command Line text box of
the Shortcut dialog box. See page 3-7 for instructions on creating a Shortcut. Choose the
RUNCOBOL icon to begin execution. Programs also may be executed by dragging the
.cob object file to the RUNCOBOL object or by double-clicking on the object file.
The format of the Runtime Command is as follows:
runcobol filename [ option ] …
filename is the name of the main program of the run unit. If the L Option (described
in the next paragraph) is not specified, filename must be a valid pathname. If a
filename extension is not specified, RM/COBOL uses first .cob, and then .COB
unless configured otherwise.

Runtime Command
The L Option allows you to invoke execution of a program contained in a library by
entering the name of the library only. (See the discussion of libraries that begins on
page 6-3.) The rules for invocation of libraries are as follows:
1. If the main program is not in a library, you must enter the appropriately qualified
pathname for filename.
2. If the main program is in a library, you must enter the L Option and the library
name containing the main program. The main program name specified by
filename must have been specified in the PROGRAM-ID paragraph of the
program.
option specifies the available RM/COBOL Runtime Command options, described in

the next section. Spaces or commas must separate options. Options may be entered
in uppercase or lowercase letters. If an option is repeated in a command, the last
occurrence of the option is used. Each option may be preceded by a hyphen. If any
option is preceded by a hyphen, then a leading hyphen must precede all options.
When a value is assigned to an option, the equal sign is optional if leading hyphens
are used.
In addition, the RM/COBOL runtime system also supports three OLE server registration
commands, which do not follow the command format described earlier in this section:
runcobol /regserver
runcobol /unregserver
runcobol /showserver
These options are described in the topic “Registering the RM/COBOLRuntime" in Chapter 3,
Installation and System Considerations for Microsoft Windows.
Runtime Command Options

A single RM/COBOL Runtime Command may include all of the options. There are no
rules of exclusivity. However, as is mentioned with the appropriate option, some options
override others.
There are four groups of Runtime Command options:
1. Configuration options
2. Debug and test options
3. Environment options
4. Program options
7-2 Running
Runtime Command
The following sections contain a complete description of the Runtime Command options.
Configuration Options
The following options designate a file to be used as the complete runtime configuration or
as a supplement to it and allow suppression of the banner and STOP RUN messages.
C Use the C Option to designate a file to be used as the runtime configuration. The
specified file replaces any attached configuration for the run of the program only.
The C Option has the following format:
C=pathname
See the discussion of the RUN-OPTION configuration record that begins on

page 10-33. See also the X Option, described in this section.
The default is to use the default configuration options described in Chapter 10,
Configuration.
K Use the K Option to suppress the banner message and the STOP RUN message. This
option is most useful when running under batch command files or shell scripts.
The default is to display the banner and STOP RUN messages.
X Use the X Option to designate a file as a supplement to the runtime configuration.

The X Option has the following format:
X=pathname
If no configuration exists (either attached or specified with the C Option,

described previously), the specified file serves as the complete configuration. See
Chapter 10, Configuration.
Debug and Test Options
The following options invoke the RM/COBOL Interactive Debugger and collect program
instrumentation data.
D Use the D Option to invoke the RM/COBOL Interactive Debugger (called Debug).
Complete details on program debugging are contained in Chapter 9, Debugging.
By default, the Interactive Debugger is not invoked.
I Use the I Option to collect RM/COBOL program instrumentation data. Complete

details on program instrumentation are contained in Chapter 11, Instrumentation.
By default, instrumentation data is not collected.

Runtime Command
Environment Options
The following options specify the runtime environment.
B Use the B Option to specify a maximum buffer size for use with the ACCEPT and
DISPLAY statements. The B Option has the following format:
B=n
The maximum buffer size is 65280 characters. The default size is 264
characters.
See page 2-23 for information about ACCEPT and DISPLAY buffers.
M Use the M Option to direct that level 2 ANSI semantics are to be used for Format 1
ACCEPT and DISPLAY statements.
The default is to use level 1 ANSI semantics in these situations (see the discussion
that begins on page 2-24).
S Use the S Option to set (or reset) the initial value of switches in the RM/COBOL
program. The S Option has the following format:
S=n ... n
Switches are numbered left to right from 1 to 8, without trailing zeroes. Each n
indicates a switch value: 0 indicates OFF and 1 indicates ON.
The default is to initialize all switches to OFF at the start of the run unit.
T Use the T Option to specify the amount of memory (n bytes) to be used for a sort
operation. The T Option has the following format:
T=n
There are a number of reasons to use the T Option in association with a sort
operation:
• To increase the amount of memory available for the sort operation, thereby
increasing the efficiency of the sort operation.
• To reduce the default memory allocation. This provides more room for loading
other data or called subprograms into memory during an input procedure.
If no SORT or MERGE statement is used in the run unit, using a value of 0 will
allow the runtime system to allocate the memory generally used to contain the
sort-merge logic for other purposes.
The default is 256000 bytes. The maximum allowed value is 2147483647 bytes.
7-4 Running
Runtime Command
Program Options
The following options define an argument to be passed to the main program and the
object libraries to be used for the run unit.
A Use the A Option to pass an argument to the main program. The A Option has the
following format:
A=[delim]string[delim]
string is an alphanumeric series of characters.
The delimiter character specified for delim may be either ' or ".
The delimiter character chosen as the opening delimiter must be used as the closing
delimiter as well. The closing delimiter must be followed by a space or comma if
another option follows the A Option. The delimiter character used cannot appear as
part of string.
If string contains no spaces, delimiter characters are not required.
Under UNIX, it is safer to delimit string using single quotation marks '. . .' because
characters in the argument might otherwise be meaningful to the shell (sh) command
interpreter.
To use the string assigned to the A option, you must have a Linkage Section for the
main program with the following form:
01 MAIN-PARAMETER.
02 PARAMETER-LENGTH PIC S9(4) BINARY (2).
02 PARAMETER-TEXT.
03 PARAMETER-CHAR PIC X OCCURS 0 TO 100 TIMES
DEPENDING ON PARAMETER-LENGTH.
The Procedure Division header should have the following form:

PRO CEDURE DIV ISION USIN G MAIN-PAR AMETER.
The variable PARAMETER-LENGTH contains the number of characters between

delimiter characters. PARAMETER-TEXT contains a copy of the characters
between the delimiter characters. If no parameter is passed with the A Option and
the main program describes a parameter as shown above, the value of
PARAMETER-LENGTH will be zero. When this is the case, PARAMETER-TEXT
should not be referenced. In all cases, no part of MAIN-PARAMETER should be
modified.
The number of characters between the delimiter characters cannot exceed 100.

Runtime Command
The following is an example program using the A Option.
PROGRAM-ID. CPASS.
* To see a command-line argument string passed to a
* COBOL main program, run this program as follows:
* runcobol cpass A="string"
DATA DIVISION.
LINKAGE SECTION.
01 APARAM.
02 APARAM-SIZE PIC S9(4) BINARY (2).
02 APARAM-STRING.
03 FILLER PIC X OCCURS 0 TO 100 TIMES
DEPENDING ON APARAM-SIZE.
PROCEDURE DIVISION USING APARAM.
0010-BEGIN.
DISPLAY APARAM-STRING(1:) LINE 22 ERASE.
STOP RUN.
END PROGRAM CPASS.
L Use the L Option to designate RM/COBOL object or non-COBOL subprogram

libraries. The L Option has the following format:
L=pathname
These libraries allow more than one program to be contained within a file.
RM/COBOL imposes no limitation on the number of times the L Option may appear
in a single Runtime Command. (See the discussion of libraries that begins on
page 6-3.)
Sample Runtime Commands

Following are examples of valid and invalid RM/COBOL Runtime Commands.
Valid Runtime Commands

runcobol payroll B=500,K
This command executes the program named payroll.cob. It establishes a maximum

buffer size of 500 bytes for ACCEPT and DISPLAY statements (the B Option) and
suppresses banner and STOP RUN messages (the K Option).
7-6 Running
Sample Runtime Commands
runcobol FIRSTPRG L=lib1\library.cob,D
This command executes the program FIRSTPRG contained in the RM/COBOL library
named lib1\library.cob.
It informs the runtime system of the name of the library (the L Option) that contains the
programs available, and invokes the Interactive Debugger (the D Option).
Invalid Runtime Commands

runcobol payroll.sal A='PRINT-RUN"
Here, the A Option is invalid, since the opening and closing delimiters are not identical.
runcobol lib1\library D T
In this example, the library used in the valid example cannot be executed by this
command, assuming the library contains more than one program. Also, the T Option is
specified without an associated value.
Runtime Messages
Messages of different classes may appear on the screen during program execution. The
message types are defined in the following paragraphs.
Diagnostic Messages
Diagnostic messages indicate either that an internal RM/COBOL error occurred or that an
I/O error occurred that was not handled by an appropriate USE procedure (see the
description of the USE statement in Chapter 5, Procedure Division, of the RM/COBOL
Language Reference Manual). If the D Option (see page 7-3) was entered in the Runtime
Command and one of these errors occurs, the Interactive Debugger will be entered to
allow examination of program data values. Otherwise, control will return to the operating
system.
Execution Messages
Execution messages report the status of the runtime system, or problems within the
RM/COBOL program that prevent successful execution.
These messages result from normal program termination, the presence of a STOP literal
statement, or an incorrectly entered option.
Diagnostic and execution error messages are detailed in Appendix A, Runtime Messages.

Runtime Messages
Program Exit Codes
An appropriate exit code is returned to the operating system when program execution
ends. The exit code may indicate that execution was successful or unsuccessful. Users
may move (or otherwise assign) any exit code value in the range 0 through 255 to the
implicitly defined RETURN-CODE special register. The program exit codes are listed
and defined in Table 7-1.
Under UNIX, the exit code can be interrogated from the shell. See shell (sh) in your
UNIX documentation for details.
Under Windows, a non-zero exit code is displayed in a message box titled “Return Code”.
Choosing the OK button closes the runtime window. The message box also will contain
the COBOL error code, if one occurred. Display of the Return Code message box may be
disabled by setting the RM/COBOL Windows registry value “Show Return Code Dialog”
to FALSE. For more information, see the section “Setting Miscellaneous Properties” in
If the runtime system was invoked from a COBOL program using the SYSTEM
non-COBOL subprogram (CALL “SYSTEM”), the exit code can be retrieved by
passing an exit code variable in the USING list. See page F-41 for more information on
the SYSTEM subprogram.
Note User-defined termination codes in the range 249–255 will be ambiguous if a

runtime system error occurs.
Table 7-1 Program Exit Codes
Code Description
0 Normal termination.
249 Internal library subprogram called with incorrect parameters.
250 System initialization error.
251 Incorrect Runtime Command.
252 Program load failure.
253 Program error.
254 Run unit canceled (by pressing the Ctrl and Break keys or the system
Interrupt key).
255 I/O error.
7-8 Running
Program Exit Codes
Chapter 8: RM/COBOL Features
This chapter offers operating system-specific information on the use of RM/COBOL
statements and on RM/COBOL file types and structure. It is assumed the reader is
familiar with RM/COBOL statements.
ACCEPT and DISPLAY Statements

Specific characteristics of your operating system affect the following aspects of
RM/COBOL ACCEPT and DISPLAY statement usage:
• The initial contents of a screen field.
• The use of certain edit keys with the ACCEPT statement.
• The use of phrases with ACCEPT and DISPLAY statements.
• Redirection and piping of standard input and standard output (for more information,
see Chapter 2, Installation and System Considerations for UNIX).
Initial Contents of a Screen Field

Depending on the current configuration and the phrases specified in the ACCEPT
statement, the initial contents of a screen field may be the following:
• Unchanged but treated as if the field contained all spaces. This is the
default if neither the PROMPT nor UPDATE phrase is specified, and if the
ACCEPT-FIELD-FROM-SCREEN keyword of the RUN-ATTR record is not
specified or is set to NO in the configuration file (as described on page 10-23).
• Unchanged if neither the PROMPT nor UPDATE phrase is specified and the
ACCEPT-FIELD-FROM-SCREEN keyword of the RUN-ATTR record is set to YES
in the configuration file (see page 10-23).
• Filled with prompt characters if the PROMPT phrase is specified in the ACCEPT
statement.
• Filled with the current value of the associated ACCEPT operand if the UPDATE
phrase is specified in the ACCEPT statement.

• Filled with the literal characters specified with the MASK keyword of the
CONTROL phrase, if that CONTROL phrase is specified. If UPDATE is also
specified, or the ACCEPT-FIELD-FROM-SCREEN keyword of the RUN-ATTR
configuration record is set to YES, then the input character positions specified in the
mask are replaced by the contents of the ACCEPT operand or the current contents of
the screen field, respectively.
You can then modify the contents of the screen field. Except for literal characters
specified with the MASK keyword of the CONTROL phrase, all positions of that field
can be modified until a field termination key is pressed. This modification of displayed
data is called field editing.
Defined Keys
The following sections list and explain the specially defined screen field editing keys and
the keys that generate field termination key codes.
Before these keys can function as described under UNIX, you must associate them with
the definition in the termcap or terminfo database (described on page 2-9, and detailed in
Chapter 10, Configuration). For example, the Left Arrow key might be associated with
the k1 termcap attribute.
8-2 RM/COBOL Features

Edit Keys
Table 8-1 describes the keys used to manipulate the cursor during field editing.
Table 8-1 Edit Keys
CONTROL
Key Phrase Action
Left Arrow Default Moves the cursor left one character without affecting
any input characters. If the cursor is already at the
leftmost character in the screen field, a beep sounds.
MASK Same as above; however, the cursor skips over literal
characters that were specified in the mask.
Right Arrow Default Moves the cursor right one character without affecting
any input characters. If the cursor is already at the
rightmost character in the screen field, a beep sounds.
MASK Same as above; however, the cursor skips over literal
characters that were specified in the mask.
Backspace Default Moves the cursor left one character, and deletes the
input character in that position. All characters to the
right of the deleted characters are shifted to the left. The
prompt character (or a space if the PROMPT phrase was
not specified) is used to pad the screen field on the right.
If the cursor is already at the leftmost character in the
screen field, a beep sounds.
MASK Same as above; however, if the character to the left of
the cursor is a literal character, the cursor is moved left
until another input character is encountered, and that
character is deleted without altering any subsequent
input characters.
Delete Character Default Deletes the input character at the cursor position. All
screen field characters to the right of the cursor are
shifted to the left. The cursor remains stationary. The
prompt character (either as specified in the PROMPT
phrase, or spaces if the PROMPT phrase was not
specified) is used to pad the screen field on the right. If
the cursor is positioned at the right margin when this
key is pressed, and no characters are deleted, a beep
sounds.
MASK Same as above; however, only input characters up to the
next literal character to the right are shifted to the left.

Table 8-1 Edit Keys (Cont.)
CONTROL
Key Phrase Action
Erase Entire Default Places the cursor at the leftmost field position, and fills
all input positions with the prompt character, or spaces
if the PROMPT phrase was not specified. Note that the
Erase Entire key is not a field terminator.
MASK Same as above; however, literal characters in the mask
are not overwritten.
Erase Default Without moving the cursor, fills all input positions from
Remainder the current cursor position to the rightmost position of
the screen field with the prompt character, or spaces if
the PROMPT phrase was not specified. Note that the
Erase Remainder key is also a field termination key.
MASK Same as above; however, literal characters in the mask
are not overwritten.
Insert Character Default Initializes insert mode. Subsequent keystrokes insert
characters at the cursor position. Screen field characters
to the right of the cursor are shifted further to the right
to accommodate the inserted characters. If an attempt is
made to shift any character except for a space or a
prompt character (if the PROMPT phrase was specified)
beyond the rightmost input position of the screen field, a
beep sounds.
Insert mode is canceled when you press a field
termination key or any screen field editing key other
than Insert Character.
MASK Same as above; however, an attempt to shift an input
character past a literal character specified in the mask is
rejected and results in a beep.

Keys That Generate Field Termination Codes
Table 8-2 lists the keys that generate field termination codes and the corresponding codes.
The table lists the default termination codes that the runtime system returns for the
indicated PC keyboard keys and for the input sequences from the terminfo and termcap
interfaces. The keys may be configured to perform different actions and return different
codes (see page 10-49 for information on the TERM-INTERFACE configuration
specifications).
An entry in brackets ([ ]) next to a terminfo or termcap entry identifies an alternate actual

input sequence that will generate the same termination code under UNIX. These
predefined input sequences are implied by the terminfo and termcap databases, as they
have no defined terminfo or termcap name.
Note Any key not covered by footnote 1 in Table 8-2 causes the ON EXCEPTION
imperative sequence.
The generic key name is described in the “EXCEPTION and NOT EXCEPTION
Phrases” section of the ACCEPT statement in Chapter 6, Procedure Division Statements,
of the RM/COBOL Language Reference Manual. See also Table 10-5 on page 10-48 of
this guide for more information.

Table 8-2 Keys that Generate Field Termination Codes
PC Keyboard Terminfo Termcap Termination

Key Name Name Generic Name Code
F1 kf1 k1 Function 1 01
F10 kf10 k; Function 10 10
F11 kf11 F1 Function 11 11
F12 kf12 F2 Function 12 12
Shift+F1 kf11 F1 Function 11 11
Shift+F10 kf20 FA Function 20 20
Ctrl+F1 kf21 FB Function 21 21
Ctrl+F2 kf22 FC Function 22 22
Ctrl+F3 kf23 FD Function 23 23
1
Causes field termination but does not take the ON EXCEPTION imperative sequence.
2
Performs the Erase Remainder.
3
Normal STTY configuration to terminate the runtime system under UNIX.
4
Terminates the runtime system under Windows. Also, the normal STTY configuration to
terminate the runtime system under UNIX.

Table 8-2 Keys that Generate Field Termination Codes (Cont.)

Ctrl+F4 kf24 FE Function 24 24
Ctrl+F5 kf25 FF Function 25 25
Ctrl+F6 kf26 FG Function 26 26
Ctrl+F7 kf27 FH Function 27 27
Ctrl+F8 kf28 FI Function 28 28
Ctrl+F9 kf29 FJ Function 29 29
Ctrl+F10 kf30 FK Function 30 30
Ctrl+Shift+F1 kf31 FL Function 31 31
Ctrl+Shift+F2 kf32 FM Function 32 32
Ctrl+Shift+F3 kf33 FN Function 33 33
Ctrl+Shift+F4 kf34 FO Function 34 34
Ctrl+Shift+F5 kf35 FP Function 35 35
Ctrl+Shift+F6 kf36 FQ Function 36 36
Ctrl+Shift+F7 kf37 FR Function 37 37
Ctrl+Shift+F8 kf38 FS Function 38 38
Ctrl+Shift+F9 kf39 FT Function 39 39
Ctrl+Shift+F10 kf40 FU Function 40 40
kf41 FV Function 41 41
kf42 FW Function 42 42
kf43 FX Function 43 43
kf44 FY Function 44 44
kf45 FZ Function 45 45
kf46 Fa Function 46 46
kf47 Fb Function 47 47
kf48 Fc Function 48 48
kf49 Fd Function 49 49
kf50 Fe Function 50 50
kf51 Ff Function 51 51
kf52 Fg Function 52 52
kf53 Fh Function 53 53


kf54 Fi Function 54 54
kf55 Fj Function 55 55
kf56 Fk Function 56 56
kf57 Fl Function 57 57
kf58 Fm Function 58 58
kf59 Fn Function 59 59
kf60 Fo Function 60 60
kf61 Fp Function 61 61
kf62 Fq Function 62 62
kf63 Fr Function 63 63
Enter [Ctrl+M]1 cr [Ctrl+M] cr [Ctrl+M] Enter 13
1, 2
Ctrl+Shift+K 13
→| kc3 [Ctrl+I] K5 [Ctrl+I] Tab Right 58
Ctrl+A Function 1 01
Ctrl+B Function 2 02
4
Ctrl+C Function 3 03
Ctrl+D Function 4 04
Ctrl+E Function 5 05
Ctrl+F Function 6 06
Ctrl+G Function 7 07
Ctrl+I Function 9 09 (58 on UNIX)
Ctrl+J Function 10 10 (55 on UNIX)
Ctrl+K Function 11 11
Ctrl+L Function 12 12
Ctrl+N Function 14 14
Ctrl+O Function 15 15
Ctrl+P Function 16 16
Ctrl+Q Function 17 17


Ctrl+R Function 18 18
Ctrl+S Function 19 19
Ctrl+T Function 20 20
Ctrl+U Function 21 21
Ctrl+V Function 22 22
Ctrl+W Function 23 23
Ctrl+X Function 24 24
Ctrl+Y Function 25 25
Ctrl+Z Function 26 26
Esc Escape 27
Ctrl+[ 27
3
Ctrl+\ 28
Ctrl+] 29
Ctrl+6 30
Ctrl+ – 31
Ctrl+Shift+C kf0 k0 Command 40
Ctrl+Shift+A ka3 K3 Attention 41
Ctrl+Shift+P lf0 l0 Print 49
↑ kcuu1 ku Up Arrow 52
↓ kcud1 kd Down Arrow 53
Home khome kh Home 54
Ctrl+Shift+N nel [Ctrl+J] nw [Ctrl+J] New Line 55
|← kc1 K4 Tab Left 56
Ctrl+Shift+E kel kE Erase Remainder 57
Ctrl+Shift+R kc3 k5 Tab Right 58
Ctrl+Shift+I kil1 kA Insert Line 59
Ctrl+Shift+D kdl1 kL Delete Line 61
Ctrl+Shift+S kb2 K2 Send 64
Ctrl+← 65
Ctrl+→ 66


PgUp kpp kP Page Up 67
PgDn knp kN Page Down 68
Ctrl+PgUp 69
Ctrl+PgDn 70
Ctrl+Shift+1 71
Ctrl+Shift+2 72
Ctrl+Shift+3 73
Ctrl+Shift+4 74
Ctrl+Shift+5 75
Ctrl+Shift+6 76
Ctrl+Shift+7 77
Ctrl+Shift+8 78
Ctrl+Shift+9 79
Ctrl+Shift+0 80
Ctrl+Home 81
End ka1 K1 End 82
Ctrl+End khlp %1 Help 83
N/A krdo %0 Redo 84
Ctrl+Shift+ – 85
Ctrl+Shift+= 87

Table 8-3 lists the default semantic actions that the runtime system returns for input
sequences from the different terminal interfaces under UNIX.
Table 8-3 Default Semantic Actions
Semantic Action Terminfo Name Termcap Name

Left Arrow kcub1 kl
Right Arrow kcuf1 kr
Backspace kbs [Ctrl+H] kb [Ctrl+H]
Set RM Insertion kich1 kI
Delete Character kdch1 kD
Erase Entire kclr kC
1
Erase Remainder kel kE
1
This action also generates a termination code.
ACCEPT and DISPLAY Phrases

The CONTROL, ERASE, HIGH, LOW, OFF, and REVERSE phrases affect the use of
color attributes with the ACCEPT and DISPLAY statements. The SIZE phrase used with
the ACCEPT and DISPLAY statements affects the size of the screen field. The TIME
phrase is used to “time-out” the execution of a pending ACCEPT statement. These
phrases are defined in the following paragraphs.
CONTROL Phrase
Some of the system dependencies that apply to the CONTROL phrase value concern
color-capable terminals. Systems with monochrome terminals ignore color information
contained in the CONTROL phrase value. (See the appropriate manufacturer's manual
for information on configuring your system with color capability.)
Under UNIX, color requests are processed only if the terminal does not require an
attribute byte and if one of the following conditions is met:
1. The terminfo database contains the set_foreground and set_background string

sequences. (The back_color_erase and orig_pairs string sequences are not required.)
The termcap database contains the Sb (set current background color) and St (set
current foreground color) sequences.
2. A configuration record is present to force the use of ISO Set Graphics Rendition
(SGR) sequences when the terminfo information is not available.

The method a terminal uses to process SGR color sequences will vary from one
manufacturer to another. When color sequences are sent to monochrome terminals, they
are either ignored, processed as shades of gray, or represented as characters on the screen.
Color sequences sent to color-capable terminals may or may not conflict with other
attributes sent to the terminal. For example, sending a color sequence followed by a blink
sequence may result in the loss of the color request. RM/COBOL always sends color
sequences after all other requested attributes. This prevents areas of the terminal screen
from appearing without the desired color. You will need to refer to the terminal
manufacturer and the UNIX terminfo documentation in order to determine the sequences
necessary to access color capabilities. See Chapter 10, Configuration, for information on
the color options of the TERM-ATTR configuration record.
RM/COBOL provides eight system-dependent keywords in the CONTROL phrase that

affect an ACCEPT or DISPLAY field: FCOLOR, BCOLOR, GRAPHICS, MASK1,
PASS-THRU1, PROMPT, REPAINT-SCREEN1, and SCREEN-COLUMNS1.
1. FCOLOR = color-name
When FCOLOR is present, color-name specifies the foreground color of the

ACCEPT or DISPLAY field. This name is then used as the default value for
subsequent ACCEPT and DISPLAY statements in the program.
See the discussion of the HIGH, LOW and OFF phrases in the following section for
information concerning high-intensity colors.
The initial default for color-name is white.
Note Under Windows, the default colors are determined by the Use Windows
Colors property as described on page 3-29.
2. BCOLOR = color-name
When BCOLOR is present, color-name specifies the background color of the

ACCEPT or DISPLAY field. This value is then used as the default value for
subsequent ACCEPT and DISPLAY statements in the program.
The initial default for color-name is black.
Table 8-4 contains a list of all the possible names for color-name. The left column
contains the valid color name. The right column shows the color that appears when
high intensity is specified (the default intensity).
Note Under Windows, the default colors are determined by the Use Windows
Colors property as described on page 3-29.
_____________________
1
These keywords are supported only under RM/COBOL for UNIX.

Table 8-4 Valid COBOL Color Names
Valid Color Names High-Intensity Color Values (Defaults)

Black Gray
Blue Light Blue
Green Light Green
Cyan Light Cyan
Red Light Red
Magenta Light Magenta
Brown Yellow
White High-Intensity White
3. GRAPHICS
The GRAPHICS keyword causes the characters in Table 8-5 to be translated to

portable, system-specific line draw characters. Characters that are not listed in
Table 8-5 are output unchanged.
Table 8-5 System-Specific Line Draw Characters
Description Single-Line Character Double-Line Character

lower-right corner j(») J(Î)
upper-right corner k(¹) K(È)
upper-left corner l(¸) L(Å)
lower-left corner m(º) M(Ë)
plus n(À) N(Ý)
horizontal line q(¶) Q(Á)
left tee t(¼) T(Ñ)
right tee u(½) U(Ô)
bottom tee v(¿) V(Ú)
top tee w(¾) W(×)
vertical line x(·) X(Â)
If the requested line draw characters are not available, the runtime system uses the
best available characters. If double-line characters are requested and only single-line
characters are available, they are used. If no line draw characters are available, then
plus-characters, vertical bars, and dashes are used.

See page 2-21 for details on how the runtime system determines whether line draw
characters are available for a given terminal under UNIX.
Here is a sample program that demonstrates how boxes are drawn:
PROGRAM-ID. GRAPHXMP.
PROCEDURE DIVISION.
GRAPHXMP.
DISPLAY " ", LINE 5 POSITION 1 ERASE.
* Single-line graphics
DISPLAY "lqqqqwqqqqk", CONTROL "HIGH, GRAPHICS".
DISPLAY "x x x", CONTROL "HIGH, GRAPHICS".
DISPLAY "tqqqqnqqqqu", CONTROL "HIGH, GRAPHICS".
DISPLAY "x x x", CONTROL "HIGH, GRAPHICS".
DISPLAY "mqqqqvqqqqj", CONTROL "HIGH, GRAPHICS".
DISPLAY " ".
* Double-line graphics
DISPLAY "LQQQQWQQQQK", CONTROL "HIGH, GRAPHICS".
DISPLAY "X X X", CONTROL "HIGH, GRAPHICS".
DISPLAY "TQQQQNQQQQU", CONTROL "HIGH, GRAPHICS".
DISPLAY "X X X", CONTROL "HIGH, GRAPHICS".
DISPLAY "MQQQQVQQQQJ", CONTROL "HIGH, GRAPHICS".
END PROGRAM GRAPHXMP.
4. MASK
A new keyword, MASK, has been added to the CONTROL phrase in ACCEPT and
DISPLAY statements. Use the following format:
MASK = mask
Note The MASK keyword is ignored when standard input or standard output is
redirected. This keyword is supported only under UNIX.
The MASK keyword in the CONTROL phrase causes a literal mask to be edited into
the ACCEPT or DISPLAY screen field. Literal mask characters are inserted into the
operand as it is transferred to the screen field if UPDATE is specified, or overlaid
onto the screen field if ACCEPT-FIELD-FROM-SCREEN is in effect.
In all cases, the size of the mask determines the size of the actual ACCEPT or
DISPLAY screen field. The optional SIZE phrase, or the size of the actual operand,
is used only to limit the number of data characters that may be edited and entered into
the ACCEPT screen field, or edited into the DISPLAY screen field prior to the
screen operation.

The mask is specified in the CONTROL phrase as a literal string with no embedded
spaces. If the mask specifies more input positions than are contained in the
ACCEPT/DISPLAY operand, then excess mask input positions are replaced by
literal spaces. The mask is limited to a total of 80 characters, including escape
characters. When a screen field is edited, literal characters specified with the MASK
keyword cannot be modified.
Table 8-6 lists the characters and character sequences that have special meanings in
the MASK keyword in a CONTROL phrase string. All other characters are treated
as literal characters.
Table 8-6 Characters Used with the MASK Keyword of a CONTROL Phrase
Character Meaning
X Specifies an input/output position. Characters will be accepted
wherever an uppercase "X" appears in the mask. DBCS characters can
be entered only into two, adjacent input positions.
_ Specifies a literal space.
\ Forces the following character to be treated as a literal character. The
backslash character is the escape character.
\X Specifies a literal "X".
\_ Specifies a literal underscore.
\, Specifies a literal comma.
\= Specifies a literal equal sign.
\\ Specifies a literal backslash.
Note 1 The preceding characters are case-sensitive. For example, “x” is not the
same as “X”.
Note 2 If a mask character overlays part of a double-byte (DBCS) character, the

entire character is replaced by blanks.
When an ACCEPT operation that specifies the MASK keyword in a CONTROL

phrase is processed, the RM/COBOL runtime takes the following actions:
a. If the operation is ACCEPT with UPDATE, characters from the operand are
copied (from left to right) into mask input positions. Mask literal characters are
skipped. If the operand is exhausted while there are still remaining input
positions, such positions are changed to literal spaces. If the mask is exhausted
before the operand, the remainder of the operand is ignored. The SIZE phrase,
if specified, limits the size of the operand, not the size of the mask.

The size of the screen field is then set to the size of the mask, including trailing
literal characters.
If PROMPT is also specified, trailing input positions that are initialized with
spaces are replaced with the prompt character.
b. If ACCEPT without UPDATE is specified, and ACCEPT-FIELD-FROM-

SCREEN is not in effect, mask input positions are initialized with spaces or with
the prompt character, if PROMPT is specified. The number of mask input
positions is still restricted, based on the SIZE phrase or the size of the operand.
c. If ACCEPT without UPDATE is specified, and ACCEPT-FIELD-FROM-

SCREEN is in effect, mask input positions are initialized from the current screen
field. In this case, there is a one-for-one correspondence between mask
characters and screen characters; that is, the mask is overlaid rather than inserted
into the screen field. If PROMPT is specified, trailing input positions that are
initialized with spaces are replaced with the prompt character.
When the ACCEPT is terminated, the input field is scanned from left to right.
Characters appearing in input positions only are copied into the ACCEPT operand.
The operand is then processed by the CONVERT and UPPER phrases as if a regular
ACCEPT operation had been performed.
Table 8-7 lists keywords and phrases that, when specified in ACCEPT and/or
DISPLAY statements, have an effect on masked input processing.

Table 8-7 Effect of Certain Keywords and Phrases on Masked Input Processing
Keyword or Phrase Effect

CURSOR The CURSOR phrase in an ACCEPT statement specifies the input
position, rather than the field position where the cursor is placed. It
returns the input position occupied by the cursor when the ACCEPT
statement is terminated.
GRAPHICS The GRAPHICS keyword in the CONTROL phrase of an ACCEPT or
a DISPLAY statement translates mask characters and input characters.
HIGH, LOW, The presence of these phrases in an ACCEPT or a DISPLAY statement
HIGHLIGHT, causes literal mask characters and input characters to be displayed at
LOWLIGHT the specified intensity.
OFF, When the OFF (SECURE) phrase is specified in an ACCEPT
SECURE statement, literal mask characters are displayed, while input characters
are not displayed.
PROMPT When the PROMPT phrase is specified in an ACCEPT statement,
trailing input positions are filled with the specified prompt character.
SIZE When the SIZE phrase is specified in an ACCEPT or a DISPLAY
statement, the size of the ACCEPT and DISPLAY operand is limited,
but there is no effect on the screen field size.
TAB If the TAB keyword is not specified in the CONTROL phrase of an
ACCEPT statement (or the TAB phrase is not specified in an ACCEPT
statement), field termination occurs when the cursor leaves the last
input position, which may be followed by literal characters.
5. PASS-THRU
The ability to write escape sequences (such as pass-through printing) to the terminal
with DISPLAY statements requires an additional keyword in the CONTROL phrase.
The keyword, PASS-THRU, indicates that all data specified in the corresponding
DISPLAY statement is to be written directly to the unit and not recorded in the
in-memory image of the screen. Thus, if the DISPLAY statement causes the screen
to change, the runtime system will have no knowledge of the change, and subsequent
DISPLAY statements may cause confusion for the terminal operator.
This ability also can be used automatically by specifying a TERM-ATTR

PASS-THRU-ESCAPE configuration file record. If used, any DISPLAY statements
beginning with one of the escape characters will behave as if PASS-THRU were
specified in the statement. See page 10-39 for more information.
Note This keyword is supported only under UNIX.

6. PROMPT = prompt-char
The PROMPT keyword causes ACCEPT statements to accept data with fill
characters in positions from which data is to be accepted. Optionally, the PROMPT
keyword may specify prompt-char, which causes the ACCEPT operation to use a
prompt character different from the system default. prompt-char must be a single,
literal character. For example:
ACCEPT FOO CONTROL "PROMPT=*,TAB".
where asterisk (*) is the prompt-char.
7. REPAINT-SCREEN
The REPAINT-SCREEN keyword causes the entire screen to be refreshed from the
runtime system’s in-memory screen image. Any characters that were written directly
to the screen, such as from C routines or DISPLAY statements with the PASS-THRU
keyword (which are not recorded in the in-memory screen image), are replaced by the
last value written to that location by regular DISPLAY statements. This provides the
ability to clean up the screen without manually having to redraw the entire display.
REPAINT-SCREEN may be used in both ACCEPT and DISPLAY statements. It is
also callable from linked C routines (see page D-23 in Appendix D, Customizing
RM/COBOL for UNIX).
8. SCREEN-COLUMNS = screen-width
The SCREEN-COLUMNS keyword instructs the runtime system to change the
current display state of the user’s terminal to accommodate the requested screen size.
Screen-width values of 80 and 132 are currently supported.
Changing the terminal state produces a new, blank screen of the requested screen
width. All characters and windows on the original display are erased. In order to
maintain valid user-defined window control blocks, programs using pop-up windows
must close all pop-up windows before changing the screen size.
Most terminals support varying screen dimensions through normal and wide terminfo
and termcap entries. These normally correspond to 80 and 132 columns,
respectively. When a screen dimension change is requested, the runtime system
switches the TERM environment variable to the appropriate value and then sends
reset or initialization strings that change the terminal’s state. For terminfo, the strings
are defined with the capabilities rs1, rs2, and rs3. For termcap, the strings are
defined with the capabilities r1, r2, and r3. If these termcap capabilities are not
defined, the runtime system attempts to use the capability is. If these strings are not
set correctly, the terminal may be changed to an unpredictable state.

Most UNIX systems append a “–w” to terminal descriptions to indicate a terminal’s
wide screen mode. For example, the wyse60 terminal description for wide displays is
normally referred to as wyse60–w. Because not all UNIX systems follow this
standard, the COBOL runtime allows users to use the RMTERM80 and
RMTERM132 environment variables. If both variables are set, the runtime system
changes the TERM environment variable to the appropriate name, as specified in
RMTERM80 or RMTERM132. For example, some systems append “w” to wide
terminal descriptions. RMTERM132 can be used to ensure proper behavior by
setting it as RMTERM132=wyse60w.
ERASE Phrase
All valid ERASE options (that is, ERASE, ERASE EOL, and ERASE EOS) erase the
screen with the specified background color, if possible. Under UNIX, if the
back_color_erase termcap or terminfo capability is set to false, or the appropriate termcap
or terminfo capability to perform the specified ERASE operation is not available, blanks
will be used to perform the operation.
HIGH Phrase
HIGH specifies that the foreground color be the corresponding high-intensity color listed
in Table 8-4 on page 8-13.
Under UNIX, when the HIGH phrase is present, the termcap capabilities used to set the
attributes of the terminal are nM, nB, nR or nS. The terminfo capabilities are sgr0,
blink, rev or sgr. The capability used is determined by the BLINK and REVERSE
phrases, and by the definition of termcap or terminfo capabilities in the terminal database.
When used with a color monitor under UNIX, the HIGH phrase specifies that the
foreground color be the high-intensity color from Table 8-4 that corresponds to the
foreground color name. If the REVERSE phrase is also present in the statement, it takes
precedence over the HIGH phrase. That is, any reversal of colors takes place before the
intensity is determined.
LOW Phrase
LOW specifies that the foreground color be the default foreground color unless
overridden with the FCOLOR keyword.
When the LOW phrase is present under UNIX, the termcap capabilities used to set the
attributes of the terminal are aL, aB, aR, or aS. The terminfo capabilities are dim or sgr.
The capability used is determined by the BLINK and REVERSE phrases, and by the

definition of termcap or terminfo capabilities in the terminal database. The BLINK and
REVERSE phrases are not supported by a terminfo runtime system unless the sgr
capability is available.
If the REVERSE phrase is also present in the statement, it takes precedence over the
LOW phrase, that is, any reversal of colors takes place before the intensity is determined.
OFF Phrase
OFF specifies that the background color be used for the foreground color. During field
editing for ACCEPT operations, the cursor is moved as specified, but without character
echoing.
If the REVERSE phrase is also present in the statement, it takes precedence over the OFF
phrase; that is, any reversal of colors takes place before the background color is
determined.
SECURE is a synonym for OFF.
REVERSE Phrase
When the REVERSE phrase is present, the specified (or default) foreground color is used
as the background color, and the background color is used as the foreground color. The
REVERSE phrase is processed before the HIGH, LOW, and OFF phrases.
SIZE Phrase
The SIZE phrase is used to specify the size of an ACCEPT or DISPLAY field. The
runtime system imposes the following restrictions and limitations on the value of the SIZE
phrase:
1. The size of an ACCEPT or DISPLAY field must not exceed the number of characters
that can appear on the screen at one time, minus the column of the first character of
the data item.
2. The ACCEPT or DISPLAY field must not exceed the size of the associated buffer:
the default is 264 (see the discussion of the B Runtime Command Option on
page 7-4).
3. Fields that extend beyond the physical right margin of the screen wrap around to
the next line.
4. Fields that extend beyond the last line of the screen cause the screen to scroll
one line.

TIME Phrase
The BEFORE TIME phrase is used to “time-out” the execution of a pending ACCEPT
statement. The value of literal-8 or identifier-8 in the BEFORE TIME phrase represents
the time-out value in hundredths of seconds. The time-out value is limited to 23 hours, 59
minutes, 59.99 seconds (or 8,639,999). A value greater than 8,639,999 and less than or
equal to 4,294,967,295 (2**32 – 1) is set to 8,639,999.
A time-out value of 0 indicates that the ACCEPT operation should terminate immediately
if there is no character waiting. A time-out value greater than 4,294,967,295
(a PIC 9(10) data item set to a value of 9999999999 is recommended) indicates that
the BEFORE TIME phrase is being overridden and the ACCEPT statement will behave
as if the BEFORE TIME phrase were not specified.
When the ACCEPT statement is executed, a target time is calculated as the sum of the
current time and the time-out value. The time-out operation runs until the target time is
reached or a key is pressed. Once a key has been pressed, the time-out function is
disabled.
If the target time is reached before a key has been pressed, the ACCEPT statement is
terminated. A termination code of 99 is returned in identifier-9 if the ON EXCEPTION
phrase is specified.
The BEFORE TIME phrase is intended for terminal input and it is not available if input is
redirected.
Under UNIX, if the CHARACTER-TIMEOUT keyword of the TERM-ATTR

configuration record has a value (see page 10-36), it will affect the BEFORE TIME
phrase of the ACCEPT statement. The actual time-out value will be the first integral
multiple of the CHARACTER-TIMEOUT value that is greater than or equal to the value
specified in the ACCEPT BEFORE TIME phrase.
Pop-Up Windows
A COBOL program can create one or more pop-up windows on the terminal output
device. A pop-up window (referred to hereinafter as a window) is a temporary subscreen
within the terminal screen to which all terminal output is directed. The rules concerning
placement of data and default video attributes that apply to full screen input/output also
apply to the window (including wrapping and scrolling). Thus the window performs just
like a full screen, except that a window is usually smaller.
A window is used for terminal input/output from the time it is created until the window is
removed by the COBOL program or another window is created. When a window is

Pop-Up Windows
removed, the contents that occupied the window area before it was created are restored,
and the previous window again becomes the active subscreen. All current defaults that
are associated with the newly restored window, such as the current video attributes, the
current line, and the current position, are restored.
Note Only information written to the screen by the RM/COBOL runtime system can be
restored to the screen in the event that it is covered by a window that is later removed.
For examples on using the RM/COBOL Pop-Up Window Manager, see your installation
directory and examine the following programs:
• wintest.cbl • winreltv.cbl
• winattrb.cbl • winstat.cbl
• winbordr.cbl • wintitle.cbl
• wincolor.cbl
Creating Pop-Up Windows

A window is created by a Format 2 DISPLAY statement containing the
WINDOW-CREATE keyword in its CONTROL phrase. See the description of
the DISPLAY statement (terminal I-O) in Chapter 6, Procedure Division Statements,
of the RM/COBOL Language Reference Manual. The general format of a DISPLAY
statement used to create a window is shown below.
Note The format shown is a subset of the Format 2 DISPLAY Terminal I-O statement
because some options of the complete statement are not applicable to window creation.

Pop-Up Windows
  BEEP  
   
  BELL  
 
 BLINK 
  COLUMN  
   identifier-3 
  COL    
   POSITION  literal-3   
     
   
 identifier-4  
 CONTROL   
   
 literal-4  
  
identifier-2   ERASE  
DISPLAY identifier-1 UNIT      
 literal-2    HIGH  
   
   
  HIGHLIGHT  
   
   LOW   
   LOWLIGHT   
   
   
 identifier-5 
LINE  
 literal-5  
 
  REVERSE  
   
  REVERSED  
  REVERSE - VIDEO  
   
identifier-1 specifies the window control block for the window creation. See pages 8-24
and 8-27 for more information.
BEEP Phrase
The presence of the BEEP phrase in the DISPLAY statement causes the audio alarm
signal to occur at the creation of the window. If the BEEP phrase is omitted, no signal is
given.
BELL is a synonym for BEEP.
BLINK Phrase
The presence of the BLINK phrase causes the border, title, and fill characters of the
window to appear in a blinking mode. If the BLINK phrase is not specified, the border,
title, and fill characters appear in a nonblinking mode.
Note The blinking attribute is not available under Windows.

Pop-Up Windows
CONTROL Phrase
A DISPLAY statement with a CONTROL phrase containing the WINDOW-CREATE

keyword (see discussion of the CONTROL phrase of the DISPLAY statement in
Chapter 6, Procedure Division Statements, of the RM/COBOL Language Reference
Manual) causes identifier-1 to be treated as a window control block, and this data item
must have the structure described in “Pop-Up Window Control Block” on page 8-27. The
window is created according to the specifications given in the window control block. The
window control block provided must not be that of an active window.
The FCOLOR and BCOLOR keywords can be used to set the colors of the border
characters, title characters, and fill characters of the window being created. FCOLOR
specifies the foreground color of each character, and BCOLOR defines the background
color. FCOLOR and BCOLOR also establish the initial default colors for ACCEPT and
DISPLAY statements performed while the window is active. See Table 8-4 on page 8-13
for valid color names. If FCOLOR and BCOLOR are not specified when creating a
window, the default colors (if any) in effect when the window creation is requested are
carried over to the new window.
Additional keywords that may be specified in the CONTROL phrase and that affect the
creation of the window include: HIGH, LOW, BLINK, NO BLINK, REVERSE, NO
REVERSE, ERASE, NO ERASE, BEEP, and NO BEEP. The meanings of these
keywords when they appear in the value of the CONTROL phrase operand are the same
as the corresponding phrases that may be written as static options of the DISPLAY
statement, with the addition of the negative forms to allow suppression of statically
declared options. The window creation effects of the static phrases and the corresponding
CONTROL phrase keywords are described in the following paragraphs.
ERASE Phrase
The presence of the ERASE phrase causes the window area to be erased upon creation of
the window.
Note Using the EOS or EOL reserved words with ERASE causes the ERASE phrase to
be ignored.

Pop-Up Windows
HIGH and LOW Phrases
The presence of the HIGH or LOW phrase causes the border, title, and fill characters of
the window to be painted at the specified intensity. When HIGH or LOW is not
specified, the default intensity is HIGH.
HIGHLIGHT is a synonym for HIGH and LOWLIGHT is a synonym for LOW.
Note Under Windows, the HIGH and LOW phrases do not affect the border or the title
of the window.
LINE and POSITION Phrases
The window is painted on the screen with LINE 1 and POSITION 1 of the window
positioned at the LINE and POSITION specified in the DISPLAY statement creating the
window. See “Defining the Location of the Pop-Up Window” on page 8-28 for further
discussion of the placement of the window. LINE 1, POSITION 1 of the window is
limited to the boundaries of the screen.
If requested, the border occupies the lines immediately above and below the window, and
the columns immediately to the right and to the left of the window. If a title is requested,
it will be painted within the top or bottom border. If a title is requested and a border is
not requested, the title will occupy the line either immediately above or immediately
below the window.
If the LINE or POSITION phrase is omitted from the DISPLAY statement, the line and
position values for the window are determined in the same manner as the line and position
values in a non-window Format 2 DISPLAY statement, except that the ERASE phrase
and the window dimensions are not considered (see the section “Determining Line and
Position” for the DISPLAY statement in Chapter 6, Procedure Division Statements, of
the RM/COBOL Language Reference Manual).
COLUMN and COL are synonyms for POSITION.
REVERSE Phrase
The presence of the REVERSE phrase causes the border, title, and fill characters of the
window to appear in a reverse video mode. If the REVERSE phrase is not specified, the
border, title, and fill characters appear in the normal video mode.
REVERSED and REVERSE-VIDEO are synonyms for REVERSE.
Note Under Windows, the REVERSE phrase does not affect the border or the title of
the window.

Pop-Up Windows
UNIT Phrase
The UNIT phrase, if specified, must be written first. The other phrases may be written in
any order. If not running under UNIX, the value of identifier-2 or literal-2 in the UNIT
phrase is ignored. Under UNIX, the value of identifier-2 or literal-2 specifies the
terminal upon which the window is to be created. If the UNIT phrase is omitted, the
terminal that started the run unit is used.
Removing a Pop-Up Window

A window is removed by a Format 2 DISPLAY statement (see the description of the
“DISPLAY Statement” in Chapter 6 of the RM/COBOL Language Reference Manual)
containing the WINDOW-REMOVE keyword in its CONTROL phrase. The general
format of a DISPLAY statement used to remove a window is shown below.
Note The format shown is a subset of the Format 2 DISPLAY statement because some
options of the complete statement are not applicable to window removal.
identifier-1  identifier-2 identifier-4 

DISPLAY   UNIT literal-2  CONTROL  
literal-1     literal-4 
identifier-1 specifies the window control block for the window creation. See pages 8-23
and 8-27 for more information.
CONTROL Phrase
A DISPLAY statement with a CONTROL phrase containing the WINDOW-REMOVE

keyword (see discussion of the CONTROL phrase of the DISPLAY statement in
Chapter 6 of the RM/COBOL Language Reference Manual) causes identifier-1 to be
treated as a window control block, and causes the active window to be removed. The
window control block should be the same one used to create the window; it must not be
that of a different active window.
UNIT Phrase
The UNIT phrase, if specified, must be written first. The other phrases may be written in
any order. If not running under UNIX, the value of identifier-2 or literal-2 in the UNIT
phrase is ignored. Under UNIX, the value of identifier-2 or literal-2 specifies the
terminal upon which the window is to be created. If the UNIT phrase is omitted, the
terminal that started the run unit is used.

Pop-Up Windows
Pop-Up Window Control Block
The following is an example of a window control block in a COBOL program. The order
of the fields, the PICTURE character-string, and the declared usage in the example are
fixed parameters that cannot be changed when defining a window control block. The
data-names and contents of the fields in the example are variable and thus may be
changed.
01 WINDOW-CONTROL-BLOCK.
03 WCB-HANDLE PIC 999 BINARY(2)
VALUE 0.
03 WCB-NUM-ROWS PIC 999 BINARY(2).
03 WCB-NUM-COLS PIC 999 BINARY(2).
03 WCB-LOCATION-REFERENCE PIC X.
88 WCB-SCREEN-RELATIVE VALUE "S".
88 WCB-WINDOW-RELATIVE VALUE "W".
03 WCB-BORDER-SWITCH PIC X.
88 WCB-BORDER-ON VALUE "Y" FALSE "N".
03 WCB-BORDER-TYPE PIC 9.
88 WCB-BORDER-WCB-CHAR VALUE 0.
88 WCB-BORDER-PLUS-MINUS-BAR VALUE 1.
88 WCB-BORDER-LINE-DRAW VALUE 2.
88 WCB-BORDER-DBL-LINE-DRAW VALUE 3.
03 WCB-BORDER-CHAR PIC X.
03 WCB-FILL-SWITCH PIC X.
88 WCB-FILL-ON VALUE "Y" FALSE "N".
03 WCB-FILL-CHAR PIC X.
03 WCB-TITLE-LOCATION PIC X.
88 WCB-TITLE-TOP VALUE "T".
88 WCB-TITLE-BOTTOM VALUE "B".
03 WCB-TITLE-JUSTIFICATION PIC X.
88 WCB-TITLE-CENTER VALUE "C".
88 WCB-TITLE-LEFT VALUE "L".
88 WCB-TITLE-RIGHT VALUE "R".
03 WCB-TITLE-LENGTH PIC 999 BINARY(2).
88 WCB-TITLE-LENGTH-COMPUTE VALUE 0.
03 WCB-TITLE PIC X(40).

Pop-Up Windows
Identifying the Pop-Up Window
The field WCB-HANDLE is initialized by the WINDOW-CREATE DISPLAY operation

to contain a value that identifies the window. This field must be set to zero before the
WINDOW-CREATE operation. The value that was placed in this field following the
WINDOW-CREATE operation must be in the WCB-HANDLE field when the
WINDOW-REMOVE DISPLAY operation is performed to remove the window. The
only other value that is allowed is zero, which removes the active window.
Note The use of zero is allowed for compatibility with previous versions of the Pop-Up
Window Manager, but it is strongly discouraged.
Defining the Size of the Pop-Up Window
The parameters WCB-NUM-ROWS and WCB-NUM-COLS define the number of rows

and columns available for ACCEPT and DISPLAY statements within the window. If the
window is to have a border, it will occupy two additional rows and two additional
columns on the screen. If the window has a title but does not have a border, the window
occupies one additional line on the screen.
Defining the Location of the Pop-Up Window
The WCB-LOCATION-REFERENCE parameter determines whether the LINE and

POSITION in the DISPLAY statement used to create the window describes a location
relative to the physical screen or the active window. A value of S indicates the location is
relative to the physical screen. A value of W indicates the location is relative to the active
window.
The created window is limited to the boundaries of the screen, not to the boundaries of
the active window.
Defining the Border of the Pop-Up Window
The parameter WCB-BORDER-SWITCH determines whether a border should be painted

around the window. A value of Y indicates that a border is to be painted. A value of N
indicates that a border is not to be painted.
The parameter WCB-BORDER-TYPE determines what characters are used to make up

the border. A value of 0 indicates that the character specified by WCB-BORDER-CHAR
is used to paint the border. A value of 1 indicates that the plus sign, hyphen, and
vertical bar characters (+, –, |) are used to paint the border. A value of 2 in the
WCB-BORDER-TYPE field indicates that graphic line draw characters are used to paint
the border. A value of 3 in the WCB-BORDER-TYPE field indicates that graphic
double-line line draw characters are used to paint the border. If the terminal does not

Pop-Up Windows
support line draw graphics characters, the border will be drawn using normal characters
(+, –, |). This field is ignored unless WCB-BORDER-SWITCH has a value of Y.
The WCB-BORDER-CHAR parameter determines the character to be used in building

the border around the window. This field is ignored unless WCB-BORDER-SWITCH
has a value of Y and WCB-BORDER-TYPE has a value of 0.
Note The WCB-BORDER-CHAR and WCB-BORDER-TYPE parameters are ignored

under Windows.
Initializing the Pop-Up Window Area
WCB-FILL-SWITCH determines whether the window should be filled with the character
defined by WCB-FILL-CHAR when it is created. If the window is not filled, then the
contents in the defined window area remain untouched until modified by a subsequent
ACCEPT or DISPLAY statement in the window. A value of Y indicates that the window
area be filled with the defined character. A value of Y will also cause an ERASE phrase
to be ignored. A value of N indicates that the window area is to be left unchanged.
The parameter WCB-FILL-CHAR determines the character to be used to fill the window
area. This field is ignored unless WCB-FILL-SWITCH has a value of Y.
Defining the Location of the Title of the Pop-Up Window
The parameter WCB-TITLE-LOCATION determines whether the text in WCB-TITLE

should be placed within the location of the top border or bottom border. A value of T
indicates that the title is to be painted at the top of the window. A value of B indicates
that the title is to be painted at the bottom of the window. This field is ignored if
WCB-TITLE-LENGTH has a value of zero and WCB-TITLE is filled with spaces.
The WCB-TITLE-JUSTIFICATION parameter determines whether the text of the title

should be centered, left-justified, or right-justified in its location at the top or bottom of
the window. A value of C indicates that the title should be centered, L indicates that it
should be left justified, and R indicates that the window should be right justified. This
field is ignored if WCB-TITLE-LENGTH has a value of zero and WCB-TITLE is filled
with spaces.
Note The WCB-TITLE-JUSTIFICATION and WCB-TITLE-LOCATION parameters

are ignored under Windows.

Pop-Up Windows
Defining the Title of the Pop-Up Window
The length of the title is defined by the value of the WCB-TITLE-LENGTH parameter.
If the value of this field is non-zero, WCB-TITLE-LENGTH indicates the number of
characters, beginning with the first character of the WCB-TITLE field, that are to be used
as the title of the window. If the value of this field is zero, the title string is made up of all
characters between the first character of the WCB-TITLE field to the last non-blank
character in the field.
The WCB-TITLE parameter defines the text to be placed in the title of the window. This
field may be any length sufficient to contain the desired title, and must be the last data
item in the window control block. The length of 40 specified in the example is an
arbitrary value.
Pop-Up Window Operation Status

The COBOL program can obtain the status of a window operation immediately after a
request is made to create or remove a window. The ACCEPT FROM EXCEPTION
STATUS statement places the status in the field designated by identifier-1. The general
format of the ACCEPT FROM EXCEPTION STATUS statement is shown below.
ACCEPT identifier-1 FROM EXCEPTION STATUS [ END - ACCEPT ]

The information requested is transferred from EXCEPTION STATUS to identifier-1
according to the rules of the MOVE statement (see the discussion of the MOVE
statement in Chapter 6, Procedure Division Statements, of the RM/COBOL Language
Reference Manual). EXCEPTION STATUS is an implicitly defined data item that
behaves as if it had been defined in the Data Division as an unsigned, three-digit, numeric
integer data item.

Pop-Up Windows
Table 8-8 is a list of the error codes and values returned to the COBOL program after a
request is made to create or remove a window.
Table 8-8 Pop-Up Window Error Codes
Code Description
0 Operation successfully completed.
1
301 Window border or title does not fit on screen.
1
302 Title is too long for window or specified title length is longer than the
title field in the window control block.
3031 Requested window will not fit on screen.
304 No windows are active.
305 Window manager is not available.
306 Out of memory.
307 Too many windows.
308 Buffer I/O error.
309 Requested REMOVE-WINDOW for inactive WCB.
310 CREATE-WINDOW requested with active WCB.
311 Invalid parameter in WCB.
1
These error codes are reported differently under Windows than under UNIX, or they are not
reported.
COPY Statement
Use the COPY statement to copy RM/COBOL source text from a specified file into the
source program. The text copied may have been created outside RM/COBOL, either
through a text editor or through some other process. The file is copied at the point at
which the COPY statement appears in the program; the file logically replaces the COPY
statement.
A copied file may in turn contain COPY statements, up to the limits of either five (the
typical case) or nine (if the last statement in the copy file is a COPY statement).
See the discussion of the COPY statement in Chapter 1, Language Structure, of the
RM/COBOL Language Reference Manual, for a description of the syntax and field
definitions.

COPY Statement
Filenames that are not reserved words and that are made up of valid RM/COBOL
alphabetic, numeric and special characters do not need to be enclosed in quotation marks
within the COPY statement. Filenames that are reserved words or contain characters
other than the standard set must be specified as a nonnumeric literal (that is, they must be
enclosed in quotation marks). A period followed by a space terminates the COPY
statement (that is, it is not considered part of a text-name or a library-name).
If a library-name is specified in the COPY statement, it is treated as a pathname for the

filename.
If you do not enter a filename extension with the filename, the compiler assumes an
extension of .cbl. If it cannot find such a file, it then looks for a file with the supplied
name with the extension .CBL. The assumed extension can be changed with the
EXTENSION-NAMES configuration record (see page 10-19). For all attempts to open
the copied file, if a directory path or a drive letter is not specified, the directory search
sequence is used to try to locate the file (see the discussion of search sequences that
begins on either page 2-4 for UNIX or page 3-11 for Windows).
Here are three examples of valid COPY statements.
COPY STDID.
The preceding COPY statement copies the file stdid.cbl from the path specified by
RMPATH.
ENVIRONMENT DIVISION.
COPY "cobol".
The preceding COPY statement copies the file cobol.cbl from the path specified by
RMPATH (see the discussion of RMPATH in the appropriate installation and system
considerations chapter in this user's guide for your specific operating system).
COP Y data1 OF lib1.
The preceding COPY statement copies the file lib1/data1.cbl relative to the
current directory.

COPY Statement
STOP RUN Numeric Statement and
RETURN-CODE Special Register
When a run unit terminates, a numeric value—termed an exit code—is returned to the
operating system. The exit code is made up of the low-order eight bits of the binary
RETURN-CODE special register.
At the start of the run unit, the RETURN-CODE special register is initialized to zero.
The program may change the RETURN-CODE special register value by using it as the
destination of a MOVE statement or arithmetic verb, or by using the “STOP RUN
numeric” form of the STOP RUN statement. Certain program exit codes (as described on
page 7-8) are used by the runtime system to indicate error conditions. Use of these values
should be avoided in the program.
CALL Statement
The CALL statement transfers control to a contained RM/COBOL subprogram, to an
external RM/COBOL subprogram, or to a non-COBOL subprogram. Called subprograms
may themselves call other subprograms during the course of execution.
There are certain regulations that must be observed before RM/COBOL subprograms or
non-COBOL subprograms can be called:
1. The RM/COBOL subprogram must have been compiled.
2. Under UNIX, the non-COBOL subprogram must have been compiled and linked with
the runtime system and must conform with the rules set forth in Appendix D,
Customizing RM/COBOL for UNIX. Under Windows, the non-COBOL subprogram
must be contained in a dynamic link library (DLL) and the non-COBOL subprogram
must conform with the rules set forth in the “Alternate Method of Preparing
Non-COBOL Subprograms Under Windows” appendix in the CodeBridge manual.
3. The name specified in the CALL statement must be complete enough to search for
and locate the program.
A called subprogram is loaded and is in its initial state in the following instances: the first
time it is called in the run unit; the first time it is called after execution of a CANCEL
statement identifying the program that directly or indirectly contains the subprogram;
every time the subprogram is called if it possesses the initial attribute; and the first time
the subprogram is called after the execution of a CALL statement identifying a program
that possesses the initial attribute and that directly or indirectly contains the subprogram.

STOP RUN Numeric Statement and RETURN-CODE Special Register
In all other entries into the called subprogram, the state of that program is unchanged
from its state when last exited.
Called RM/COBOL subprograms remain in memory until implicitly or explicitly

canceled. Under UNIX, since the subprogram is linked with the runtime system, memory
is not recovered. A called subprogram is implicitly canceled in only two cases. A called
subprogram with the initial attribute (that is, one with the INITIAL clause specified in the
PROGRAM-ID paragraph) is implicitly canceled whenever it executes an EXIT
PROGRAM statement, and is therefore in its initial state every time it is called. All
programs associated with a run unit are implicitly canceled when the run unit terminates.
In all other cases, an explicit CANCEL statement identifying the program is required in
order to cancel it.
Subprogram Loading
When a CALL statement is executed, the program name (the value of identifier-1 or
literal-1 as defined in the discussion of the CALL statement in Chapter 1, Language
Structure, of the RM/COBOL Language Reference Manual) determines the subprogram
to which control is transferred. This is done in the following order:
1. If the program name matches the value of program-name or literal as specified

in the PROGRAM-ID paragraph of a program directly contained in the calling
program or of a program possessing the common attribute that is directly contained in
a program that directly or indirectly contains the calling program, control is
transferred to that program.
2. If a program has been loaded and not canceled, and is called again by the same
program name, control is transferred to that program.
3. If the program name matches the value of program-name or literal (see the
RM/COBOL Language Reference Manual) as specified in the PROGRAM-ID
paragraph of a program in an RM/COBOL program library, the program is
loaded and control transferred to it. Remember, at the point of loading, the program
is in its initial state. In the same manner, if the program name matches a called name
literal in a non-COBOL subprogram library (see Appendix D in this user’s guide or
the “Alternate Method of Preparing Non-COBOL Subprograms Under Windows”
appendix in the CodeBridge manual), control transfers to the subprogram associated
with the called name literal.
Libraries—both RM/COBOL and non-COBOL—are searched in the order specified

by the L Runtime Command Option (see page 7-6). The first program name matched
is the only one considered during program loading. Under UNIX, program names
linked in C libraries are searched after all RM/COBOL libraries.

CALL Statement
4. If the program name matches the name of a subprogram in the RM/COBOL
subprogram library, control transfers to that subprogram. See Appendix F,
Subprogram Library, for a description of the RM/COBOL subprogram library.
5. If the program name contains no extension, a default filename extension of first

.cob and then .COB is added to the name before beginning the search for a valid
program file. If such a file exists and contains only one object program, the program
is loaded and control is transferred to that program, regardless of the name in its
PROGRAM-ID paragraph. The default extension can be changed with the
EXTENSION-NAMES configuration record (see page 10-19).
6. Under Windows, if the program name specifies a filename extension .dll—or if it

specifies no filename extension at all—the filename extension .dll is used with the
filename before starting the search for a valid non-COBOL subprogram file. If such
a file exists, it is loaded and control is transferred to that program as described in
Appendix B, Alternate Method of Preparing Non-COBOL Subprograms Under
Windows, of the CodeBridge manual.
7. If the program name does not specify a filename extension, or if the program
name specifies a filename extension other than .dll (under Windows), the program
name is used to search for a valid RM/COBOL program file. If such a file exists, and
contains only one object program, the program is loaded and control is transferred to
it, regardless of the name in its PROGRAM-ID paragraph.
8. If the program name cannot be found, an exception condition occurs. This

condition may be detected by the calling program with the ON EXCEPTION or ON
OVERFLOW phrase. If the calling statement does not contain the ON EXCEPTION
or ON OVERFLOW phrase, execution ends.
Steps 5 through 7 search the environment for a match with the name used in each step. If
an environment variable name matches the name in one of those steps, the value of the
environment variable replaces that name in that step for the purpose of locating the file.
Steps 5 through 7 also use the RUNPATH directory search sequence as described on
either page 2-4 for UNIX or page 3-11 for Windows. RM/COBOL for Windows searches
for dynamic link libraries (DLLs) specified without a drive or path specification in the
following order:
1. The directory from which the application executable was loaded; for example, the
directory containing runcobol.exe.
2. The directory from which the COM server DLL was loaded; for example, the
directory containing rmcblrun.dll.
3. The current working directory.

CALL Statement
4. The Windows System directory (or directories on NT); for example,
c:\windows\system.
5. The Windows directory; for example, c:\windows.
6. The directories listed in the PATH environment variable.
7. The directories listed in the RUNPATH environment variable.
The use of contained programs and program libraries eliminates Steps 5 through 7. In the
case of RM/COBOL program libraries, the I/O overhead of searching for the program file
is minimized.
External Objects
A source program may use the EXTERNAL clause to declare three types of external
objects:
1. Data records, named by record-names
2. File connectors, named by file-names
3. Indexes, named by index-names
See the discussion of the EXTERNAL clause in Chapter 4, Data Division, of the
RM/COBOL Language Reference Manual for more details.
During execution of a run unit, the runtime system maintains a list of external objects.
The list is established as being empty when the run unit begins. When an object program
is loaded, the names of external objects it declares are checked for a match—of both
name and type—against the list of external objects. If both name and type match, the
declared external objects and existing external objects are considered references to the
same object. The declared object is then checked to determine whether it matches the
description of the external object. A mismatch in the description terminates execution
and displays an error message. If either name or type does not match, the declared
external object is allocated and added to the list. If there is not enough memory to load
the object, execution ends and an error message appears.

CALL Statement
The determination of matching descriptions depends on the type of object file:
1. Data Records. The record-name for both objects must be described with the same
number of character positions.
2. File Connectors. The file-name for both objects must be described as follows:
• The file organization specified in the ORGANIZATION clause, that is,

SEQUENTIAL, RELATIVE, or INDEXED, must be the same.
− If the organization is sequential, both objects must agree on the presence or

absence of LINAGE and PADDING CHARACTER.
− If the organization is relative, both objects must declare the same external
data item as the relative key data item, or must omit specification of a
relative key data item.
− If the organization is indexed, both objects must declare the same number of
record keys at the same positions in the record, and must agree on the
presence or absence of a COLLATING SEQUENCE clause. Both objects
must have the same COLLATING SEQUENCE clause, if the clause is
present. In addition, if split keys are present, both objects must have the
same split key clauses.
• The access mode specified in the ACCESS MODE clause must be the same.
• The presence or absence of the OPTIONAL phrase in the SELECT clause of the
file control entry must be the same.
• The number of input-output areas specified in the RESERVE clause must be the
same.
• The alphabet specified in the CODE-SET clause of the file control entry or the
file description entry (RM/COBOL allows the CODE-SET clause in either entry)
must be the same.
• The BLOCK CONTAINS clause in the file description entry must specify the
same minimum and maximum values, and must agree on whether these are
expressed in CHARACTERS or RECORDS.
• The RECORD clause in the file description entry must specify the same
minimum and maximum record size.
• The LABEL RECORDS clause in the file description entry must specify the
same property of OMITTED or STANDARD.

CALL Statement
3. Indexes. The index-name for both objects must be associated with the same external
data record. Both index-names must be associated with table items that span the
same number of character positions.
Note It is recommended that source programs use COPY statements to copy a common
definition of an external object in order to avoid mismatched external object descriptions.
Once an external object is added to the runtime-maintained list, it remains in existence

until the end of the run unit. Execution of a CANCEL statement identifying a program
that describes an external object does not affect the allocation, contents or state of the
external object. For external file connectors left in an open mode, the runtime system
closes the file when the run unit terminates but not when a program describing the file
is canceled.
File Sharing
RM/COBOL supports shared environments1, which allow files to be shared by two
or more users. This includes allowing two or more users to have a file open
simultaneously and apply updates to that file. The FORCE-USER-MODE keyword
of the RUN-FILES-ATTR configuration record (see page 10-28) can force files not to
be shared.
The WITH LOCK phrase may be used on the OPEN statement to restrict the use of a file
by other users during the period the file is open. When used on an OPEN I-O, OUTPUT
or EXTEND statement, the WITH LOCK phrase prevents other RM/COBOL users from
opening the file. When used on an OPEN INPUT statement, the WITH LOCK phrase
prevents other RM/COBOL users from opening the file I-O, OUTPUT or EXTEND.
When the WITH LOCK phrase is used, file performance is improved by eliminating the
overhead of locking records and permitting the buffering of file data in program memory.
Note On UNIX systems in which record locking is implemented through the fcntl()
system call, the file must be available with read/write access to enforce file locking. If the
file is not available with read/write access, the file is opened but file locking is not
enforced.
When the WITH LOCK phrase is absent, file access permits sharing by other users. The
WITH LOCK phrase is ignored in single-user configurations. Table 8-9 illustrates the
sharing permitted between applications in shared environments.
In a shared environment, a sequential file is considered shared if the WITH LOCK phrase
is omitted, even for OPEN OUTPUT and OPEN EXTEND. This permits other users to
OPEN EXTEND the same file and write records at the end of file.

File Sharing
Note RM/COBOL version 5.3 and later runtime systems do not lock program files that
are being executed. Although this characteristic improves performance, under certain
circumstances it can allow the compiler to recompile a program that is being executed at
the time.
Table 8-9 Sharing Permissions
Current Open Mode

1
Desired I-O
Open Input/ Output
1
Mode Input Output Output Extend Input Extend
Input
Input/
Output
Output
Extend
1
Input
1
I-O
Output
Extend
Open granted.
Open denied with I/O error

93,02 or 90,05.
1
WITH LOCK.

File Sharing
File Buffering
Buffering of the data in files can significantly increase the speed of accessing a file by
keeping frequently accessed data in memory buffers instead of reading the data from disk
every time it is needed. RM/COBOL maintains a pool of memory from which it takes the
buffers for all files. When the memory in this pool is exhausted, the memory for buffers
which have not been used recently will be taken from the file that had been using them
and given to the file that needs them. This accommodates applications that open large
numbers of files, but concentrates on only a few files at once.
Sequential and relative files must be opened WITH LOCK in order to make use of more
than one buffer from the buffer pool.
The amount of memory in the buffer pool can be controlled by use of the BUFFER-
POOL-SIZE keyword on the RUN-FILES-ATTR configuration record (see page 10-26).
Increasing the default may improve the performance of the I/O of the application file.
Decreasing the default value can increase the amount of program memory available.
The minimum size of the buffer pool must be adequate for the block sizes of the files
opened by the application. See the description of the BLOCK CONTAINS clause for
indexed files on page 8-53 for more information.
File Types and Structure

There are three types of files supported by RM/COBOL. Each file type and structure is
most useful for specific functions. This section describes each of the following file types:
1. Sequential files
2. Relative files
3. Indexed files

File Buffering
Sequential Files
Sequential files are organized such that records are always read or written serially. In
other words, during a specific I/O operation, the first record read is always the first record
in the file, and the next record written is always written after the last record currently in
the file. RM/COBOL has two types of sequential files:
1. Line Sequential Files. Line sequential files should contain only ASCII text data.
(In other words, they are equivalent to standard source files.) Each logical record
within line sequential files is variable in length and ends with a line feed or carriage
return/line feed pair.
If the ASCII control codes, that is, carriage return (CR), line feed (LF), form feed
(FF) or SUB, are present in a record, the record cannot be written. When reading a
file under UNIX, the LF, CR, FF, LF CR, CR LF, and FF CR sequences terminate a
record. Under Windows, the CR LF sequence terminates a record and leading and
trailing LF and FF sequences are ignored. SUB terminates the file and tab (HT)
causes one or more spaces to be inserted according to the default tab column
positions, which are every four columns, starting with column 8 and ending with
column 72.
The device-name in the ASSIGN clause of the file control entry determines the
treatment of spaces in a line sequential record. If the device-name is DISC, DISK,
or RANDOM, trailing spaces are preserved when a line sequential record is
written. The record length returned when the record is read is the length of the
record when it was written. If the device-name is CASSETTE, INPUT-OUTPUT,
MAGNETIC-TAPE, OUTPUT, PRINT or PRINTER, all trailing spaces are
removed when a record is written to the file. If the device-name is CARD-READER,
CARD-PUNCH, CASSETTE, INPUT, INPUT-OUTPUT or MAGNETIC-TAPE,
records read are padded with spaces to the maximum record length, and the record
length returned is always the maximum record length.
A file that is assigned to either of the device-names PRINT or PRINTER, for which
the LINAGE clause is used, or for which the ADVANCING phrase of the WRITE
statement is used, is always treated as a line sequential file. In this case, ASCII
control codes are allowed.
Each logical record within line sequential files has a maximum record length of
65280 bytes.

2. Binary Sequential Files. Whereas line sequential files contain ASCII text data,
binary sequential files may contain any type of data. Binary sequential files may be
fixed length or variable length.
A fixed-length binary sequential file is one for which only one record description
exists or all record descriptions describe the same number of characters, and for
which no record description contains the OCCURS . . . DEPENDING ON clause, or
for which the RECORD clause specifies fixed-length records. Such files may have a
maximum record length of 65280 characters. Fixed-length binary sequential files are
recorded by RM/COBOL without any additional structure; the byte count implied by
the record length provides data transparency.
A variable-length binary sequential file does not satisfy the record length
requirements for fixed length. The data is encapsulated in an eight-byte overhead to
provide data transparency. The maximum record size for variable-length binary
sequential files is 65280 characters.
Note The compiler listing allocation map indicates in the “Debug” column whether
a file has been described with fixed- or variable-length records. This is described on
page 6-24 and illustrated in Figure 6-6.
RECORD Clause (File Description Entry)
The RECORD clause specifies the minimum and maximum lengths of records in a
sequential file. The minimum and maximum record lengths are not recorded with the file;
however, a READ statement encountering a record whose length is less than the minimum
record length receives an error. Also, an OPEN EXTEND for a fixed-length binary
sequential file succeeds only if the total file size at the time of the OPEN is a multiple of
the maximum record length of the file.
BLOCK CONTAINS Clause (File Description Entry)
In a single-user environment, sequential disk files are physically read and written in fixed
length pieces called blocks. In a shared environment, sequential files are read and written
in blocks only when the WITH LOCK phrase is specified. When the WITH LOCK
phrase is omitted, the records of the file are read or written individually (without
blocking) from the operating system.
The size of a block is determined by the BLOCK CONTAINS clause in the

RM/COBOL program. A larger block size causes more data to be transferred in a single
request, requires more time to effect the data transfer, reduces the total number of disk
accesses, and requires more memory from the buffer pool. Blocking in this fashion may
increase performance; however, because blocking may defer the physical writing of a
block to disk until well after the WRITE statement that first places data in the block,

errors (which can include loss of data) caused by that physical write may not be reported
until a subsequent WRITE or CLOSE statement for the file is executed.
The file block size is not considered a fixed attribute of a sequential file; different
programs may specify different block sizes for the same file.
The runtime system uses the following algorithm to determine the block size when
opening a sequential disk file:
1. If no BLOCK CONTAINS clause is present, the block size is 4096 characters. The
default block size may be changed with a RUN-SEQ-FILES configuration record
(see page 10-34).
2. If a BLOCK CONTAINS nnn CHARACTERS clause is present, the block size is the
specified number of characters.
3. If a BLOCK CONTAINS nnn RECORDS clause is present, the block size is the
specified number of records multiplied by the sum of the maximum record length and
the record overhead.
The maximum allowed block size on most systems is 65535 characters.
LINAGE Clause (File Description Entry)
When a file described with the LINAGE clause is opened for output, it is assumed the
output device is already positioned to the first line of the first logical page body. This is
the operator's responsibility. The program should be written to allow the operator an
opportunity to adjust the forms in the printer (or any other output device) as required.
As an alternative, the LINAGE-INITIAL-FORM-POSITION keyword in the

PRINT-ATTR configuration record may be set to the value TOP-OF-FORM. In this
case, which is particularly useful for page printers, it is assumed that the output device is
positioned at the top of the form. When the first record is written to the file, the record
will be written after advancing over the top margin on the first logical page. The
LINAGE-INITIAL-FORM-POSITION keyword is further described on page 10-21.
The logical pages of a file described with the LINAGE clause are normally
written contiguously with no additional spacing provided between pages. The
LINAGE-PAGES-PER-PHYSICAL-PAGE keyword in the PRINT-ATTR configuration
record may be used to cause physical page breaks, such as form feed characters, to be
written to the file. The LINAGE-PAGES-PER-PHYSICAL-PAGE keyword is further
described on page 10-22.

RESERVE Clause (File Control Entry)
The RESERVE clause is ignored. Buffer memory is automatically managed based on the
amount of activity of a particular file. See “File Buffering” on page 8-40.
CODE-SET Clause (File Control Entry or File Description Entry)
The CODE-SET clause determines the character set used to represent the sequential file.
For example, if the CODE-SET is EBCDIC, all records written to the file are translated
from ASCII to EBCDIC. The CODE-SET is not considered a fixed attribute of the
sequential file. Different programs may specify different character sets for the same file.
REVERSED Phrase (OPEN Statement)
The REVERSED phrase is not supported. If specified, it is ignored.
WITH NO LOCK Phrase (READ Statement)
If a READ statement without the WITH NO LOCK phrase fails because the record is
locked, the contents of the record area are undefined and the file position indicator is
unchanged. A subsequent READ behaves as if the failing READ statement had never
been issued.
A READ statement with the WITH NO LOCK phrase may be used to read a record
without regard to the lock status of the record. If an OPEN INPUT statement opened the
file, the WITH NO LOCK phrase is assumed on all READ statements on the file.
If the file control entry does not contain a FILE STATUS clause or there is no USE
declarative procedure defined for a file, record lock status is not reported to the program.
Instead, the runtime system waits for the record to become unlocked. By using the
FATAL-RECORD-LOCK-TIMEOUT keyword in the RUN-FILES-ATTR configuration
record (see page 10-27), the runtime system can be made to return a fatal error instead of
waiting indefinitely. If the record is locked using a different file descriptor in the same
run unit, then the runtime system never waits. Instead, to prevent a deadlock situation, it
returns an error indicating that the record is locked.
If the file control entry does contain a FILE STATUS clause and there is a USE
declarative procedure defined for a file, the record lock status is normally reported to the
program immediately by calling the USE procedure. By using the USE-PROCEDURE-
RECORD-LOCK-TIMEOUT keyword in the RUN-FILES-ATTR configuration record
(see page 10-30), the runtime system can be told how long to wait before calling the USE
procedure. If the record is unlocked during this time, the USE procedure is not called.

ADVANCING ZERO LINES Phrase (WRITE Statement)
As explained in the discussion on the WRITE statement in Chapter 6, Procedure Division

Statements, of the RM/COBOL Language Reference Manual, WRITE statements acting
on sequential files allow overprinting on a line for systems whose physical devices
support this feature. However, some line printers are designed to advance one line after
each line is printed. In such a case, the ADVANCING ZERO LINES phrase is treated as
an ADVANCING 1 LINE phrase.
ADVANCING mnemonic-name Phrase (WRITE Statement)
RM/COBOL allows the WRITE . . . ADVANCING mnemonic-name statement when

mnemonic-name is associated with a channel-name from the SPECIAL-NAMES
paragraph. No standard way exists to communicate channel slewing information.
Because of this, the runtime system interprets C01 as if page were specified; it interprets
any other channel as if 1 LINE were specified.
REEL and UNIT Phrases (CLOSE Statement)
The REEL and UNIT phrases are not supported. If specified, they are ignored.
WITH NO REWIND Phrase (CLOSE Statement)
A print file is released to the operating system at run unit termination or when a CLOSE
statement (without the WITH NO REWIND phrase) is issued.
The WITH NO REWIND phrase may be used to prevent the release of a print file to the
operating system. This feature may be used to prevent undesirable side effects such as
banner pages and form feeds provided by the operating system when the print file is
released.
A subsequent OPEN statement (typically, OPEN EXTEND) must be issued before the
print file can again be successfully accessed by the program.
A print file is a line sequential file that has any or all of the following RM/COBOL source
program features:
1. ASSIGN TO PRINT or ASSIGN TO PRINTER clause in the file control entry for
the file.
2. LINAGE clause in the file description entry for the file.
3. ADVANCING phrase in a WRITE statement for the file.
For all other file types, the WITH NO REWIND phrase is ignored.

Device Support
Files that are opened on devices are treated as read-only (INPUT) or write-only
(OUTPUT or EXTEND) sequential files. A program may open the same device more
than once within the same run unit. Those devices that are opened with the same mode
(read-only or write-only) share the same file handle and the same buffer. Those devices
that are opened with different modes use different file handles and have different buffers.
At most, two buffers are allocated to each device; one when opened for read-only and one
when opened for write-only. These buffers are dedicated to the device and do not come
from the buffer pool.
Because of the non-portability of applying locks to devices, locks are never applied to
device files. Thus, files opened on devices WITH LOCK do not guarantee exclusive
access to the file.
Printer Support
Under UNIX, printer support is provided either through the lp or the lpr spooler. Under
Windows, RM/COBOL provides printer support using the Windows printer devices.
Under UNIX, the RM/COBOL runtime system creates a write-only pipe to the print
spooler and sends all print records to it. The pipe is closed and the output is allowed to
print only when the RM/COBOL program issues a CLOSE statement to the file (except
for CLOSE WITH NO REWIND, as explained previously).
Under Windows, when a file is opened with the name PRINTER, the output is sent to the
default system printer configured under the Windows operating system. When a file is
opened with the name PRINTERx, where x is a single-digit number, output is sent to the
device connected to LPTx.
The device is opened for writing only and is closed only when the RM/COBOL program
issues a CLOSE statement to the file (except for CLOSE WITH NO REWIND, as
explained previously).
The destination for files named PRINTER can be changed by assigning an environment
variable PRINTER (see the discussion of file access names that begins either on page 2-5
for UNIX or page 3-13 for Windows), by defining a synonym in the Windows registry
(see page 3-29), or by configuring a keyword in the DEFINE-DEVICE record (see
page 10-16).

Tape Support
Under UNIX, RM/COBOL provides tape support through direct access to the tape
devices. When a file is opened with the name TAPE, the RM/COBOL runtime system
opens the tape device and writes or reads to it as directed by the RM/COBOL program.
The tape device is closed when the RM/COBOL program issues a close to the file except
for CLOSE WITH NO REWIND. Since the operating system does not provide a
mechanism to write a tape mark to a tape without closing the device (which may rewind
it), the RM/COBOL runtime system only simulates the close as it does for the printer
device.
Most systems allow multiple files to be placed on a tape by specifying that the tape is not
to be rewound on OPEN and CLOSE. This must be specified at the OPEN of the file by
using the correct name for the operation. For example, rtpyy may mean rewind on OPEN
and CLOSE while rtpyn may mean rewind on OPEN but not on CLOSE. (Actual names
vary between implementations. Consult your system administrator for the actual names.)
If it is desired to place multiple files on a single tape, it will be necessary to use
DEFINE-DEVICE configuration records to name the different options desired and use
the names within the RM/COBOL program appropriately.
All sequential record formats are supported on the tape: line, binary fixed, and binary
variable-length records. For transfer of information to other RM/COBOL programs, any
method may be used. For transferring information to other programs executing on other
equipment, fixed-length binary records are most compatible.
The destination for files named TAPE can be changed either by assigning an environment
variable TAPE as explained in the discussion of file access names that begins on
page 2-5, or by using a DEFINE-DEVICE configuration record as explained in the
discussion that begins on page 10-16.
Named Pipe Support
Under UNIX, named pipes are treated as sequential devices. They are allowed to be
opened as INPUT, OUTPUT or EXTEND, but never I-O. Also, as with the other
devices, OPEN WITH LOCK does not guarantee exclusive access to the pipe.
Relative Files
Relative files are ordered collections of records, each of which is directly addressable by
use of a relative record number; this number is a non-zero integer corresponding to the
ordinal position of a record within the file. A record within a relative file acquires its
record number when it is written to the file with a WRITE statement.

If the access mode of the file at the time the record is written is sequential, the record
number is assigned by the runtime system, and is one greater than the last record number
assigned (or 1 if no records have been written to the file). If the access mode is random
or dynamic, specify the record number before execution of the WRITE statement. To do
this, move (or otherwise assign) the value to the data item declared to be the relative key
for the file.
Record numbers do not necessarily correspond to actual records in a file. For instance, a
record number may never have been given a corresponding data record, or some numbers
may correspond to data records that have been deleted.
Relative files must be assigned to a disk device, since the records can be accessed
randomly.
The maximum record length is 65280 bytes. Records can be variable length. No
restrictions are placed on the value of individual bytes within the record.
Records in a relative file are written to disk in a fixed-length area four bytes longer than
the length of the longest record declared for the file. Estimate the total disk space
requirement by multiplying the maximum record length plus four by the anticipated
number of records.
The RECORD clause specifies the minimum and maximum record lengths of records in a
relative file. The maximum record length is a fixed attribute of the file, and is validated
against the file size during an OPEN statement.
The minimum record length is not recorded with the file; however, a READ statement
encountering a record whose length is less than the minimum record length will receive an
error. A REWRITE statement may change the record length of a record in a
relative file.
In a single-user environment, relative files are physically read and written in fixed-length
pieces called blocks. In a shared environment, relative files are read and written in blocks
only when the WITH LOCK phrase is specified. When the WITH LOCK phrase is
omitted, the records of the file are read or written individually (without blocking) from
the operating system.
The size of a block is determined by the BLOCK CONTAINS clause in the

RM/COBOL program. A larger block size causes more data to be transferred in a single
request, requires more time to effect the data transfer and requires more memory from the

buffer pool. A smaller block size allows more blocks in memory for a fixed amount of
memory. Blocking may increase performance; however, because blocking may defer the
physical writing of a block to disk until well after the WRITE statement that first places
data in the block, errors (including loss of data) caused by that physical write may not be
reported until a subsequent statement for the file is executed.
The file block size is not considered a fixed attribute of a relative file. Different programs
may specify different block sizes for the same file.
The runtime system uses the following algorithm to determine the block size when
opening a relative file:
1. If no BLOCK CONTAINS clause is present, the block size is typically 4096

characters if the file is opened for DYNAMIC or SEQUENTIAL access. The default
block size may be changed with a RUN-REL-FILES configuration record (see
page 10-34).
2. If a BLOCK CONTAINS nnn CHARACTERS clause is present, the block size is the
specified number of characters.
3. If a BLOCK CONTAINS nnn RECORDS clause is present, the block size is the
specified number of records multiplied by the sum of the maximum record size, plus
four. The maximum allowed block size on most systems is 65489 characters.
The RESERVE clause is ignored. Allocating buffer memory is automatically managed

based on the amount of activity of a particular file. See “File Buffering” on page 8-40.
The CODE-SET clause determines the character set used to represent the relative file
on disk. For example, if the CODE-SET is EBCDIC, all records written to the file will be
translated from ASCII to EBCDIC. The CODE-SET is not considered a fixed attribute of
the relative file. Different programs may specify different character sets for the same file.
A READ statement with the NEXT phrase and without the WITH NO LOCK phrase that
fails because the record to which the file position indicator points is locked, does not
modify the file position indicator and the contents of the record area are undefined. The
record is not read and the program should not depend on the contents of the record area
being unchanged. A subsequent READ statement behaves as if the failing READ
statement had never been issued.

declarative procedure defined for a file, the record lock status is normally reported to the
program immediately by calling the USE procedure. By using the USE-PROCEDURE-
RECORD-LOCK-TIMEOUT keyword in the RUN-FILES-ATTR configuration record
(see page 10-30), the runtime system can be told how long to wait before calling the USE
procedure. If the record is unlocked during this time, the USE procedure is not called.
Indexed Files
Indexed organization files contain data and one or more indexes or keys. These indexes
are used to locate data in the file by identifying the key value and the location in the file
of the corresponding record.
Every record in an indexed file contains a prime record key and may contain a number of
alternate record keys.
Data Compression
Each record of the file may be represented in a compressed or uncompressed data format.
Data record compression replaces multiple occurrences of space, zero and null or
repeated characters with a single compression character. Uncompressed data records
contain the data written by the program, with no compression characters. Data record
compression almost always improves the performance of indexed files by reducing the
file size and allowing more information to be read in a single physical transfer. When an
indexed file is created by the runtime system, data record compression is enabled. This
default may be changed as described on page 10-31. Whether data record compression is
enabled for a particular file may be established with the Define Indexed File utility
(rmdefinx), described in the discussion that begins on page G-19.
RM/COBOL indexed files allow index keys to be compressed or uncompressed. Key

compression replaces the leading characters of a key that equal the preceding key, and

any trailing space characters of a key, with compression characters. This usually reduces
the amount of disk space occupied by a file, especially a file in which many keys contain
trailing spaces (such as names and addresses). When an indexed file is created by the
runtime system, key compression is enabled. This default may be changed as described
on page 10-32. Whether key compression is enabled for a particular file may be
established with the rmdefinx.
Data Recoverability
RM/COBOL provides a choice of data recovery strategies for indexed files. A data
recovery strategy is a tradeoff between deferring the writing of data to disk in order to
improve the performance of file modification operations, and forcing the writing of data
to disk in order to guarantee that the data is available for recovery if there is a system
failure. The data recovery strategy for a particular indexed file is determined when the
file is first opened OUTPUT or when the file is predefined. The file may be predefined
using the Define Indexed File utility (rmdefinx) described on page G-19. If the file is not
predefined, the default recovery strategy is used by the runtime system. This default
strategy may be configured as described in the discussion of the RUN-INDEX-FILES
configuration record beginning on page 10-31. Unlike other attributes associated with an
indexed file, the recovery strategy for a file may be changed, thus allowing optimal
performance when a file is being built and switching to a higher level of data integrity
when a file is updated. Use the Define Indexed File utility (rmdefinx) to change the
recovery strategy for a file.
The following four options are available to provide the various levels of data recovery
strategy:
1. Force File Closed (FORCE-CLOSED keyword). The indexed file header contains
a count of the number of concurrent run units that have the file open for modification.
If the system fails while this count is non-zero, the file index structure must be rebuilt
using the Indexed File Recovery utility (recover1). (See the discussion of the
“Indexed File Recovery Utility (recover1)” that begins on page G-23.) Selecting this
option causes the runtime system to increment this count before each DELETE,
REWRITE or WRITE operation and decrement the count at the end of each
operation. Otherwise, the count will be incremented when the OPEN statement is
executed and decremented when the CLOSE statement is executed.
Selecting this option causes two additional disk transfers for each modify operation,
but gives a high probability that a file rebuild will not be required if a system failure
occurs.
Selecting this option causes the runtime system to act as if the following three options
are also set.

2. Force Disk (FORCE-DISK keyword). Your operating system maintains a system
disk buffer pool in its memory. Issuing an operating system write request, as
described below in the Force Data option, causes data to be written from the buffer
maintained by the runtime system to a buffer in this disk buffer pool. The data is not
necessarily written to the disk at that time. Thus, the selected data recovery strategy
may be defeated.
Selecting this option causes the runtime system to attempt to force the operating
system to actually write its buffer to disk.
3. Force Data (FORCE-DATA keyword). Selecting this option causes the runtime
system to issue a write request to the operating system when a block containing a data
record is modified. Otherwise, such blocks remain in the block buffer pool
maintained by the runtime system for the file, and the write request to the operating
system is not made until the buffer containing the block is needed for a different
block.
This option is available only when a file is in single-user mode, that is, when the
runtime system is in single-user mode or the file is opened WITH LOCK. This
option is always selected for files in a shared environment.
4. Force Index (FORCE-INDEX keyword). Selecting this option causes the runtime
system to issue a write request to the operating system when a block containing index
information is modified. Otherwise, such requests are issued only as buffer
availability in the block buffer pool maintained by the runtime system dictates. This
option is always selected for files in a shared environment.
The RECORD clause specifies the minimum and maximum length of records in an
indexed file. These record lengths are considered fixed attributes of the file. Any
program using an indexed file must specify the minimum and maximum length specified
in the program that created the file.
The following algorithm computes the maximum disk space required to represent a
record:
1. Assume the record representation disk space is the maximum record size of the file.
2. If data record compression is enabled, increase the record representation space by the
ceiling of the maximum record size divided by 127.
3. Increase the record representation space by four times the number of alternate keys
that allow duplicates.
4. Add four to the record representation disk space.

RM/COBOL indexed files are restricted both in the maximum record size declared in the
program and in the maximum disk space required to represent a record. The maximum
record size allowed an indexed file is 65280. The maximum disk space required to
represent a record must not exceed 65527. The disk space limitation is the more
restrictive, especially when data record compression is enabled.
RM/COBOL indexed files are physically read and written in fixed-length pieces called
blocks. The size of a block is determined by the BLOCK CONTAINS clause in the
RM/COBOL program, or with the Define Indexed File utility (rmdefinx) (see
page G-19). A larger block size transfers more data in a single request, requires more
time to effect the data transfer, and requires more memory from the buffer pool. A
smaller block size allows more blocks in memory for a fixed amount of memory, but
requires more time to randomly access a record by increasing the depth of each index.
The file block size is considered a fixed attribute of the file. The BLOCK CONTAINS
clause in a program that uses a file must be identical to the BLOCK CONTAINS clause in
the program that created the file.
To access a block of an indexed file, the runtime system must use a piece of the buffer
pool memory that is at least as large as the file block size. The indexed file algorithms
require that a minimum of three pieces of buffer pool memory be available. If the file
block size exceeds 32768, the buffer pool must be at least as large as the sum of 131072
and the block size. If the file block size exceeds 16384, the buffer pool must be at least as
large as the sum of 65536 and the block size.
The algorithm used to determine the block size of an indexed file is outlined in the
following paragraphs. The algorithm distinguishes specified block size from actual block
size. Specified block size is defined by the BLOCK CONTAINS clause, and may be a
function of the maximum disk space required to represent a record, defined previously in
the RECORD clause description. Actual block size is defined as a function of the
specified block size. When the term block size is used by itself elsewhere in this
document in reference to an indexed file, it means the computed actual block size.
1. If no BLOCK CONTAINS clause is present, and the file already exists, the current
block size is used as the block size.
2. If no BLOCK CONTAINS clause is present, and the file does not already
exist, assume the block size is 512. This default may be changed with a
RUN-INDEX-FILES configuration record (see page 10-31).
3. If a BLOCK CONTAINS nnn CHARACTERS clause is present, the specified block
size is the number of characters.

4. If a BLOCK CONTAINS nnn RECORDS clause is present, the specified block size
is eight characters more than the specified number of records multiplied by the
maximum disk space required to represent a record, as described above.
5. The actual block size chosen is the lowest multiple of the specified block size that
meets the following criteria:
a. The actual block size must be at least 256.
b. The actual block size must be at least 292 if an enumerated CODE-SET or
COLLATING SEQUENCE is specified.
c. The actual block size must be sufficient to contain three index keys. This is
approximately the longest key length times 3 plus 46.
d. The actual block size must be sufficient to contain one data record. This
minimum is eight characters more than the maximum disk space required to
represent a single record, as described above. If the record described in the FD
will not fit in the block size determined by the preceding rules, then the block
size is rounded up to the next multiple of the default block size.
6. If the computed actual block size does not meet all the following restrictions, the
indexed file description is invalid and the file cannot be opened:
a. The actual block size must not exceed 65489.
b. If key entries are compressed, the actual block size must not exceed 65499 less
four times the length of the longest key. If no alternate record key allows
duplicates, the limit is 65515 less four times the length of the longest key.
c. If key entries are uncompressed, the actual block size must not exceed 65526,
less the length of the longest key. If no alternate record key allows duplicates,
the limit is 65530, less the length of the longest key.
The RESERVE clause is ignored. Buffer memory is automatically managed based on the
amount of activity of a particular file. See “File Buffering” on page 8-40.
The CODE-SET clause determines the character set used to represent the indexed file on
disk. For example, if the CODE-SET is EBCDIC, all records written to the file will be
translated from ASCII to EBCDIC. The CODE-SET specified when an indexed file is
created is a permanent attribute of the file, and will be used whenever the file is accessed
by a program not specifying a CODE-SET. However, a program may specify a different

CODE-SET than that used to create the file, and that code set will be used for the duration
of the program.
COLLATING SEQUENCE Clause (File Control Entry)
The COLLATING SEQUENCE clause allows a program to determine the collating

function used when comparing keys in an indexed file (for example, whether uppercase
and lowercase letters are to be treated identically). The collating function specified when
an indexed file was created is a fixed attribute of the file. If a program opening an
indexed file specifies a COLLATING SEQUENCE clause, the specified collating
function must be identical to that specified when the file was created.
A READ statement with the NEXT phrase and without the WITH NO LOCK phrase that
fails because the record is locked does not modify the file position indicator and the
contents of the record area are undefined. The record is not read and the program should
not depend on the contents of the record area being unchanged. A subsequent READ
statement will behave as if the failing READ statement had never been issued.
declarative procedure defined for a file, the record lock status is normally
reported to the program immediately by calling the USE procedure. By using the
USE-PROCEDURE-RECORD-LOCK-TIMEOUT keyword in the RUN-FILES-ATTR
configuration record (see page 10-30), the runtime system can be told how long to wait
before calling the USE procedure. If the record is unlocked during this time, the USE
procedure is not called.

File Allocation
As an indexed file grows in size, the runtime system allocates additional blocks to the file.
The number of blocks allocated is determined by the allocation increment. The default
allocation increment is eight blocks; a different allocation increment may be set with the
Define Indexed File utility (rmdefinx). A larger allocation increment may improve
performance when writing records to the file, by reducing the number of operating system
allocation requests. A smaller allocation increment may yield less wasted space.
Unused blocks in an indexed file are kept on the empty block list. The format of this list
is determined by the file version number. Beginning with file version number 2, a new
list format and algorithm are used to maintain the empty block list in order to increase
performance when adding records to the file. This new algorithm keeps track of the first
unused empty block in the file, which is followed only by other unused empty blocks, and
avoids reading those blocks from the disk when they are used. New files are created with
a version number of 2, although this default can be changed with the DEFAULT-FILE-
VERSION-NUMBER configuration keyword (see page 10-31). The version number can
also be changed on existing files or set when creating new files with the Define Indexed
File utility, rmdefinx (see page G-19).
When a file version number is set to 2, the minimum write version number of the file is
also set to 2 in order to prevent previous versions of RM/COBOL from attempting to
modify the empty block list. The minimum read version number of the file is not
changed. Files with a version number of 2 can be read but not modified by versions of
RM/COBOL prior to version 6. If an OPEN OUTPUT is performed on a file with
version number of 2 by a runtime system prior to version 6, the file version number and
minimum write version number will be reset to 0, and the previous style of the empty
block list will be used.
File Size Estimation

Use the following formulas to set upper and lower bounds on the number of characters
that are required. Of course, with record data compression and key compression, the
actual disk space required for records and keys varies greatly with the contents of the
records.
In these formulas, “ceiling” means rounding up and “floor” means rounding down.
For example:
7.145
has a ceiling of 8 and a floor of 7.
Variables - A = allocation increments in blocks
B = block size in bytes
Kn = length of nth key in bytes
MaxL = maximum record size

MinL = minimum record size
N = number of keys
Nd = number of keys that allow duplicates
R = number of records
Subtotals - H = 1
H = H + 2 if code-set is enumerated
H = H + 1 if collating sequence is enumerated
If N > floor ((B - 256)÷36) then

H = H+ceiling((N-((B-256)÷36))÷((B-6)÷36))
If records are compressed:

MaxD = ceiling(R÷(floor((B-8)÷(MaxL+4+
(4*Nd)+ceiling(MaxL÷127)))))
MinD = ceiling(R÷(floor((B-8)÷(ceiling
(MinL÷65)+4+(4*Nd)))))
If records are uncompressed:

MaxD = ceiling(R÷(floor((B-8)÷
(MaxL+4+(4*Nd)))))
MinD = ceiling(R÷(floor((B-8)÷
MinL+4+(4*Nd)))))
For each key n, 0 through N-1:

TOn = 4
TOn = TOn+4 if key n allows duplicates
If key compression is enabled:

TOn = TOn+2
MaxTEn = floor((B-10)÷TOn)
MinTEn = floor((B-10)÷(2*(TOn+Kn)))
MaxLEn = floor((B-10)÷(TOn+1))
MinLEn = floor((B-10)÷(2*(TOn+Kn+1)))
If key compression is not enabled:

MaxTEn = floor((B-10)÷(TOn+Kn))
MinTEn = ceiling(MaxTEn÷2)
MaxLEn = floor((B-10)÷(TOn+Kn+1))
MinLEn = ceiling(MaxLEn÷2)
For each key n:

MaxLBn = ceiling(R÷MinLEn)
MinLBn = ceiling(R÷MaxLEn)
MaxTHn = ceiling(Log10(MaxLBn)÷Log10(MinTEn))
MinTHn = ceiling(Log10(MinLBn)÷Log10(MaxTEn))
MaxWn = ceiling(MaxLBn÷(MinTEn**(MaxTHn-1)))
MinWn = floor(MinLBn÷(MaxTEn**(MinTHn-1)))
MaxTBn = 1+MaxWn*(((MinTEn**
(MaxTHn-1))-1)÷(MinTEn-1))
MinTBn = 1+MinWn*((MaxTEn**
(MinTHn-1))-1)÷(MaxTEn-1)
Totals - MaxFB = H+MaxD+Sum(MaxLBn+MaxTBn)

MinFB = H+MinD+Sum(MinLBn+MinTBn)
MaxSize = (A*ceiling(MaxFB÷A))*B
MinSize = (A*ceiling(MinFB÷A))*B

For example, suppose a single key indexed file of 2000 records is written. Every record
is 100 bytes long. The prime record key is 15 bytes. Assume a default block size of 512
bytes, allocation increment of 8 blocks, the default compression state, and that key
compression and record compression are enabled. No code-set or collating sequence
is specified.
Variables - A = 8
B = 512
K0 = 15
MaxL = 100
MinL = 100
N = 1
Nd = 0
R = 2000
Subtotals - H = 1
MaxD = ceiling(2000÷(floor((512-8)÷(100+
4+(4*0)+ceiling(100÷127)))))
= 500
MinD = ceiling(2000÷(floor((512-8)÷
(ceiling(100÷65)+4+4(4*0)))))
= 24
TO0 = 4
TO0 = 4+2
= 6
MaxTE0 = floor((512-10)÷6)
= 83
MinTE0 = floor((512-10)÷(2*(6+15)))
= 11
MaxLE0 = floor((512-10)÷(6+1))
= 71
MinLE0 = floor((512-10)÷(2*(6+15+1)))
= 11
MaxLB0 = ceiling(2000÷11)
= 182
MinLB0 = ceiling(2000÷71)
= 29
MaxTH0 = ceiling(Log10(182)÷Log10(11))
= 3
MinTH0 = ceiling(Log10(29)÷Log10(83))
= 1
MaxW0 = ceiling(182÷(11**(3-1)))
= 2
MinW0 = floor(29÷(83**(1-1)))
= 29
MaxTB0 = 1+2*(((11**
(3-1))-1)÷(11-1))
= 25
MinTB0 = 1+29*((83**
(1-1))-1)÷(83-1)
= 1

Totals - MaxFB 1+500+(182+25)
= 708
MinFB = 1+24+(29+1)
= 55
MaxSize = (8*ceiling(708÷8))*512
= 364544
MinSize = (8*ceiling(55÷8))*512
= 28672
This file will require between 28672 and 364544 bytes, depending on the contents of the
records and the order in which the records are written. Since, in most cases, the key and
data compression will save much less than all the bytes in the keys and records, the actual
file size will probably be nearer to the maximum size than to the minimum size.
Temporary Files
The sort-merge facility of RM/COBOL makes use of temporary files for its intermediate
sort files. These files are given unique names and are placed in the current directory and
the current disk drive.
The choice of the directory in which to place the temporary files under Windows may be
changed by use of the environment variables TMP or TEMP. If both variables are set, the
value of TMP is used. Assign the environment variable a value before executing the
RM/COBOL program. Under Windows, a synonym may be set in the registry database.
Under UNIX, the TMPDIR environment variable is used.
Indexed File Performance

RM/COBOL indexed files contain data records and indexes to these data records. The
index structure is based on B+ trees, described by D. E. Knuth and others. The index for
each record key is maintained as a separate tree in the file. Each tree consists of nodes
that contain key values and pointers to records or to other nodes. If an index node can
contain N keys and pointers, a file of N or fewer records can be indexed by a single node.
A file containing N*N records may be indexed by two levels of nodes, a root node of N
entries pointing to N leaf nodes, each leaf node containing N entries pointing to records.
Each random access to an indexed file requires that the entire index tree be traversed from
the root node through any intermediate nodes to the leaf node and finally to the desired
data record. Write operations to a file require adding the data record to the file, adding
each key of the record to the appropriate index tree, possibly creating new leaf and
intermediate nodes, or even creating a new root node and increasing the height of the
index tree.

Temporary Files
Since modifications to an indexed file require updating the index tree for each key added,
changed, or deleted, one way to improve performance is to reduce the number of record
keys. An application may use an index key to rapidly find a particular record. Some
applications use record keys simply to sort records for report generation. If a record key
is used only to access records in a particular order when generating a report, consider
removing that record key and sorting the records with the SORT verb when the report is
generated. Not only will this reduce the number of disk operations by using the more
efficient sort algorithm, but it will also perform the operations only when the report is
requested. When an index key is used to select a subset of the file’s records for a report,
the same selection can be performed with a SORT INPUT PROCEDURE.
The index tree manipulation algorithms are designed to keep each index node at least half
full of entries. When records are written in ascending order by key, the algorithms can
completely fill each index node with entries, reducing both the tree height and the size of
the file. This improves performance by reducing both the number of disk operations and
the required arm movement for the operations performed. If a file is infrequently
modified, it should be built in ascending order by the key most frequently used to access
the records.
In-Memory Buffering
Disk operations can be reduced by keeping file fragments in memory as long as possible.
Subsequent accesses to the same information use the copy in memory instead of rereading
the information from disk. This technique of in-memory buffering of data is the single
most effective method of improving performance.
RM/COBOL files offer two levels of in-memory buffering of data: buffering by the
operating system and buffering by the runtime system. A combination of the two seems
to yield the best performance. Both UNIX and Windows provide buffering automatically.
Additional memory may be dedicated to the buffering of disk data by further increasing
the number of operating system buffers, or by increasing the size of the memory pool that
the runtime system uses for disk buffers. The size of the memory pool may be increased
through use of the BUFFER-POOL-SIZE keyword on the RUN-FILES-ATTR
configuration record (see page 10-26).
Runtime system disk buffers, like the operating system buffers, are shared among all files
opened by an application. Runtime system buffering is especially useful in a network
environment. When a file is shared over a network, the operating system is unable to
perform any buffering. Every WRITE operation must be sent to the remote machine and
every READ operation must receive the data from the remote machine. With runtime
system buffering of index files, at the beginning of each operation the runtime system
determines which buffers still contain valid data and which contain data that may have
been modified by an application on another machine. This significantly reduces the

number of remote READ operations required (although all modified data must still be
written to the remote machine).
Providing sufficient space in the buffer memory pool can supply the runtime system with
enough buffers to work efficiently.
The optimal number of buffers for a particular file depends on the operations being
performed and the height of each index tree. The height of the index trees for a particular
indexed file may be obtained with the Map Indexed File utility (rmmapinx), described on
page G-14. If a file is being read randomly by only a single key, the minimal number of
buffers that will improve performance is the height of the particular key’s index tree, plus
one. Fewer buffers than this number require that all index nodes be read for each
operation. Increasing the number of buffers above this minimum increases the probability
that needed nodes already will be in memory. WRITE operations require that every key
be updated. It is desirable that the number of buffers available be greater than the sum of
the heights of all trees. Short of this number, buffers equal to the height of the tallest tree
plus one should be available. Again, increasing the number of buffers above the
minimum increases the probability that required nodes will already be in memory.
Once the desired number of buffers is known, the amount of space to allocate in the buffer
pool can be computed by using the following calculations:
N = Desired Number of Buffers

BSz = Size of Buffer1
NBSeg = Number of Buffers per Segment = INT(65496/BSz)
NSeg = Number of Segments = INT(N/NBSeg)
PSz = Pool Size = NSeg*65496 + (N – NSeg*NBSeg)*BSz
If more than one file is expected to be active at the same time, the computed Pool Size
(PSz) for the files usually can be added together, especially if the files have the same
buffer size. (In fact, if the files have the same buffer size, it is best to add the number of
desired buffers together and make the calculation using that number.) However, if the
files have different buffer sizes and the difference between the buffer size and the block
size of the file having the larger buffer size is greater than the buffer size of another active
file, the amount of space required will be less than the sum of the separate buffer pool size
calculations for the two files. (Recall that the buffer size is computed from the block size
rounded to the next power of two. Not all that space, however, is in use by the buffer;
only the block size rounded up to the next multiple of 512. The remainder is available for
use by other buffers.)
_____________________
1
The size of the buffer (Bsz) is computed by rounding the block size up to the next power of two. If this is
less than 512, use 512 instead.

Altering the Size of Indexed File Blocks
RM/COBOL indexed files are accessed in fixed size fragments called blocks. The size of
these blocks is determined by the application with the BLOCK CONTAINS clause. The
default block size is the smallest multiple of the disk sector size sufficient to contain one
record or an index node. In general, this default block size is also the optimal choice.
Although larger block sizes allow more entries in an index node and thus reduce the
height of the index trees, this reduction in height is usually not sufficient to compensate
for the reduced number of buffers available. Doubling a file’s block size usually reduces
the height of the trees by much less than a factor of 2. This means that if the memory
available for buffers is just sufficient to contain the height of the tree at the smaller block
size, it will no longer be sufficient at the larger block size. If there is insufficient memory
even with a block size of only one sector for the desired minimal number of buffers
discussed above (for example, the sum of the heights of the index trees when write
operations are performed), a larger block size may improve performance. If the
application does choose a block size greater than the default, this block size should still
be a multiple of the disk sector size; otherwise, whenever a block is written, the operating
system must read a sector of the disk, modify the block data in the sector, and rewrite the
sector to disk.
Controlling the Length of Record Keys

The length of record keys affects indexed file performance by affecting the height of the
index trees. Each index node consists of as many pairs of keys and pointers as fit in a
block. A longer key means fewer entries, and increases the number of disk operations.
Key length is especially significant if uncompressed keys are requested. When key
compression is enabled for a file, leading characters in an entry that duplicate the
preceding entry and trailing space characters are removed. This reduces the node entry to
its significant characters, reducing an entry whose key is equal to its preceding entry to
only 10 bytes.
Whether a key allows or prohibits duplicates affects performance primarily as it affects

the tree height. Node entries that allow duplicates are four bytes longer than node entries
that prohibit duplicates. If the key length were very short, the height of the index tree
may increase. Each key that allows duplicates also increases the length of the data record
representation by four bytes. This is usually insignificant, but it may increase the size of
the file and degrade performance if the records are very short or if a large number of keys
allow duplicates. Of course, any file with a large number of keys may be expected to
have poorer performance than a file with a relatively small number of keys. If there are
fewer buffers available than the sum of the heights of the index trees, keys that prohibit

duplicates degrade performance more than keys that allow duplicates. When a write
request is made, every key that prohibits duplicates must be checked to see if the record to
be written will create an illegal duplicate key value. When insufficient disk buffers are
available, this will cause some additional disk operations.
Record length affects indexed file performance by placing a lower limit on the block size,
perhaps forcing the block size to be larger than one sector, increasing the transfer time
and reducing the number of buffers that will fit in available memory. Large record
lengths also affect indexed file performance by increasing the disk space required by the
file. RM/COBOL indexed files support variable-length records, using only sufficient disk
space to contain the actual record data. Converting fixed-length records to variable-
length records, however, is not necessary to improve performance. With data record
compression enabled, fixed-length records with trailing space filled fields are almost as
small as variable-length records. Of course, larger data records require more disk space.
This can reduce the effectiveness of the disk buffers by reducing the percentage of the file
that can be kept in memory and thus the probability that a desired file block will already
be in memory.
Correct Data Recovery Strategy

RM/COBOL indexed files support several optional data recovery strategies that
determine when and how much data should be written to the operating system or disk
when the application executes a file modification statement. Enabling a data recovery
strategy that does not defer I/O operations degrades performance. This is especially true
if index tree modifications are written in addition to data record modifications, since a
single record operation may cause many index modifications. Of course, the user might
consider disabling a data recovery strategy to be a performance problem if the machine is
turned off without exiting the application and hours of data entry are lost.
Using Key and Data Compression

RM/COBOL indexed files support key compression, in which leading characters of an
index node entry key that match the preceding entry and trailing space characters are
removed from the entry. This is usually a performance benefit, by increasing the number
of entries in an index node, decreasing the height of the tree, decreasing the size of the
file, and decreasing the number of disk operations. An exception occurs when sufficient
buffers can be reserved to contain all or almost all of a file’s index trees. This will make
the file operations compute bound instead of disk bound. Changing the file to have
uncompressed keys may improve performance. Typically, this occurs when running small
benchmark programs with all of the memory reserved for disk buffers. Key compression
may also degrade performance when numeric keys are used or when the key length is only
1 or 2, by unnecessarily adding two compression overhead characters to keys which, in
fact, compress by fewer than three characters.

RM/COBOL indexed files support data record compression, in which repeated characters
in a data record are replaced by a single compression character. Since the compression
algorithm operates on all repeated characters, not just repeated zeros and spaces, this
compression almost always results in less disk space for each data record, less disk space
for the entire file, less arm movement when reading the file, and fewer disk operations to
access the file. It may not be beneficial on very short data records, and data records that
are artificially forced to be incompressible. It also yields anomalous results when a file is
initially created with records that are almost all spaces, and these records are then
rewritten with the actual data.
Using RM/COBOL Facilities

The WITH LOCK phrase on the OPEN statement may be used to improve the
performance of exclusively accessed files in a network environment. When files are
shared, at the beginning of each operation the runtime system must lock the file, read the
header of the file to determine which buffers no longer contain valid data, and lock the
record being modified. The file, and sometimes the record, are unlocked at the end of the
operation. If a file should be opened by only one user at a time, then opening the file
WITH LOCK avoids the locking and validation overhead on each operation. With a
sufficient number of buffers, this can make the difference between four network
transactions and zero network transactions to perform an operation.
Some applications may be written to delete and write a record when the record contents
are changed, instead of using a REWRITE statement. A REWRITE statement always
yields better performance than the DELETE and WRITE statements. This is because
there is always at least one key whose value has not been changed, the prime record key.
The index trees for unchanged keys need not be updated and, except for the prime record
key, need not even be accessed.
File Version Level 2

Indexed files with a version level of 2 have a modified structure that can improve
performance when adding records to the file. This feature is most noticeable when the
file has been opened WITH LOCK. Files with a version level of 2 can be read but not
modified by versions of RM/COBOL prior to version 6. Although by default, files are
created with a version level of 2, this can be changed by using the DEFAULT-FILE-
VERSION-NUMBER keyword of the RUN-INDEX-FILES configuration record. For
more information, see page 10-31.
To change the version level of an existing file, use the Define Indexed File utility
(rmdefinx). If the version level is changed to or from level 0, the Indexed File
Recovery utility (recover1) must be run on the file. (See Appendix G, Utilities, for
more information.)

File Version Level 3
Indexed files with a version level of 3 can grow to a larger size than those with a version
level of 0 or 2. When creating a file with a version level of 3, the LARGE-FILE-LOCK-
LIMIT keyword of the RUN-FILES-ATTR configuration record is used to determine the
largest address that can be locked in the file. This value is also stored in the file header,
allowing different files to have different lock limit values. Files with a version level of 3
cannot be read or written by prior versions of RM/COBOL. See Chapter 10,
Configuration, for more information on the LARGE-FILE-LOCK-LIMIT keyword, or for
information on how to change the default indexed file version number to 3 using the
DEFAULT-FILE-VERSION-NUMBER keyword of the RUN-INDEX-FILES
configuration record.
To change the version level of an existing file, or to change the lock limit stored in the
header, use the Define Indexed File utility (rmdefinx). If the version level is changed to
or from level 0, the Indexed File Recovery utility (recover1) must be run on the file. (See
Appendix G, Utilities, for more information.)
Message Control System (MCS)

RM/COBOL does not provide runtime support for the Communications Module of ANSI
COBOL 1985, which requires the presence of a highly application-specific Message
Control System (MCS). This MCS is required for correct operation of the
Communications Module statements: ACCEPT MESSAGE COUNT, DISABLE,
ENABLE, PURGE, RECEIVE, and SEND. However, RM/COBOL provides an open
MCS interface with which application designers can design and include their own MCS.
Note An MCS interface is not provided by the runtime system in the Windows
environment.
Dummy Module osmcs.c

The runtime system provides a dummy module osmcs.c, which is replaced by the
application designer’s own MCS module with the two entry points OSMCSINITIALIZE
and OSMCS implementing the desired message control system. A new runtime system
executable file must be linked. (See Appendix D, Customizing RM/COBOL for UNIX, for
more information on preparing C subprograms.)

Initializing the MCS
The routine OSMCSINITIALIZE is called at runtime initialization to initialize the MCS
interface. If the interface is present and initialization completes properly,
OSMCSINITIALIZE should return TRUE (non-zero). Otherwise, it should return
FALSE (zero).
RM/COBOL Statements and the MCS

The MCS is required for correct operation of the following RM/COBOL statements:
• ACCEPT MESSAGE COUNT • PURGE
• DISABLE • RECEIVE
• ENABLE • SEND
The MCS uses two data structures to communicate with the COBOL program. The first
structure is the McsPointerArea, described below. The second structure is the
communications descriptor map (CCD), which is described in the following section and
illustrated in Figure 8-1 on page 8-68.
The McsPointerArea is described with the following C data structure:
typedef struct McsPtrAreaStruct

{
char *CcdAreaAddress;
char *CdRecordAddress;
char *MessageAreaAddress;
char *McsPointer[10];
}
This data structure is defined in C and contains only pointers (addresses). The size of the
structure (in bytes) depends on the size of pointers for a given system. The structure is
aligned so that pointers may be referenced directly. The CcdAreaAddress contains the
address of the CCD.
The CdRecordAddress contains a pointer to the record area implicitly associated with
the CD.
The MessageAreaAddress contains a pointer to the message area for a SEND or

RECEIVE operation, or the key (password) value for an ENABLE or DISABLE
operation.
The array of ten McsPointers is reserved for use by the MCS function.

The MCS functions are defined:
OSMCSINITIALIZE()
and
OSMCS (McsFunction, McsPtrArea)
long McsFunction;
char *McsPtrArea;
The valid McsFunction codes are as follows:
1 ACCEPT MESSAGE COUNT

2 DISABLE
3 ENABLE
4 RECEIVE
5 SEND
6 PURGE
The parameter McsPtrArea contains a pointer to the C data structure described

previously.
Upon exit, the MCS must return a completion code as defined in Table 8-10.
Table 8-10 MCS Completion Codes
Code Description
0 Function processed. No error.
1 RECEIVE . . . NO DATA processed. No data.
2–1499 Error. Terminate run unit with MCS error. The displayed error code
will be the value plus 350.
The MCS is notified when a program containing one or more CCDs is terminated due to
the execution of a CANCEL statement or to run unit termination. In this case, upon
entry to the MCS, McsFunction will be 7 and McsArea will point to a CCD. The MCS
must then determine the action to be taken for the CCD solely from the CD Type (byte
offset 2) field and the area reserved for the MCS. The MCS will be called once for each
communications description defined in the program being terminated.
The MCS is explicitly notified of run unit termination after all CCDs have been
terminated. When this happens, upon entry to the MCS, McsFunction will be 8.
No error codes are anticipated or processed when the MCS is called with
McsFunction 7 or 8.

RM/COBOL Communications Descriptor (CCD)
The RM/COBOL communications descriptor (CCD) contains values derived from the CD
description in the Data Division as well as from the Procedure Division statement that
caused the request. Figure 8-1 illustrates a map of the CCD.
Figure 8-1 Communications Descriptor Map (CCD)
BYTE
OFFSET
0 Reserved - do not modify
1
2 CD Type
3 Options
4 Destination Table Occurrences
5
.
.
.
11
12 Reserved for use by MCS
.
.
.
19
20 Message Area Length
21
23 Message Indicator
24 Advancing Flags
26 Advancing Count
27
28 Reserved for use by MCS
.
.
.
79

CD Type has:
Bit 0 (0x01) is set if CD . . .FOR INPUT.
Bit 1 (0x02) is set if CD . . .FOR OUTPUT.
Both bits are set if CD . . .FOR I-O.
Options has:
Bit 0 (0x01) is set if RECEIVE . . .MESSAGE.
Bit 1 (0x02) is set if RECEIVE . . .SEGMENT.
Bit 2 (0x04) is set if RECEIVE . . .NO DATA.
Bit 3 (0x08) is set if ENABLE INPUT TERMINAL or DISABLE INPUT
TERMINAL.
Destination Table Occurrences contains the value specified in the DESTINATION
TABLE OCCURS clause, most-significant-byte first. Zero indicates that there is no
DESTINATION TABLE OCCURS clause.
Message Area Length contains the length, as a short integer of the message area for a
SEND or RECEIVE operation, and of the key (password) for an ENABLE or DISABLE
operation. Zero indicates no message area (no FROM phrase in a SEND statement), or
no key value (no KEY phrase in a DISABLE or ENABLE statement).
Message Indicator contains the binary value of the message indicator specified by the
WITH phrase of the SEND statement. 0=no indicator, 1=ESI, 2=EMI and 3=EGI. The
value is incremented by 16 if the REPLACING LINE phrase was specified in the SEND
statement.
Advancing Flags contains information about the ADVANCING phrase of the SEND
statement. Bit 7 (0x80) is set if the BEFORE phrase was specified, and is cleared if the
AFTER phrase was specified. Bit 6 (0x40) is set if mnemonic-name was specified. Bits
0-3 (0x0F) contain the channel number associated with mnemonic-name in this case. If
bit 6 is clear, bit 3 (0x08) is set to indicate the page phrase was specified, or bit 0 (0x01)
is set to indicate the LINE(S) phrase was specified.
Advancing Count contains the binary values stored as a short integer of the literal or
identifier specified in the LINE(S) clause of the ADVANCING phrase of the SEND
statement.
The remaining area is set to zero by the RM/COBOL compiler, and may be used by the
MCS, as required.

Chapter 9: Debugging
RM/COBOL provides an interactive debugging facility, the RM/COBOL Interactive
Debugger (called Debug). This chapter details the concepts, structure, and use of Debug.
This chapter describes the following aspects of Debug:
• Invoking a program for Debug
• General Debug concepts
• Debug references
• Screen positions
• Data address development
• Regaining control
• Debug command prompt
• Debug error messages
• Debug commands
Invoking a Program for Debug

In order to execute programs for debugging, enter the D Option in the RM/COBOL
Runtime Command (see page 7-3). Any compiled RM/COBOL program is ready to be
run under control of Debug. In general, no special Compile Command options or
compilation steps are required. However, if data references are to be specified in the D
(Display), M (Modify), T (Trap), and U (Untrap) Commands, you need to enter either the
A or Y Compile Command Option (you may need to enter both). See pages 6-9 and 6-13,
respectively, for details on these options.
Any program within the run unit that was compiled with the Q Compile Command Option
will not contain any debugging information and will, therefore, appear “invisible” to the
Interactive Debugger.
Table 9-1 summarizes the RM/COBOL Debug commands.

Invoking a Program for Debug
Table 9-1 Debug Command Summary
Command Function
Address Stop (A) Sets a breakpoint and resumes program execution (see
page 9-20).
Breakpoint (B) Sets a breakpoint or displays all active breakpoints (see
page 9-21).
Clear (C) Clears breakpoints (see page 9-22).
Display (D) Displays the value of a specified data item (see page 9-23).
End (E) Ends debugging and resumes standard program execution (see
page 9-27).
Line (L) Specifies the line on which Debug displays will appear (see
page 9-28).
Modify (M) Modifies the value of a specified data item (see page 9-28).
Quit (Q) Terminates program execution and returns control to the
operating system (see page 9-33).
Resume (R) Resumes program execution at a specified location (see
page 9-34).
Step (S) Executes the program to the start of the next statement,
paragraph or section, or trace execution (see page 9-35).
Trap (T) Sets a data trap or displays all active data traps (see page 9-36).
Untrap (U) Clears data traps (see page 9-40).
General Debug Concepts

This section highlights some general concepts about Debug.
Statements
Debug considers section names, paragraph names and procedural statements to be
statements for the purpose of setting breakpoints, stepping, execution counts or program
area references (see page 9-5). Procedural statements are those RM/COBOL statements
that begin with a Procedure Division verb (for example, IF, ADD, MOVE, READ,
PERFORM, GO, STOP, and so forth).
9-2 Debugging
Breakpoints
Breakpoints can be set for any statement. When the RM/COBOL runtime system
encounters a breakpoint, it stops before it executes the statement at which the breakpoint
is set. At this point, using the appropriate Debug commands, you can examine and
modify the value of data within the program. Note that line numbers are used to indicate
breakpoints. Breakpoints may be set for lines that have no statement (such as comment
lines), but this does not cause a stop in response to the breakpoint. Any number of
breakpoints can be set.
Traps
Traps are used to compare the current value of a data item to its last known value, to see
if a change has occurred. Whereas breakpoints stop program execution before the
statement at which the breakpoint was set, traps wait until the statement has completed,
then compare for a change in value. If such a change occurs, program execution is
suspended and the current value of the data item appears. Any number of traps can be set.
Stepping
When you step through the program, you direct that execution halt before the next
statement, paragraph, or section is executed.
Execution Counts
You can specify the number of times a breakpoint is to be ignored before Debug halts the
program. For example, if you set a breakpoint at line 100 and specify an execution count
of 15, upon resumption of execution the statement at line 100 will be executed 14 times.
When the statement is encountered the 15th time, Debug will halt the program before
executing that statement. If the statement is not executed the specified number of times
before execution ends, execution will not stop in response to the breakpoint.
The maximum value for an execution count is 65535.
Line and Intraline Numbers

References to statements are made by a line number, optionally modified by an intraline
value. For example:
150 MOVE A TO B, MOVE B TO C, MOVE C TO D1
There are three procedural statements here: the first—MOVE A TO B—is referenced
only by the line number 150. The second statement in the line—MOVE B TO C—is

referenced by the line number and the intraline number (or offset): in this case, 150 + 1.
And the third statement—MOVE C TO D—is referenced by the line number and its
intraline number: 150 + 2.
Debug Values
All numeric values used by Debug (for instance, to specify an address) are entered and
displayed as decimal numbers (see the section “Data Address Development” that begins
on page 9-6 for more information).
Data Types
Certain Debug commands allow (and in some cases require) you to enter a value for type.
type indicates the type of data item. This makes Debug aware of the internal
representation of the data item specified. The value of type is generally the value shown
for the data item in the Debug column of the allocation map. However, other values may
be specified for type if you want the data item decoded according to a different
representation.
The allowed values for type are listed in Table 9-2.
Table 9-2 Valid Data Types
Data Type Meaning Data Type Meaning

ABS Alphabetic NLC Numeric display signed
(leading combined
ABSE Alphabetic edited NLS Numeric display signed
(leading separate)
ANS Alphanumeric NPP Packed unsigned
ANSE Alphanumeric edited NPS Packed signed
GRP Group NPU Numeric unsigned
HEX Hexadecimal NSE Numeric edited
IXN Index-name NSU Numeric display unsigned
NBS Binary signed NTC Numeric display signed
(trailing combined)
NBU Binary unsigned or index NTS Numeric display signed
data item (trailing separate)
NCS Numeric unpacked signed PTR Pointer
NCU Numeric unpacked unsigned
9-4 Debugging
Debug References
There are a number of ways to refer to specific lines of code or to specific data items
within an RM/COBOL program.
Program Area References

You can refer to statements by the line number as it exists in your source program, by an
intraline number if more than one statement is on a source line, and by a program name as
it appears in the PROGRAM-ID paragraph in the Identification Division.
Data Item References

A data item can be referred to by its address and size, plus the specific occurrence
(subscript) information if defined within an OCCURS clause, plus the argument number if
defined within the Linkage Section or the external number if defined with the external
attribute. A data item may be referred to by its symbolic name if the symbol table is
included in the object program (see the discussion of the Y Compile Command Option
that begins on page 6-13).
Screen Positions
You can request that Debug screen displays appear on a particular line. This feature is
useful when you are debugging interactive programs (those that accept and display
information on the screen) because it minimizes the risk of overwriting a program display
with Debug commands or messages. For instance, if your screen display uses lines 10
through 25, you can direct that Debug commands and messages appear on line 6.

Debug References
Data Address Development
Several Debug commands require you to specify particular data items, or specific
occurrences of specific data items. Debug provides three ways for you to enter this
information:
1. Identifier format
2. Address-size format
3. Alias format
All three methods can be used during a single Debug session if the conditions required for
their use are satisfied. Only one method can be used for an individual Debug command.
Identifier Format
The identifier format is similar to the source format for identifier specification. This
method requires that you specify (or configure) the Y Compile Command Option (see
page 6-13), which outputs the symbol table to the object file for use by Debug. If the
symbol table is absent from the object file, this format cannot be used.
The syntax is as follows:
name-1 [ { IN | OF } n a m e - 2 ] … [ script ] [ r e f m o d ]
[ , { type | { * | & } [ type ] } ] [ # alias ]
name-1 is a name declared as a constant-name, data-name, or index-name in the Data

Division of the current program or a constant-name, data-name, or index-name with
the global attribute in a program that contains the current program. name-2 is a
qualifier for name-1. References to alphabet-names, cd-names, class-names,
condition-names, file-names, mnemonic-names, paragraph-names, program-names,
screen-names, section-names and symbolic-characters are not allowed, except that a
file-name or cd-name may appear as the final qualifier of a data-name. The sequence
of names must form a valid qualified reference to a data item, according to the rules
for source program data references. A constant-name may only be specified in the
D (Display) Command.
9-6 Debugging
script is required if the data item referenced by name-1 is a table element. If it is not,
do not specify script. The format for script is as follows:
( integer-1 [ [ , ] integer-2 ] … )
integer-n is a sequence of one or more decimal digits. Parentheses are required.

Either commas or spaces can separate the integers. The number of integers must
match the number of OCCURS clauses in the hierarchy of data description
entries for the data item referenced by name-1. The value of integer-n is
interpreted as an occurrence number in the same way as a literal subscript in the
source program.
refmod selects a subfield of the data item in the same manner as a
reference-modification in the source program. It has this format:
( offset : [ length ] )
offset is a string of decimal digits whose value ranges from 1 to the length of the
data item referenced by name-1. The parentheses and the colon following offset
are required.
length is a string of decimal digits whose value ranges from 1 to the remaining
length of the data item referenced by name-1, after offset has been applied.
Failure to specify length requests the maximum length from offset to the end of
the data item referenced by name-1.
type specifies the type of data item referenced. If this parameter is omitted, type
defaults to the type of the named data item except when a type modifier is specified.
(See the list of valid data types in Table 9-2.) The type value IXN may only be used
with index-names and, when the named data item is an index-name, the only
permissible type value is IXN. The type value PTR may only be used with pointer
data items and, when the named data item is a pointer data item, the only permissible
type value is PTR, except when a type modifier is specified. The type modifiers
* and & have the following effect:
• The * type modifier indicates an indirect reference, that is, a reference to the
data item referenced by a pointer data item value. The data item specified in the
command must be a pointer data item (data type PTR). In this case, type, if
specified, indicates the type of the data item referenced by the pointer data item
value. If type is not specified, the default is hexadecimal. If refmod is not
specified, the command refers to the entire effective memory area specified by

the pointer data item value. The effective memory area specified by
a pointer data item value begins with the effective address
(pointer.address + pointer.offset) and ends just before the effective limit address
(pointer.address + pointer.length). If refmod is specified for an indirect
reference, refmod is applied to the indirect reference rather than the pointer data
item itself. Thus, refmod may be used to specify an offset and length (subfield)
within the current effective memory area of an indirect reference.
• The & type modifier indicates that the address of the data item specified is
the data item referenced by the command. In this case, the type of the operand
will always be a pointer and, if type is specified, type must be PTR. The
D (Display) Command may use the & type modifier for any data item type
except index-names (data type IXN). The & type modifier may not be used with
a constant-name since a constant-name does not name a data item. The & type
modifier may be used in the M (Modify), T (Trap), and U (Untrap) Commands
only if the referenced data item is a based linkage record because, otherwise, the
address is not modifiable.
alias is a name you enter to serve as another name for the data operand specification
that precedes it. If present, alias must follow a pound sign (#). The characters
that follow the # must form a valid COBOL word. Only the first three characters
of this word are significant. Once specified, alias can be used in later Debug
commands that use the alias format. (See the discussion of this format that begins
on page 9-11.) The three-character alias must be unique. If you assign the same alias
to a different data operand, it will no longer refer to the earlier operand. When a
command defines an alias and specifies the * (indirect through pointer) type
modifier, the indirection is resolved at the time the alias is defined. In this case, the
alias continues to refer to the data item that that the pointer data item referenced
when the alias was defined even if the pointer data item value has subsequently been
changed. When a command defines an alias and specifies the & (address of data
item) type modifier, the address of the data item is resolved each time the alias is
specified using an alias format command.
9-8 Debugging
Address-Size Format
This method requires that you specify the A Compile Command Option (see page 6-9) to
produce an allocation map in the listing file. This map provides the information that must
be entered in a Debug command employing this method.
The syntax is as follows:
[ base : ] address [ + occur-size * occur-num ] … , size ,

[ type ] [ # alias ]
base specifies the base item for formal arguments, based linkage items, and external
items as follows:
• For a USING formal argument, base is specified as U arg-num, where arg-num
specifies the ordinal position of the argument in the USING list of the Procedure
Division header provided in the allocation map of the program listing.
• For a GIVING formal argument, base is specified as G, as shown in the

allocation map of the program listing.
• For a based linkage item, base is specified as B item-num, where item-num

specifies the compiler assigned based linkage item number provided in the
• For an external item, base is specified as X ext-num, where ext-num specifies the
compiler assigned external number provided in the allocation map of the
program listing.
Note A Linkage Section data item, which is neither a formal argument item nor a
based linkage item, is shown as "Not addressable:" in the allocation map of the
program listing. Since such items have not been used in the source program, the
compiler does not allocate a base pointer item for them and the Interactive Debugger
cannot access them.
address specifies the decimal data address of the data item to be displayed, modified
or monitored. The value is obtained from the data allocation map in the compiler
listing.
occur-size specifies the size of data items that contain OCCURS clauses in their
definitions. If occur-size is present, the plus sign (+)must appear as well. When a
referenced data item contains an OCCURS clause in its definition, occur-size is equal
to the value of size (defined in this section).

occur-num is the occurrence number for data items with OCCURS clauses in their
definitions.
size specifies the size of the data item to be displayed, modified or monitored. (For
IXN items, size specifies the span of the data item indexed by the index-name.)
type specifies the data type of the data item to be displayed, as it appears in the
Debug column of the data allocation map. (The allocation map is described on
page 6-22; complete details on the types of data allowed with RM/COBOL are found
in Chapter 4, Data Division, of the RM/COBOL Language Reference Manual; and a
list of the data types appears in Table 9-2 on page 9-4.) If this parameter is omitted,
type defaults to hexadecimal. The type modifiers * (indirect through pointer) and &
(address of data item) may not be specified in the address-size format.
alias is the name you assign to the data item referenced by the preceding entry. See
the full description of the alias format on page 9-11.
Note that the term:
+occur-size*occur-num
selects specific occurrences of data items in tables.
Look at the program listing and associated data allocation map in Figure 9-1. Then look
at Figure 9-2, which shows a developed reference to GRP-2(3).
The effect of this reference is the creation of a developed data address of 946, which
appears as the address on the first line of the data display. Subsequent references to
GRP-2(3) may appear as 946, 471 instead of 4 + 471*3, 471.
Note This developed data address is not the algebraic equivalent of the formula
4 + 471*3. It is the algebraic equivalent of 4 + (471*(3-1)) = 4 + (471*2) = 946.
Figure 9-1 Data Allocation Map
z 8
9 DATA DIVISION. z
10 WORKING-STORAGE SECTION.
O 11 01 GRP-1. O
z 13
14
02 GRP-2
03 FILLER
OCCURS 20.
PIC X(6). z
15 03 GRP-3 OCCURS 15.
O 16 04 FILLER PIC X(5). O
z 17
18
04 THE-ITEM
04 FILLER
PIC 9V9 OCCURS 12.
PIC X(2). z
O Working-Storage Section for program ALLOCMAP O
z Address Size Debug Order Type Name z
4 9420 GRP 0 Group GRP-1
O 4 471 GRP 1 Group GRP-2 O
z 10
15
31
2
GRP
NSU
2
3
Group
Numeric unsigned
GRP-3
THE-ITEM z
9-10 Debugging
Figure 9-2 Developed Data Address
address [+occur-size*occur-num], size
4 + 471 * 3 , 471
The size of the data item to be inspected.
The occurrence number (occur-num).
The size of the first order element containing GRP-2 (occur-size).
The address of GRP-2, from the data allocation map.
Alias Format
The alias format allows you to reference a data item or index that had been assigned an
alternate name. Once assigned, the alias applies to that data item until you use it to name
another data item or you end the Debug session.
The general format for referring to an item with an alias is as follows:
# alias
# is required.
alias must be a valid COBOL word, only the first three characters of which are used.
The alias must be previously defined in an identifier or address-size format
specification.
Regaining Control
Debug regains control under the following conditions:
• Breakpoint
• Runtime system error
• Step through a statement, paragraph or section
• Execution of a STOP RUN statement
• Trap

Regaining Control
Debug Command Prompt
The Debug command prompt first appears at the lower-left corner (line 25) of the screen.
It looks like this:
condition line [ + intraline ] n a m e C?_
condition is the name of a condition that has stopped program execution. It may be
one or more of the following:
• BP, which indicates a breakpoint is present.
• DT, which indicates a data trap has occurred.
• ER, which indicates a runtime system error has occurred.
• SR, which indicates the program has executed a STOP RUN statement.
• ST, which indicates program stepping is active.
line is the line on which the next statement to be executed begins. The string “Line?”
appears if the line number is not known.
intraline indicates the next statement to be executed when line contains more than
one statement.
name is the name of the currently executing program.
C?_ is the prompt and cursor.
Any Debug command may be entered when the prompt appears on the screen. If the last
Debug command was an S (Step) Command, you can repeat it by pressing Enter in
response to the prompt.
9-12 Debugging
Debug Command Prompt
Debug Error Messages
This section lists and defines the error messages that may be generated during debugging.
Command Error
Indicates that you entered an invalid command character, or a command with inconsistent
or invalid parameter values. The Debug command prompt appears again.
This message appears if any errors occur in scanning a reference in address-size format.
Further, this message appears after any of the following specific errors are diagnosed.
Address too big
Indicates that the address value specified for a data item in a Debug address-size format is
not correct.
This means that the end of the data item, calculated by summing the address of the data
item, including any subscript calculations, and the length of the data item less one,
exceeds the size of the region containing the data item. If the item resides in the program,
the end of the data item must not exceed the sum of the lengths of the File Section and the
Working-Storage Section. If the item is a Linkage Section item that is, or is subordinate
to, a formal argument, the end of the data item must not exceed the length of the
corresponding actual argument item. If the item is a Linkage Section item that is, or is
subordinate to, a based linkage item, the end of the data item must not exceed the length
of the area of memory addressed by the pointer value used to set the base address of the
based linkage item. If the item is external, the end of the data item must not exceed the
length of the highest level containing external item.
Colon (:) expected
Indicates that the colon is misplaced or omitted in the reference modification specified
with a data item address in a Debug identifier format.
A reference modification specification consists of a left parenthesis, a non-zero integer

starting position, a colon, optionally a non-zero integer length, and a right parenthesis.
This message appears if the left parenthesis is not followed by a colon, there is no right
parenthesis, or the colon follows the right parenthesis. The reference modification
specification follows a subscript specification, if present.

Dword alignment
Indicates that the address specified for an index-name (Debug type IXN) is not a multiple
of four.
Extraneous characters
Indicates that the command entered to Debug contains characters that are not expected
past the data item specification or modification value.
The D (Display) and T Trap Commands accept an alias identifier of a data item or a data
item specification with an optional alias definition. The M (Modify) Command accepts
the same parameters as a D (Display) Command followed by a modification value. The U
(Untrap) Command accepts the data item specification or alias identifier of a data item
with which a trap is currently associated. No additional characters are accepted.
Identifier expected
Indicates that the first character of what should be an identifier is not alphabetic, numeric,
or hyphen.
An identifier is expected at the start of a Debug reference in an identifier format,

following IN or OF in identifier format, and following the pound sign (#), which
identifies an alias.
Identifier not a data item
Indicates that the symbolic identifier specified is a user-defined word in the COBOL
source, but is not a data item.
The Debug commands, D (Display), M (Modify), and T (Trap), allow access to program
data items. The state of user-defined words, such as condition-names or switch-names,
which are not data items, cannot be examined. Examine the source or the allocation map
to determine the data item that contains the field to be accessed.
This error message also occurs if a symbolic identifier specifies a Linkage Section data
item that is neither a formal argument (USING or GIVING) nor a based linkage item.
Since such items have not been used in the source program, the compiler does not allocate
a base pointer item for them and the Interactive Debugger cannot access them.
9-14 Debugging
Identifier refers to constant
Indicates that in a command other than the D (Display) Command, the symbolic identifier
specified refers to a constant-name or is the constant address (& type modifier specified)
for a data item that is not a based linkage data item. Constant-names and constant
addresses may not be specified in the M (Modify), T (Trap), or U (Untrap) Commands.
IN or OF expected
Indicates that the symbolic identifier in a Debug identifier format specification of a data
item is followed by something other than a qualification specification.
If a symbolic name is not followed by the special characters left parenthesis, comma, or
pound sign, it must be followed by IN or OF and the symbolic name of a higher level data
item.
Incorrect number of subscripts
Indicates that too few subscripts are provided with a data item in a Debug
identifier format.
Index Error
Indicates that you requested the display of an index-name (Debug type IXN) and Debug
discovered an inconsistency in the internal representation of the index-name.
This message generally indicates that the address or size value of the index-name was
entered incorrectly.

Index-name inconsistency
Indicates that the symbolic identifier conflicts with the type value specified in the
command. One of the following conflicts has occurred:
• The symbolic identifier refers to an index-name, but a type value other than IXN was
specified. Index-names may not use a type value other than IXN.
• The symbolic identifier does not refer to an index-name, but the type value IXN was
specified. Only index-names may be specified with the type value IXN.
• The symbolic identifier refers to an index-name and a refmod field was specified.
Reference modification of an index-name is not allowed.
• The type modifier & (address of data item) was specified with a symbolic identifier
that refers to an index-name (data type IXN). The type modifier & may not be
specified for an index-name.
Left parenthesis expected
Indicates that the data item in a Debug identifier format refers to a table element and no
subscript identifying a particular element is entered.
Length too big
Indicates that the sum of the starting position value and the length, specified in the
reference modification of a data item in a Debug identifier format, exceeds the declared
length of the data item.
A reference modification specification consists of a left parenthesis, a non-zero integer

starting position, a colon, optionally a non-zero integer length, and a right parenthesis.
The ending position, that is, the sum of the starting position minus 1 and the length,
must not exceed the length of the symbolic data item. If the symbolic data item is a
variable-length group, the ending position must not exceed the maximum length of
the group.
9-16 Debugging
Name undefined
Indicates that a symbolic identifier entered in a Debug identifier format specification of a

data item does not exist in the COBOL program.
The name appears undefined when debugging a contained program if the name is defined
in a containing program but is not described with the GLOBAL attribute. When
debugging a containing program, names in contained programs appear undefined. This
message also appears if a name provided as a qualifier is not defined anywhere in the
separately compiled program.
No such based linkage item
Indicates that you specified a based linkage item number for a data item in the Debug
address-size format incorrectly. This means that the integer between the letter B and the
following colon does not correspond to a based linkage item.
No such external
Indicates that you specified an external number for a data item in the Debug address-size
format incorrectly. This means that the integer between the letter X and the following
colon does not correspond to an external group item.
No such parameter
Indicates that a USING argument value for a data item in the Debug address-size format
is specified incorrectly.
This means that the integer between the letter U and the following colon does not
correspond to a Linkage Section data item included in the USING list of the Procedure
Division or that the calling program did not pass a value in the corresponding position of
its CALL statement.
Non-zero integer expected
Indicates that a subscript, reference modification starting position, or reference

modification length in a Debug identifier format specification of a data item is zero or is
not numeric.

Not enough free memory to continue
Indicates that Debug cannot allocate memory.
Debug allocates memory to remember names associated with an alias and to contain the
symbol table of the current program.
Offset too big
Indicates that the starting position value entered in a reference modification, specified
with a data item address in a Debug identifier format, exceeds the declared length of the
data item.
Pointer inconsistency
Indicates that the symbolic identifier conflicts with the type value specified in the
command. One of the following conflicts has occurred:
• The symbolic identifier refers to a pointer data item, but a type value other than PTR
was specified without a type modifier. Pointer data items may not use a type value
other than PTR.
• The symbolic identifier does not refer to a pointer data item, but the type value PTR
was specified. Only pointer data items may be specified with the type value PTR.
• The symbolic identifier refers to a pointer data item without the type modifier *
(indirect through pointer) and a refmod field was specified. Reference modification
of a pointer data item is not allowed.
• The type modifier * (indirect through pointer) was specified with a symbolic
identifier that is not a pointer data item. The type modifier * may only be used with
pointer data items.
• The type modifier & (address of data item) was specified with a type value other than
PTR. The type modifier & always results in a pointer value and thus cannot specify
a type value other than PTR.
• The type modifier & (address of data item ) was specified with a symbolic identifier
that refers to a constant-name. The type modifier & may not be specified with a
constant-name.
• For the M (Modify) Command, the = value modifier was followed by a symbolic
identifier that does not refer to a pointer data item or reference modification was
specified for the pointer.
9-18 Debugging
Pointer memory access violation
Indicates that the * (indirect through pointer) type modifier was specified with a pointer
data item that has a null value or a value that points to memory that cannot be read by the
program. For the M (Modify) Command, this may mean that the program cannot write to
the memory area referenced by the pointer value.
Program not compiled with Y option
Indicates that a data item is entered in a Debug identifier format to a D (Display), M

(Modify), or T (Trap) Command, but no symbol table is available.
Qualifier undefined
Indicates that an alias identifier is undefined or that the symbolic qualifier provided after
an IN or OF in a Debug item address in an identifier format is not a higher level data item
of the preceding identifier.
Check the qualification specification with the program source or the allocation map of the
compilation listing.
Qualification ambiguous
Indicates that the symbolic qualifiers provided after an IN or OF in a Debug item address
in an identifier format do not uniquely identify a data item.
Qualification allows unique specification of data items with the same name. The
qualification identifiers must be the names of lower numbered group items or the name of
the COBOL filename if the data item is in the File Section. Check the qualification
specification with the program source or the allocation map of the compilation listing.
Reenter the command with additional qualification items to uniquely identify the desired
data item.
Right parenthesis expected
Indicates that a subscript or reference modification field, specified with a data item
address in a Debug identifier format, is missing its closing right parenthesis or that too
many subscripts are provided.
Subscript value too big
Indicates that a subscript exceeds 65535 or that the offset corresponding to the specified
subscripts exceeds 232.

A (Address Stop) Command
Use the A Command to set a breakpoint and to resume program execution from the
current location. When the specified breakpoint is reached and Debug regains control,
the breakpoint is cleared and has no further effect.
The syntax for the A Command is as follows:
A [ line [ + intraline ] [ , [ prog-name ] [ , [ count ] ] ] ]
line indicates the line number containing the statement at which the breakpoint is to
be set. line always refers to the first statement of the line. If this parameter is
omitted, no breakpoint is set before execution is resumed.
intraline refers to a specific statement within the program line. For example, 1
indicates the first intraline statement (or the second actual statement), 2 indicates the
second intraline statement, and so forth. If this parameter is omitted, the first
statement on the line is assumed.
prog-name provides for explicit program qualification during debugging. The value
of prog-name must be a program name from the PROGRAM-ID paragraph of the
Identification Division. If this parameter is omitted, it is assumed the reference is to
the currently executing program. If this parameter is omitted and count is specified,
there must be two commas before count.
count is an execution count. Debug allows the statement to execute a number of
times equal to count minus one, then honors and clears the breakpoint immediately
before the next execution (which now equals count) of the statement. Debug then
regains control. The maximum value for count is 65535. If this parameter is
omitted, count defaults to 1.
When you use the A Command, keep in mind that the specified breakpoint remains in
effect until it is honored. In other words, if execution halts and Debug regains control
at a statement other than that specified in the A Command, the breakpoint set by the
A Command remains in effect. It can be cleared by the C Command and displayed by
the B Command.
9-20 Debugging
A (Address Stop) Command
B (Breakpoint) Command
Use the B Command to display all currently set breakpoints or to set breakpoints at
specific procedural statements. Note that—unlike the A Command—a breakpoint set by
this command is not cleared once the conditions have been satisfied. To clear breakpoints
set with a B Command, you must enter a C Command.
The command syntax is nearly identical to that used with the A Command:
B [ line [ + intraline ] [ , [ prog-name ] [ , [ count ] ] ] ]
line indicates the line number containing the statement at which the breakpoint is to
be set. line always refers to the first statement of the line. If this parameter is
omitted, no breakpoint is set. Instead, all currently set breakpoints are displayed.
the currently executing program. If this parameter is omitted and count is specified,
there must be two commas before count.
count is an execution count. Debug allows the statement to execute a number of
times equal to count minus one, then honors and clears the breakpoint immediately
before the next execution (which now equals count) of the statement. Debug then
regains control. The maximum value for count is 65535. If this parameter is
omitted, count defaults to 1. Because the B Command does not clear breakpoints
after responding to them (as does the A Command), it remains in effect for all
subsequent occurrences.
For example, entering:
B 150+2, PAY-TAX, 5
sets a breakpoint at the third statement (second intraline statement) at line 150 in the
program PAY-TAX. When execution resumes, the breakpoint is ignored four times and
honored the fifth time. Program control then returns to Debug.

B (Breakpoint) Command
The format of the breakpoint display (when line is omitted) is as follows for each active
breakpoint:
line [ + intraline ] p r o g - n a m e c o u n t
A count of zero is equivalent to a count of one.
C (Clear) Command
Use the C Command to clear any breakpoints that have been set with the A or B
Commands.
The syntax for the C Command is as follows:
C [ line [ + intraline ] [ , [ prog-name ] ] ]
line is the line number containing the statement at which the breakpoint to be cleared
is set. If no line number is specified, all currently active breakpoints are removed.
the currently executing program. If a line is specified on which no breakpoint exists,
the command is in error.
C 100+2
clears the breakpoint set at the second intraline statement of line 100 in the currently
executing program.
9-22 Debugging
C (Clear) Command
D (Display) Command
Use the D Command to display on the screen the value of a specified data item.
Identifier Format
The syntax for the D Command with the identifier format (see the discussion of this
format that begins on page 9-6) is as follows:
D name-1 [ { IN | OF } n a m e - 2 ] … [ script ] [ r e f m o d ]
[ , { type | { * | & } [ type ] } ] [ # alias ]
name-1 is a name declared as a constant-name, data-name, or index-name for the

literal value, data item, or index to be displayed. name-2 is a qualifier for name-1.
Qualification is required if the name is not unique. The named data item or index
must be described in the Data Division of the current program or be described with
the GLOBAL attribute in a program that contains the current program.
script specifies subscripting and is required if the data item referenced by name-1 is a
table element. (See page 9-7 for a complete description.) If the data item is not a
table element, do not specify script. The format for script is as follows:
refmod specifies a subfield of the data item. (See page 9-7 for a complete
description.) It has this format:
type specifies the data type to be used for displaying the named data item or index. If
this parameter is omitted, type defaults to the type of the item specified except when
a type modifier is specified. The type value IXN may only be used with index-names
and, when the named data item is an index-name, the only permissible type value is
IXN. The type value PTR may only be used with pointer data items and, when the
named data item is a pointer data item, the only permissible type value is PTR,

D (Display) Command
except when a type modifier is specified. The type modifiers * and & have the
following effect:
• The * type modifier indicates that the data item to be displayed is the data
item determined by an indirect reference, that is, a reference to the data item
referenced by a pointer data item value. The data item specified in the command
must be a pointer data item (data type PTR). In this case, type, if specified,
indicates the type of the item referenced by the pointer data item value. If type
is not specified, the default is hexadecimal. If refmod is not specified for an
indirect reference, the entire effective memory area specified by the pointer data
item value is displayed. The effective memory area specified by a pointer data
item value begins with the effective address (pointer.address + pointer.offset)
and ends just before the effective limit address (pointer.address +
pointer.length). If refmod is specified for an indirect reference, refmod is
applied to the indirect reference rather than the pointer data item itself. Thus,
refmod may be used to display a subfield within the current effective memory
area of an indirect reference.
to be displayed as a pointer value (data type PTR). Since the result type will
always be a pointer, if type is specified, type must be PTR. The & type modifier
may be used with a data item of any data type except an index-name (data type
IXN). The & type modifier may not be used with a constant-name since a
constant-name does not name a data item. The address of the data item will be
displayed as three sets of sixteen hexadecimal digits; the first set is the base
address, the second set is the offset (SET pointer UP/DOWN), and the third set
is the length of the memory area covered by the pointer.
that precedes it. (See page 9-11 for a complete description.) If present, alias must
follow a pound sign (#). The characters that follow the # must form a valid COBOL
word. Only the first three characters of this word are significant. When a command
defines an alias and specifies the * (indirect through pointer) type modifier, the
indirection is resolved at the time the alias is defined. In this case, the alias continues
to refer to the data item that the pointer data item referenced when the alias was
defined even if the pointer data item value has subsequently been changed. When a
command defines an alias and specifies the & (address of data item) type modifier,
the address of the data item is resolved each time the alias is specified using an alias
format command.
9-24 Debugging
D (Display) Command
D MONTH-NAME(11)(1:3)
directs Debug to display the first three bytes of the 11th element in the table
MONTH-NAME. Debug then displays the following:
140 ANS NOV
This shows the data address of 140, the type of data as alphanumeric, and the value
as NOV.
Address-Size Format
The syntax for the D Command with the address-size format (see the discussion of this
D [ base : ] address [ + occur-size * o c c u r - n u m ] … , size ,

items as follows:


program listing.
cannot access them.

D (Display) Command
address specifies the address of the data item to be displayed. This is based on the
value obtained from the data allocation map. (See page 9-9 for more information on
addresses used with Debug.)
definitions.
occur-num specifies the occurrence number for data items that contain OCCURS
clauses in their definitions.
size specifies the size of the data item to be displayed. If type is IXN, this is the
value that appears in the Span column of the data allocation map.
type specifies the data type of the data item to be displayed. If this parameter is
omitted, type defaults to hexadecimal. The type modifiers * (indirect through
pointer) and & (address of data item) may not be specified in the address-size format.
alias must form a valid COBOL word, only the first three characters of which are
valid. (See page 9-11 for a complete description.) Once specified, the alias can be
used to refer to the operand to which it is assigned.
The specified data item appears in the following format:
address type value …
address is the developed data address.

type is the type of data item to be displayed.
value is the value of the data in the format specified by type in the D Command.
D 13 + 2*7,2,NSU
directs Debug to display the data item located at decimal data address 25.
Debug then displays:
25 NSU 15
This shows that at the developed data address of (decimal) 25 is a value of 15, of type
numeric string unsigned.
9-26 Debugging
D (Display) Command
If the L Command (described on page 9-28) is used to specify a line number of the
monitor, the display appears one line at a time, at the line specified in the L Command. If
the display does not fit on one line, press the Enter key to see the next line. To return to
the Debug command prompt after the last line of data appears, press Enter.
If the L Command was not used, the display begins at the next line and scrolls when the
bottom of the screen is reached.
Alias Format
The syntax for the D Command with the alias format for specifying a data item or index
reference is as follows:
D # alias
# is required.
valid. (See page 9-11 for a complete description.) The alias must have been
previously defined in an identifier or address-size format specification.
E (End) Command
Use the E Command to leave Debug. The currently executing program runs until
completion.
The syntax of the E Command is as follows:

E (End) Command
L (Line Display) Command
Use the L Command to specify a line on the monitor screen at which command input
echoes and Debug responses are to be displayed.
The syntax of the L Command is as follows:
L [ line-display ]
line-display designates a line number on the monitor and may be in the range 0
through the number of lines on the screen.
This command is useful when you are debugging programs that have a variety of
interactive ACCEPT and DISPLAY statements. By selecting a specific line for Debug
displays, you can reduce or avoid conflicts between lines produced by Debug and lines
produced by the program.
If line-display is omitted from the command, or line-display equals 0, the screen resumes
its standard mode of operation (scrolling).
M (Modify) Command
Use the M Command to change the value of a specified data item.
Identifier Format
The syntax for the M Command with the identifier format (see the discussion of this
M name-1 [ { IN | OF } n a m e - 2 ] … [ script ] [ r e f m o d ]
[ , { type | { * | & } [ type ] } ] [ # alias ] , value
name-1 is a name declared as a data-name or index-name for the data item or index
to be modified. name-2 is a qualifier for name-1. Qualification is required if the
name is not unique. The named data item or index must be described in the Data
Division of the current program or be described with the GLOBAL attribute in a
program that contains the current program.
9-28 Debugging
L (Line Display) Command
script specifies subscripting and is required if the data item referenced by name-1 is a
table element. (See page 9-7 for a complete description.) If the data item is not a
table element, do not specify script. The format for script is as follows:
type specifies the data type of the item to be modified. If this parameter is omitted,
type defaults to the type of the item specified except when a type modifier is
specified. The type value IXN may only be used with index-names and, when the
named data item is an index-name, the only permissible type value is IXN. The type
value PTR may only be used with pointer data items and, when the named data item
is a pointer data item, the only permissible type value is PTR, except when a type
modifier is specified. The type modifiers * and & have the following effect:
• The * type modifier indicates that the data item to modify is determined by an
indirect reference, that is, a reference to the data item referenced by a pointer
data item value. The data item specified in the command must be a pointer data
item (data type PTR). In this case, type, if specified, indicates the type of the
data item referenced by the pointer data item value. If type is not specified, the
default is hexadecimal. If refmod is not specified for an indirect reference, the
entire effective memory area specified by the pointer data item value is modified.
The effective memory area specified by a pointer data item value begins with the
effective address (pointer.address + pointer.offset) and ends just before the
effective limit address (pointer.address + pointer.length). If refmod is specified
for an indirect reference, refmod is applied to the indirect reference rather than
the pointer data item itself. Thus, refmod may be used to modify a subfield
to be modified. The data item referenced in the command must be a based
linkage record because, otherwise, the address is not modifiable. The data item
referenced in the command may be any data type except an index-name (data
type IXN). When the & type modifier is used, the value must be a pointer value
and, if type is specified, type must be PTR.

M (Modify) Command
format command.
value specifies the new value for the data item or index. The format for specifying
the value is described by type in the following section, “Address-Size Format.”
M MONTH-NAME(12), DECEMBER
directs Debug to modify the 12th element of the table MONTH-NAME to have the value
of DECEMBER.
Address-Size Format
The syntax for the M Command with the address-size format (see the discussion of this
M [ base : ] address [ + occur-size * o c c u r - n u m ] … , size ,

[ type ] [ # alias ] , value
items as follows:


9-30 Debugging
M (Modify) Command
program listing.
cannot access them.
address specifies the address of the data item to be modified. This is based on the
definitions.
size specifies the size of the data item to be modified. If type is IXN, this is the value
that appears in the Span column of the data allocation map.
defaults to hexadecimal. The type modifiers * (indirect through pointer) and &
word. Only the first three characters of this word are significant.
value is the value of the data in the format specified by type in the M Command line.
If type is HEX—or omitted in the address-size format—value is entered as a string of

hexadecimal digits. This hex value is stored in the specified data item and is left justified
with zero fill or truncation on the right. The hexadecimal value must contain an even
number of digits.
If type is one of the nonnumeric types ANS, ANSE, ABS, ABSE, GRP or NSE, value is
stored in the specified data item and is left justified with blank fill or truncation on the
right. Note that no editing is performed during this operation.
If type is one of the numeric types NBS, NBU, NCS, NCU, NLC, NLS, NPP, NPS,
NPU, NSU, NTC or NTS, value is converted to a signed integer according to the rules
for a MOVE from a numeric edited sending item to a numeric destination item (see the

M (Modify) Command
“MOVE Statement” section in Chapter 6, Procedure Division Statements, of the
RM/COBOL Language Reference Manual for more information).
If type is IXN, value is converted to a signed integer occurrence number. This number is
then converted to the internal index-name representation based on the value of size.
If type is PTR, value must be a pointer value. The pointer value 0 is equivalent to NULL
(NULLS). For pointer values other than 0, a pointer value is forty-eight hex digits, where
the first sixteen digits specify the base address, the middle sixteen digits specify the offset
from the base address, and the last sixteen digits specify the length of the memory area.
Embedded spaces are allowed and ignored. Leading zeroes must be specified. If the
program was compiled with the Y Compile Command Option, then a pointer value may
also be specified with either of the value modifiers = or =& as follows:
{ = | =& } name-3 [ { IN | OF } name-4 ] … [ script ] [ refmod ]
If the = value modifier is specified (without the &), name-3 must refer to a pointer data
item and refmod is not allowed. The current value of the referenced pointer data item is
used for value. This is equivalent to the COBOL statement:
SET name-1 [OF name-2] … TO name-3 [OF name-4] …
If the =& value modifier is specified, value is composed from the address of the data item
named by name-3, an offset of zero, and the length of the data item named by name-3.
This is equivalent to the COBOL statement:
SET name-1 [OF name-2] … TO

ADDRESS OF name-3 [OF name-4] …
Note The Interactive Debugger attempts to validate a pointer value when specified,
but the validation results may not be conclusive. It is the user's responsibility to take
care when modifying pointer data items or based linkage base addresses to ensure
correctness. One easy method of correctly modifying a pointer value is to display the
desired pointer value using the D Command and then using copy/paste to paste the
value into the value field of an M Command. Another method is to use one of the =
or =& value modifiers described above.
In all other cases, the resulting integer is stored in the data item as if the item had no
assumed decimal point. If conversion results in a noninteger, an error message appears
and the specified data item remains unaltered.
9-32 Debugging
M (Modify) Command
M 13+2*7,2,NSU,0
directs Debug to modify the data item located at decimal data address 25. The NSU data
item will have a new value of 0.
Alias Format
The syntax for the M Command with the alias format for specifying a data item or index
M # alias , value
# is required.
previously defined in an identifier or address-size format reference to the desired
item (for example, in a D (Display) Command).
value specifies the new value for the data item or index. The format for specifying
the value is described by type in the preceding section, “Address-Size Format.”
Q (Quit) Command
Use the Q Command to stop program execution. This command terminates the program
as if a STOP RUN statement were executed.
The syntax of the Q Command is as follows:
When the Q Command is executed, open files are closed and control returns to the
operating system.

Q (Quit) Command
R (Resume) Command
Use the R Command to specify that program execution resume at the current location, or
at another location specified in the command.
The syntax of the R Command is as follows:
R [ statement-address ]
statement-address specifies the specific program address for the sentence at which
execution is to resume. If statement-address is not specified, execution resumes at
the current location. statement-address appears in the Debug column at the left of
the program listing, and should be entered as printed. statement-address is not a
line number.
An error condition or stop run condition (that is, the command prompt contains ER or SR)
forces the R Command to disallow statement-address. The R Command may be used in
its simple form (that is, without an accompanying statement-address) to allow Debug to
trace back through the program units of a run unit, but the run unit may not be restarted
when an error or stop run condition occurs.
Note The R Command used with a statement-address resets the program counter. If an
improper statement-address is specified, Debug displays an error. The program counter
remains invalid until another R Command with a valid statement-address is used. An
R Command with no statement-address at this time causes Debug to display an error.
9-34 Debugging
R (Resume) Command
S (Step) Command
Use the S Command to specify that program execution occur one step at a time. With
Debug, you can step through a statement, a paragraph, or an entire section.
The syntax of the S Command is as follows:
S [ P | S ] [ count ]
P specifies that paragraphs are to be stepped through.

S specifies that sections are to be stepped through. If neither P nor S is present,
statements are stepped through.
count specifies the number of statements, paragraphs or sections that are to be
executed before execution suspends. The maximum value for count is 65535. A
value of zero is treated as 1. The default is 1.
Specifying count greater than 1 causes Debug to trace the statements, paragraphs or
sections executed while in stepping mode. The format of the trace message is as follows:
TR line [+intraline] name
line is the line number on which the statement begins.

intraline is the specific statement within a line.
name is the name of the program as it appears in the PROGRAM-ID paragraph of the
Identification Division.
SS 10
directs Debug to execute 9 sections, produce 9 trace messages, and then halt before
executing the 10th.

S (Step) Command
T (Trap) Command
Use the T Command to monitor the value of a specified data item, and to suspend
execution whenever a change in that value occurs. The T Command can also be used to
display all currently set traps. If you enter only the command keyword T, all currently
active data traps appear.
A data trap set with the T Command can be removed with the U (Untrap) Command. A
data trap set on a Linkage Section data item is removed automatically when the program
exits. A data trap set on a File Section, Working-Storage Section or Screen Section data
item is removed automatically when the separately compiled program is canceled. A data
trap set on an external data item will continue until the run unit ends.
Identifier Format
The syntax for the T Command with the identifier format (see the discussion of this
T name-1 [ { IN | OF } n a m e - 2 ] … [ script ] [ r e f m o d ]
[ , { type | { * | & } [ type ] } ] [ # alias ]
to be monitored. name-2 is a qualifier for name-1. Qualification is required if the
name is not unique. The named data item or index must be described in the Data
Division of the current program or be described with the GLOBAL attribute in a
program that contains the current program.
script specifies subscripting and is required if the data item referenced by name is a
table element. (See page 9-7 for a complete description.) If it is not a table element,
9-36 Debugging
T (Trap) Command
type specifies the data type to be used in displaying the monitored data item or index
when a change in value occurs. If this parameter is omitted, type defaults to the type
of the item specified except when a type modifier is specified. The type value IXN
may only be used with index-names and, when the named data item is an index-name,
the only permissible type value is IXN. The type value PTR may only be used with
pointer data items and, when the named data item is a pointer data item, the only
permissible type value is PTR, except when a type modifier is specified. The type
modifiers * and & have the following effect:
• The * type modifier indicates that the data item to start monitoring is determined
by an indirect reference, that is, a reference to the data item referenced by a
pointer data item value. The data item specified in the command must be a
pointer data item (data type PTR). In this case, type, if specified, indicates the
type of the item referenced by the pointer data item value. If type is not
specified, the default is hexadecimal. If refmod is not specified for an indirect
reference, the entire effective memory area specified by the pointer data item
value is monitored. The effective memory area specified by a pointer data item
value begins with the effective address (pointer.address + pointer.offset) and
ends just before the effective limit address (pointer.address + pointer.length). If
refmod is specified for an indirect reference, refmod is applied to the indirect
reference rather than the pointer data item itself. Thus, refmod may be used to
monitor a subfield within the current effective memory area of an indirect
reference. The indirect reference is resolved at the time the trap is set with the
T (Trap) Command and subsequent changes to the pointer data item used to set
the trap do not change the data item that is being monitored by the trap. To
monitor changes in the pointer data item itself, do not use the * type modifier.
• The & type modifier indicates that the base address of the data item specified is
to be monitored. The data item referenced in the command must be a based
linkage record because, otherwise, the address is not modifiable. The data item
referenced in the command may be any data type except an index-name (data
type IXN). When the & type modifier is used, the value to be monitored is a
pointer value and, if type is specified, type must be PTR. A trap set on a based
linkage data item, without the & type modifier, is resolved at the time the trap is
set and subsequent changes to the base address of the based linkage item do not
change the data item that is being monitored. To monitor changes in the base
address of a based linkage item, use the & type modifier with the based linkage
record data-name.

T (Trap) Command
format command.
T MONTH-NAME(12)
directs Debug to suspend execution whenever the value of the 12th element in the table
MONTH-NAME changes.
Address-Size Format
The syntax for the T Command with the address-size format (see the discussion of this
T [ base : ] address [ + occur-size * o c c u r - n u m ] … , size ,

items as follows:


program listing.
9-38 Debugging
T (Trap) Command
cannot access them.
address specifies the address of the data item to be monitored. This is based on the
occur-size specifies the size of data items that contain OCCURS clauses in
their definitions.
size specifies the size of the data item to be monitored.
defaults to hexadecimal. The type modifiers * (indirect through pointer) and &
word. Only the first three characters of this word are significant.
Before RM/COBOL executes a statement, it examines the contents of the specified data
item with the value the data item had at the point program execution last resumed. If a
change has not occurred, execution proceeds to the next statement. If a change has
occurred, execution is suspended and the contents of the data item appear according to the
rules set down in the discussion of the D Command that begins on page 9-23. The trap is
updated, and remains in effect until a U Command is executed.
Alias Format
The syntax for the T Command with the alias format for specifying a data item or index
T [ # alias ]
# is required.
item (for example, in a D (Display) Command).

T (Trap) Command
U (Untrap) Command
Use the U Command to clear a single active data trap, or all currently active data traps.
Identifier Format
The syntax for the U Command with the identifier format (see the discussion of this
U name-1 [ { IN | OF } n a m e - 2 ] … [ script ] [ r e f m o d ]
[ , { type | { * | & } [ type ] } ]
whose data trap is to be removed. name-2 is a qualifier for name-1. Qualification is
required if the name is not unique. The named data item or index must be described
in the Data Division of the current program or be described with the global attribute
in a program that contains the current program.
script specifies subscripting and is required if the data item referenced by name is a
table element. (See page 9-7 for a complete description.) If it is not a table element,
9-40 Debugging
U (Untrap) Command
type specifies the data type of the monitored data item that is to be removed from the
monitored item list. If this parameter is omitted, type defaults to the type of the item
specified except when a type modifier is specified. The type value IXN may only be
used with index-names and, when the named data item is an index-name, the only
permissible type value is IXN. The type value PTR may only be used with pointer
data items and, when the named data item is a pointer data item, the only permissible
type value is PTR, except when a type modifier is specified. The type modifiers *
and & have the following effect:
• The * type modifier indicates that the data item to discontinue monitoring is
determined by an indirect reference, that is, a reference to the data item
referenced by a pointer data item value. The data item specified in the command
must be a pointer data item (data type PTR). In this case, type, if specified,
indicates the type of the item referenced by the pointer data item value. If type is
not specified, the default is hexadecimal. If refmod is not specified for an
indirect reference, the entire effective memory area specified by the pointer data
item value is the data reference to discontinue monitoring. The effective
memory area specified by a pointer data item value begins with the effective
address (pointer.address + pointer.offset) and ends just before the effective limit
address (pointer.address + pointer.length). If refmod is specified for an indirect
reference, refmod is applied to the indirect reference rather than the pointer data
item itself. Thus, refmod may be used to discontinue monitoring a subfield
• The & type modifier indicates that the data item to discontinue monitoring is the
address of the data item specified. The data item referenced in the command
must be a based linkage record because, otherwise, the address is not modifiable.
The data item referenced in the command may be any data type except an
index-name (data type IXN). When the & type modifier is used, the monitored
item is a pointer data item and, if type is specified, type must be PTR.
U MONTH-NAME(12)
clears the trap on the 12th element in the table MONTH-NAME.

U (Untrap) Command
Address-Size Format
The syntax for the U Command with the address-size format (see the discussion of this
U [ [ b a s e : ] address [ + occur-size * o c c u r - n u m ] … ]
items as follows:


program listing.
cannot access them.
address specifies the address of the data item for which a trap is active. This is based
on the value obtained from the data allocation map. (See page 9-9 for more
information on addresses used with Debug.) If address is not specified, all currently
active data traps are cleared.
definitions.
9-42 Debugging
U (Untrap) Command
If you enter only U, all currently activated traps are cleared.
For example:
U 13+2*7
clears the trap on the data item located at decimal data address 25.
If a specific data trap does not exist, the command is in error.
Alias Format
The syntax for the U Command with the alias format for specifying a data item or index
U [ # alias ]
# is required.
used. (See page 9-11 for a complete description.) The alias must have been
item (for example, in the T (Trap) Command which set the trap).

U (Untrap) Command
9-44 Debugging
U (Untrap) Command
Chapter 10: Configuration
Configuration determines such actions as screen displays, indexed file characteristics,
default operational modes, the method by which the terminal is to be accessed, and
general terminal characteristics.
Configuration is altered by writing a specific set of configuration directives into a

configuration record. The complete set of configuration records is then written to a
configuration file.
This chapter details the configuration file structure, configuration error format,
configuration record types, and terminal configuration record types.
Configuration File Structure

Configuration directives are contained in the configuration file. The configuration file is
a line sequential file, and it can be created with any convenient text editor. The
configuration file can then be specified in the Compile Command (using the G and H
Options, as described on page 6-6) or in the Runtime Command (using the C and X
Options, as described on page 7-3).
Configuration records can appear in any order within the configuration file, except where
noted otherwise. The first field in each record identifies the type of record or value being
defined. The format of the remainder of the record depends on the type of record.
Except for specific character sequences, keywords and parameters in the records are case
insensitive; uppercase and lowercase letters are equivalent.
The records are free field; that is, individual fields need not start in any predetermined
column. The general syntax is as follows:
r e c o r d - n a m e k e y w o r d =value[,value]
record-name is the name of one of the configuration records detailed in this chapter.
keyword is the name of the keyword specification being described. It must be
followed by an equal sign. Optional spaces following the equal sign are allowed.
value, depending on the keyword, may be either a string or a number. Value strings
that contain a space, equal sign, or comma must be quoted with either the double

Configuration File Structure
quote (") or single quote (') character, and must use the same beginning and ending
quote character. Quoted strings that contain the quote character must use a pair of
consecutive quote characters to represent one quote character. For some keywords,
the value may be either a single character-string or a number. In such cases, if the
single character-string is a digit (0–9), it must be quoted or it will be considered to be
a number. In all other cases, strings may be specified without quotes. Value strings
are limited to a maximum of 80 characters. Value numbers may be specified in
decimal notation as a string of decimal digits (0–9) or in hexadecimal notation as
string of hexadecimal digits (0–9, A–F) with a leading 0x or trailing h.
Configuration records may vary in length. Configuration records may be continued

beyond one record by placing an ampersand (&) character in column 1 of the second and
subsequent records. The ampersands are logically replaced with spaces and the records
are logically concatenated, ignoring trailing spaces. The maximum total length of a
configuration record, including all continued records, is 510 characters.
Comments may be included in the configuration file. Comment text begins with a slash
and an asterisk (/*) in columns 1 and 2. Lines that have /* in columns 1 and 2, as well as
blank lines, are ignored in their entirety.
Built-In and Attached Configuration Files

The UNIX version of RM/COBOL allows a configuration file to be linked in to the
runtime system and compiler system. The source module, oscnfg.c, contains a section
that can be modified to reflect configuration records that will be linked in to the runtime
system and compiler when the runtime and compiler are relinked. Simply take the desired
configuration records and using any editor, add quotation marks (") at the beginning and
end of each record, add a comma (,) at the end of each record, and then insert the lines
into the oscnfg.c source file. Then relink the runtime system and compiler by executing
the customiz script. The customiz script is described in Appendix D, Customizing
RM/COBOL for UNIX.
The Windows version of RM/COBOL allows configuration files to be physically attached

to rmcobol.exe, runcobol.exe, and recover1.exe using the Attach Configuration utility
(rmattach.exe). When attached, a configuration file will be processed prior to any
configuration file specified with a command line option. For more information on this
utility, see page G-39.
10-2 Configuration
Built-In and Attached Configuration Files
Configuration Errors
If your configuration file contains errors, you will see a message similar to one of the
following:
Configuration error code at record number in configuration file.
Configuration error code in configuration file.
code is the error number listed for configuration records, described in Appendix A,
Runtime Messages, starting on page A-37.
number is the logical record in the configuration file where the error occurred. When
using number to determine which record is in error, count lines combined with their
continuation lines as one record, and do not count comment lines or blank lines.
If the message is of the first format shown, the text of the configuration record in error
will follow the message.
The actual error message formats are described in Chapter 6, Compiling, for the compiler
and in Appendix A, Runtime Messages, for the runtime system and Indexed File
Recovery utility.
Configuration Records
Table 10-1 lists and describes the types of configuration records. Configuration
options that are not used by the compiler, the runtime system, or the Indexed File
Recovery utility (recover1) are ignored. Therefore, the same configuration file may be
used to configure the compiler, the runtime system, and the Indexed File Recovery
program, if appropriate.
Note Configuration is never necessary unless you want to change default

option settings.

Table 10-1 Types of Configuration Records
Runtime
Record Type Description Compiler System Recover1
COMPILER-OPTIONS Allows default compiler 9
options to be changed
(see page 10-6).
DEFINE-DEVICE Associates the file 9 9
access name with a
physical filename of a
device or process (see
page 10-16).
EXTENSION-NAMES Defines the character- 9 9
strings to be used for
filename extensions (see
page 10-19).
EXTERNAL-ACCESS- Describes the access to 9 9
METHOD external file access
methods, such as
Btrieve, RM/plusDB,
and RM/InfoExpress,
from the RM/COBOL
file management system
(see page 10-20).
PRINT-ATTR Describes printer 9 9
characteristics (see
page 10-20).
RUN-ATTR Describes general 9
runtime characteristics
(see page 10-23).
RUN-FILES-ATTR Describes the 9 9 9
characteristics common
to all file organizations
(see page 10-26).
1
Terminal configuration records are never necessary because terminal independence is
provided by terminfo and termcap. Terminal configuration is still provided, however,
to allow extensions to the basic capabilities provided by terminfo and termcap in a
manner that will not conflict with other applications on your system.
9 Indicates that the configuration record is used.
10-4 Configuration
Table 10-1 Types of Configuration Records (Cont.)
Runtime
Record Type Description Compiler System Recover1
RUN-INDEX-FILES Describes indexed file 9
page 10-31).
RUN-OPTION Describes default 9
runtime option values
(see page 10-33).
RUN-REL-FILES Describes relative file 9 9
page 10-34).
RUN-SEQ-FILES Describes sequential file 9 9 9
page 10-34).
RUN-SORT Describes SORT- 9
MERGE characteristics
(see page 10-36).
TERM-ATTR1 Describes terminal 9 9
page 10-36).
TERM-INPUT1 Defines incoming 9 9
character sequences (see
page 10-41).
TERM-INTERFACE1 Specifies the format for 9 9
the other terminal
configuration records,
as well as the interface
to be used for screen
I/O (see page 10-49).
TERM-UNIT1 Associates the unit 9
(UNIX Only) number of ACCEPT
and DISPLAY
statements with the
actual device on
the system (see
page 10-49).

COMPILER-OPTIONS Record
The COMPILER-OPTIONS record identifier is followed by one or more keywords. If
the keyword is allowed to have a value, it is followed by an equal sign (=) and the value.
The COMPILER-OPTIONS record allows options to be configured (see the discussion of
Compile Command options that begins on page 6-5). Configured options can be
overridden by options entered in the Compile Command line.
Certain options require that another option be present before the compiler can proceed.
For example, it is not valid to specify a cross reference if the program listing is not being
generated. Other options may conflict with each other. For instance, the option to treat
COMPUTATIONAL operands as binary is not valid if the program is being compiled in
RM/COBOL (74) version 2.n-compatible mode. These conditions are not checked when
the configuration file is processed. Rather, they are deferred until the command line
options have also been processed.
COMPILER-OPTIONS are processed in the order they appear in the configuration

file. New options are simply added to old options. If a LISTING-PATHNAME or
OBJECT-PATHNAME occurs more than once, the last occurrence of each is used.
The possible keywords for the COMPILER-OPTIONS record are as follows:
1. ACCEPT-SUPPRESS-CONVERSION. This keyword suppresses automatic input

conversion for Format 1 and 3 ACCEPT statements with numeric operands. If the
value is set to YES, conversion is suppressed. If the value is set to NO, conversion is
performed. The default value is NO.
This keyword corresponds to the compiler M Option. (see page 6-11).
2. BINARY-ALLOCATION. This keyword allows configuration of the allocation

sizes allowed for a binary numeric data item. The value may be specified in any of
the following ways:
BINARY-ALLOCATION=RM specifies the traditional RM/COBOL allocation

scheme of two, four, eight, or sixteen bytes. This is the default configuration.
BINARY-ALLOCATION=RM1 specifies that one- and two-digit binary data items

will be allocated as a single byte. For three to thirty digits, traditional RM/COBOL
allocation of two, four, eight, or sixteen bytes will be used.
BINARY-ALLOCATION=MF-RM specifies that the minimum number of bytes

will be allocated for binary numeric data items consistent with the PICTURE
character-string. This is the traditional Micro Focus COBOL binary allocation
when the IBMCOMP directive is not specified, but modified to use the minimum
number of bytes needed for digit counts of nineteen through thirty. The number of
bytes allocated is described in Table 10-2.
10-6 Configuration
Table 10-2 MF-RM Binary Allocation
Digits in PICTURE character-string Bytes of memory allocated

Signed: S9(n) Unsigned: 9(n)
1-2 1-2 1
3-4 3-4 2
5-6 5-7 3
7-9 8-9 4
10-11 10-12 5
12-14 13-14 6
15-16 15-16 7
17-18 17-19 8
19-21 20-21 9
22-23 22-24 10
24-26 25-26 11
27-28 27-28 12
29-30 29-30 13
BINARY-ALLOCATION=CUSTOM=integer-list specifies a user-selected custom

binary allocation configuration, where integer-list is a comma-separated list of
integers. Each integer in integer-list is 1 through 16 and specifies an allowed
allocation size in bytes. Allocation sizes not listed in integer-list will not be used.
For a custom configuration, the compiler will allocate the minimum number of bytes
allowed by the custom configuration that supports the number of digits described in
the PICTURE character-string for a numeric binary data item. See Table 10-2 for the
minimum number of bytes necessary for a given number of digits.
The RM, RM1, and MF-RM values for the BINARY-ALLOCATION keyword have
the following relationships to the CUSTOM=integer-list value:
• BINARY-ALLOCATION=RM is equivalent to BINARY-

ALLOCATION=CUSTOM=2,4,8,16 when BINARY-ALLOCATION-
SIGNED=YES. When BINARY-ALLOCATION-SIGNED=NO (the default),
the only difference is that 19-digit unsigned binary is allocated with 16 bytes of
storage for RM mode and 8 bytes of storage for the CUSTOM mode.
• BINARY-ALLOCATION=RM1 is equivalent to BINARY-

ALLOCATION=CUSTOM=1,2,4,8,16 when BINARY-ALLOCATION-
SIGNED=YES. When BINARY-ALLOCATION-SIGNED=NO (the default),

the only difference is that 19-digit unsigned binary is allocated with 16 bytes of
storage for RM mode and 8 bytes of storage for the CUSTOM mode.
• BINARY-ALLOCATION=MF-RM is equivalent to BINARY-

ALLOCATION=CUSTOM=1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16. Note,
however, that since 30 digits only require 13 bytes of storage for signed or
unsigned binary, no item will be allocated with 14, 15, or 16 bytes of storage.
Some examples of custom binary allocation are:
• If BINARY-ALLOCATION=CUSTOM=16, all binary items will be

16-bytes long.
• If BINARY-ALLOCATION=CUSTOM=1,4,16, then all one-digit and two-digit

binary items will be 1-byte long, any binary items greater than two digits and
less than ten digits will be 4-bytes long, and all remaining binary items will be
16-bytes long.
Use of the BINARY-ALLOCATION configuration keyword will affect:
• File record structures that include binary data items.
• REDEFINES validity when the subject or object define binary data items.
• Any LINAGE-COUNTER special-registers.
• CALL statement arguments that are binary or are groups that contain binary data
items. This includes CALL statement arguments for the supplied subprogram
library, for example, arguments for C$CARG and C$SCRD.
• Pop-up windows, because the Pop-Up Window Control Block is a group that
contains binary data items that must be allocated a specific number of bytes.
Thus, this configuration capability should be used with care. The binary allocation
override language feature of RM/COBOL (see the USAGE clause in the data
description entry) is more appropriate in situations where the programmer wants to
control the allocated sizes of certain binary data items on a case by case basis. The
binary allocation configuration capability is intended mostly for easing conversion to
RM/COBOL from other COBOL dialects that use a different allocation scheme.
When this configuration keyword is used, it must be used consistently throughout a
programming project, and, in some cases, the binary allocation override language
feature may need to be used to resolve conflicts (for example, when defining
argument data items for the Liant supplied subprogram library).
10-8 Configuration
3. BINARY-ALLOCATION-SIGNED. This keyword causes unsigned binary data
items to be allocated as if they were signed, so that signed and unsigned data items
with the same number of digits will be allocated the same number of bytes of storage.
If the value is set to YES, unsigned binary data items are allocated the same number
of bytes of storage as if they were signed; only the allocation is affected, the data
item is not treated as signed for any other purpose. If the value is set to NO,
unsigned items are allocated the minimum number of bytes necessary to support the
unsigned precision specified by the PICTURE character-string, which for several
cases is one less byte of storage than for the corresponding signed precision. The
default value is NO.
4. COBOL-74. This keyword allows programs created for ANSI COBOL 1974 to be
compiled. If the value is set to YES, ANSI COBOL 1974 semantics and I-O status
values are assumed. If the value is set to NO, ANSI COBOL 1985 semantics and
I-O status values are assumed. The default value is NO.
This keyword corresponds to the compiler 7 Option (see page 6-14).
5. COMPUTATIONAL-AS-BINARY. This keyword, when the value is set to YES,

causes the compiler to treat data items described in the source program as usage
COMP or COMPUTATIONAL as if they had been described as usage BINARY. If
you set the value of this keyword to NO—and do not set a value for the
COMPUTATIONAL-TYPE keyword—usage COMP and COMPUTATIONAL
retain their usual format (see pages C-18 and C-21 for illustrations). The default
value is NO.
Note Setting COMPUTATIONAL-AS-BINARY=YES creates compatibility

between COMP data items and IBM OS/VS COMP data items. This can improve
computational speed at runtime and reduce the amount of storage occupied by a
COMP data item.
When the value is set to YES, this keyword corresponds to the compiler U=B Option
(see page 6-7).
COMPUTATIONAL-AS-BINARY is an obsolete configuration capability retained

for compatibility with existing configuration files. COMPUTATIONAL-AS-
BINARY=YES is equivalent to COMPUTATIONAL-TYPE=BINARY.
COMPUTATIONAL-TYPE and COMPUTATIONAL-AS-BINARY should not be

specified together in the same configuration.

6. COMPUTATIONAL-TYPE. This keyword determines the data format used
for data items described as COMPUTATIONAL or COMP in their data
description entry.
The COMPUTATIONAL-TYPE keyword may be assigned one of the following

values: BINARY, DISPLAY, or PACKED-DECIMAL. If the value is set to
BINARY, the format is the same as if BINARY had been specified in the USAGE
clause in the data description entry. If the value is set to DISPLAY, the format is
the same as if DISPLAY had been specified in the USAGE clause in the data
description entry. If the value is set to PACKED-DECIMAL, the format is the same
as if PACKED-DECIMAL had been specified in the USAGE clause in the data
description entry. If the value is set to UNPACKED-DECIMAL, the format is
the default unpacked decimal format for COMPUTATIONAL data items (see
pages C-11 and C-13 for illustrations). The default data format for
COMPUTATIONAL or COMP data items is UNPACKED-DECIMAL.
Setting COMPUTATIONAL-TYPE=BINARY corresponds to the compiler U=B

Option. Setting COMPUTATIONAL-TYPE=DISPLAY corresponds to the compiler
U=D Option. Setting COMPUTATIONAL-TYPE=PACKED-DECIMAL
corresponds to the compiler U=P Option. See page 6-7.
COMPUTATIONAL-TYPE and COMPUTATIONAL-AS-BINARY should not be

specified together in the same configuration.
7. COMPUTATIONAL-VERSION. This keyword modifies the data format of data

items described as signed COMPUTATIONAL (COMP) and signed
COMPUTATIONAL-3 (COMP-3) in their data description entry. This configuration
option affects the value used for positive sign representation.
The COMPUTATIONAL-VERSION keyword may be assigned one of the following

values: RMCOBOL85, RMCOBOL2 or RMCOS. The RMCOBOL85 value
represents the default positive sign convention for RM/COBOL compilers and causes
UNPACKED data items to use the hexadecimal value 0C to indicate positive values,
and PACKED-DECIMAL data items to use the hexadecimal value C to indicate
positive values. The RMCOBOL2 value selects the positive sign convention for
previous RM/COBOL (74) version 2 compilers and causes UNPACKED data
items to use the hexadecimal value 0B to indicate positive values, and
PACKED-DECIMAL data items to use the hexadecimal value F to indicate
positive values. The RMCOS value selects the positive sign convention for the
RM/COBOL-74 compiler for the RM/COS operating system and causes
UNPACKED data items to use the hexadecimal value 0B to indicate positive values,
and PACKED-DECIMAL data items to use the hexadecimal value B to indicate
positive values.
10-10 Configuration
The RMCOBOL2 and RMCOS options allow applications to access files containing
COMPUTATIONAL and COMPUTATIONAL-3 data items that use previous sign
representations. This keyword has no corresponding Compile Command line option.
The default value is RMCOBOL85.
Note 1 The COMPUTATIONAL-VERSION keyword may be used in conjunction
with the COMPUTATIONAL-TYPE keyword or the compiler U Option (see
page 6-7). For example, by setting COMPUTATIONAL-TYPE=PACKED-DECIMAL
(or the compiler U=P Option in the Compile Command) and COMPUTATIONAL-
VERSION=RMCOBOL2, COMPUTATIONAL data items will be PACKED-
DECIMAL with the RM/COBOL (74) version 2 sign representation.
Note 2 When using the COMPUTATIONAL-VERSION keyword, you cannot
specify an object version level less than 7.
8. DEBUG. This keyword determines whether source programs are to be compiled as
if the WITH DEBUGGING MODE clause appeared in each program. If the value is
set to YES, the debugging mode is selected. If the value is set to NO, debugging
mode is not selected. The default value is NO.
This keyword corresponds to the compiler D Option (see page 6-15).
9. DEBUG-TABLE-OUTPUT. This keyword, when the value is set to YES, causes
the compiler to include both the symbol table and the debug line table in the
object program. Furthermore, when the value is set to ALL, the actual text of
compiler-generated lines that do not appear in source or copy files is also included
in the object file and is available during debugging.
When the debug line table is included in the object program, CodeWatch can display
the program’s source at execution time. Setting YES is sufficient for most purposes.
If ALL is set, the displayed source has the appearance of a printed listing. Note that
this may lead to large object program files. (After debugging is complete, this
information may be removed by the STRIP option in the Combine Program utility
(rmpgmcom), as described in Appendix G, Utilities.)
When the value of this keyword is set to NO, the line table is not included in the
object file. The default value is NO.
Setting DEBUG-TABLE-OUTPUT=YES corresponds to the compiler Y=2 Option.

Setting DEBUG-TABLE-OUTPUT=ALL corresponds to the compiler Y=3 Option.
(See page 6-13 for a description of these options.) Both options imply
SYMBOL-TABLE-OUTPUT=YES (see page 10-16).

10. DERESERVE. This keyword directs the compiler to remove words (and their
associated language features) from the reserved words list. The value of the
DERESERVE keyword is a comma-separated list of those words to be removed from
the reserved words list. All words specified must be found in the compiler reserved
words list. By default, no words are removed from the reserved words list.
This keyword has no corresponding Compile Command line option.
11. FLAGGING. This keyword flags specified elements of the COBOL language in the
listing file. Multiple values are separated by commas. One or more of the following
values may be included in any order:
COM1 INTERMEDIATE
COM2 OBSOLETE
EXTENSION SEG1
HIGH SEG2
COM1 flags COM1 and COM2 elements of the language.
COM2 flags COM2 elements of the language.
EXTENSION flags RM/COBOL extensions to ANSI COBOL 1985.
HIGH flags HIGH elements of the language.
INTERMEDIATE flags HIGH and INTERMEDIATE elements of the language.
OBSOLETE flags obsolete elements of the language.
SEG1 flags SEG1 and SEG2 elements of the language.
SEG2 flags SEG2 elements of the language.
By default, none of the occurrences of the preceding items is flagged. This keyword
corresponds to the compiler F Option (see page 6-15).
12. LISTING-ATTRIBUTES. This keyword determines which information is to be

included in the program listing, and where the program listing will be directed. One
or more of the following values may be included, in any order (multiple values must
be separated by commas):
ALLOCATION-MAP NO-TERMINAL-DISPLAY
CROSS-REFERENCE PRINT-LISTING
ERROR-ONLY-LIST SUPPRESS-COPY-FILES
LISTING-FILE TERMINAL-LISTING
ALLOCATION-MAP generates an allocation map. When set to this value, the
LISTING-ATTRIBUTES keyword corresponds to the compiler A Option (see
page 6-9). By default, the allocation map is not generated.
10-12 Configuration
CROSS-REFERENCE generates a cross reference map. When set to this value, the
LISTING-ATTRIBUTES keyword corresponds to the compiler X Option (see
page 6-11). By default, the cross reference listing is not generated.
ERROR-ONLY-LIST includes only erroneous source lines in the listing file. When
set to this value, the LISTING-ATTRIBUTES keyword corresponds to the compiler
E Option (see page 6-9). By default, the source program component of the listing is
not suppressed.
LISTING-FILE writes a copy of the listing file to disk. When set to this value, the
LISTING-ATTRIBUTES keyword corresponds to the compiler L Option (see
page 6-9). By default, a copy of the listing file is not written to disk.
NO-TERMINAL-DISPLAY suppresses the display of informational messages on the

screen. When set to this value, the LISTING-ATTRIBUTES keyword corresponds
to the compiler K Option (see page 6-7). By default, the informational messages are
displayed.
PRINT-LISTING prints a copy of the listing file. When set to this value, the
LISTING-ATTRIBUTES keyword corresponds to the compiler P Option (see
page 6-10). By default, the listing file is not printed.
SUPPRESS-COPY-FILES directs that text in the copy files not be placed in the
listing file. When set to this value, the LISTING-ATTRIBUTES keyword
corresponds to the compiler C Option (see page 6-9). By default, copy files are
placed into the listing file.
TERMINAL-LISTING displays a copy of the listing file on the screen. When set to
this value, the LISTING-ATTRIBUTES keyword corresponds to the compiler T
Option (see page 6-11). By default, a copy of the listing is not written to the standard
output device.
13. LISTING-DATE-FORMAT. This keyword directs the compiler to use a specific

format for the compilation date in the header lines on listing pages. The value must
be one of the following:
MMDDYY (for month-of-year, day-of-month, year-of-century)

DDMMYY (for day-of-month, month-of-year, year-of-century)
YYMMDD (for year-of-century, month-of-year, day-of-month)
YYDDD (for year-of-century, Julian day-of-year)
MMDDYYYY (for month-of-year, day-of-month, year-of-millennium)
DDMMYYYY (for day-of-month, month-of-year, year-of-millennium)
YYYYMMDD (for year-of-millennium, month-of-year, day-of-month)
YYYYDDD (for year-of-millennium, Julian day-of-year)
The default value is MMDDYYYY.

Note This keyword affects the date inserted for the DATE-COMPILED paragraph.
The same date format used in the listing header is inserted in the DATE-COMPILED
paragraph.
14. LISTING-DATE-SEPARATOR. This keyword directs the compiler to use a
specific separator character for the compilation date in the header lines on listing
pages. The value of this keyword must be a single character-string or a number from
0 to 255. The default value is “/” (47 or 0x2f).
Note This keyword affects the date inserted for the DATE-COMPILED paragraph.
The same date format used in the listing header is inserted in the DATE-COMPILED
paragraph.
15. LISTING-PATHNAME. This keyword directs the compiler to write the program
listing to the indicated directory. When using this keyword, it is not necessary to set
LISTING-ATTRIBUTES=LISTING-FILE.
This keyword corresponds to the compiler L Option (see page 6-9).
16. LISTING-TIME-SEPARATOR. This keyword directs the compiler to use a
specific separator character for the compilation time in the header lines on listing
pages. The value of this keyword must be a single character-string or a number from
0 to 255. The default value is “:” (58 or 0x3a).
17. OBJECT-PATHNAME. This keyword directs the compiler to write the object file
to the indicated directory.
This keyword corresponds to the compiler O Option (see page 6-12).
18. OBJECT-VERSION. This keyword specifies the highest allowed object version
level of code generated by the compiler. The value must be an integer in the range 1
through 8. The default value is the current object version number, 8.
This keyword corresponds to the compiler Z Option (see page 6-14).
19. RESEQUENCE-LINE-NUMBERS. This keyword directs the compiler to generate
a sequential line number in the first six columns of source records as they appear on
the listing. The source file is not affected.
If the value is set to YES, this keyword numbers records beginning with 1 for each
source or copy input file. The number can be helpful when editing the source file.
This line number cannot be used with the RM/COBOL Interactive Debugger.
10-14 Configuration
If the value is set to NO, the compiler will print the source record exactly as read,
including any commentary information present in columns 1 through 6.
The default value for this keyword is NO. This keyword corresponds to the compiler
R Option (see page 6-10).
20. RMCOBOL-2. This keyword allows programs created for the RM/COBOL (74)
version 2.n compiler to be compiled. If the value is set to YES, RM/COBOL (74)
version 2.n programs are accepted. If the value is set to NO, they are not. The
This keyword corresponds to the compiler 2 Option (see page 6-16).
21. SEPARATE-SIGN. This keyword determines whether the compiler is to use a

separate or a combined sign for a signed numeric data item with DISPLAY specified
in the USAGE clause when a SIGN clause is not specified in the data description
entry. If the value is set to YES, a separate sign is assumed. If the value is set to
NO, a combined sign is assumed. The default value is NO.
This keyword corresponds to the compiler S Option (see page 6-7).
22. SEQUENTIAL-FILE-TYPE. This keyword determines the organization of

sequential files not explicitly defined as binary sequential or line sequential in their
SELECT entries.
The SEQUENTIAL-FILE-TYPE keyword may be assigned one the following values:

LINE or BINARY. If the value is set to LINE, all files not defined as binary
sequential are line sequential. If the value is set to BINARY, all files not defined as
line sequential are binary sequential. If this keyword is not configured and no
selection is made at compile time, the decision on whether the file is BINARY or
LINE is deferred to program execution. The choice is then controlled by the
configured DEFAULT-TYPE (see page 10-35).
Setting SEQUENTIAL-FILE-TYPE=BINARY corresponds to the compiler B

Option (see page 6-8). Setting SEQUENTIAL-FILE-TYPE=LINE corresponds to
the compiler V Option (see page 6-8).
23. SUPPRESS-NUMERIC-OPTIMIZATION. The optimized code that the compiler

normally generates for numeric operations assumes that all nonbinary numeric data
items contain only standard digits and signs as described in Appendix C, Internal
Data Formats. Setting the value of the SUPPRESS-NUMERIC-OPTIMIZATION
keyword to a value of YES directs the compiler to generate unoptimized code for all
nonbinary numeric operations. The unoptimized code is more likely to interpret
correctly a nonbinary numeric field that contains nonstandard digits and signs. In
particular, it will treat space characters and binary zero characters as if they were
display zeros, and it will accept a wider range of representations of a positive sign.

The unoptimized code takes longer to execute than the optimized code. The
difference will be noticeable in programs that have a very high density of numeric
operations. When the value of the SUPPRESS-NUMERIC-OPTIMIZATION
keyword is set to NO, the compiler generates the normal, optimized code for numeric
operations.
The default value for this keyword is NO. This keyword has no corresponding
Compile Command line option.
24. SYMBOL-TABLE-OUTPUT. This keyword, when its value is set to YES, causes
the compiler to include the symbol table in the object program. (Note that this
information may be removed by the STRIP option in the Combine Program utility
(rmpgmcom), as described in Appendix G, Utilities.) When the symbol table is
included in the object program, source program data-names and index-names may be
used in Debug commands at execution time (see Chapter 9, Debugging).
When the value of this keyword is set to NO, the symbol table is not included in the
object program. The default value is NO.
Selecting SYMBOL-TABLE-OUTPUT=YES corresponds to the compiler Y Option
(see page 6-13).
25. WORKSPACE-SIZE. This keyword allows the specification of the amount of
workspace area that the compiler will allocate for its internal tables. Control of this
keyword will allow larger programs to be compiled, or memory to be conserved
when compiling small programs on a system with limited memory. This keyword’s
value is a decimal number that reserves memory in increments of 1024 (1 KB) bytes;
for example, a value of 100 would reserve 102400 bytes. The minimum value is 32
and the maximum value is 16384. This keyword may be overridden using the
compiler W Option (see page 6-7).
The default value for this keyword is 1024 kilobytes.
DEFINE-DEVICE Record
The DEFINE-DEVICE record is used to associate a physical device to a value for an
RM/COBOL file access name. The keywords DEVICE and PATH must be present. The
DEFINE-DEVICE record identifier is followed by one or more keywords. If the keyword
is allowed to have a value, it is followed by an equal sign (=) and the value. The possible
keywords are as follows:
1. DEVICE. This keyword specifies the RM/COBOL file access name value that will
be associated with the operating system device. If the value of the DEVICE keyword
is the same as the value specified as the file access name, the value supplied in the
PATH keyword will be used as the actual pathname.
10-16 Configuration
2. PATH. This keyword specifies the pathname to be used as the pathname or pipe for
the device. This value may be enclosed in quotation marks to allow spaces to be
included in a pipe (see the next paragraph). If it necessary to place a quotation mark
in the pipe, use a pair of consecutive quotation marks for each quote within the string.
3. PIPE. This keyword determines whether the value of the PATH keyword is a
process to be spawned. If the value is set to YES, the runtime system will start
another program to simulate a device receiving the record by creating a write-only
pipe and forking a child shell process using the value of the PATH keyword as the
shell’s command. Thus, the value of the PATH keyword specifies the program to
start. If you use quotation marks to enclose the command, any shell command may
be given along with any options. If the value is set to NO, the runtime system will
use the PATH value as the actual pathname. The default value is NO.
Note The PIPE keyword is supported only under UNIX.
4. RAW. This keyword determines whether the Windows printer described by the
value of the PATH keyword is opened in RAW mode. If the value is set to YES,
the runtime system will open the printer in RAW mode. This allows certain
Windows NT networked printers to respond to embedded escape sequences. See
“P$SetRawMode” subprogram in Appendix E, Windows Printing, for a more
complete description of RAW mode. Most P$ subprograms are not available if
RAW mode is used. If the value is set to NO, the runtime system will treat the
printer as a normal Windows printer. The default value is NO.
Note The RAW keyword is supported only under Windows.
5. ESCAPE-SEQUENCES. This keyword determines whether the Windows printer

described by the value of the PATH keyword allows embedded RM/COBOL-specific
escape sequences. See “RM/COBOL-Specific Escape Sequences” in Appendix E for
a more complete description. If the value is set to YES, the RM/COBOL runtime
system will recognize the sequences. If the value is set to NO, the runtime system
will not recognize those escape sequences. The default value is NO.
Note The ESCAPE-SEQUENCES keyword is supported only under Windows.
The presence of a single DEFINE-DEVICE record overrides the automatic internal

configuration for the PRINTER and TAPE support. See the discussions of printer and
tape support on pages 8-46 and 8-47, respectively, for more information.

Windows Printers
The DEFINE-DEVICE record is used to associate a Windows printer device with an

RM/COBOL file access name. It is not possible to bypass the Windows printer drivers by
using the DEFINE-DEVICE record. If the Windows printer driver is used, it is not
possible to send raw escape sequences to the printer. When using DEFINE-DEVICE to
specify a Windows printer, both the DEVICE and PATH keywords are required.
The PATH keyword specifies the Windows printer device to use. The syntax is as
follows:
PATH=[ [Device Name] [, [Port] [, [Font Name] [, [Size] ] ] ]
Device Name is the name of the printer.

The name “DEFAULT” can be used to indicate that the default Windows printer
should be used. If a Device Name is specified, the Port is ignored.
Port specifies the port to which the printer is attached. Port must be defined on the
Details tab for a printer shown in the Printers folder or COBOL I/O error 35 will be
returned from the OPEN statement.
Font Name specifies the font to use.
Size specifies the size of the font to use. It is specified in points.
Note If neither a Device Name nor Port is specified, the default printer is used.
Examples of DEFINE-DEVICE records are as follows:

DEFINE-DEVICE DEVICE=PRINTER PATH=",LPT1"
Note “LPT1” can also be specified as “LPT1:”. The colon is optional.

DEFINE-DEVICE DEVICE=FOO PATH="HP LaserJet"
For compatibility with Windows, whenever a device name followed by the colon
character is encountered in either the DEVICE or PATH keywords, it is treated as if the
colon were not present. For example, the following configuration records:
DEFINE-DEVICE DEVICE=PRN: PATH=",LPT1"
DEFINE-DEVICE DEVICE=LPT2 PATH=",LPT2:"
would be treated as if they were:

DEFINE-DEVICE DEVICE=PRN PATH=",LPT1"
DEFINE-DEVICE DEVICE=LPT2 PATH=",LPT2"
10-18 Configuration
To perform translation of “PRINTERx” names in the same way that the RM/COBOL for
DOS runtime system does, the following default synonym table is used.
DEVICE=PRINTER PATH="DEFAULT"
DEVICE=PRINTER? PATH="DYNAMIC"
DEVICE=PRINTER1 PATH=",LPT1"
The “PRINTER?” synonym is provided to allow dynamic assigning of the Windows at

printer open time. See page 3-15 for more information on the use of “PRINTER?”.
EXTENSION-NAMES Record
The EXTENSION-NAMES record identifier is followed by one or more keywords
indicating file usages. Each keyword is allowed to have a value, and is followed by an
equal sign (=) and the value. More than one file usage keyword may be listed in one
EXTENSION-NAMES record. The extension value must be one to three characters in
length. The extension value may be specified as a single period to indicate that no
extension is to be used for files of the file usage indicated by the keyword. In all other
cases, the characters specified for the extension value must be in the set of characters that
are valid for a filename extension under the current operating system.
The file usage keywords are the following:
1. COPY. This keyword specifies the extension to be used for files referenced by
COPY statements in a COBOL source program. The default extension for copy files
is cbl.
2. LISTING. This keyword specifies the extension to be used for COBOL listing files.
The default extension for listing files is lst.
3. OBJECT. This keyword specifies the extension to be used for COBOL object
program files. The default extension for object files is cob.
4. SOURCE. This keyword specifies the extension to be used for COBOL source
program files. The default extension for source files is cbl.

EXTERNAL-ACCESS-METHOD Record
The EXTERNAL-ACCESS-METHOD record is used to identify external file access
methods that should be applied. It can be repeated more than once to identify multiple
access methods and the order in which they are to be accessed. UNIX supports the
following external access methods: RMPLUSDB, RMINFOX, and USRMTACC.
Windows supports RMBTRV32, RMSPX32, and RMTCP32. (Refer to Chapter 4,
System Considerations for Btrieve, for more information about RMBTRV32).
The EXTERNAL-ACCESS-METHOD record identifier is followed by one or more

keywords. Each keyword is followed by an equal sign (=) and the value to be assigned to
that keyword. The possible keywords are as follows:
1. CREATE-FILES. This keyword controls whether the external access method will
be called to create new files. If the value is set to YES, the external access method
will be allowed to create files. If the value is set to NO, and the file does not exist,
the external access method will not be called to create it. The default value for this
keyword is YES.
2. NAME. This keyword is used to identify the name of the external access method. It
is required and has no default value. The external access method names currently
identified are RMPLUSDB, RMINFOX, and USRMTACC for UNIX, and
RMBTRV32, RMSPX32, and RMTCP32 for Windows.
3. OPTIONS. This keyword is used to pass options to the external access method
interface. The options must be enclosed in quotation marks. The possible values
depend on the external access method that is specified in the NAME keyword. If this
keyword is not specified, no options will be passed to the external access
method interface.
PRINT-ATTR Record
The PRINT-ATTR record is used to describe the characteristics of the printer to which
printer files are assigned or on which printer files will eventually be printed. A printer
file is a line sequential file that has any or all of the following RM/COBOL source
program features:
• ASSIGN TO PRINT or ASSIGN TO PRINTER phrase in the file control entry for
the file
• LINAGE phrase in the file description entry for the file
• ADVANCING phrase in a WRITE statement for the file
The compiler listing is a printer file.
10-20 Configuration
The PRINT-ATTR record identifier is followed by one or more keywords. If the
keyword is allowed to have a value, it is followed by an equal sign (=) and the value. The
possible keywords are as follows:
1. AUTO-LINE-FEED. This keyword determines whether a line feed is needed after a

carriage return to cause a single line advance of the carriage. If the value is set to
YES, a single line advance is automatic so no line feed character will be written. If
the value is set to NO, a single line advance is not automatic, thus requiring a line
feed character. The default value is NO.
2. COLUMNS. This keyword determines the number of columns across a line,

represented as a decimal number in the range 1 through 65280. All records written to
a printer file will be truncated to this value. The default value is not to truncate.
3. FORM-FEED-AVAILABLE. This keyword indicates whether the printer supports

the form feed character, FF, to slew to the top of a new page. If the value is set to
NO, top-of-page will be reached by issuing an appropriate number of line feeds; the
LINES keyword should be used to describe the page size. If the value is set to YES,
top-of-page will be reached by writing a form feed character. The default value is
YES.
Note This option only determines the method used by the runtime I-O system to
position the file to a new physical page. The runtime I-O system would normally
print a form feed character to accomplish a physical page break. If the user's printer
does not support advancing to the next physical page when a form feed character is
printed, the value of this option can be set to NO to tell the runtime I-O system not to
use a form feed character for this purpose. Regardless of the setting of this option,
files described with the LINAGE clause do not normally use physical page breaks
because the LINAGE clause describes logical rather than physical pages. Files
described with the LINAGE clause will be affected by this option only if either of the
PRINT-ATTR configuration record keywords LINES or LINAGE-PAGES-PER-
PHYSICAL-PAGE are set to a nonzero value.
4. LINAGE-INITIAL-FORM-POSITION. This keyword determines the assumed

initial position of the form in the printer for a file described with the LINAGE clause
(see page 8-43). If set to TOP-OF-FORM, the form is assumed to be positioned at
the top of the page (that is, on the first line of the top margin). In this case, the
runtime writes the first line after advancing over the top margin of the first page so as
to reach the first line of the logical page body. The value TOP-OF-FORM would
normally be used for page printers that do not use continuous forms. If set to
PAGE-BODY-LINE-1, the form is assumed to be positioned at line one of the page
body and the runtime ignores the top margin specified for the first logical page. The
value PAGE-BODY-LINE-1 would normally be used with line printers that use

continuous forms that have been positioned by the operator to print the first line of
the logical page body. The default value is PAGE-BODY-LINE-1.
5. LINAGE-PAGES-PER-PHYSICAL-PAGE. This keyword determines whether

physical page breaks are generated for files described with the LINAGE clause (see
page 8-43). When this keyword is set to the value 0, the set of logical pages is
printed contiguously with no additional spacing provided between logical pages,
except as explained in the note regarding the PRINT-ATTR configuration keyword
LINES. Form feed characters, in particular, are not normally used between pages.
When this keyword is set to a value from 1 to 255, the value indicates the number of
logical pages that fit on a physical page. Each time that many pages have been
printed, a physical page break will be generated. For example, a value of 1 causes a
physical page break (see the note below for additional details on physical page
breaks) between each logical page. As another example, assuming that there are
three logical pages (for example, checks) per physical page, a value of 3 could be
used to cause a physical page break between each set of three logical pages. A
nonzero value is typically useful for page printers when the logical page, or a set of
logical pages, does not fill a physical page. A zero value is typically useful for line
printers using continuous forms. The default value is 0.
Note This option instructs the runtime I-O system to insert a physical page break
between certain logical pages. The physical page break is normally a form feed
character. However, the PRINT-ATTR configuration record keyword settings
FORM-FEED-AVAILABLE=NO and LINES=n may be used together in those cases
where a form feed character is either not available or not desirable. In this case, a
physical page break is accomplished by printing the number of line feed characters
necessary to ensure n lines per physical page.
6. LINES. This keyword determines the number of lines on a page, represented

as a decimal number in the range 1 through 65535. Use this keyword when
FORM-FEED-AVAILABLE=NO (see the preceding keyword). This keyword may
be used with FORM-FEED-AVAILABLE=YES to cause form feed characters to be
placed in the file after the specified number of lines have been written. The default
value is not to have page size processing.
This keyword also determines the number of lines on a page of a compilation listing.
If not specified, the RM/COBOL compiler assumes 66 lines per page.
Note This option, when set to a nonzero value, will cause files described with the
LINAGE clause to advance to a new physical page whenever that number of lines
have been printed. This may result in unintended additional spacing between or
within logical pages, depending on the relationship between the value specified for
LINES and the size(s) of logical pages. For page printers, setting LINES to the size
of the logical page may have the desired effect of ejecting pages from the printer
10-22 Configuration
when a logical page is complete. However, the PRINT-ATTR configuration record
keyword LINAGE-PAGES-PER-PHYSICAL-PAGE, which only affects files
described with the LINAGE clause, is better suited to this purpose.
7. TOP-OF-FORM-AT-CLOSE. This keyword determines whether the printer file is

positioned to top-of-form when closed. If the value is set to YES, the printer file will
be positioned to top-of-form with form feed or line feed characters. If the value is set
to NO, no additional control characters will be written when the printer file is closed.
The default value is NO.
8. WRAP-COLUMN. This keyword determines the column number after which

automatic line wrap-around occurs, represented as a decimal number in the range 1
through 65535. The default value is to assume that the printer does not automatically
wrap long lines.
9. WRAP-MODE. This keyword specifies whether automatic line wrapping occurs

when the WRAP-COLUMN character is written. If the value is set to EXACT,
wrapping occurs when the WRAP-COLUMN character is written. If the value is set
to NEXT, wrapping occurs when the character following the WRAP-COLUMN
character is written.
RUN-ATTR Record
The RUN-ATTR record identifier is followed by one or more keywords. If the keyword
is allowed to have a value, it is followed by an equal sign (=) and the value. The
following descriptions include the default values that are used if the keyword is not
modified by a RUN-ATTR record. The possible keywords are as follows:
1. ACCEPT-FIELD-FROM-SCREEN. This keyword controls the behavior of

ACCEPT statements that do not specify either the PROMPT or the UPDATE phrase.
If the value is set to YES, the field is initialized with the current contents of the field
on the display. If the value is set to NO, the field is initialized to all blanks. The
default value is NO. In either case, the contents of the field as displayed are
unchanged.
Only fields output by the RM/COBOL runtime system can be reliably retrieved. The
contents of a field that appeared on the display prior to the invocation of the runtime
are considered undefined.
2. ACCEPT-INTENSITY. This keyword determines the default intensity level used

within ACCEPT statements. If the value is set to HIGH, high intensity is used.
If the value is set to LOW, low intensity is used. The default ACCEPT intensity
value is HIGH.

3. ACCEPT-PROMPT-CHAR. This keyword enables the ACCEPT statements
default prompt character to be overridden with the character corresponding to the
value of the keyword. Changing the default prompt character does not affect
ACCEPT statements that do not use the PROMPT phrase. The value of this keyword
must be a single character-string or a number from 0 to 255. The default value is “_”
(95 or 0x5F).
4. BEEP. This keyword determines whether the runtime system should override the
beeps (BEEP) that are coded in ACCEPT and DISPLAY statements. If the value
is set to YES, the beeps that are coded in the statements (including the default beeps
on ACCEPT statements) cause the terminal to beep. If the value is set to
FORCED-ACCEPT, all Format 3 ACCEPT statements cause the terminal to beep;
all other ACCEPT and DISPLAY statements behave as if the value were set to YES.
If the value is set to NO, the beeps that are coded in the statements are ignored. The
default value is YES.
5. BLINK. This keyword determines whether the runtime system should override
blinking (BLINK) coded in the ACCEPT and DISPLAY statements. If the value is
set to YES, blinking is used as directed by the statements. If the value is set to NO,
blinking is not used. The default value is YES.
Note The blinking attribute is not available under Windows.
6. DISPLAY-INTENSITY. This keyword determines the default intensity level used

within DISPLAY statements. If the value is set to HIGH, high intensity is used. If
the value is set to LOW, low intensity is used. The default DISPLAY intensity is
HIGH.
7. EDIT-COMMA. This keyword enables the comma edit character (thousands

separator) to be overridden with the character corresponding to the value of the
keyword. This configuration option is not affected by the presence of the
DECIMAL-POINT IS COMMA clause in the source program, except for the default
value. The value of this keyword must be a single character-string or a number from
0 to 255. The default value is “,” (44 or 0x2c), or, if DECIMAL-POINT IS
COMMA clause is specified in the source program, the default is “.” (46 or 0x2e).
8. EDIT-CURRENCY-SYMBOL. This keyword enables the currency symbol edit

character (cs) to be overridden with the character corresponding to the value of the
keyword. This keyword has effect only when a CURRENCY SIGN IS clause is
present in the Configuration Section of the program. This configuration option does
not affect the currency sign ($) (see the EDIT-DOLLAR keyword for overriding the
currency sign value). The value must be a single character-string or a number from 0
to 255. The default value is “$” (36 or 0x24).
10-24 Configuration
9. EDIT-DECIMAL. This keyword enables the decimal point edit character to be
overridden with the character corresponding to the value of the keyword. This
configuration option is not affected by the presence of the DECIMAL-POINT IS
COMMA clause in the source program, except for the default value. The value of
this keyword must be a single character-string or a number from 0 to 255. The
default value is “.” (46 or 0x2e), or, if the DECIMAL-POINT IS COMMA clause is
specified in the source program, the default is “,” (44 or 0x2c).
10. EDIT-DOLLAR. This keyword enables the currency sign ($) to be overridden with
the character corresponding to the value of the keyword. This configuration option is
not affected by the presence of the CURRENCY SIGN clause in the source program,
unless the program specifies CURRENCY SIGN IS “$”. In that case, the “$” in that
program is the currency symbol and the EDIT-DOLLAR keyword has no effect.
(See the EDIT-CURRENCY-SYMBOL keyword for overriding the currency symbol
value.) The value must be a single character-string or a number from 0 to 255. The
default value is “$” (36 or 0x24).
11. ERROR-MESSAGE-DESTINATION. This keyword determines the destination to

which the runtime system should direct error messages, Interactive Debugger input
and output, STOP literal messages and STOP RUN messages. ACCEPT . . . FROM
CONSOLE and DISPLAY . . . UPON CONSOLE are not affected by this keyword.
The two possible values are STANDARD-ERROR and STANDARD-INPUT-OUTPUT.
If the value is set to STANDARD-ERROR, these messages are directed to the
standard error device. If the value is set to STANDARD-INPUT-OUTPUT,
these messages are written to standard output and, in the cases of Debug input and
STOP literal message operator responses, the responses are read from standard input.
The value STANDARD-ERROR does not allow redirection of the messages;
STANDARD-INPUT-OUTPUT does allow redirection. The default value is
STANDARD-ERROR. (See page 2-22 for information on the standard input, output,
and error devices.)
12. REVERSE. This keyword determines whether the runtime system should override
reverse video (REVERSE) coded in the ACCEPT and DISPLAY statements. If the
value is set to YES, reverse video is used as directed by the statements. If the value
is set to NO, reverse video is not used. The default value is YES.
13. SCROLL-SCREEN-AT-TERMINATION. This keyword determines whether the

runtime system should scroll the screen by one line before returning to the shell. If
the value is set to NO, the screen is not scrolled. If the value is set to YES, the screen
is scrolled only if the COBOL program performed any screen I/O, such as ACCEPT
or DISPLAY statements. The default value is YES.

14. TAB. This keyword controls the default behavior of ACCEPT statements that do not
have a TAB phrase. If the value of the keyword is set to YES, ACCEPT statements
are executed as if the TAB phrase were present. If value is set to NO, ACCEPT
statements are executed as if the NO TAB keyword were present in the CONTROL
phrase. The default value is NO.
15. UNDERLINE. This keyword determines whether the runtime system should
override underlining (UNDERLINE) coded in the Screen Section or the CONTROL
phrase of ACCEPT and DISPLAY statements. If the value is set to YES, underlining
is used as directed by the statements. If the value is set to NO, underlining is not
used. The default value is YES.
For complete descriptions of the ACCEPT and DISPLAY statements, see Chapter 6,
Procedure Division Statements, of the RM/COBOL Language Reference Manual.
RUN-FILES-ATTR Record
The RUN-FILES-ATTR record identifier is followed by one or more keywords. If the
keyword is allowed to have a value, it is followed by an equal sign (=) and the value.
Some of the following keywords are allowed on both the RUN-FILES-ATTR record and
on the RUN-INDEX-FILES, RUN-REL-FILES, and RUN-SEQ-FILES records. For
these keywords, specifying a value on a RUN-FILES-ATTR record is equivalent to
specifying the same value on RUN-INDEX-FILES, RUN-REL-FILES, and RUN-SEQ-
FILES records. If a keyword exists on both a RUN-FILES-ATTR and on a RUN-xxx-
FILES record, then the last one in the configuration file will be used. The possible
1. ALLOW-EXTENDED-CHARS-IN-FILENAMES. This keyword controls

whether extended characters in the range 128 through 255 (0x80 through 0xFF) are
allowed in filenames. If this keyword is set to YES, these characters are allowed. If
this keyword is set NO, these characters are excluded from filenames. The default
value is NO.
Note This keyword is supported only under Windows.

2. BLOCK-SIZE. This keyword determines the default disk block size for all file
organizations except program files, represented as a decimal number. It can be
overridden by a configuration record for a particular organization. A program can
override this with the BLOCK CONTAINS clause in the file description entry. The
maximum value is 65489. The minimum value is 256. Under UNIX, the default
value is BUFSIZ, taken from the C include file <stdio.h>. Under Windows, the
default value is the disk sector size. Program files always use 512-byte blocks.
3. BUFFER-POOL-SIZE. This keyword determines the amount of memory that
should be allocated in the disk buffer pool, represented as a decimal number. The
10-26 Configuration
maximum value is 664838. The minimum value is 1. A value of 1 will cause the
minimum disk buffer pool to be allocated. The default value is 20480 for the
compiler and 256000 for the runtime system.
4. DISABLE-COMMIT-FILE. This keyword can be used to prevent the use of the
DOS Commit File function. If the value is set to YES, then the Commit File function
will never be used. If the value is set to NO, and the Commit File function is
available, then it will be used to flush data to the disk. The default value is NO.
5. ENABLE-OLD-DOS-FILENAME-HANDLING. This keyword controls whether
filenames are processed in the way they were handled in earlier DOS runtimes. If
this keyword is set to YES, filenames are converted to uppercase, all spaces are
eliminated, and each node name (characters between separators) is truncated to 8.3
format. For example, the filename “c:\long directory.name\long filename.extension”
would become “C:\LONGDIRE.NAM\LONGFILE.EXT”. If this keyword is set to
NO, filenames remain in mixed case, spaces are allowed, and long node names are
allowed (that is, no truncation). The default value is NO.

6. EXPANDED-PATH-SEARCH. This keyword controls when the directory search
sequence is used. If a filename is specified with no directory path, the directory
search sequence will always be used. If the filename begins with a forward slash (/),
a backward slash (\), or a tilde (~), the directory search sequence will not be used. If
the filename contains a directory path that does not begin with a slash or tilde, the
directory search sequence will be used only if this keyword is set to YES. In this
case, the entire name, including the directory path, will be appended to each entry in
the directory search sequence. The default value for this keyword is NO.
7. FATAL-RECORD-LOCK-TIMEOUT. This keyword affects record locking. For
file descriptors whose file control entry has no FILE STATUS clause and file
descriptors that have no USE declarative procedure defined, this keyword determines
how many seconds to wait when attempting to lock a record that is locked by another
run unit before returning a fatal error to the calling program. A value of 0, the
default value, indicates an infinite wait. The minimum value is 0, and the maximum
value is 65,535 seconds.
If the record is locked using a different file descriptor in the same run unit, the error
will always be returned immediately to prevent a deadlock situation.
8. FILE-HANDLE-LIMIT. This keywords determines the number of file handles the
RM/COBOL file management system may use. The default value is 255.

9. FILE-LOCK-LIMIT. This keyword determines the limit for the location to apply
locks to a file. This number can vary depending on the system on which the file
resides. The lock limit applies to all file organizations. For record and file locks to
perform correctly, all run units opening a file must use the same file lock limit. The
lock limit also limits the actual amount of data that can be stored in a file. This data
limit is dependent on the file organization. Sequential and relative files can store
slightly less than half this number. For indexed files, the data size limit varies with
the block size: a block size of 1024 will allow eighty percent of this number for data
storage; a block size of 4096 will allow over ninety percent. The maximum value is
07FFFFFFEh (approximately two gigabytes). The minimum value is 1. The default
value is 07FFFFFFEh.
For information on superseding the limit for the location to apply locks to a file that
will be accessed as a large file, see the description of the LARGE-FILE-LOCK-
LIMIT keyword later in this section.
10. FILE-PROCESS-COUNT. This keyword determines the maximum number of run
units that can have a file open at the same time. It applies to all file organizations.
For record and file locks to perform correctly, all run units opening a file must use
the same file process count. The maximum value is 4096. The minimum value is 8.
The default value is 1024.
11. FORCE-USER-MODE. This keyword determines whether the runtime system

should assume a single-user or a shared environment. If the value is set to SINGLE,
local files are locked and treated as if they were unshared. If the value is set to
MULTI, local files are treated as if they were shared, and locks are applied as
specified in OPEN statements. This keyword does not affect remote files. Remote
files are always assumed to be in a shared environment. The default value is MULTI.
12. KEEP-FLOPPY-OPEN. This keyword determines whether the runtime system will
open and close program and message files that reside on a floppy drive every time it
accesses them. If the value is set to NO, the RM/COBOL file management system
closes these files as often as possible in order to prevent floppy corruption problems
that can occur when swapping diskettes during a program execution. If the value is
set to YES, the RM/COBOL file management system will not attempt to close
floppy-based program and message files after every access. The default value is NO.
13. LARGE-FILE-LOCK-LIMIT. This keyword determines the limit for the location
to apply locks to a file that will be accessed as a large file, superseding the limit
specified by the FILE-LOCK-LIMIT keyword. For record and file locks to perform
correctly, all run units opening a particular file must use the same file lock limit. The
lock limit also limits the actual amount of data that can be stored in a file. (See the
10-28 Configuration
description of the FILE-LOCK-LIMIT keyword, described earlier in this section, for
details on this relationship.) The value assigned to this keyword is specified in
gigabytes (GB). The maximum value is 1048576, which equates to 1 petabyte (250).
The minimum value is 1. The default value is 64.
For an explanation of how to indicate that a relative file or a sequential file will be
accessed as a large file, see the description of the USE-LARGE-FILE-LOCK-LIMIT
configuration keyword of the RUN-REL-FILES and RUN-SEQ-FILES records on
page 10-34. See the description of File Version Level 3 on page 8-65 and the
description of the DEFAULT-FILE-VERSION-NUMBER configuration keyword
of the RUN-INDEX-FILES record on page 10-31 for information on using the
LARGE-FILE-LOCK-LIMIT with indexed files.
14. RESOLVE-LEADING-NAME. This keyword controls when the first directory
name specified in a file access name is resolved from the environment. The first
directory name is defined as a name that is not preceded by a slash character. Under
Windows, the slashes that may appear in a volume name are ignored. If the name is
not found in the environment, no substitution will occur, and the name will remain as
specified (after the possible removal of the leading character). There are several
possible values for this keyword, including ALWAYS, NEVER, or one of these
seven leading characters: !, @, #, $, %, ^, or &.
If RESOLVE-LEADING-NAME is set to ALWAYS, and the directory name exists
in the environment, the value of the environment variable will replace the name. If
RESOLVE-LEADING-NAME is set to one of the seven leading characters, the
directory name begins with that character, and the directory name without that
character exists in the environment, then the value of that environment variable will
replace the name. If the value is set to NEVER, then the leading directory name will
never be replaced. The default value for this keyword is NEVER.
In the special case that the file access name does not contain any directory specifiers,
substitution will always be attempted.
For example, if the environment contains a variable name DIR with the value
MYDIR, and does not contain the variable D1, the following substitutions would
occur.
Name Specified RESOLVE-LEADING-NAME value
ALWAYS NEVER @
DIR/FILE MYDIR/FILE DIR/FILE DIR/FILE

@DIR/FILE @DIR/FILE @DIR/FILE MYDIR/FILE
@D1/FILE @D1/FILE @D1/FILE D1/FILE
DIR MYDIR MYDIR MYDIR
@DIR @DIR @DIR MYDIR

15. RESOLVE-SUBSEQUENT-NAMES. This keyword controls when directory
names or the filename specified in a file access name are resolved from the
environment. It does not apply to the leading name (see RESOLVE-LEADING-NAME
keyword, described previously). If the name is not found in the environment, no
substitution will occur, and the name will remain as specified (after the possible
removal of the leading character). There are several possible values for this
keyword, including ALWAYS, NEVER, or one of these seven leading characters:
!, @, #, $, %, ^, or &.
If RESOLVE-SUBSEQUENT-NAMES is set to ALWAYS, and the directory or

filename exists in the environment, the value of the environment variable will replace
the name. If RESOLVE-SUBSEQUENT-NAMES is set to one of the seven leading
characters, the directory or filename begins with that character, and the directory or
filename without that character exists in the environment, then the value of that
environment variable will replace the name. If the value is set to NEVER,
the directory or filename will never be replaced. The default value for this keyword
is NEVER.
For example, if the environment contains a variable name DIR with the value
MYDIR, a variable name FILE with the value MYFILE, and does not contain the
variable D1, the following substitutions would occur.
Name Specified RESOLVE-SUBSEQUENT-NAMES value

ALWAYS NEVER @
DIR/FILE DIR/MYFILE DIR/FILE DIR/FILE
/DIR/@FILE /MYDIR/@FILE /DIR/@FILE /DIR/MYFILE
/@D1/FILE /@D1/MYFILE /@D1/FILE /D1/FILE
16. USE-PROCEDURE-RECORD-LOCK-TIMEOUT. This keyword affects record

locking. For file descriptors whose file control entry has a FILE STATUS clause and
for which a USE declarative procedure is defined, it determines how many seconds to
wait when attempting to lock a record that is locked by another run unit before
returning an error to the calling program. A value of 0, the default value, indicates
that the error should be returned immediately. The minimum value is 0, and the
maximum value is 65,535 seconds.
If the record is locked using a different file descriptor in the same run unit, the error
is always returned immediately to prevent a deadlock situation.
10-30 Configuration
RUN-INDEX-FILES Record
The RUN-INDEX-FILES record identifier is followed by one or more keywords. If the
1. ALLOCATION-INCREMENT. This keyword determines the allocation increment

of indexed files created by the runtime system. The value is the decimal number
of blocks to be added to the file. The maximum value is 9999. The minimum value
is 1. The default value is 8.
2. ATOMIC-TRANSFER-SIZE. This keyword informs the RM/COBOL file

management system of the maximum block size that the network software will
transmit as a single atomic entity. The maximum value is 65536. The minimum
value is 0. The default value is 65536.
If an indexed file has a block size greater than this value, then the RM/COBOL file
management system will not perform certain network optimizations. If this keyword
has a value of zero, the optimizations are disabled for all indexed files.
3. BLOCK-SIZE. This keyword determines the default sector size, represented as a

decimal number. The sector size is used by the runtime system when creating an
indexed file to determine the default block size. A program can override this with the
BLOCK CONTAINS clause in the file description entry (see the discussion of this
clause in Chapter 4, Data Division, of the RM/COBOL Language Reference
Manual). The maximum value is 65489. The minimum value is 256. Under UNIX,
the default value is BUFSIZ, taken from the C include file <stdio.h>. Under
Windows, the default value is the disk sector size.
4. DATA-COMPRESSION. This keyword determines whether the indexed files

created by the runtime system use data compression. If the value is set to YES, data
compression is used. If the value is set to NO, data is stored in uncompressed form.
The default value is YES.
5. DEFAULT-FILE-VERSION-NUMBER. This keyword determines the default file

version number for new files when an OPEN OUTPUT is performed. The version
number for existing files or files predefined with the Define Indexed File utility
(rmdefinx), as described in Appendix G, Utilities, will not be changed when an
OPEN OUTPUT is performed. Allowable values are 0, 2, and 3. The default value
is 2.
6. FORCE-CLOSED. This keyword determines whether an indexed file created by

the runtime system is marked closed on disk between file modification operations.
If the value is set to YES, the file header is marked open at the beginning of a
DELETE, REWRITE, or WRITE operation and marked closed at the end of the

operation. This minimizes the risk that a power interruption would necessitate a
recovery of the indexed file. If the value is set to NO and the file is opened I-O,
OUTPUT, or EXTEND, any power interruption will require a recovery of the
indexed file. The default value is NO.
7. FORCE-DATA. This keyword determines—for an indexed file created by the

runtime system and opened WITH LOCK—whether the runtime system forces data
blocks to be given to the operating system when modified. If the value is set to YES,
data block write requests are issued to the operating system whenever information is
changed. If the value is set to NO, data block write requests are made as dictated by
buffer space. The default value is NO.
8. FORCE-DISK. This keyword determines—for an indexed file created by the

runtime system—whether the runtime system forces disk blocks to be written to
disk when modified. If the value is set to YES, blocks written to the operating
system are forced to be written to disk as well. If the value is set to NO, blocks
written to the operating system remain in the operating system buffer pool. The
9. FORCE-INDEX. This keyword determines—for an indexed file created by the

runtime system and opened WITH LOCK—whether the runtime system forces index
blocks to be given to the operating system when modified. If the value is set to YES,
index block write requests are issued to the operating system whenever the index
block is changed. If the value is set to NO, index block write requests are made as
buffer space dictates. The default value is NO.
10. KEY-COMPRESSION. This keyword determines whether the indexed files created
by the runtime system use key compression. If the value is set to YES, key
compression is used. If the value is set to NO, keys are stored in uncompressed form.
The default value is YES.
10-32 Configuration
RUN-OPTION Record
The RUN-OPTION record identifier is followed by one or more keywords. If the
1. B. This keyword controls the default ACCEPT and DISPLAY buffer size and is
represented as a decimal number. The maximum value is 65280. The minimum
value is 1. A default value specified with this keyword may be overridden by the
runtime B Option (see page 7-4).
2. ENABLE-LOGGING. This keyword controls the generation of various error and

information log files. The LOG-PATH keyword (described below) must be included
to specify the location of the directory for the log file. By default, no logging is
performed. Multiple keyword values are separated by commas. One or more of the
following values may be included:
ALL
TERMINATION
PERM-OS-ERRORS
ENABLE-LOGGING=ALL turns on all logging.
ENABLE-LOGGING=TERMINATION turns on logging of termination errors,

including all traceback information. The log file generated is named
RMTERM.LOG. Note that termination logging is available only for Windows.
UNIX users should continue to redirect standard error (STDERR).
ENABLE-LOGGING=PERM-OS-ERROR turns on logging of detailed information

about errors encountered by the runtime when making operating system (OS) calls.
This is normally turned on only at the request of a Liant support representative. The
log file generated is named RMOSERR.LOG.
3. K. This keyword controls the suppression of the banner notice and the STOP RUN
message. If the value is set to SUPPRESS, the banner notice and STOP RUN
message are suppressed. If the value is set to DISPLAY, the suppression of the
banner notice and the STOP RUN message is controlled by the runtime K Option
(see page 7-3). The default value is DISPLAY.
4. LOG-PATH. This keyword specifies the location (directory) where the log file (as
specified in the ENABLE-LOGGING keyword above) will be written. The directory
must already exist before the runtime is started, and the user must have create and
write permission for the directory. The runtime will create the log file, if necessary,
and the file will be opened in append mode.

5. M. This keyword controls which level of ANSI semantics is used with ACCEPT
and DISPLAY statements. If the value is set to 2, ANSI level 2 semantics are used.
If the value is set to 1, the level of ANSI semantics is controlled by the runtime
M Option (see page 7-4). The default value is 1.
RUN-REL-FILES Record
The RUN-REL-FILES record identifier is followed by one keyword. The keyword is
followed by an equal sign (=) and a value. The possible keyword is as follows:
1. BLOCK-SIZE. This keyword determines the default block size, represented as a

decimal number, for relative files opened WITH LOCK. The maximum value is
65489. The minimum value is 0, which specifies that the default value is no
blocking. The presence of a BLOCK CONTAINS phrase in the file description entry
of an unshared relative file forces that file to be blocked, even if no blocking is
specified by this keyword. The default value is BUFSIZ, taken from the C include
file <stdio.h>, if the file is opened for RANDOM access. Under UNIX, if the file is
opened for DYNAMIC or SEQUENTIAL access, the default value is BUFSIZ, taken
from the C include file <stdio.h>, or 4096, whichever is larger. Under Windows, the
default value is the disk sector size or 4096, whichever is larger.
2. USE-LARGE-FILE-LOCK-LIMIT. This keyword determines which value to

use for the limit when applying locks to a relative file. If the value of this keyword
is set to NO, the value of the FILE-LOCK-LIMIT configuration keyword
of the RUN-FILES-ATTR record is used. If the value is set to YES, the value of the
LARGE-FILE-LOCK-LIMIT configuration keyword is used. (For a description of
these keywords in the RUN-FILES-ATTR record, see page 10-26.) For record and
file locks to perform correctly, all run units opening a file must use the same file lock
limit. The default value is NO.
RUN-SEQ-FILES Record
The RUN-SEQ-FILES record identifier is followed by one or more keywords. If the
1. BLOCK-SIZE. This keyword determines the default block size represented as a

decimal number, for sequential disk files opened WITH LOCK. The maximum value
is 65489. The minimum value is 0, which specifies that the default value is no
blocking. The presence of a BLOCK CONTAINS phrase in the file description entry
of an unshared sequential file forces that file to be blocked, even if no blocking is
specified by this keyword. Under UNIX, the default value is BUFSIZ, taken from
10-34 Configuration
the C include file <stdio.h>, or 4096, whichever is larger. Under Windows, the
default value is the disk sector size or 4096, whichever is larger.
2. DEFAULT-TYPE. This keyword determines whether unspecified sequential files

are line sequential or binary sequential. If the value is set to BINARY, unspecified
sequential files are binary sequential. If the value is set to LINE, unspecified
sequential files are line sequential. The default value is BINARY.
3. DEVICE-SLEWING-RESERVE. This keyword determines the number of

character positions to be reserved for form feed and line feed characters. The value
for this keyword is a decimal number. The maximum value is 999. The minimum
This keyword applies to line sequential files written directly to a nontape device. It
also applies to line sequential files on disk that are not opened WITH LOCK or are
not blocked. The value required for this keyword is generally the maximum value
specified by any BEFORE/AFTER ADVANCING phrase in a WRITE statement in
the program, plus 2. This value is configurable for performance considerations only,
since it enables the record—along with the appropriate number of control
characters—to be written in one write request. If the value specified for this keyword
is less than the maximum specified by the BEFORE/AFTER ADVANCING phrase,
the operation will be performed correctly, but will require more than one write
request to complete the operation.
4. TAB-STOPS. This keyword determines an ascending sequence of tab stop columns
represented as decimal numbers separated by commas. Up to 18 tab stop columns
are allowed. TAB-STOPS=0 specifies that no tab stop columns exist. The default
TAB-STOPS sequence is 8, 12, 16, 20, 24, 28, 32, 36, 40, 44, 48, 52, 56, 60, 64,
68, 72.
5. USE-LARGE-FILE-LOCK-LIMIT. This keyword determines which value to use
for the limit when applying locks to a sequential file. If the value of this keyword is
set to NO, the value of the FILE-LOCK-LIMIT keyword of the RUN-FILES-ATTR
record is used. If the value is set to YES, the value of the LARGE-FILE-LOCK-
LIMIT configuration keyword is used. (For a description of these keywords in the
RUN-FILES-ATTR record, see page 10-26.) For record and file locks to perform
correctly, all run units opening a file must use the same file lock limit. The default
value is NO.

RUN-SORT Record
The RUN-SORT record identifier is followed by one or more keywords. If the keyword is
allowed to have a value, it is followed by an equal sign (=) and the value. The possible
1. INTERMEDIATE-FILES. This keyword determines the number of intermediate

sort files represented as a decimal number. The maximum value is 9. The minimum
2. MEMORY-SIZE. This keyword determines the default sort memory size

represented as a decimal number. The maximum value is available memory. The
minimum value is 0. If unspecified, the default sort memory size is 256000 bytes.
The maximum allowed value is 2147483647 bytes. If the MERGE or SORT
statements are used in the run unit, sort memory size must be non-zero.
TERM-ATTR Record
The TERM-ATTR record provides information about terminal attributes. The
TERM-ATTR record identifier is followed by one or more keywords. If the keyword is
allowed to have a value, it is followed by an equal sign (=) and the value. The possible
1. BCOLOR. This keyword indicates the initial background color value to use for
ACCEPT and DISPLAY statements. The terminal will be restored to this color when
the run unit ends. The default color value is BLACK.
Note Under Windows, the default background color is determined by the system
settings. In particular, the default background color is the default “window
background” color.
2. CHARACTER-TIMEOUT. This keyword sets the time-out period related to the

inter-character timer used by the RM/COBOL runtime system when processing input
sequences. The timer is used to determine whether a character is a final character in
a sequence. The default wait time before deciding that no more characters are
pending is .5 seconds. The inter-character timer may need to be increased on certain
systems or in some cases when the user is logged in from a network (rlogin). The
value for the CHARACTER-TIMEOUT keyword is specified in tenths of seconds.
Note 1 This keyword is supported only under UNIX.
Note 2 The value of the inter-character timer also affects the BEFORE TIME
phrase of the ACCEPT statement (see page 8-21).
10-36 Configuration
3. COLUMNS. This keyword determines the number of columns the runtime system
will display on the terminal screen, represented as a decimal number between 1 and
255. The default value is 80.
4. DATA-CHARACTERS. This keyword has as its value a comma-separated pair of

decimal integers. The first number is the lower bound of characters to be interpreted
as text characters. The second number is the upper bound of characters to be
interpreted as text characters. On input, characters not in this range and not part of
a TERM-INPUT sequence (see page 10-41) are illegal. The default range is 20h
to 7Eh.
5. DBCS-CHARACTERS. This keyword enables support for double-byte character

set (DBCS) characters and specifies the lead-byte character ranges.
In DBCS, a character is represented by either one or two bytes. Double-byte

character set characters have the following components:
• Lead byte. If the value of this byte falls into the lead-byte range, a DBCS
character is indicated.
• Trail byte. This byte further refines the selected character. The trail byte can
have any value except zero (0), but is typically restricted to a subset of all
possible characters.
Double-byte character set characters occupy two, physically adjacent positions on the
screen and are usually displayed as a double-width character.
Double-byte character set characters, however, are not the same as “wide” characters.
In a wide-character set, such as Unicode, all characters are represented by two bytes,
which provides up to 65,536 characters. In DBCS, the value of the first byte
determines whether the second byte is considered part of the current character.
Values for this keyword are specified as a pair of numbers separated by a comma.
The syntax of this keyword is as follows:
TERM-ATTR DBCS-CHARACTERS=n1,n2
These numbers specify a range of characters to be considered lead-byte characters.

Multiple ranges of characters can be specified by repeating the DBCS-CHARACTERS
keyword, but ranges must not overlap. These numbers must also be wholly contained
within the DATA-CHARACTERS range which, by default, is 32 through 254.

DBCS-CHARACTERS must be specified after DATA-CHARACTERS if both
keywords are specified. Specifying DATA-CHARACTERS causes preceding
DBCS-CHARACTERS and TERM-INPUT values to be discarded.
Note This keyword is only supported under UNIX.
Restrictions
The following restrictions apply to double-byte character set characters in

RM/COBOL:
• Because a DBCS character cannot be entered in a field where there is only one
remaining character position, DBCS characters cannot be any of the following:
− Entered into one-character ACCEPT fields.
− Typed into the last position of a field.
− Inserted into a field where only one position remains available.
− Typed over single-byte characters in a field where no positions remain

available.
• A DBCS character cannot be displayed on a position that would physically or

logically separate the trail byte from the lead byte. DBCS characters, therefore,
cannot be displayed in the last column of a screen or window. In addition, when
a new window is opened, any lead bytes or trail bytes that would be orphaned by
the window are blanked and restored when the window is removed.
• If an ACCEPT field spans a window or screen row, RM/COBOL will permit the
entry of a DBCS character when the cursor is in the last column of the window
or screen. The cursor advances two character positions and the DBCS character
is saved but not displayed (two spaces are displayed instead). If characters are
inserted or deleted from the field such that the character no longer wraps across
rows, it becomes visible. If another DBCS character wraps as a result, it
becomes invisible. All entered characters will be returned to the RM/COBOL
program when the ACCEPT is terminated.
• Such an invisible character cannot be retrieved with the ACCEPT-FIELD-

FROM-SCREEN keyword in the RUN-ATTR record or the C$SCRD
subprogram. Instead, spaces are returned.
• DBCS characters must not be used as a character specified either in the

PROMPT phrase of an ACCEPT statement or in the GRAPHICS keyword of the
CONTROL phrase of an ACCEPT or DISPLAY statement.
• DBCS characters must not be used in filenames or pathnames.
10-38 Configuration
6. FCOLOR. This keyword indicates the initial foreground color value to use for
ACCEPT and DISPLAY statements. The terminal will be restored to this color when
the run unit ends. The default color value is WHITE.
Note Under Windows, the default foreground color is determined by the system
settings. In particular, the default foreground color will be the default “window text”
color. The default high-intensity foreground color is determined by the default
“selected text” color.
7. PASS-THRU-ESCAPE. This keyword allows certain DISPLAY statements to write

sequences directly to standard output, bypassing screen optimization and buffering.
If used, any DISPLAY statement that begins with one of the specified characters will
exhibit the PASS-THRU behavior. No cursor positioning is performed. All
attributes specified in the DISPLAY statement are ignored. The characters are
represented in ordinal form (for example, the ASCII ESC character is 27) within a
comma separated list as both individual values and ranges (for example, 0-31,255).
The default is to have no PASS-THRU-ESCAPE characters.
8. REDRAW-ON-CALL-SYSTEM. This keyword sets a variable that is checked by

the C language subprogram, SYSTEM, before restoring the screen. The values for
this keyword are YES and NO. The default value is YES. A value of YES causes
the runtime system to redraw the screen in order to maintain screen integrity. An
additional argument, (PIC X) to CALL “SYSTEM”, gives control of this feature on
an individual call basis. See “Restrictions to C (or Assembly) Language
Subprograms” and “Debugging C (or Assembly) Language Subprograms” on
page D-19, for more information.
9. ROWS. This keyword determines the number of rows the runtime system will
display on the terminal screen, represented as a decimal number between 1 and 255.
The default value is 25.
10. SCREEN-CONTENT-OPTIMIZE. This keyword determines whether the runtime

system optimizes DISPLAY output based on current screen contents. If the value is
set to YES, the runtime system avoids displaying an unnecessary character if the
screen image already contains that character in the desired location, thereby
increasing terminal I/O efficiency. If the value is set to NO, the runtime system
forces every character to be written to the screen even if this results in duplicating the
existing screen contents. Because turning off screen content optimization clears the

screen image, repainting the screen will result in a blank display. The default value is
YES.
11. SUPPRESS-NULLS. This keyword controls whether the RM/COBOL runtime

system sends NULL or LOW-VALUE characters to the screen. Setting the value of
this keyword to YES causes NULL characters to be stripped from all displayed
fields. The NULL characters will, however, remain in the internal data storage. The
12. USE-COLOR. Setting the value of this keyword to YES forces a COBOL program
to perform all DISPLAY and ACCEPT statements using either the default color
values or the color values specified in a CONTROL phrase. If the termcap or
terminfo database contains color support and the set_foreground and set_background
strings are present, these strings are used to process the request. Otherwise, the
RM/COBOL runtime system will generate the seven-bit SGR (Set Graphics
Rendition) sequences assigned by the International Standards Organization for color.
These sequences are defined as follows:
Control Sequence Parameter
Introducer Selection Terminator
Foreground ESC [ 3 [0-7] m
Background ESC [ 4 [0-7] m
The color values associated with the parameter values zero through seven are as
follows:
Parameter
Color Second Digit
BLACK 0
RED 1
GREEN 2
YELLOW 3
BLUE 4
MAGENTA 5
CYAN 6
WHITE 7
If the value of the USE-COLOR keyword is set to NO, color sequences will not be
used until the first ACCEPT or DISPLAY that requests to use color and only if there
is support for color in the termcap or terminfo database. NO is the default value.
10-40 Configuration
If none of the color keywords is specified, color processing will be disabled until a
CONTROL phrase is encountered that specifies the use of a valid color. When a
CONTROL phrase is encountered, it is honored provided there is color support in the
termcap or terminfo database. When the run unit ends, the terminal will be restored
to the values specified in the FCOLOR and BCOLOR keywords in the TERM-ATTR
configuration record.
TERM-INPUT Record
The TERM-INPUT record associates field editing semantics, exception codes, or a single
data character with incoming character sequences. See page 8-2 for more information on
defining keys under your operating system.
The TERM-INPUT record identifier is followed by one or more optional keywords and
finally, by the character sequence specification. If the keyword is allowed to have a
value, it is followed by an equal sign (=) and the value. The keywords may appear in
any order, but must precede the character sequence specification (see pages 10-42
through 10-44). The possible keywords are as follows:
1. ACTION. This keyword specifies the field editing action or screen action to be
performed. The allowed values (described in detail under “Field Editing Actions”
beginning on page 10-45) are as follows:
BACKSPACE REPAINT-SCREEN
CONTROL-BREAK RESET-ANSI-INSERTION
DELETE-CHARACTER RIGHT-ARROW
ERASE-ENTIRE SCREEN-ESCAPE
ERASE-REMAINDER SCREEN-HOME
ESCAPE-TO-COMMAND SCREEN-PREVIOUS-FIELD
ESCAPE-TO-OS SCREEN-TERMINATE
FIELD-HOME SET-ANSI-INSERTION
INSERT-CHARACTER SET-RM-INSERTION
LEFT-ARROW TOGGLE-ANSI-INSERTION
2. CODE. This keyword specifies the numeric exception code value to be returned to
the program. The definition of an exception code identifies a key sequence that
terminates input. Key sequences without exception codes do not terminate field input
unless one of the screen actions is defined for that key sequence (as described in the
ACTION keyword).

3. DATA. This keyword specifies the data character or character equivalent to be
returned to the program when the incoming character sequence is received (see
“Character Sequence Specification” on page 10-42). If a DATA keyword is
provided, neither the ACTION nor CODE keywords may be specified.
4. EXCEPTION. This keyword specifies whether the ON EXCEPTION clause of the

ACCEPT statement should be executed (see “Input Sequence Specification” on
page 10-44). The EXCEPTION keyword is legal only if the CODE keyword,
described above, is also provided. If a value of YES is specified, the ON
EXCEPTION clause is executed; if a value of NO is specified, the ON EXCEPTION
clause is not executed. The default value is YES. The EXCEPTION keyword is
ignored during an ACCEPT screen-name statement.
5. PRECEDENCE. This keyword assigns a precedence to the TERM-INPUT record.

The value specified is a decimal number from 0 to 14, with 0 considered to have the
highest precedence. The PRECEDENCE keyword is used only when a terminal
generates the same input character sequence for two different keys. The Left Arrow
and Backspace keys form a typical example. The PRECEDENCE keyword can
specify which interpretation of the input sequence is to be used. The TERM-INPUT
record with the highest precedence replaces that with a lower one. If two TERM-
INPUT records have the same precedence, a procedure error occurs when the unit is
first accessed. The default value is 0.
Character Sequence Specification
Terminal configuration allows the specification of incoming character sequences. The

syntax of the sequences is one or more characters or character equivalents, separated by
spaces. Any single character delimited by spaces is interpreted as the represented ASCII
character. More than one character delimited by spaces is interpreted as a character
equivalent. If the characters are digits, they are interpreted as the decimal value of the
ASCII code. The recognized character equivalents may be one of those listed in the
following tables.
Table 10-3 lists the ASCII equivalents.
10-42 Configuration
Table 10-3 ASCII Equivalents
Character Character
ASCII Code Equivalent ASCII Code Equivalent
000 NUL 017 DC1
001 SOH 018 DC2
002 STX 019 DC3
003 ETX 020 DC4
004 EOT 021 NAK
005 ENQ 022 SYN
006 ACK 023 ETB
007 BEL 024 CAN
008 BS 025 EM
009 HT 026 SUB
010 LF 027 ESC
011 VT 028 FS
012 FF 029 GS
013 CR 030 RS
014 SO 031 US
015 SI 032 SP
016 DLE 127 DEL
Additional character equivalents, listed in Table 10-4, have been defined for the character
sequence specifications in Windows. If one of these character equivalents, other than
WSFT or WCNT, is used to specify an incoming character sequence, the specification
should begin with NUL. This is necessary to distinguish between the special Windows
character equivalents and normal ASCII characters.
Note Alt-key sequences are not available under RM/COBOL for Windows because the
underlying Windows-based environment traps the Alt-key sequences. Alt-key sequences
are entered as Ctrl-Shift-key combination sequences. For example, use Ctrl-Shift-I
instead of Alt-I.

Table 10-4 Additional Character Equivalents Under RM/COBOL for
Windows
Code Name Description

WSFT Shift key
WCNT Control key
WPGU PgUp key
WPGD PgDn key
WEND End key
WHOM Home key
WLFT Left Arrow key
WUP Up Arrow key
WRGT Right Arrow key
WDWN Down Arrow key
WPRT Print key
WINS Insert key
WDEL Delete key
WF1 . . . WF16 Function 1 … Function 16
Input Sequence Specification
Incoming character sequences are specified by the corresponding attribute name. For
example, assume you have a keyboard with a Next page key (knp in the terminfo
database, and kN in the termcap database) and you want that to cause the ON
EXCEPTION branch of your ACCEPT statement to be taken with the decimal value 80
stored in the EXCEPTION variable. This could be described in the following ways:
For terminfo:
TERM-INPUT CODE=80 EXCEPTION=YES knp
For termcap:
TERM-INPUT CODE=80 EXCEPTION=YES kN
For Windows:
TERM-INPUT CODE=80 EXCEPTION=YES NUL WPGU
10-44 Configuration
Field Editing Actions
RM/COBOL ACCEPT statements define fields on the terminal in which the operator may
enter data. Depending on the phrases specified in the ACCEPT statement and the setting
of the ACCEPT-FIELD-FROM-SCREEN keyword of the RUN-ATTR configuration
record (see page 10-23), the initial contents of the screen field may be empty (all spaces),
filled with characters from the screen, filled with prompt characters or filled with the
current value of the associated ACCEPT operand. The operator may then modify the
displayed contents of the screen field; all positions of that screen field may continue to be
modified until a field termination key is entered. This modification of the displayed data
is called field editing.
Data entry is processed in either insertion mode or replacement mode. In insertion mode,
incoming text characters are inserted at the current cursor position, and following
characters are moved to the right in the field. In replacement mode, incoming text
characters replace the characters at the current cursor position. The RM/COBOL terminal
model defines three types of insertion mode:
1. Single-character insertion mode reverts to replacement mode after one text character
is inserted.
2. RM insertion mode reverts to replacement mode when data entry in the field is
terminated or when a field editing key is entered.
3. ANSI insertion mode remains active across ACCEPT operations until reset by the
operator to RM insertion mode or replacement mode.
The RM/COBOL terminal interface provides the following field editing facilities that may
be made available to the operator. These facilities can be specified with the ACTION
keyword of the TERM-INPUT configuration record (see page 10-41).
1. BACKSPACE. The BACKSPACE value accomplishes a destructive backspace by

moving the cursor left one position in the field, deleting the character at that position,
moving all following characters left one position, and inserting a prompt character at
the right end of the screen field. If entered in the leftmost position of
the screen field, the key sequence is treated as a field termination key or as an illegal
keystroke depending on whether an exception code has been assigned to the key
sequence.
2. CONTROL-BREAK. The CONTROL-BREAK value causes the run unit to be

terminated immediately, as if a STOP RUN statement were executed.
3. DELETE-CHARACTER. The DELETE-CHARACTER value deletes the

character at the current cursor position, moves all following characters left one
position, and inserts a prompt character at the right end of the screen field.

4. ERASE-ENTIRE. The ERASE-ENTIRE value replaces all character positions in
the screen field with prompt characters, and moves the cursor to the leftmost position
of the field.
5. ERASE-REMAINDER. The ERASE-REMAINDER value replaces characters

from the current position to the rightmost position of the screen field with prompt
characters.
6. ESCAPE-TO-COMMAND. The ESCAPE-TO-COMMAND value causes the

runtime system to run a user-specified command whenever the configured key is
pressed. The screen is cleared and the terminal is returned to a shell state before the
shell command is run. After the shell or command terminates, the COBOL screen is
restored. The SHELL environment variable determines the shell that is used. If none
is set, /bin/sh is used. The RM_ESCAPE_TO_COMMAND environment variable
determines the command that is used. If none is set, /bin/sh is used.
Note This value is supported only under UNIX.
7. ESCAPE-TO-OS. The ESCAPE-TO-OS value causes the runtime system to bring

up a command shell whenever the configured key is pressed. This allows the user to
press a configured key to bring up a shell, execute OS commands, and then return to
the COBOL program without having to change the COBOL source code.
8. FIELD-HOME. The FIELD-HOME value moves the cursor to the leftmost position
of the screen field.
9. INSERT-CHARACTER. The INSERT-CHARACTER value inserts a single space

character at the current character position. When entered in replacement mode, this
causes the subsequent text character to appear to be inserted.
10. LEFT-ARROW. The LEFT-ARROW value moves the cursor left one position in
the screen field. If entered in the leftmost position of the screen field, this value is
treated as a field termination key or as an illegal keystroke, depending on whether an
exception code has been assigned to the key sequence.
11. REPAINT-SCREEN. The REPAINT-SCREEN value causes the runtime system to

reinitialize the terminal and redraw the screen from an in-memory image. This
allows the user to restore a terminal’s display after events such as a loss of power to
the terminal.
12. RESET-ANSI-INSERTION. The RESET-ANSI-INSERTION value changes the

handling of subsequent text characters to replacement mode.
10-46 Configuration
13. RIGHT-ARROW. The RIGHT-ARROW value moves the cursor right one position
in the screen field. The key sequence is illegal if the character at the current
character position is a prompt character. If entered in the rightmost screen field
position, the key sequence is treated as a field termination key or as an illegal
keystroke, depending on whether an exception code has been assigned to the key
sequence.
14. SCREEN-ESCAPE. The SCREEN-ESCAPE value terminates an ACCEPT

screen-name statement. The current field is neither checked for errors nor moved to
the intermediate area for screen data items. If the current ACCEPT is not an
ACCEPT screen-name statement, no action is taken (unless the keyword CODE is
defined for the same key sequence).
15. SCREEN-HOME. The SCREEN-HOME value moves the cursor to the first input
field defined in the Screen Section for the current screen. The current field is
checked for errors. No semantic action is taken for ACCEPT identifier statements.
16. SCREEN-PREVIOUS-FIELD. The SCREEN-PREVIOUS-FIELD value moves

the cursor to the beginning of the previous field (as defined in the Screen Section)
after the current field is validated. No semantic action is taken for ACCEPT
identifier statements.
17. SCREEN-TERMINATE. The SCREEN-TERMINATE value terminates an

ACCEPT screen-name statement, but, unlike the SCREEN-ESCAPE value, the
current field is validated and moved to the intermediate area. No semantic action is
taken for ACCEPT identifier statements.
18. SET-ANSI-INSERTION. The SET-ANSI-INSERTION value changes the

handling of following text characters. Upon entry to the run unit, terminal
handling is in replacement mode. The SET-ANSI-INSERTION value causes
later incoming text characters to be handled in insertion mode. Insertion mode
continues until a TOGGLE-ANSI-INSERTION, RESET-ANSI-INSERTION or
SET-RM-INSERTION value is entered.
19. SET-RM-INSERTION. The SET-RM-INSERTION value changes the handling of

following text characters. Upon entry to the run unit, terminal handling is in
replacement mode. The SET-RM-INSERTION value causes later incoming text
characters to be handled in insertion mode.
RM insertion mode is reset when any field editing key sequence is entered or when
the field input is terminated.

20. TOGGLE-ANSI-INSERTION. The TOGGLE-ANSI-INSERTION value changes
the handling of following text characters. If terminal handling is currently in
replacement mode, it is changed to ANSI insertion mode. If terminal handling is
currently in RM or ANSI insertion mode, it is changed to replacement mode.
If a key sequence assigned to an exception code has also been assigned to any of the field
editing facilities (excluding BACKSPACE, LEFT-ARROW, and RIGHT-ARROW), the
editing action is performed and field editing will terminate.
We recommend that all terminal configurations include values to generate the

RM/COBOL generic exception keys, which are shown in Table 10-5.
Table 10-5 RM/COBOL Generic Exception Keys
Code Generic Name Code Generic Name

13 Enter 18 Function 18
01 Function 1 19 Function 19
02 Function 2 20 Function 20
03 Function 3 40 Command
04 Function 4 41 Attention
05 Function 5 52 Up Arrow
06 Function 6 53 Down Arrow
07 Function 7 54 Home
08 Function 8 55 New Line
09 Function 9 56 Tab Left
10 Function 10 57 Erase Right
11 Function 11 58 Tab Right
12 Function 12 59 Insert Line
13 Function 13 61 Delete Line
14 Function 14 64 Send
15 Function 15 83 Help
16 Function 16 84 Redo
17 Function 17
10-48 Configuration
TERM-INTERFACE Record
The terminal configuration records have different formats, depending on the type of
terminal interface the runtime system uses: termcap, terminfo, or graphical user interface
(GUI). The TERM-INTERFACE record describes the format of records in this
configuration file. The runtime system will use this information to correctly process the
records and to ensure that it is the correct version of the runtime system (termcap,
terminfo, or GUI) to be using the information.
The TERM-INTERFACE record must precede all other terminal interface configuration
records except TERM-UNIT.
The TERM-INTERFACE record identifier is followed by one keyword that describes the
format. The possible keywords are as follows:
1. GUI. This value must be specified for use with RM/COBOL for Windows. It
indicates that the terminal interface is a graphical user interface (GUI).
2. TERMCAP. This keyword specifies that the runtime system is expected to

process the termcap database and handle all input and output to the terminal directly.
TERM-INPUT configuration records use termcap input sequence.
3. TERMINFO. This keyword specifies that the runtime system is expected to

use the terminfo database and handle all input and output to the terminal directly.
TERM-INPUT configuration records use terminfo input sequence.
4. WINDOWS. This value is identical to the value of GUI.
TERM-UNIT Record
The TERM-UNIT record is used to associate RM/COBOL units to stations (devices).
The TERM-UNIT record identifier is followed by one or more keywords. If the keyword
is allowed to have a value, it is followed by an equal sign (=) and the value.
Note The TERM-UNIT configuration record is supported only under UNIX.
The TERM-UNIT record must contain the PATH keyword if the UNIT keyword does not
specify the default unit. The possible keywords are as follows:
1. BPS. This keyword specifies the Bits Per Second to which the communication port
should be initialized when the unit is first accessed by the RM/COBOL program.
The default for this keyword is the value to which the operating system has set the
port. The valid values for this keyword are 50, 75, 110, 134.5, 150, 200, 300, 600,
1200, 1800, 2400, 4800, 9600, EXT-A and EXT-B (for external A and external B).

2. CHARACTER-WIDTH. This keyword specifies the character size, in bits, to
which the communication port should be initialized when the unit is first accessed
by the RM/COBOL program. The default for this keyword is the value to which
the operating system has set the port. The valid values for this keyword are 5, 6, 7
and 8.
3. DEFINE-CONTROL-CHARACTERS. This keyword specifies whether the

terminal control characters, Ctrl+A through Ctrl+Z, are to be predefined in the unit’s
input sequences to terminate input and generate exception codes of 1 through 26.
On the termcap and terminfo runtime systems, Ctrl+H, Ctrl+I, Ctrl+J, and Ctrl+M
are always predefined to be Backspace, Tab, New Line, and Carriage Return,
respectively.
If the DEFINE-CONTROL-CHARACTERS keyword has the value YES, the

characters are defined. If the DEFINE-CONTROL-CHARACTERS keyword has the
value NO, they are not defined. The default value for this keyword is YES.
4. MOVE-ATTR. This keyword specifies the handling of terminals with positional

attributes. On such terminals, attributes are implemented by placing special
characters on the terminal screen. These attribute characters take up screen positions
and overwrite any data there.
If the MOVE-ATTR keyword has the value NO, it specifies that the attribute
characters are placed at the line and position requested by the RM/COBOL program
and the actual start of the field is moved to the right, accordingly.
If the MOVE-ATTR keyword has the value YES, it specifies that the field should be
placed in the line and position requested and the attributes moved to the left. The
only time this will not be done is when the termcap capability database indicates that
the attributes set by the attribute characters will not cross a line boundary or if the
field starts in line 1, position 1 and the database does not indicate that the attribute
will wrap from the bottom to the top of the screen.
The default value for this keyword is NO.
5. PARITY. This keyword specifies the parity to which the communication port should
be initialized when the unit is first accessed by the RM/COBOL program. The
default for this keyword is the value to which the operating system has set the port.
The valid values of this keyword are: EVEN, ODD and NONE.
6. PATH. This keyword specifies the device pathname that will be used for this unit.
This must be a tty port that currently has no other processes attached to it and has
read and write privileges for the user who starts the run unit. This is a required field
if the unit being described is not the default unit. If the unit being described is the
default unit, this keyword must not be present.
10-50 Configuration
7. STOP-BITS. This keyword specifies the number of stop bits that the
communication port should send following transmitted characters. The default for
this keyword is the value to which the operating system has set the port. The valid
values of this keyword are 1 and 2.
8. TYPE. This keyword specifies the terminal type connected to the port. This is the
name that is used when searching the termcap or terminfo database. The default
value for this keyword is the value of the TERM environment variable.
9. UNIT. This keyword specifies the RM/COBOL unit number being described and is
either a decimal number between 0 and 255 or the value DEFAULT-UNIT. If the
value is DEFAULT-UNIT, this TERM-UNIT record describes the unit that is used
when no UNIT clause appears on the ACCEPT or DISPLAY statement. If it is a
number, this TERM-UNIT record describes a particular UNIT number that will be
used in an RM/COBOL ACCEPT or DISPLAY statement. The default for this
keyword is DEFAULT-UNIT.
Default Configuration Files

The following examples illustrate the default configuration files for terminfo, termcap,
and Windows systems.
Termcap Example
The following records define the default configuration as provided by Liant on systems
that use termcap.
RUN-ATTR accept-intensity=high beep=yes blink=yes
&display-intensity=high reverse=yes
RUN-ATTR error-message-destination=standard-error
RUN-OPTION b=264 k=display m=1
RUN-INDEX-FILES allocation-increment=8
RUN-INDEX-FILES data-compression=yes force-closed=no force-data=no
&force-disk=no
RUN-INDEX-FILES force-index=no key-compression=yes
RUN-SEQ-FILES default-type=binary
RUN-SEQ-FILES device-slewing-reserve=255
RUN-SEQ-FILES tab-stops=8,12,16,20,24,28,32,36,40,44,48,52,
&56,60,64,68,72
RUN-SORT intermediate-files=5 memory-size=16000
TERM-UNIT move-attr=no define-control-characters=yes
TERM-INTERFACE TERMCAP
TERM-INPUT action=left-arrow kl

TERM-INPUT action=right-arrow kr
TERM-INPUT action=backspace precedence=1 kb
TERM-INPUT action=set-rm-insertion kI
TERM-INPUT action=delete-character kD
TERM-INPUT action=erase-entire kC
TERM-INPUT action=screen-terminate code=01 k1
TERM-INPUT action=screen-terminate code=10 k;
TERM-INPUT code=11 F1
TERM-INPUT code=20 FA
TERM-INPUT code=21 FB
TERM-INPUT code=22 FC
TERM-INPUT code=23 FD
TERM-INPUT code=24 FE
TERM-INPUT code=25 FF
TERM-INPUT code=26 FG
TERM-INPUT code=27 FH
TERM-INPUT code=28 FI
TERM-INPUT code=29 FJ
TERM-INPUT code=30 FK
TERM-INPUT code=31 FL
TERM-INPUT code=32 FM
TERM-INPUT code=33 FN
TERM-INPUT code=34 FO
TERM-INPUT code=35 FP
TERM-INPUT code=36 FQ
TERM-INPUT code=37 FR
TERM-INPUT code=38 FS
TERM-INPUT code=39 FT
TERM-INPUT code=40 FU
TERM-INPUT code=41 FV
TERM-INPUT code=42 FW
10-52 Configuration
TERM-INPUT code=43 FX
TERM-INPUT code=44 FY
TERM-INPUT code=45 FZ
TERM-INPUT code=46 Fa
TERM-INPUT code=47 Fb
TERM-INPUT code=48 Fc
TERM-INPUT code=49 Fd
TERM-INPUT code=50 Fe
TERM-INPUT code=51 Ff
TERM-INPUT code=52 Fg
TERM-INPUT code=53 Fh
TERM-INPUT code=54 Fi
TERM-INPUT code=55 Fj
TERM-INPUT code=56 Fk
TERM-INPUT code=57 Fl
TERM-INPUT code=58 Fm
TERM-INPUT code=59 Fn
TERM-INPUT code=60 Fo
TERM-INPUT code=61 Fp
TERM-INPUT code=62 Fq
TERM-INPUT code=63 Fr
TERM-INPUT code=13 exception=no cr
TERM-INPUT code=40 k0
TERM-INPUT code=41 K3
TERM-INPUT code=49 l0
TERM-INPUT action=screen-previous-field code=52 ku
TERM-INPUT code=53 kd
TERM-INPUT action=screen-home code=54 kh
TERM-INPUT code=55 nw
TERM-INPUT action=erase-remainder code=57 kE
TERM-INPUT code=59 kA
TERM-INPUT code=61 kL
TERM-INPUT code=67 kP
TERM-INPUT code=68 kN
TERM-INPUT code=83 precedence=1 %1
TERM-INPUT code=84 %0
PRINT-ATTR auto-line-feed=no
PRINT-ATTR form-feed-available=yes top-of-form-at-close=no
DEFINE-DEVICE device=PRINTER path="lp -s" pipe=yes
DEFINE-DEVICE device=TAPE path=/dev/rtp pipe=no

Terminfo Example
The following records define the default configuration as provided by Liant on systems
that use terminfo.
&force-disk=no
&56,60,64,68,72
TERM-UNIT move-attr=no define-control-characters=yes
TERM-INTERFACE TERMINFO
TERM-INPUT action=left-arrow kcub1
TERM-INPUT action=right-arrow kcuf1
TERM-INPUT action=backspace precedence=1 kbs
TERM-INPUT action=set-rm-insertion kich1
TERM-INPUT action=delete-character kdch1
TERM-INPUT action=erase-entire kclr
TERM-INPUT action=screen-terminate code=01 kf1
TERM-INPUT code=11 kf11
10-54 Configuration
TERM-INPUT code=13 exception=no cr
TERM-INPUT code=41 ka3
TERM-INPUT code=49 lf0
TERM-INPUT action=screen-previous-field code=52 kcuu1

TERM-INPUT code=53 kcud1
TERM-INPUT action=screen-home code=54 khome
TERM-INPUT code=55 nel
TERM-INPUT code=56 kc1
TERM-INPUT action=erase-remainder code=57 kel
TERM-INPUT code=58 kc3
TERM-INPUT code=59 kil1
TERM-INPUT code=61 kdl1
TERM-INPUT code=64 kb2
TERM-INPUT code=67 kpp
TERM-INPUT code=68 knp
TERM-INPUT code=82 ka1
TERM-INPUT code=83 precedence=1 khlp
TERM-INPUT code=84 krdo
DEFINE-DEVICE device=PRINTER path="lp -s" pipe=yes
DEFINE-DEVICE device=TAPE path=/dev/rtp pipe=no
10-56 Configuration
Windows Example
The following records define the default configuration provided by Liant for the Windows
operating system.
&force-disk=no
&56,60,64,68,72
TERM-INTERFACE GUI
TERM-ATTR Data-Characters=32,126
TERM-INPUT Code=1 SOH
TERM-INPUT Code=2 STX
TERM-INPUT Action=Control-Break ETX
TERM-INPUT Code=4 EOT
TERM-INPUT Code=5 ENQ
TERM-INPUT Code=6 ACK
TERM-INPUT Code=7 BEL
TERM-INPUT Action=Backspace BS
TERM-INPUT Code=9 HT
TERM-INPUT Code=10 LF
TERM-INPUT Code=11 VT
TERM-INPUT Code=12 FF
TERM-INPUT Code=13 Exception=No CR
TERM-INPUT Code=14 SO
TERM-INPUT Code=15 SI
TERM-INPUT Code=16 DLE
TERM-INPUT Code=17 DC1
TERM-INPUT Code=21 NAK
TERM-INPUT Code=22 SYN
TERM-INPUT Code=23 ETB
TERM-INPUT Code=24 CAN
TERM-INPUT Code=25 EM

TERM-INPUT Code=26 SUB
TERM-INPUT Action=Screen-Escape Code=27 ESC
TERM-INPUT Code=28 FS
TERM-INPUT Code=29 GS
TERM-INPUT Code=30 RS
TERM-INPUT Code=31 US
TERM-INPUT Code=27 WCNT [
TERM-INPUT Action=Control-Break NUL NUL
TERM-INPUT Action=Backspace NUL BS
TERM-INPUT Code=58 NUL HT
TERM-INPUT Code=56 NUL WSFT HT
TERM-INPUT Code=13 Exception=No NUL CR
TERM-INPUT Action=Erase-Remainder Code=57 WSFT WCNT E
TERM-INPUT Code=58 WSFT WCNT R
TERM-INPUT Code=59 WSFT WCNT I
TERM-INPUT Code=49 WSFT WCNT P
TERM-INPUT Code=41 WSFT WCNT A
TERM-INPUT Code=64 WSFT WCNT S
TERM-INPUT Code=61 WSFT WCNT D
TERM-INPUT Action=Erase-Remainder Code=13 Exception=No WSFT WCNT K
TERM-INPUT Code=40 WSFT WCNT C
TERM-INPUT Code=55 WSFT WCNT N
TERM-INPUT Action=Screen-Home Code=54 NUL WHOM
TERM-INPUT Action=Screen-Previous-Field Code=52 NUL WUP
TERM-INPUT Code=67 NUL WPGU
TERM-INPUT Action=Left-Arrow NUL WLFT
TERM-INPUT Action=Right-Arrow NUL WRGT
TERM-INPUT Code=82 NUL WEND
TERM-INPUT Code=53 NUL WDWN
TERM-INPUT Code=68 NUL WPGD
TERM-INPUT Action=Set-RM-Insertion NUL WINS
TERM-INPUT Action=Delete-Character NUL WDEL
TERM-INPUT Action=Screen-Terminate Code=1 NUL WF1
TERM-INPUT Code=11 NUL WSFT WF1
10-58 Configuration
TERM-INPUT Code=21 NUL WCNT WF1
TERM-INPUT Code=31 NUL WSFT WCNT WF1
TERM-INPUT Code=65 NUL WCNT WLFT
TERM-INPUT Code=66 NUL WCNT WRGT
TERM-INPUT Code=83 NUL WCNT WEND
TERM-INPUT Code=70 NUL WCNT WPGD
TERM-INPUT Code=81 NUL WCNT WHOM
TERM-INPUT Code=71 WSFT WCNT 49
TERM-INPUT Code=85 WSFT WCNT -
TERM-INPUT Code=87 WSFT WCNT =
TERM-INPUT Code=69 NUL WCNT WPGU
TERM-INPUT Code=11 NUL WF11
TERM-INPUT Code=12 NUL WF12

10-60 Configuration
Chapter 11: Instrumentation
RM/COBOL provides a method for examining the performance of RM/COBOL programs
at the statement level. This facility—called Instrumentation—involves a two-step
process. First, program data must be gathered. Instrumentation provides the tools for
data gathering. Next, the gathered data must be analyzed in a manner consistent with
your specific requirements. The delivered RM/COBOL Instrumentation contains one
example of a data analysis program, called analysis. This program also can be used as a
starting point for creating your own data analysis program.
The data gathered by Instrumentation and reported by analysis can be used during
program development to optimize program flow, identify bugs caused by run-away loop
control, and improve program integrity by pinpointing unexecuted program code.
Invoking Instrumentation
Instrumentation is invoked when you enter the I Runtime Command Option (see
page 7-3). If you intend to use analysis as well, all programs in the run unit should be
compiled with the L Compile Command Option (see page 6-9).
Keep in mind that the runtime system needs additional memory when the I Runtime
Command Option is used. Furthermore, each program in the run unit requires additional
memory as it is loaded by the Runtime Command or by a CALL statement (see the
“CALL Statement” section in Chapter 6, Procedure Division Statements, of the
RM/COBOL Language Reference Manual). The exact amount of required memory
depends on the number of lines in the PROCEDURE DIVISION, as described in the
next section.

Invoking Instrumentation
Data Collection
For each program in a run unit, a file is generated that contains the following information:
• PROGRAM-ID value
• Line number of the PROCEDURE DIVISION header
• Total number of source lines in the program
• Total number of statements executed in the program
• Number of times each statement was executed
• Number of times each paragraph and section were executed
This information is gathered in a data structure that could be described by the

RM/COBOL record description, shown in Figure 11-1.
Figure 11-1 Sample Data Structures Description
z 01 PROGRAM-IDENTIFICATION.
02 PROGRAM-ID-VALUE PIC X(30). z
02 PROCEDURE-DIVISION-LINE PIC 9(8) BINARY.
O 02 SOURCE-LINE-COUNT PIC 9(8) BINARY. O
z 02 TOTAL-STATEMENTS-EXECUTED
02 TOTAL-STATEMENTS-PITCHED
PIC 9(8) BINARY.
PIC 9(8) BINARY. z
02 PIC X(14).
O 02 OCCURS 1 TO 65000 O
z DEPENDING ON number of procedure lines.
03 OCCURS 2. z
04 STATEMENT-TYPE PIC X(1).
O 88 NO-STATEMENT-OR-NOT-EXECUTED O
z 88 SECTION-COUNT
VALUE LOW-VALUE.
VALUE 'X'. z
88 PARAGRAPH-COUNT VALUE 'P'.
O 88 STATEMENT-COUNT VALUE 'S'. O
z 04 COUNT-VALUE PIC 9(9) BINARY.
z
The size of the required structure may be calculated as follows:
n = source-line-count - procedure-division-line + 1
size (in bytes) = 60 + (n * 10)
The data structure for a program is allocated when the first statement in that program is
executed. The data structure remains allocated even when the associated program is
canceled.
As with the RM/COBOL Interactive Debugger, Instrumentation treats section names,

paragraph names and procedural statements as statements for the purpose of data
gathering. See pages 9-2 and 9-3 for the definitions of statements and line and intraline
11-2 Instrumentation
Data Collection
numbers. Likewise, programs within the run unit that were compiled with the
Q Compile Command Option are invisible to Instrumentation. No information will be
gathered nor file created for such programs.
As each statement is executed, Instrumentation adds 1 to the total number of statements

executed for that program (TOTAL-STATEMENTS-EXECUTED in the record
description above). If the executing statement is the first or second statement on a line, 1
is added to the count of executions (COUNT-VALUE (line, intraline + 1) in the record
descriptor above) and the appropriate statement type (STATEMENT-TYPE (line,
intraline + 1) in the record descriptor above) is set to true for that statement. If the
executing statement is the third or subsequent statement on a line, 1 is added to a count of
statements not counted individually (TOTAL-STATEMENTS-PITCHED in the record
description above).
When program execution completes—normally or abnormally—each data structure is

written to disk. The name of the disk file is constructed from the first eight characters of
the PROGRAM-ID value, concatenated to the file extension .CNT. If the program name
is less than eight characters, the entire name is concatenated to the file extension. For
example, for a program named example, the data collection file would be named
example.CNT. If the name of the program was generates, the data collection file would
be named generate.CNT.
The runtime directory search sequence (described on page 2-4 for UNIX and page 3-11
for Windows) is used when writing these files. An existing file within the directories
named in the RUNPATH specification will be replaced by a data collection file with the
same name. If no file with the same name exists, a new data collection file will be
created.
Instrumentation either replaces or creates new data collection files for each invocation of
a run unit. Historical information is not maintained from run unit to run unit. This is a
function of the analysis program, which processes the data collection files after each run
unit.
Instrumentation writes messages to the screen as each data collection file is written. The
form of the message when no errors occur is the following:
n a m e .CNT Opening Writing Closing
name is derived from the first eight characters of the PROGRAM-ID, as described
above. Should an error occur during the opening, writing or closing of the file, an
error message (see Appendix A, Runtime Messages) appears after the name of the
operation encountering the error. If Opening receives an error, Writing and Closing
are not attempted and will not be included in the message.

Data Collection
Data Analysis
As was mentioned at the start of this chapter, a data analysis program—named analysis—
is provided with RM/COBOL Instrumentation. Use this program as delivered, or modify
it to fit your precise requirements. As delivered, analysis provides the following:
• Statement count data from the .CNT file is added to the statement count data
gathered from earlier invocations of Instrumentation. This keeps a total count of the
statements executed.
• Statement count data from the total count file is merged with the listing file, creating
a new listing file showing execution counts for each statement.
• A summary of execution counts for each paragraph and section is appended to the
new listing file.
To use analysis as delivered, first compile the program with the RM/COBOL Compile
Command:
rmcobol analysis A L X
This creates a source listing, allocation map, and cross reference on a listing file named
analysis.lst in the directory containing analysis.cbl. An RM/COBOL object file,
analysis.cob, is also created in that directory. See Chapter 6, Compiling, for more
information about the compilation options and parameters.
Next, execute the analysis program by entering the RM/COBOL Runtime Command:
runcobol analysis [ A='p a t h ' ]
The optional A=‘path’ may be used to supply a pathname of the directory where the
merged listing files created by analysis are to reside. If this parameter is omitted, the
RUNPATH specification is used. See Chapter 7, Running, for more information about
the Runtime Command options and parameters.
Data Analysis
The analysis program is listing-file driven, that is, the filenames of one or more listing
files are supplied by the user. These listing files are then processed by analysis, one at a
time, as follows:
1. The merged listing file is opened using the same filename as the listing file, with the
extension .HST.
2. The source listing section is scanned to find the PROGRAM-ID paragraph.
3. The program name found in the PROGRAM-ID paragraph is used to construct the
filename of the .CNT file.
4. The .CNT file is opened.
5. The program name used in the PROGRAM-ID paragraph is used to construct the
filename of the total count (.TOT) file.
6. The .TOT file is opened.
7. The .TOT file is updated (or created if it does not exist) by adding the statement
counts from the .CNT file to the corresponding statement counts in the .TOT file.
8. The source listing section is reformatted merging the statement counts from the .CNT
or .TOT file with the source listing.
9. Summary information about the program is written to the merged file.
10. All listing file information between the end of one program and the beginning of
another in the file or end of file is copied to the merged file.
11. If another program exists in the listing file, this process is repeated starting at
Step 2.
12. If the name of another listing file is supplied by the user, this process is repeated
starting at Step 1.
13. analysis terminates.
When prompted to supply a listing filename, enter only the filename portion of the name;
the .lst extension is supplied automatically. To indicate there are no more listing files,
press Enter without typing a name. Use redirected input on the Runtime Command to
automate the entry of filenames where repeated runs are desired.

Data Analysis
Figure 11-2 illustrates an excerpt from a merged listing, as it pertains to analysis.
Figure 11-2 Excerpt of a Merged Listing
z Count1 Count2 LINE

1
PG/LN A..B..2..3..4..5..6..7..ID...8
FPERF
z
2 PROGRAM-ID. FPERF.
O . O
z .
. z
205 77 PROCEDURE DIVISION.
O 1 78 MAIN SECTION. O
z .
. z
.
O 1 91 A. O
z 1
1
92
93
MOVE ZEROS TO COUNT-ER, ERROR-COUNT.
MOVE SPACE TO PRINT-RECORD. z
1 1 94 MOVE "PATH" TO PATH. MOVE "A" TO P-R.
O 1 95 PERFORM B. O
z 1
1
96
97
IF COUNT-ER = 1
WRITE PRINT-RECORD FROM PASS-LINE z
98 ELSE
O 99 WRITE PRINT-RECORD FROM FAIL-LINE O
z 1
100
101
ADD 1 TO ERROR-COUNT.
MOVE "B" TO P-R. z
102
O 8 8 103 B.WRITE PRINT RECORD FROM PASS-LINE. O
z 8 104
Summary Statistics for FPERF
ADD 1 TO COUNT-ER.
z
The program contains 242 lines, of which 166 are procedure division lines.
O The procedure division has 92 lines which had COBOL verbs executed at least O
z once, and 26 lines which had procedure-names executed at least once.
There were 205 verb executions counted, of which 151 were COBOL statements z
and 54 were procedures.
O . O
z .
. z
Count % LineParagraph/Section
O 8 14.81 103 B O
z 6 11.11 197 K
. z
.
O . O
z 1 1.85 200 A
z
Count1, associated with the PROCEDURE DIVISION line, is the total number of
statements executed in this program. Count2, associated with the PROCEDURE
DIVISION line, is the total number of statements pitched (unattributed) in this program.
For all other lines in the Procedure Division, Count1 is the number of times the section,
paragraph or statement was executed. Count2 is the number of times the next statement
on the line was executed. If there are more than two statements on the line, the execution
counts of the remaining statements are not displayed.
If the line was not referenced or executed, Count1 and Count2 will be blank. This
indicates that the line did not contain a verb, or that it is code that was never executed.
Data Analysis
Some parts of the merged listing file may be suppressed with the S Runtime Command
Option. In this case, the Runtime Command would be:
runcobol analysis S=xpnuc [ A='p a t h ' ]
The values of x, p, n, u and c have the following results:

• x = 1 excludes all lines in the original listing file from the merged listing file;
x = 0 includes these lines. x = 0 is the default.
• p = 1 excludes the paragraph and section execution counts from the summary
information; p = 0 includes these counts. p = 0 is the default.
• n = 1 excludes all lines from the merged listing file that are not contained in the
Procedure Division of the source listing portion; n = 0 includes such lines. n= 0
is the default. n has no additional effect if x = 1.
• u = 1 suppresses the update of the total execution counts derived from the total
count file; u = 0 allows the update. u = 0 is the default.
• c = 1 produces the merged listing file from the .CNT file. c = 0 produces the
merged listing file from the .TOT file. c = 0 is the default. c has no effect if
x = 1.
For example:
runcobol analysis S=10101
produces a merge listing file with only paragraph and section execution counts
and some summary information from the .CNT file but updates historical data for
all statements.

Data Analysis
Data Analysis
Appendix A: Runtime Messages
This appendix presents the types of messages generated during program execution,
including those generated following normal termination as well as those generated when
an error occurs.
Error Message Types

Data Reference, Procedure, Input/Output, Sort-Merge, Message Control,
Configuration, and Initialization errors have error numbers along with the error
messages (detailed below) to help pinpoint the error being diagnosed.
A Traceback message traces back through one or more calling programs when an error
occurs within a called subprogram. The traceback traces the path from the statement
causing the error through all programs currently active in the run unit.
An Internal Error message indicates that an inconsistency not normally caused by a flaw
in the source program has been detected. The numbers within the error message are
needed by Liant technical support services should an internal error occur.
An Operator-Requested Termination error occurs when an operator ends execution by

pressing the Ctrl and Break keys (Interrupt key under UNIX).
A Normal Termination message appears when program execution terminates

successfully.
Error Message Format

The different types of messages use the same general format:
COBOL type error code at line number in

prog-id compiled date time
RM/COBOL User's Guide for 32-Bit Windows A-1

Error Message Types
type is one of the following types of messages:
• Data reference • Operator-requested termination
• Procedure • Sort-merge
• Input/output • Message control
• Internal • Configuration
• Traceback • Initialization
code is the first two digits of the error numbers listed in this appendix.
number identifies a particular line in the Procedure Division of the source program.
It is the line in which the statement being referred to starts, and it can be looked up in
the leftmost column (labeled “Line”) of the source listing produced by the compiler.
If a question mark appears in this position, the following prog-id field refers to a
machine language subprogram, or indicates that a valid line number has not been
established following an Interactive Debug R (Resume) Command (see page 9-34).
If the program has been compiled with the Q Compile Command Option, line
numbers are not available. Instead, the statement address, which appears under the
“Debug” heading in the listing, will appear. The statement address consists of a
segment number and a segment offset and can be distinguished from a line number
since the segment offset is always displayed as a six-digit number (with leading
zeros, if necessary). The segment number is not displayed if it is zero. If a segment
number is present, it precedes the segment offset and the two are separated by a slash
(/) character.
Note The statement address in the error message may not match exactly any of the
statement addresses in the program listing. If the statement address in the error
message does match a statement address in the program listing, the error condition
may have been caused by the statement whose address is just prior to the error
address.
prog-id identifies the program interrupted in order to produce this message. It has
the following format:
program-name (pathname.ext)
program-name is taken from the PROGRAM-ID paragraph of the

source program.
pathname.ext is the fully qualified pathname of the object library in which the
object program resides.
A-2 Runtime Messages

Error Message Format
date and time are the date and time the program was compiled. They correspond
exactly to the date and time printed on the program listing.
Note 1. Traceback and operator-requested termination messages do not include the

“error code” portion of this message.
2. The format of configuration and initialization errors does not precisely

conform to the format shown above. See the discussion of configuration
errors that begins on page A-37.
Data Reference Errors

Data reference errors include invalid data types, improper data definitions, improper data
values and illegal subscripting.
Number Description
101 For one of the following reasons, no operand exists corresponding to

the referenced Linkage Section item:
1. There are more data items specified in the Procedure Division

header than are specified in the USING phrase of the CALL
statement in the calling program.
2. The Procedure Division header in the first (or main) program in the
run unit specifies more than one data item (see the discussion of the
A Runtime Command Option that begins on page 7-5 for more
details). This is just a special case of reason 1 since the main
program is called with only one argument.
3. The CALL statement in the calling program specified OMITTED

for the argument corresponding to the Procedure Division header
argument for the Linkage Section data item in the called program.
Note This error does not occur if the Linkage Section data item
is referenced in the ADDRESS OF special register or in an
ADDRESS OF phrase in a SET statement. Thus, this error can
be prevented by first testing if ADDRESS OF identifier-1
NOT = NULL before attempting to reference identifier-1 directly.

Number Description
102 A reference to a variable length group is illegal because the value in the
DEPENDING data item (data-name-1) is less than the minimum value
(integer-1) or greater than the maximum value (integer-2) in the
OCCURS clause.
103 An identifier or literal referenced in an INSPECT CONVERTING

statement is illegal for one of the following reasons:
1. The source translation template (identifier-6 or literal-4) contains

multiple occurrences of the same value.
2. The source translation template (identifier-6 or literal-4) does not

have the same length as the destination translation template
(identifier-7 or literal-5).
3. The destination translation template (literal-5) is figurative and its

length is not one.
104 A reference to a data item is illegal for one of the following reasons:
1. The computed composite subscript value for a subscripted

reference has a value that is negative, zero or exceeds the
maximum value for the referenced item.
2. There is a reference to a Linkage Section data item that is a formal

argument whose description specifies more characters than are
present in the corresponding operand in the USING or GIVING
phrases of the CALL statement that called the current called
program.
3. There is a reference to a Linkage Section data item in the first (or

main) program in the run unit whose description specifies more
characters than are supplied by the A Runtime Command Option.
4. There is a reference to a Linkage Section data item that is a based

linkage record whose description specifies more characters than are
present in the area of memory covered by the pointer value that
was used to set the base address of the record.
5. There is a reference to a Linkage Section data item that is a based

linkage record and the offset value for the base address has been
set outside the area of memory covered by the address and length
fields of the base address. That is, a Format 6 SET statement has
set the pointer offset value outside the area of memory covered by

Number Description
104 (Cont.) the pointer data item. In this case, the error occurs not when the
Format 6 SET statement is executed, but when the resultant pointer
value is used as the base address of a based linkage record.
105 A subscript calculation overflowed or underflowed.
106 An index-name value indicates more than 65535 occurrences.
107 A reference modification is illegal for one of the following reasons:
1. A reference modification offset value is less than or equal to zero,

or is greater than the length of the data item being reference
modified.
2. A reference modification length value is less than or equal to zero

or is greater than the remaining length of the data item being
reference modified after application of the offset value.
108 The referenced Linkage Section data item (which is other than one
associated with an argument listed in the USING or GIVING phrases of
the Procedure Division header), has a null base address because of one
of the following reasons:
1. The base address has never been set during this run unit.
2. The base address has been explicitly set to NULL or to a pointer

data item with a null value during this run unit.
Note This error does not occur if the Linkage Section data item
is referenced in the ADDRESS OF special register or in an
ADDRESS OF phrase in a SET statement. Thus, this error can
be prevented by first testing if ADDRESS OF identifier-1
NOT = NULL before attempting to reference identifier-1 directly.
110 A reference to a data item is illegal because the base address for the
data item has been set to a pointer value, other than NULL, that does
not point to memory that the program may access. This error occurs
when the based linkage item is referenced after, but not at, the time the
bad base address is established in a Format 6 SET statement.

Procedure Errors
Procedure errors include improper program structure or invalid calls.
Number Description
201 A CANCEL statement has attempted to cancel a program that is still

active. That is, a program that has called, directly or indirectly, the
program attempting the cancel.
202 The program-name on a CALL statement has a value that is equal to

spaces.
203 The program-name on the Runtime Command or CALL statement does

not match any of the PROGRAM-ID names in any library but does
match a valid RM/COBOL library object filename. The call-by-
filename technique is valid only for single-program object files.
204 The program-name on the Runtime Command or CALL statement does

not match any of the PROGRAM-ID names in any library and does not
match a valid RM/COBOL object filename or non-COBOL executable
file. Note that an object program with a higher object version number
than that supported by the runtime system is not considered a valid
program (see Appendix H, Object Versions, for more information).
Under UNIX, if the CALL statement specified a subprogram name that
does not match any of the names in the subprogram name table, this
error occurs.
Under Windows, if the CALL statement specified SYSTEM, this error

can occur when the external routine SYSTEM was successfully found
and loaded, but the command processor required by SYSTEM could
not be found. This can occur when the COMSPEC environment
variable is not defined or its value contains an invalid drive, path, or
filename. This error can also indicate that the length of the parameter
passed to SYSTEM exceeds the limits specified in the documentation
of SYSTEM on page F-41.
Under Windows, if the CALL statement specified a DLL file that does
not contain a nonresident ordinal one entry point, this error occurs.
If the CALL statement specified the ON EXCEPTION or ON
OVERFLOW phrase, this procedure error is suppressed and execution
continues with the imperative statement in the ON EXCEPTION or ON
OVERFLOW phrase.

Procedure Errors
Number Description
205 A CALL statement has attempted to call a program that is still active.
An active program is one that has called, directly or indirectly, the
program attempting the call in error.
206 The called filename is not a valid RM/COBOL object file. The file
may be corrupt or contain information that makes it invalid for this run
unit. A corrupt file could be caused by a system failure or abnormal
termination of the RM/COBOL compiler. The file also could be invalid
for this run unit if the registration information is not correct or if the
object was compiled with features that make it incompatible with the
calling program (for example, the computational versions may not
match).
207 There is not enough memory to load the program from the Runtime
Command or the CALL statement, or to build the in-memory library
structures indicated in the Runtime Command, or to reserve memory for
the ACCEPT and DISPLAY buffers. This may be caused by memory
fragmentation resulting from the dynamics of CALL and CANCEL
operations and file I/O, or it may mean the requested program is too
large for the available memory. More memory can be made available
during a SORT statement by using the T Runtime Command Option to
reduce the memory requested by sort. Additional memory can be made
available by reducing the amount of buffer pool memory through the
use of the BUFFER-POOL-SIZE keyword on the RUN-FILES-ATTR
configuration record (see page 10-26). See page 6-29 for details on
memory size requirements for object programs.
Under Windows, if the CALL statement specified SYSTEM, this error

can occur when there is insufficient memory to load the command
processor required by SYSTEM.

continues with the imperative-statement in the ON EXCEPTION or ON
OVERFLOW phrase.
208 The ALTER statement cannot be executed because of an error in the

source program. The compilation listing provides the specific reason
for the error; for example, an undefined procedure-name, an ambiguous
procedure-name reference, an attempt to ALTER a procedure-name that
is not alterable, a conflict with segmentation rules, and so forth.

Procedure Errors
Number Description
209 The GO TO statement cannot be executed because it does not specify a

default procedure-name and it was not altered before attempting
execution. The source program may have a compilation error if no
ALTER statement specifies the paragraph containing the GO TO
statement. However, the source program may compile without error if
at least one ALTER statement exists that specifies the paragraph
containing the GO TO statement. In the latter case, no such ALTER
statement is executed in the logical sequence of statements leading to
the execution of the GO TO statement.
210 The GO TO or PERFORM statement cannot be executed because

of an error in the source program. The compilation listing provides
the specific reason for the error; for example, an undefined
procedure-name, an ambiguous procedure-name reference, a conflict
with segmentation rules, and so forth.
211 An “E” level compilation error has been encountered.
212 The USE procedure cannot exit because it was invoked by the
execution of a SORT or MERGE statement and the sort-merge
operation is either no longer active or the exit location has been lost.
213 The RM/COBOL object library file specified in the Runtime Command
cannot be found.
214 The RM/COBOL object library file specified in the Runtime Command
does not contain a valid object program.
215 A PERFORM statement in an independent segment has performed a

section or paragraph in a fixed segment that performed a section or
paragraph in a different independent segment.
216 An external item with the same name and type (data record, file
connector or index name) as an existing external in the run unit has a
different description than the existing external.
For an external data record, the length of the record is different.
For an index-name, the span of the table item associated with the index
name is different, or the index-name is associated with a different
external record.

Procedure Errors
Number Description
216 (Cont.) For a file connector, any of the file control clauses, file description
clauses or record description lengths are different. For a relative
organization external file connector, this error is caused if the new
external does not reference the same external data item for the relative
key as is referenced by the existing external file connector.
For additional details on the matching rules required for external

objects with the same name described in more than one program of a
run unit, see the discussion of the “External Objects” section that begins
on page 8-36.
217 An external file connector is invalid since it indicates a SAME AREA

or MULTIPLE FILE TAPE association. Typically, the compiler
prevents this error from occurring by diagnosing the problem at
compile time.
218 There is not enough memory to allocate the data structures necessary to
support an external item declared in the program currently being
loaded.
219 There is not enough memory to allocate the data structures necessary to
support entry into a USE GLOBAL procedure following the occurrence
of an I/O error for which the USE GLOBAL procedure is applicable.
The program is terminated as if no applicable USE procedure were
found.
222 Under Windows, the SYSTEM routine was called but the command
processor required by SYSTEM could not be loaded for some
unexpected reason, such as, bad environment, access denied, too many
open files, or bad format for the command processor. If the command
processor could not be found, error 204 would occur instead of this
error. If there was insufficient memory, procedure error 207 would
occur instead of this error. If the operating system fails to load the
command processor for any other reasons, then this error occurs.

OVERFLOW phrase.

Procedure Errors
Number Description
223 Under Windows, an error occurred while loading a DLL file. If the
DLL file could not be found, error 204 would occur instead of this
error. If there was insufficient memory, procedure error 207 would
occur instead of this error. If the operating system fails to load the DLL
for any other reasons, then this error occurs. This error generally
indicates that the DLL was found, but has an invalid format for the
operating system being used. Some “system out of memory” conditions
may cause an error 223, since Windows returns an ambiguous error
status in some low memory situations.

OVERFLOW phrase.
251 Under UNIX, a syntax error was detected while scanning the termcap
entry for a terminal type.
252 Under UNIX, the terminal type name specified by the TERM
environment variable or by the termcap entry tc cannot be located.
253 Under UNIX, an internal table overflowed while processing a termcap

or terminfo entry. The entry is too complex and its size should be
reduced.
254 Under UNIX, two termcap or terminfo entries have identical input
sequences for this terminal. Use the PRECEDENCE= keyword to
indicate that one entry takes precedence over another (see page 10-42).
255 Under UNIX, the terminal described in the termcap or terminfo entry
has no cursor positioning sequence, or the rows or columns for the
terminal are zero.
256 Under UNIX, the unit number specified in an ACCEPT or DISPLAY

statement has not been defined using a TERM-UNIT configuration
record.
257 Under UNIX, an attempted dynamic load of a machine language

subprogram or library failed because dynamic load is not supported by
your operating system.

Procedure Errors
Number Description
299 An attempt to use Instrumentation on a run unit failed because a

program in the run unit contains more than 65535 source lines or
there was insufficient memory to allocate the data collection structure
for a program in the run unit. See the “Data Collection” section on
page 11-2 for additional information on the memory requirements of
Instrumentation.
Input/Output Errors
Input/output errors include all errors that can occur during file access. The format is as
follows:
COBOL I/O error number on COBOL-filename

file file-access-name
The numerically ordered list presented below shows the values that can appear as number
in the I/O error messages, and a description of each error. The list is presented in
numerical order. The I/O error number has the form:
mm, nn
mm is a two-digit decimal number indicating the general class of error that occurred.
It is also the value stored into the file status data item if such an item has been
specified for the associated file. Thus, this value is available to the program.
nn is a two-digit code that provides more specific information on the nature of the
error. This value is available to the program only if you call the subprogram
C$RERR (described in the discussion that begins on page F-22).
When the I/O error is 30, the I/O error number has the form:
30, OS error nnnnn
OS is the operating system that generated the error and indicates how the nnnnn code
should be interpreted.

Input/Output Errors
nnnnn is the operating system error code that was returned when the error occurred.
This value is available to the program only if you call the subprogram C$RERR
(described in the discussion that begins on page F-22).
The phrase “1985 mode” indicates that the error message description applies only to
ANSI COBOL 1985. The phrase “1974 mode” indicates that the error message
description applies only to ANSI COBOL 1974. Messages not marked with either phrase
indicate that the description applies to both ANSI COBOL 1985 and 1974.
Number Description
00 The operation was successful.
02 The operation was successful but a duplicate key was detected. For a
READ statement, the key value for the current key of reference is equal
to the value of that same key in the next logical record within the
current key of reference. For a REWRITE or WRITE statement, the
record just written created a duplicate key value for at least one
alternate record key for which duplicates are allowed.
04, 05 The record read from the file is shorter than the minimum record length.
(1985 mode)
04, 06 The record read from the file is longer than the record area.
(1985 mode)
05 The operation was successful but the file was not present at the time the
statement began. For a DELETE FILE statement, the file was not
found. For an OPEN statement, the optional file was not found. If the
open mode is I-O or EXTEND, the file has been created. (1985 mode)
07 The operation was successful. If the operation was a CLOSE statement

with a NO REWIND, REEL, UNIT or FOR REMOVAL clause, or if
the operation was an OPEN statement with the NO REWIND clause,
the file is not on a unit or reel medium. (1985 mode)
10 A sequential READ statement was attempted and no next (or previous)

logical record exists in the file because the end (or beginning) of file
was reached, or a sequential READ statement was attempted for the
first time on an optional input file that is not present.
14 A sequential READ statement was attempted for a relative file and the
number of significant digits in the relative record number is larger than
the size of the relative key data item. (1985 mode)

Input/Output Errors
Number Description
21 A sequence error exists for a sequentially or dynamically accessed

indexed file using duplicate prime keys. For a REWRITE statement,
the prime record key was changed by the program between the
execution of the preceding READ statement for the file and the
execution of the REWRITE statement. Or, for a WRITE statement, the
ascending sequence requirements for successive record key values were
violated.
22 The new record value attempts to duplicate an indexed file key which
prohibits duplicates, or a relative record number that already exists.
23 An attempt was made to randomly access a record that does not exist in
the file, or a START or random READ statement was attempted on an
optional input file that is not present.
24 There is insufficient disk space for the operation on a relative or

indexed file.
24, 01 A sequential WRITE statement was attempted for a relative file and the
number of significant digits in the relative record number is larger than
the size of the relative key data item, or the relative record number is
zero. (1985 mode)
24, 02 There is insufficient room left in the file for the operation. See the
description of the FILE-LOCK-LIMIT and FILE-PROCESS-COUNT
keywords of the RUN-FILES-ATTR configuration record on
page 10-28 for more details.
This error may occur when attempting to delete a record from an

indexed file if enough free blocks cannot be made available to split an
index block. Running the Indexed File Recovery utility (recover1) on
the file could consolidate enough index blocks to allow continued use
of the file.
This error may occur on UNIX systems if the file's size exceeds the
user's ulimit.
24, 03 An attempt was made to add the 4294967296th record to an indexed

file. The maximum number or records allowed in an indexed file in
4294967295.

Input/Output Errors
Number Description
24, 04 An attempt was made to add a record to a shared relative file that is so
far beyond the current EOF that the entire intervening region exceeds
the maximum size of a file region lock.
30, OS RM/COBOL returned a permanent error in this 30, OS error code

error format. OS indicates the operating system that is the source of the error
code code. If OS is Btrieve, code is defined in Table A-1 on page A-32. If
OS is UNIX, code is defined in the errno.h include file. If OS is
Windows, refer to the file WINERROR.TXT, which is distributed
with the media. If OS is Runtime Library, code is defined in Table A-2
on page A-35. If OS is File Manager Detected, code is defined in
Table A-3 on page A-35. If OS is any other value, then code and its
meaning are system-dependent. Please refer to the documentation
provided with your operating system for more information.
Using the eleven-character data item on the C$RERR subprogram will

allow permanent errors to include the OS error code. For example,
30,06,00058 is Btrieve error 58 (see the “C$RERR” section in
Appendix F, Subprogram Library).
A Procedure Division statement that explicitly or implicitly causes an

overlay segment to be loaded may receive this error if the RM/COBOL
object file cannot be read when the statement is executed.
30, 25 This permanent error may be returned for Btrieve files. It indicates that
an error occurred during the creation of the file. It may also mean that
the file was already opened during the creation. If the file did not exist
at the time the RM/COBOL-to-Btrieve Adapter program checked for
the existence of the file but did exist at the time of the attempt to create
it, then the Adapter program will misinterpret the error as an I/O error
and return the permanent error code.
30, 58 The Btrieve compression size is too small. Use the appropriate Btrieve
Setup utility to increase the size for the Largest Compressed Record
Size setting (see the appropriate Btrieve installation and operation
manual for more details). The Btrieve MicroKernel Database Engine
(MKDE) must be restarted before the increase will take effect.
30, 64 End of file occurred when ACCEPTing from a redirected input file.

Input/Output Errors
Number Description
30, 97 The Btrieve requester’s data message length is too small. Reconfigure
the requester and specify a higher value. Be certain also to ensure that
the maximum record length (Communication Buffer Size), configured
on server-based Btrieve, is at least as large as the requester’s value (see
the appropriate Btrieve installation and operation manual for more
details).
34 There is insufficient disk space for the operation on a sequential file.

34, 02 There is insufficient room left in the file for the operation. See the
description of the FILE-LOCK-LIMIT and FILE-PROCESS-COUNT
keywords of the RUN-FILES-ATTR configuration record on
page 10-28 for more details.
35 The file is not available because the file identified by the resultant file
access name could not be found. The pathname or filename may be
misspelled or may not be valid for the operating system. Specifying a
pathname or filename that is not a valid name or that is longer than
allowed also results in this error. The directory search sequence
specified by RUNPATH may be incorrect. See the “Locating
RM/COBOL Files” sections either on pages 2-3 through 2-7 for UNIX
or pages 3-10 through 3-15 for Windows for information on the
resultant file access name. (1985 mode)
37, 01 The file must be mass storage. The device-name specified for the file
was DISC, DISK or RANDOM, but the resultant file access name
identifies a file that does not reside on a disk. (1985 mode)
37, 07 The requested operation conflicts with the permissions allowed to the
run unit for the file. This error can occur under any of the following
conditions: a DELETE FILE statement failed because the run unit did
not have write permission for the directory containing the file; an
OPEN statement with the OUTPUT or EXTEND phrase failed because
the run unit does not have write permission for the file; an OPEN
statement with the INPUT phrase failed because the run unit does not
have read permission for the file; or, an OPEN statement with the I-O
phrase failed because the run unit does not have read and write
permissions for the file. (1985 mode)
38 An OPEN or DELETE FILE operation failed because the filename was

previously closed WITH LOCK. (1985 mode)

Input/Output Errors
Number Description
39, 01 The file organization specified for the filename does not match the
actual file organization of the physical file. (1985 mode)
This message may not occur if the file is actually a Btrieve file. The
Btrieve MicroKernel Database Engine (MKDE) always opens its files
with lock, and the OPEN WITH LOCK error condition is encountered
by the RM/COBOL file management system, preventing it from
determining the organization of the file.
39, 02 The minimum record length specified in the RECORD CONTAINS

clause or implied by the record descriptions of the filename does not
match the actual minimum record length of the physical file. (1985
mode)
For Btrieve files, if the minimum record length of the file is less than
four bytes, the file will be implemented using four-byte records. In this
situation, the RM/COBOL-to-Btrieve Adapter program cannot detect
the initial minimum record length and will fail to diagnose the
mismatched minimum record length error condition.
39, 03 The maximum record length specified in the RECORD CONTAINS

match the actual maximum record length of the physical file. (1985
mode)
This error can occur when reopening a print file closed WITH NO
REWIND if the OPEN statement specifies a different record length
than was used on the previous OPEN statement.
This error does not occur with variable-length record Btrieve files.
Btrieve files do not support a mechanism to record this information and,
thus, it cannot be verified.
39, 04 The minimum block length specified in the BLOCK CONTAINS clause
for the filename does not match the actual minimum block size of the
physical file. (1985 mode)
39, 05 The maximum block length specified in the BLOCK CONTAINS

clause for the filename does not match the actual maximum block size
of the physical file. (1985 mode)
This error does not occur with variable-length record Btrieve files.

Input/Output Errors
Number Description
39, 06 The record delimiting technique, LINE-SEQUENTIAL or

BINARY-SEQUENTIAL, specified for the filename does not match the
actual record delimiting technique of the physical file. (1985 mode)
39, 07 The CODE-SET specified for the filename does not match the actual
character code of the physical file. (1985 mode)
39, 08 The COLLATING SEQUENCE specified for the indexed file does not
match the actual collating sequence of the physical file. (1985 mode)
39, 09 The record type attribute, fixed or variable, specified in the RECORD
CONTAINS clause or implied by the record descriptions of the
filename does not match the record type attribute of the physical file.
(1985 mode)
39, 0A The character specified in the PADDING CHARACTER clause for the
filename does not match the actual padding character of the file on the
external medium. (1985 mode)
39, 30 The key duplicates allowed flag specified for keys 0 through 14 does
through not match the corresponding key duplicates allowed flag of the physical
39, 3E file. The prime record key is 0. Alternate record keys are numbered in
ascending order of key offset, starting with 1. (1985 mode)
For Btrieve files, this error also indicates that in the physical file, a key
attribute other than duplicate, modifiable, binary, null, alternate
collating sequence, or extended type was specified for the Btrieve key
that corresponds with the COBOL key defined for the key offset. (For
example, descending, supplemental, and manual key attributes may not
be used for RM/COBOL keys.) In addition, the primary key may not
have a null attribute.
Btrieve allows multiple keys to be defined at the same key offset,

but only the first is considered by the RM/COBOL-to-Btrieve
Adapter program.

Input/Output Errors
Number Description
39, 3F The key duplicates allowed flag specified for an alternate record key 15
through 254 does not match the corresponding key duplicates allowed
flag of the physical file. (1985 mode)
collating sequence or extended type was specified for the Btrieve key
example, descending, supplemental and manual key attributes may not
be used for RM/COBOL keys.)
Btrieve allows multiple keys to be defined at the same key offset, but
only the first is considered by the RM/COBOL-to-Btrieve Adapter
program.
39, 40 The offset from the start of the record area to the start of the key area
through for keys 0 through 14 does not match the corresponding key offset of
39, 4E the physical file. The prime record key is 0. Alternate record keys are
numbered in ascending order of key offset, starting with 1.
(1985 mode)
39, 4F The offset from the start of the record area to the start of the key area
for an alternate key 15 through 254 does not match the corresponding
key offset of the physical file. (1985 mode)
39, 50 The length of the key area for keys 0 through 14 does not match the
through corresponding key length of the physical file. The prime record key is
39, 5E key 0. Alternate record keys are numbered in ascending order of key
offset, starting with 1. (1985 mode)
This error also occurs if the number of keys specified does not match
the actual number of keys in the physical file. The key number 1
through E, if greater than the number of keys in the file description,
indicates that the file contains more keys than the program describes.
The key number 1 through E, if less than or equal to the number of keys
in the file description, provides a value one greater than the number of
keys contained in the file. (1985 mode)

Input/Output Errors
Number Description
39, 5F The length of the key area for an alternate key 15 through 254 does not
match the corresponding key offset of the physical file. (1985 mode)
the actual number of keys in the physical file. (1985 mode)
39, 60 The number of segments for keys 0 through 14 does not match the
through corresponding key number of segments of the physical file. The prime
39, 6E record key is 0. Alternate record keys are numbered in ascending order
of key offset, starting with 1. (1985 mode)
39, 6F The number of segments for an alternate key 15 through 254 does not
match the corresponding key number of segments of the physical file.
(1985 mode)
41, 01 A duplicate open was rejected by a system that does not allow the
physical file to be opened twice. (1985 mode)
COBOL filename to be opened twice. (1985 mode)
41, 03 A DELETE FILE was rejected because the file was open. (1985 mode)
42 A CLOSE or UNLOCK operation was attempted on an unopened file.

(1985 mode)
43 A DELETE or REWRITE operation was attempted on a file declared to

be ACCESS MODE SEQUENTIAL or on an indexed file declared to
be ACCESS MODE DYNAMIC that specifies a prime key that allows
duplicate values, and the last operation on the file was not a successful
READ operation. (1985 mode)
44, 03 The length of the record area specified in the WRITE, REWRITE or
RELEASE statement is less than the minimum record length of the file.
(1985 mode)
RELEASE statement is greater than the maximum record length of the
file. (1985 mode)
44, 07 A REWRITE statement attempted to change the length of a record in a

sequential organization file. (1985 mode)

Input/Output Errors
Number Description
46 No file position is currently defined. A sequential READ operation was

attempted, but the last READ or START operation was unsuccessful or
returned an at end condition. (1985 mode)
46, 02 The position was lost. (1985 mode)
For Btrieve files, A READ NEXT operation was attempted and could
not be completed because the Btrieve MicroKernel Database Engine
(MKDE) position was lost due to the current record (and surrounding
records) being deleted by programs at other computers. See the
“Current Record Position Limitations” section in Chapter 4, System
Considerations for Btrieve.
47, 01 The requested operation conflicts with the open mode of the file. A
START or READ operation was attempted on a file that is not open in
the INPUT or I-O mode. (1985 mode)
47, 02 A READ or START operation was attempted on an unopened file.

(1985 mode)
48, 01 The requested operation conflicts with the open mode of the file. This
error can occur under the following conditions: a WRITE operation
was attempted on a file that is not open in the EXTEND, I-O, or
OUTPUT mode; or, a WRITE operation was attempted on a file in the
sequential access mode that is open in the I-O mode. (1985 mode)
48, 02 A WRITE operation was attempted on an unopened file. (1985 mode)
49, 01 The requested operation conflicts with the open mode of the file. A
DELETE or REWRITE operation was attempted on a file that is not
open in the I-O mode. (1985 mode)
49, 02 A DELETE or REWRITE operation was attempted on an unopened

file. (1985 mode)
90 An unrecognizable message has been received by the

RM/COBOL-to-Btrieve Adapter program from the RM/COBOL file
management system.
This error also indicates that an invalid request has been made to the
RM/COBOL file management system or some other external access
method. This may be caused by an internal error or when
communicating to an earlier version of RM/InfoExpress.

Input/Output Errors
Number Description
90, 01 The requested operation conflicts with the open mode of the file. This
error can occur under the following conditions: a READ or START
operation was attempted on a file that is not open in the INPUT or I-O
mode; a WRITE operation was attempted on a file that is not open in
the EXTEND, I-O, or OUTPUT mode or a WRITE operation was
attempted on a file in the sequential access mode that is open in the I-O
mode; or, a DELETE or REWRITE operation was attempted on a file
that is not open in the I-O mode. (1974 mode)
90, 02 A DELETE or REWRITE operation was attempted on a file declared to

be ACCESS MODE SEQUENTIAL, and the last operation on the file
was not a successful READ operation. (1974 mode)
90, 03 The requested operation conflicts with the media type. This error can
occur under the following conditions: a READ or OPEN INPUT
operation was attempted on a file with a device-name of OUTPUT,
PRINT or PRINTER; a WRITE, OPEN OUTPUT or EXTEND
operation was attempted on a file with a device-name of CARD-
READER or INPUT; or a DELETE, REWRITE, START or OPEN I-O
operation was attempted on a file with a device-name other than DISC,
DISK or RANDOM.
90, 04 The requested operation conflicts with the defined organization. A

DELETE or START operation was attempted on an ORGANIZATION
SEQUENTIAL file.
90, 05 A file truncate operation conflicts with other users. An OPEN

OUTPUT operation was attempted on a physical file that is currently in
an open mode for another file connector of this run unit or a file
connector of another run unit that shares the file.
On Btrieve files, Error 90, 05 also indicates that an I/O error occurred
on the creation of the file. (If the file already existed and the Btrieve
MicroKernel Database Engine (MKDE) returned a Create I/O Error,
25, then the RM/COBOL-to-Btrieve Adapter program will misinterpret
the error as truncation conflict because the Btrieve MKDE uses this
error for both conditions.)

Input/Output Errors
Number Description
90, 06 The file access name specified in the OPEN statement indicates that the
file is accessed through an alternative access method and the alternative
access method refused to accept the request by the RM/COBOL file
management system to establish a session.
This error also indicates that the RM/COBOL file management system
refused one of the configuration parameters passed to it. The runtime
system validates all the configuration parameters of the RM/COBOL
file management system; however, if there is insufficient memory to
create a buffer pool of the requested size, this will not be detected until
later. Reducing the size of the buffer pool may resolve the problem.
90, 07 The requested operation conflicts with the permissions allowed to the
run unit for the file. This error can occur under the following
conditions: a DELETE FILE statement failed because the run unit did
not have write permission for the directory containing the file; an
OPEN statement with the OUTPUT or EXTEND phrase failed because
the run unit does not have write permission for the file; or, an OPEN
statement with the INPUT or I-O phrase failed because the run unit
does not have read permission for the file. (1974 mode)
For Btrieve files, this error code may also indicate that a DELETE,
WRITE, or REWRITE operation was performed on a file that has been
opened for read-only access using an RM/COBOL-to-Btrieve Adapter
program mode option of M=R (read-only). See page 4-14 for more
information about this option. (1974 and 1985 mode)
90, 08 The requested operation is not supported by the alternative access

method. A COBOL I/O statement was attempted to a non-RM/COBOL
file and the access method for the file does not support the statement.
91 A CLOSE or UNLOCK operation was attempted on an unopened file.

(1974 mode)
91, 02 A READ, START, WRITE, DELETE or REWRITE operation was
attempted on an unopened file. (1974 mode)
physical file to be opened twice. (1974 mode)
COBOL filename to be opened twice. (1974 mode)

Input/Output Errors
Number Description
92, 03 A DELETE FILE was rejected because the file was in an open mode.
(1974 mode)
93, 02 An operation was rejected because file lock conflicts with another user.
An OPEN WITH LOCK was attempted on a file that is already open, or
an OPEN without lock was attempted and the file is already open
WITH LOCK.
A DELETE FILE was attempted on a file that is currently open.
This message may occur in cases with Btrieve files when it would not
occur with RM/COBOL indexed files, because the Btrieve MicroKernel
Database Engine (MKDE) always opens its files WITH LOCK. See
error messages 39, 01 and 94, 01 for more information.
For Btrieve files, this error code may also indicate either of the
following conditions:
• Another computer has a transaction in progress on this file.
• Or, an attempt was made to open a file that another computer had
opened already with a conflicting RM/COBOL-to-Btrieve Adapter
program mode option (see page 4-14 for more information about
the mode option). For example, if the first computer opens a file
with a value of A (accelerated) for the mode option, then the
accelerated mode option must be specified by all other computers
that subsequently open the file. Conversely, if the first computer
opens a file and does not specify the accelerated mode option, then
no other computers that subsequently open the file can specify the
accelerated mode option either. These restrictions remain in effect
until all computers have closed the file.
93, 03 An OPEN or DELETE FILE operation failed because the filename was
previously closed WITH LOCK. (1974 mode)
93, 04 The file could not be opened because another file in the same SAME
AREA clause is currently open.
93, 05 The file could not be opened because another file in the same
MULTIPLE FILE TAPE clause is already open.
93, 06 The file could not be created because a file with the same name
already exists.

Input/Output Errors
Number Description
93, 07 The file could not be opened because a lock table for the requested
open mode was full. See the FILE-PROCESS-COUNT keyword of the
RUN-FILES-ATTR configuration record on page 10-28 for more
information.
94, 01 The file organization specified for the filename does not match the
actual file organization of the physical file. (1974 mode)
This message may not occur if the file is actually a Btrieve file. The
Btrieve MicroKernel Database Engine always opens its files WITH
LOCK, and the OPEN WITH LOCK error condition will be
encountered by the RM/COBOL file management system, preventing it
from determining the organization of the file.
94, 02 The minimum record length specified in the RECORD CONTAINS

match the actual minimum record length of the physical file. (1974
mode)
For Btrieve files, if the minimum record length of the file is less than
four bytes, the file will be implemented using four-byte records. In this
situation, the RM/COBOL-to-Btrieve Adapter program cannot detect
the initial minimum record length and will fail to diagnose the
mismatched minimum record length error condition.
94, 03 The maximum record length specified in the RECORD CONTAINS

match the actual maximum record length of the physical file. (1974
mode)
This error can occur when reopening a print file closed WITH NO
REWIND if the OPEN statement specifies a different record length
than was used on the previous OPEN statement.
This error will not occur with variable-length record Btrieve files.
94, 04 The minimum block length specified in the BLOCK CONTAINS clause
for the filename does not match the actual minimum block size of the
physical file. (1974 mode)

Input/Output Errors
Number Description
94, 05 The maximum block length specified in the BLOCK CONTAINS

clause for the filename does not match the actual maximum block size
This error will not occur with variable-length record Btrieve files.
94, 06 The record delimiting technique, LINE-SEQUENTIAL or

BINARY-SEQUENTIAL, specified for the filename does not match the
actual record delimiting technique of the physical file. (1974 mode)
94, 07 The CODE-SET specified for the filename does not match the actual
character code of the physical file. (1974 mode)
94, 08 The COLLATING SEQUENCE specified for the indexed file does not
match the actual collating sequence of the physical file. (1974 mode)
94, 09 The record type attribute, fixed or variable, specified in the RECORD
CONTAINS clause or implied by the record descriptions of the
filename does not match the record type attribute of the physical file.
(1974 mode)
94, 20 The file is not available because the file identified by the resultant file
access name could not be found. The pathname or filename may be
misspelled or may not be valid for the operating system. Specifying a
pathname or filename that is not a valid name or that is longer than
allowed also results in this error. The directory search sequence
specified by RUNPATH may be incorrect. See the “Locating
RM/COBOL Files” sections either on pages 2-3 through 2-7 for UNIX
or pages 3-10 through 3-15 for Windows for information on the
resultant file access name. (1974 mode)
94, 21 The file organization specified is invalid or unsupported, or the

requested open operation is illegal on the specified organization.
94, 22 The minimum record length is invalid. The minimum record length
specified in the RECORD CONTAINS clause for the filename exceeds
the maximum record length.
94, 23 The maximum record length is invalid. The maximum record length
specified in the RECORD CONTAINS clause of the filename exceeds
65280, or the indexed records are not compressed and the maximum
record length exceeds the block size.

Input/Output Errors
Number Description
94, 24 The minimum block size is invalid. The minimum block size specified
in the BLOCK CONTAINS clause of the filename exceeds the
maximum block size.
94, 25 The maximum block size is invalid. The maximum block size specified
in the BLOCK CONTAINS clause of the filename is too large. The
method of computing the block size and the limitations on the block
size for each organization are described on pages 8-41 (sequential
files), 8-47 (relative files), and 8-50 (indexed files).
For indexed organization files, the computed block size is also a
function of the maximum record size. In general, if the BLOCK
CONTAINS clause is omitted, the runtime system defaults to the valid
block size that is a multiple of the disk sector size. For files with a very
large record size, specifying BLOCK CONTAINS 1 RECORDS yields
the minimum possible block size.
94, 26 The record delimiter is invalid. A record delimiting technique other
than LINE-SEQUENTIAL or BINARY-SEQUENTIAL was specified.
94, 27 The CODE-SET specified is invalid or unsupported.
94, 28 The COLLATING SEQUENCE specified for an indexed file is invalid
or unsupported.
94, 29 The record type attribute, fixed or variable, specified for the filename is
unsupported.
94, 30 The key duplicates allowed flag specified for keys 0 through 14 is
through invalid (1974 and 1985 modes) or does not match the corresponding
94, 3E key duplicates allowed flag of the physical file (1974 mode). The
prime record key is 0. Alternate record keys are numbered in
ascending order of key offset, starting with 1.
For Btrieve files, this error also indicates a key attribute other than
duplicate, modifiable, binary, null, alternate collating sequence, or
extended type was specified for the Btrieve key that corresponds with
the COBOL key defined for the key offset. (For example, descending,
supplemental, and manual key attributes may not be used for
RM/COBOL keys.) In addition, the primary key may not have a null
attribute.
Btrieve allows multiple keys to be defined at the same key offset,
but only the first key is considered by the RM/COBOL-to-Btrieve
Adapter program.

Input/Output Errors
Number Description
94, 3F The key duplicates allowed flag specified for an alternate record key 15
through 254 is invalid (1974 and 1985 modes) or does not match the
corresponding key duplicates allowed flag of the physical file. (1974
mode)
collating sequence or extended type was specified for the Btrieve key
example, descending, supplemental and manual key attributes may not
be used for RM/COBOL keys.)
Btrieve allows multiple keys to be defined at the same key offset, but
only the first key is considered by the RM/COBOL-to-Btrieve Adapter
program.
94, 40 The offset from the start of the record area to the start of the key area
through for keys 0 through 14 is invalid (1974 and 1985 modes) or does not
94, 4E match the corresponding key offset of the physical file (1974 mode).
The prime record key is 0. Alternate record keys are numbered in
ascending order of key offset, starting with 1.
Error 94, 40 also occurs if more than 254 alternate record keys are
specified.
For Btrieve files, this error also indicates that the key extends into the
variable portion of a Btrieve file record.
94, 4F The offset from the start of the record area to the start of the key area
for an alternate key 15 through 254 is invalid (1974 and 1985 modes)
or does not match the corresponding key offset of the physical file.
(1974 mode)
For Btrieve files, this error also indicates that the key extends into the
variable portion of a Btrieve file record.

Input/Output Errors
Number Description
94, 50 The length of the key area for keys 0 through 14 is invalid (1974 and
through 1985 modes) or does not match the corresponding key length of the
94, 5E physical file (1974 mode). The prime record key is key 0. Alternate
record keys are numbered in ascending order of key offset, starting
with 1.
This error also occurs if the number of specified keys does not match
the actual number of keys in the physical file. The key number 1
through E, if greater than the number of keys in the file description,
indicates that the file contains more keys than the program describes.
The key number 1 through E, if less than or equal to the number of keys
in the file description, provides a value one greater than the number of
keys contained in the file. (1974 mode)
A Btrieve file is allowed to have more keys defined in it than in the

COBOL description of the file, but not less.
94, 5F The length of the key area for an alternate key 15 through 254 is invalid
(1974 and 1985 modes) or does not match the corresponding key offset
the actual number of keys in the physical file (see error messages
94, 50 through 94, 5E). (1974 mode)
94, 60 There is insufficient memory to open file. The amount of memory

required to open a file can be reduced by specifying a smaller
maximum block size in the BLOCK CONTAINS clause. Additional
memory can be made available by decreasing the amount of buffer pool
memory through the use of the BUFFER-POOL-SIZE keyword on the
RUN-FILES-ATTR configuration record (see page 10-26).
94, 61 There is insufficient disk space to create a file.
94, 62 The LINAGE parameters are invalid for an OPEN statement. One or
more LINAGE parameters are negative or greater than 32767, LINAGE
equals zero, FOOTING equals zero, or FOOTING is greater than
LINAGE.
94, 63 An OPEN WITH LOCK was attempted on a system that does not
support WITH LOCK.
94, 64 The filename specified is invalid. This error can occur if the filename
is set to spaces.

Input/Output Errors
Number Description
94, 65 An OPEN was attempted on the controlling console device.

94, 66 There are no more file handles available. An OPEN was rejected
because an operating system limit on the number of files was reached.
94, 67 The file is too large. An attempt was made to open a file that is too
large for this system. The file was probably created on another
system using the LARGE-FILE-LOCK-LIMIT configuration
keyword or is a version 3 indexed file, or an attempt was made to
use a LARGE-FILE-LOCK-LIMIT value on a system that does not
support files larger than 2 GB. See the description of the
LARGE-FILE-LOCK-LIMIT keyword in the RUN-FILES-ATTR
record on page 10-28, or the description of File Version Level 3 files
on page 8-65 for more information.
94, 68 An attempt was made to open an indexed file that has a future file
version number. The indexed file may have been created by a later
version of RM/COBOL or the indexed file may be corrupt.
94, 69 The specified large file lock limit is too large for either the operating
system on which the runtime is running, or the file system on which the
file would reside. For example, Windows 98 does not support a large
file lock limit greater than four gigabytes (4 GB).
95, 01 The file must be mass storage. The device-name specified for the file
was DISC, DISK or RANDOM, but the resultant file access name
identifies a file that does not reside on disk. (1974 mode)
96 No file position is currently defined. A sequential READ operation was

attempted, but the last READ or START operation was unsuccessful or
returned an at end condition. (1974 mode)
96, 02 The position was lost. (1974 mode)

For Btrieve files, A READ NEXT operation was attempted and could
not be completed because the Btrieve MicroKernel Database Engine
(MKDE) position was lost due to the current record (and surrounding
records) being deleted by programs at other computers. See the
“Current Record Position Limitations” section in Chapter 4, System
Considerations for Btrieve.
97, 01 One or more characters in the record are illegal in a line sequential file.
97, 02 One or more characters could not be translated from the native
character set to the external code-set.

Input/Output Errors
Number Description
RELEASE statement is less than the minimum record length of the file.
(1974 mode)
RELEASE statement is greater than the maximum record length of the
file. (1974 mode)
97, 05 The record read from the file is shorter than the minimum record length.
97, 06 The record read from the file is longer than the record area.
97, 07 A REWRITE statement attempted to change the length of a record in a

sequential organization file. (1974 mode)
97, 08 The LINAGE parameters are invalid for a WRITE statement. One or
more LINAGE parameters are negative or greater than 32767, LINAGE
equals zero, FOOTING equals zero, or FOOTING is greater than
LINAGE.
97, 09 The TO LINE value is outside the page body.
98, 01 The indexed file structure includes a count of the number of times the
file is currently open for modification. The count should be zero
whenever a file in a single-user environment is opened or a file in a
shared environment is opened WITH LOCK. If the count is non-zero
when the file is opened WITH LOCK, a 98, 01 error is returned. The
conditions that determine whether the runtime system assumes a
single-user or shared environment are described in the “File Types and
Structure” section (see page 8-40) and in the explanation of the
FORCE-USER-MODE keyword of the RUN-FILES-ATTR
configuration record (see page 10-28).
The count is incremented when a program opens the file I-O, OUTPUT,
or EXTEND and decremented when the program closes the file. If the
count is non-zero when the file is opened in a single-user environment
or opened WITH LOCK in a shared environment, then the system must
have terminated without closing the file. This error can also appear
when a file with a non-zero count is moved from a shared environment
to a single-user environment. The indexed file will be inconsistent if all
the modifications to it were not written to disk. Use the Indexed File
Recovery utility (recover1) to rebuild or recover disk information (see
page G-23).

Input/Output Errors
Number Description
98, 01 (Cont.) You can reduce the likelihood of encountering this error by changing
the Indexed File Recovery utility strategy to “Force File Closed” (see
page 8-51). This causes the count to be changed around every write
operation instead of during open and close. Use the Define Indexed
File utility (rmdefinx) to change the recovery strategy of an existing
indexed file (see page G-19).
98, 02 A fatal error occurred during a DELETE, REWRITE, or WRITE

statement when the file was last open. The index structure is
inconsistent and must be rebuilt. Use the Indexed File Recovery utility
(recover1) to rebuild or recover disk information (see page G-23).
98, nn Invalid file structure. The nn subcode may be useful in determining

which runtime system procedure detected the error.
For an indexed organization file, there appears to be an inconsistency in

the file structure. If the error occurs when the file is being read, it may
be a disk read error which goes away when the operation is retried. If
the error occurs during a DELETE, REWRITE, or WRITE statement, a
later OPEN statement will probably receive a 98, 02
error. It may be possible to correct the file structure inconsistency
by rebuilding the index structure. Use the Indexed File Recovery utility
(recover1) to rebuild or recover disk information (see
page G-23).
For a sequential or relative organization file, this error usually indicates

the file description does not match the organization of the file, record
type, record delimiting technique or record length. It may also indicate
that the file data was not written or read correctly.
99 A DELETE, READ, or REWRITE statement failed because the record

is locked by another user.

Input/Output Errors
1
Table A-1 Btrieve Status Codes and Messages
Code Message Code Message

1 Invalid operation 19 Unrecoverable error
2 I/O error 20 Record manager inactive
3 File not open 21 Key buffer too short
4 Key value not found 22 Data buffer length
5 Duplicate key value 23 Position block length
6 Invalid key number 24 Page size error
7 Different key number 25 Create I/O error
8 Invalid positioning 26 Number of keys
9 End-of-file 27 Invalid key position
10 Modifiable key value error 28 Invalid record length
11 Invalid filename 29 Invalid key length
12 File not found 30 Not a Btrieve file
13 Extended file error 31 File already extended
14 Pre-image open error 32 Extend I/O error
15 Pre-image I/O error 34 Invalid extension name
16 Expansion error 35 Directory error
17 Close error 36 Transaction error
18 Disk full 37 Transaction is active
1
This list of Btrieve status codes and messages is provided for convenience only, and is not
intended to supply complete information. For a full list of codes and messages with
descriptions, refer to the Btrieve for Windows NT/Windows 95 Installation and Operation
manual, the Btrieve for NetWare Installation and Operation manual, or the Btrieve for
Windows NT Server Edition Installation and Operation manual.

Input/Output Errors
1
Table A-1 Btrieve Status Codes and Messages (Cont.)

38 Transaction control I/O error 64 Filter limit reached
39 End/abort transaction error 65 Incorrect field offset
40 Transaction max files 74 Transaction rolled back
41 Operation not allowed 75 Server routing list too small
42 Incomplete accelerated access 76 File server list too small
43 Invalid record address 77 VAP wait error
44 Null key path 78 Deadlock detected
45 Inconsistent key flags 79 Programming error
46 Access to file denied 80 Conflict
47 Maximum open files 81 Lock error
48 Invalid alternate sequence 82 Lost position
definition
49 Key type error 83 Read outside transaction
50 Owner already set 84 Record in use
51 Invalid owner 85 File in use
52 Error writing cache 86 File table full
53 Invalid interface 87 Handle table full
54 Variable page error 88 Incompatible mode error
55 Auto-increment error 90 Redirected device table full
56 Incomplete index 91 Server error
57 Expanded memory error 92 Transaction table full
58 Compression buffer too short (see 93 Incompatible lock type
page A-14 for resolution
suggestion)
59 File already exists 94 Permission error
60 Reject count reached 95 Session no longer valid
61 Work space too small 96 Communications environment error
62 Incorrect descriptor 97 Data message too small (see
page A-15 for resolution
suggestion)
63 Invalid extended insert buffer 98 Internal transaction error

Input/Output Errors
1
Table A-1 Btrieve Status Codes and Messages (Cont.)

99 Requester cannot access NetWare 1008 Initialization parameter invalid
Runtime server
100 No cache buffers 1009 Transaction filename parameter
invalid
101 Insufficient OS memory 1010 Transaction control file error
102 Insufficient stack space 1011 Compression buffer parameter
invalid
103 Chunk offset too big 1012 Invalid /n option (pre-v6.0)
104 Unknown locale 1013 Task list full
105 Cannot create VAT file 1014 Stop warning. Files still active
106 Cannot get next chunk 1015 Pointer parameter invalid
107 Chunk operation on pre-v6.0 file 1016 MKDE already initialized
109 Unknown error creating or 1017 Requester cannot locate
accessing semaphore wbtrvres.dll
130 MKDE out of system locks 1018 MKDE called from callback
132 File full 1019 Operation canceled by callback
133 More than 5 concurrent engines 1020 Requester communications error
accessing same file
1001 Lock parameter is invalid 2001 Memory allocation insufficient
1002 Memory allocation error 2002 Requester option invalid
1003 Invalid memory size parameter 2003 Requester cannot access local file
1004 Page size error 2004 SPX not installed
1005 Preimage drive parameter invalid 2005 Incorrect SPX version
1006 Preimage buffer parameter invalid 2006 No available SPX connection
1007 Files parameter invalid 2007 Pointer parameter invalid

Input/Output Errors
1
Table A-2 Runtime System Library Error Codes

1 No such file or directory 21 I/O error
2 Arg list too big 22 Is a directory
3 Exec format error 23 Not a directory
4 Bad file number 24 Too many links
5 Not enough memory 25 Block device required
6 Permission denied 26 Not a character device
7 File exists 27 No such device or address
8 Cross-device link 28 Not owner
9 Invalid argument 29 Broken pipe
10 File table overflow 30 Read-only file system
11 Too many open files 31 Illegal seek
12 No space left on device 32 No such process
13 Argument too large 33 Text file busy
14 Result too large 34 Bad address
15 Resource deadlock would occur 35 Name too long
16 Interrupt 36 No such device
17 Child does not exist 37 No locks available in system
18 Resource unavailable, try again 38 Unknown system call
19 Device or resource busy 39 Directory not empty
20 File too large
1
This list of runtime system library error codes and meanings is provided for convenience only,
and is not intended to supply complete information.
Table A-3 File Manager Detected Error Codes
Code Message
1 Memory management failure
2 Operator requested termination
3 Locks lost

Input/Output Errors
Internal Errors
In general, internal errors are caused when the object file has been corrupted. If the
corruption was caused by an undetected data error reading the object file from disk or
over a network, the failure should disappear or change when the program is run again. If
the object file on disk is corrupted, compiling the program to generate correct object
should fix the problem.
Sort-Merge Errors
Sort-merge errors include errors processing a SORT or MERGE statement.
Number Description
301 There was insufficient memory available to initiate a sort or merge

process. The default or specified sort memory size was insufficient to
hold ten records of the record length to be sorted, or the specified sort
memory size is not available. Use the T Runtime Command Option to
increase the memory requested by the SORT statement.
302 Fewer than three intermediate files were available to begin a SORT
statement. The sort procedure cannot begin unless it is able to create at
least three intermediate files.
303 A record read from a MERGE file or SORT USING file was not long
enough to include all the keys.
304 Too many out of sequence records were passed to the sort process. Use
the T Runtime Command Option to increase the memory available to
sort. Or, divide the records to be sorted into several files, sort the
several files, and merge the resulting files.
305 A SORT or MERGE statement was attempted while a sort or merge

process was already active.
306 A RELEASE or RETURN statement was attempted and no sort or

merge was active.
307 A RELEASE or RETURN statement was attempted for a sort or merge

description other than the one currently being sorted or merged.

Internal Errors
Number Description
308 A RELEASE statement was attempted in an OUTPUT PROCEDURE,

or a RETURN statement was attempted in an INPUT PROCEDURE.
309 A RETURN statement was attempted in an OUTPUT PROCEDURE

after the at end condition was returned on the sort or merge file.
310 An application I/O statement was attempted on a file currently opened

as a sort or merge USING or GIVING file.
Message Control Errors

Message control errors include errors that occur when using the Message Control
System (MCS).
Number Description
351 An ENABLE, DISABLE, SEND, RECEIVE or ACCEPT . . . FROM

MESSAGE COUNT statement was encountered and no MCS was
present.
Configuration errors include all errors that occur because of an error in the configuration.
The formats are as follows:
COBOL configuration error code at record

number in location.
COBOL configuration error code. Error

processing configuration.
code is the error number listed below.
number identifies the logical record in the configuration file (location) at which the
error was found. Each logical record is identified with a configuration record type.
In other words, when you are using the record number provided in the message to
determine the erroneous record, count the lines combined with their corresponding
continuation lines as one line, and do not count the comment lines and blank lines.

Message Control Errors
location identifies the configuration file containing the error. The possible values are
as follows:
1. Overriding configuration file
2. Supplemental configuration file
These two locations correspond to the C Runtime Command Option (G Compile

Command Option) and the X Runtime Command Option (H Compile Command
Option), respectively (described on page 7-3).
The first format is used if an error is detected during the processing of a configuration
record. The error message will be followed by a line containing the portion of the record
being processed when the error occurred and another line placing a currency symbol
underneath the item being processed when the error occurred.
The second format is used if an error is detected after all configuration records have been
processed or if an error is detected with which a record is not associated.
Number Description
401 A character has been defined as a data character in a TERM-ATTR

record as well as the beginning character of an input sequence in a
TERM-INPUT record.
402 An invalid delimiter was found.
403 The input sequence in the current TERM-INPUT record has been
defined in a previous TERM-INPUT record.
404 A keyword has not been provided where expected or the keyword is
invalid.
405 The resulting terminal input configuration table (used by the runtime
system during ACCEPT statements) is too large or out of memory.
406 An attempt has been made to redefine the terminal interface.
407 Syntax error.
408 An attempt has been made to describe a terminal characteristic and

either a terminal interface has not been defined, or the terminal
characteristic is not valid with the defined terminal interface.
409 A value has not been provided where expected or the value is invalid.

Number Description
410 The configuration file requested in the Runtime Command was not
found.
411 A logical configuration record exceeds the maximum length.
Runcobol Initialization Messages

During its initialization, the runtime system may issue several messages, some of which
are error diagnostics and some of which are informational.
Initialization Errors
If the runtime system receives an error from the operating system during initialization, the
following message appears:
RM/COBOL: Operating System Initialization Error. OS Error

Code: code
code depends on the operating system on which the file resides. See the description
of the 30, OS error code on page A-14 for more information.
Message File Processing Errors

During initialization, the runtime system locates and reads its message file. If it cannot
find its message file or the message file is corrupt, one of the following messages appears:

The runtime system compares its version number and product code with those in the
message file. If they do not match, one or both of the following messages appears:
RM/COBOL: Message file version mismatch, expected 7.0n.nn, found n.nn.nn

RM/COBOL: Message file product mismatch, expected XX, found YY
When any of the above messages appear, the runtime system terminates with the
following message:
Error invoking mismatched runtime and message file.

The runtime system message file may have the wrong name or be in the wrong directory.
The runtime system message file must have the name run.msg (RUN.MSG under
UNIX). The runtime system attempts to find the message file in the directory that
contains the runcobol executable file, the current directory, or through the PATH
directory search sequence (see page 2-4 for UNIX or page 3-11 for Windows).
Note On some UNIX environments, it is impossible to determine which directory

When the runtime system detects that the message file version does not match its own
version, the following message appears:
RM/COBOL: Message file version mismatch.
The occurrence of this message does not prevent the runtime system from continuing, but
the messages that it generates may be not correct.
Option Processing Errors

If the runtime system detects an unknown option letter, a known option letter in error or
an option not terminated with a space or comma, the following message appears:
letter option not valid.
letter is the erroneous option letter.
Further processing is done for libraries (as specified by the L Runtime Command Option)
during which control structures are built for use later in the run unit. If errors are
encountered during this processing, the following message appears:
COBOL procedure error code. Error processing library.
Main Program Loading Errors

If errors are encountered during the load and initialization of the main program, the
COBOL procedure error code. Error loading main program.

Runcobol Banner Message
The banner message appears when you first invoke RM/COBOL. This message may be
suppressed with the K Runtime Command Option:
RM/COBOL Runtime - Version 7.0n.nn for operating system.

Copyright(c) 1985, 1986-1999 by Liant Software Corp. All rights reserved.
Registration Number: xx-nnnn-nnnnn-nnnn
Runcobol Usage Message

The following message appears in response to entering a Runtime Command without
parameters:
Usage: runcobol name [options]

Options: [A=arguments] [B=buffersize] [C=configfile] [D] [I] [K]
[L=libname] [M] [S=switches] [T=sortsize] [X=configmod]
Registration Error Messages

Attempting to execute more runtime systems than are authorized causes the following
message to appear:
Error invoking unauthorized copy of runtime.
Note Registration checking on Novell is sometimes performed using server facilities and
will be enforced until the runtime product terminates, or the server is aware that the client
station is no longer connected to the network. If a runtime system is not properly
terminated due to the powering off of the client machine or rebooting it, the server will
not be aware of the absence of the client until the client starts the network shell again.

COBOL Normal Termination Messages
When the runtime system encounters a STOP RUN statement or a GOBACK statement in
the main program of a run unit, the following message appears:
COBOL STOP RUN at line number in prog-id
This message may be suppressed with the K Runtime Command Option.
When the runtime system encounters a STOP literal or STOP data item statement, the
"literal or data item" at line number in prog-id

Continue (Y/N)?
If you enter Y or y, execution continues with the next executable statement. If you enter
N or n, execution ends as if a STOP RUN statement was encountered.

COBOL Normal Termination Messages
Appendix B: Limits and Ranges
This appendix describes RM/COBOL limits and ranges.
Note See also Chapter 4, System Considerations for Btrieve, for a description of the
limitations of the Btrieve MicroKernel Database Engine (MKDE), and the way in which
these limitations affect RM/COBOL indexed files. Although these two systems perform
the same functions, they do not operate in the same manner.
RM/COBOL Limits and Ranges

No more than 98133 unique user-defined words (alphabet-names, cd-names, class-names,
condition-names, data-names, file-names, index-names, key-names, mnemonic-names,
paragraph-names, section-names, and symbolic-characters), where each name is
30 characters in length, may be defined in a single source program. When names
average less than 30 characters in length, more unique user-defined words are allowed.
For example, names averaging 12 characters in length doubles the limit to 196,266
unique user-defined words. The COBOL user-defined word categories level-number,
library-name, program-name, segment-number and text-name do not count towards
this limit.
No more than 65534 identifiers may be defined in a single source program, including any
of its nested source programs. Only 65533 identifiers may be defined in the Data
Division (see below for information about compiler generated identifiers that occur in the
Procedure Division). Note that the compiler implicitly defines identifier entries, reducing
the number that can be explicitly defined, as follows:
• one for each LINAGE-COUNTER associated with any files described with the
LINAGE clause;
• one for each variable length record file that has multiple record descriptions and no
record description is a group having the maximum record length;
• one for each indexed file with a CODE-SET or COLLATING-SEQUENCE that
requires that an external collating sequence be provided, that is, when the specified or
implicit code-set for the file requires a mapping other than identity to obtain the
specified or implicit collating sequence used for record keys of the file;
• one for each RERUN clause;
• one for a RETURN-CODE special register item if the program contains an explicit
reference to RETURN-CODE or contains a STOP RUN identifier/integer statement;
RM/COBOL User's Guide for 32-Bit Windows B-1

• one for each temporary index needed for any INITIALIZE, INSPECT, MOVE,
STRING or UNSTRING statements that reference one or more subscripted data
items (the compiler reuses these for each statement, thus defining only the maximum
needed for any one such statement); and
• five for control information if one or more simple (COBOL nucleus level 1)
INSPECT statements are contained in the source program. The maximum length of
an elementary data item is 65280 characters.
The maximum length of an element of a table is 65280 characters (that is, data items
subordinate to an OCCURS clause cannot exceed 65280 characters in length).
The maximum number of occurrences of a table element is 65535. That is, in an

OCCURS clause, the value of integer-2 must be less than or equal to 65535.
Data items greater than 65280 characters in length may be referenced in a MOVE
statement or the USING phrase of a CALL statement, but may not be referred to in any
other context.
Data items greater than 65280 characters in length may not be reference modified.
The maximum guaranteed precision for mathematical calculations is 36 decimal digits.

This limit applies to all mathematical operations except exponentiation where the
maximum guaranteed precision is 18 decimal digits.
A record key of an indexed file may not exceed 254 characters in length.
A maximum of 255 keys may be declared for an indexed file (one prime key and up
to 254 alternate keys).
A record of a file may not exceed 65280 characters in length.
A single paragraph cannot exceed 32512 bytes of generated object code.
The maximum number of USING items in a CALL statement or a Procedure Division

header is 255.
The maximum length of literals generated for any one segment type within a program may
not exceed 65535 bytes. Segment type refers to fixed permanent, fixed overlayable and
independent. Segmentation can greatly increase the number of literals a program may
have, since literals are overlaid for each segment.
The maximum number of external items in a single, separately compiled program—

including any of its contained programs—is limited to 2046.
Note Refer to Table 6-1 (beginning on page 6-36) for additional compilation limits.
B-2 Limits and Ranges

Appendix C: Internal Data
Formats
This appendix describes and illustrates the internal representations of the data types.
Internal Data Formats

The particular format in which the RM/COBOL compiler stores data is determined
by the specification of any of the following clauses in the data description entry for the
data item:
1. PICTURE clause. This clause classifies a data item as signed or unsigned numeric
or as nonnumeric.
2. USAGE clause. This clause modifies the format of a numeric data item. All
nonnumeric data items are always considered to be DISPLAY usage.
3. SIGN clause. This clause determines the format and the position (separate leading,
combined leading, separate trailing or combined trailing) of the operational sign for
signed numeric DISPLAY data items. The SIGN clause cannot be used for any
other type of data item.
The following formats are described:

• Nonnumeric data: Alphanumeric Edited, Alphabetic Edited, Alphabetic, and
Numeric Edited
• Numeric data:
− Unsigned numeric DISPLAY (NSU) − Signed numeric COMPUTATIONAL-1
− Signed numeric DISPLAY − Unsigned numeric COMPUTATIONAL-3
(TRAILING SEPARATE sign) (PACKED-DECIMAL)
− Signed numeric DISPLAY − Signed numeric COMPUTATIONAL-3
(LEADING SEPARATE sign) (PACKED-DECIMAL)
− Signed numeric DISPLAY − Unsigned numeric COMPUTATIONAL-4
(TRAILING sign) (BINARY)
− Signed numeric DISPLAY − Signed numeric COMPUTATIONAL-4
(LEADING sign) (BINARY)
− Unsigned numeric COMPUTATIONAL − Unsigned numeric COMPUTATIONAL-6
− Signed numeric COMPUTATIONAL
RM/COBOL User's Guide for 32-Bit Windows C-1

Internal Data Formats
Illustrations are presented as follows:
01 EXAMPLE PIC S9(3)V9(2) VALUE +514.72

DISPLAY SIGN LEADING SEPARATE.
0 1 2 3 4 5
2B 35 31 34 37 32
The line of source code shows the RM/COBOL statement itself. The values inside the
box show the hexadecimal data values in bytes, as stored in memory. The numbers above
the box show the hexadecimal relative byte address.
The ASCII code-set is used to represent all data items whose usage is DISPLAY.
Nonnumeric Data
Nonnumeric data items are formatted one character per byte. The leftmost character
starts at the lowest address. Edited nonnumeric data items have an associated editing
PICTURE character-string that is used only when the data item is a receiving operand.
Nonnumeric data items always have DISPLAY usage.
The SIGN clause does not apply to nonnumeric data items. The BLANK WHEN ZERO
clause—when associated with a numeric PICTURE character-string—causes the data
item to be treated as numeric edited.
Table C-1 lists the types of nonnumeric data, the compiler designation for each type, and
the valid picture symbols for each type.
Table C-1 Nonnumeric Data
Data Type Compiler Designation Picture Symbols

Alphanumeric ANS A X 9
Alphanumeric Edited ANSE A B X 0 9 /
Alphabetic ABS A
Alphabetic Edited ABSE A B
Numeric Edited NSE B P V Z 0 9/ , . $ + – *
CR DB
When the CURRENCY SIGN clause is specified in the SPECIAL-NAMES paragraph,

the character specified in that clause is also a permissible picture symbol for numeric
edited data items.
C-2 Internal Data Formats

Nonnumeric Data
The full ASCII code-set is stored as follows:
01 ANS1 PIC X(95) VALUE

" !""#$%&'()*+,-./0123456789:;<=>?
- "@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_
- "`abcdefghijklmnopqrstuvwxyz{|}~"
DISPLAY.
0 1 2 3 4 5 6 7
00: 20 21 22 23 24 25 26 27
08: 28 29 2A 2B 2C 2D 2E 2F
10: 30 31 32 33 34 35 36 37
18: 38 39 3A 3B 3C 3D 3E 3F
20: 40 41 42 43 44 45 46 47
28: 48 49 4A 4B 4C 4D 4E 4F
30: 50 51 52 53 54 55 56 57
38: 58 59 5A 5B 5C 5D 5E 5F
40: 60 61 62 63 64 65 66 67
48: 68 69 6A 6B 6C 6D 6E 6F
50: 70 71 72 73 74 75 76 77
58: 78 79 7A 7B 7C 7D 7E

Nonnumeric Data
Alphanumeric Edited
01 ANSE1 PIC XX/9900/AABB VALUE "**/1200/QR " DISPLAY.
0 1 2 3 4 5 6 7 8 9 a b
2A 2A 2F 31 32 30 30 2F 51 52 20 20
Alphabetic
01 ABS1 PIC A(12) VALUE "STOCK NUMBER" DISPLAY.
0 1 2 3 4 5 6 7 8 9 a b
53 54 4F 43 4B 20 4E 55 4D 42 45 52
Alphabetic Edited
01 ABSE1 PIC AA BAABAA VA LUE "XX YY ZZ" DISPL AY.
0 1 2 3 4 5 6 7
58 58 20 59 59 20 5A 5A
Numeric Edited
01 NSE1 PIC $*(5).**CR VALUE "$***24.13 " DISPLAY.
0 1 2 3 4 5 6 7 8 9 a
24 2A 2A 2A 32 34 2E 31 33 20 20
01 NSE2 PIC $(6).99+ VALUE 4913.78 DISPLAY.

0 1 2 3 4 5 6 7 8 9
20 24 34 39 31 33 2E 37 38 2B

Nonnumeric Data
Numeric Data
Any numeric data item, regardless of usage, must contain at least one digit position and
may contain as many as thirty digit positions.
A numeric data item may vary in size from 1 to 31 bytes. Storage requirements for a
numeric item depend on the usage, the number of digits, and the presence of an
operational sign.
Numeric DISPLAY data items are formatted one digit character per byte. The number is
formatted as an integer aligned with the most significant digit at the lowest address and
the least significant digit at the highest address. The position of the implied decimal point
is maintained in a separate data descriptor. The format descriptions of the numeric
DISPLAY data items begin on page C-6.
Numeric computational data items are formatted in a variety of ways depending on the
specific USAGE applied to the data item and whether the data item is unsigned or signed.
The various numeric computational data item formats are described beginning on
page C-11

Numeric Data
Unsigned Numeric DISPLAY (NSU)
No storage is allocated for an operational sign.
Valid picture symbols are 9, V and P. Usage is always DISPLAY.
Format Illustrations
01 NSU1 PIC 9(3)V9(2) VALUE 731.24 DISPLAY.
0 1 2 3 4
37 33 31 32 34
01 NSU2 PIC 9(6)V9(6) VALUE 3456.7 DISPLAY.

0 1 2 3 4 5 6 7 8 9 a b
30 30 33 34 35 36 37 30 30 30 30 30
01 NSU3 PIC 9(5)PP VALUE 5712300 DISPLAY.

0 1 2 3 4
35 37 31 32 33
01 NSU4 PIC P9(7) VALUE 0.09431726 DISPLAY.

0 1 2 3 4 5 6
39 34 33 31 37 32 36

Numeric Data
Signed Numeric DISPLAY (TRAILING SEPARATE)
Signed numeric DISPLAY data items described with the SIGN IS TRAILING
SEPARATE clause are formatted with an additional byte for the operational sign. This
sign occupies a separate byte following the least significant digit byte. A positive sign is
represented by a value of 2Bh. A negative sign is represented by a value of 2Dh.
If the S (separate sign) Compile Command Option is specified, the compiler assumes the
presence of the SIGN IS TRAILING SEPARATE clause for all signed numeric
DISPLAY data items for which the SIGN clause is not explicitly stated.
Signed numeric DISPLAY data (TRAILING SEPARATE) is designated as NTS. The

valid picture symbols are S, 9, V and P. Usage is always DISPLAY. The sign is always
TRAILING SEPARATE.
01 NTS1 PIC S9(3)V9(2) VALUE -731.24

SIGN TRAILING SEPARATE DISPLAY.
0 1 2 3 4 5
37 33 31 32 34 2D
01 NTS2 PIC S9(4)V9(7) VALUE -34.567

0 1 2 3 4 5 6 7 8 9 a b
30 30 33 34 35 36 37 30 30 30 30 2D
01 NTS3 PIC S9(5)PP VALUE +5712300

0 1 2 3 4 5
35 37 31 32 33 2B
01 NTS4 PIC SP9(7) VALUE -.09431726

0 1 2 3 4 5 6 7
39 34 33 31 37 32 36 2D

Numeric Data
Signed Numeric DISPLAY (LEADING SEPARATE)
Signed numeric DISPLAY data items described with the SIGN IS LEADING
SEPARATE clause are formatted with an additional byte for the operational sign. The
operational sign occupies a separate byte preceding the most significant digit byte. A
positive sign is represented by a value of 2Bh. A negative sign is represented by a value
of 2Dh.
Signed numeric DISPLAY data (LEADING SEPARATE) is designated as NLS. The

valid picture symbols are S, 9, V and P. Usage is always DISPLAY. The sign is always
LEADING SEPARATE.
01 NLS1 PIC S9(3)V9(2) VALUE +731.24

SIGN LEADING SEPARATE DISPLAY.
0 1 2 3 4 5
2B 37 33 31 32 34
01 NLS2 PIC S9(2)V9(7) VALUE -7.6543

0 1 2 3 4 5 6 7 8 9
2D 30 37 36 35 34 33 30 30 30
01 NLS3 PIC S9(5)PP VALUE +5712300

0 1 2 3 4 5
2B 35 37 31 32 33
01 NLS4 PIC SP9(7) VALUE +.09431726

0 1 2 3 4 5 6 7
2B 39 34 33 31 37 32 36

Numeric Data
Signed Numeric DISPLAY (TRAILING)
Signed numeric DISPLAY data items described with the SIGN IS TRAILING clause are
formatted with the highest addressed byte containing the operational sign combined with
the low-order digit.
Because of the combined digit and sign, this format is sometimes called trailing combined
sign. It is also sometimes called trailing zoned sign because the sign is represented in a
manner consistent with a sign zone punch and digit punch on Hollerith punch cards.
The hexadecimal values that result from this combination are shown in Table C-2.
Table C-2 Combined Digit and Sign
Digit Positive Negative

0 7B 7D
1 41 4A
2 42 4B
3 43 4C
4 44 4D
5 45 4E
6 46 4F
7 47 50
8 48 51
9 49 52
This format is the default for all signed numeric DISPLAY data items when the SIGN
clause is not specified, unless the S (separate sign) Compile Command Option is
specified.
Signed numeric DISPLAY data (TRAILING) is designated as NTC. The valid picture
symbols are S, 9, V and P. Usage is always DISPLAY. The sign is always TRAILING.
Note that if an NTC data item is sent directly to a printer or display device, the position
that contains the combined sign and digit appears as a special character or letter. A
positive zero value appears as {. A negative zero value appears as }. Positive 1 through
9 values appear as A through I. Negative 1 through 9 values appear as J through R.

Numeric Data
01 NTC1 PIC S9(3)V9(2) VALUE -731.24

SIGN TRAILING DISPLAY.
0 1 2 3 4
37 33 31 32 4D
01 NTC2 PIC S9(2)V9(7) VALUE -3.14159

0 1 2 3 4 5 6 7 8
30 33 31 34 31 35 39 30 7D
01 NTC3 PIC S9(5)PP VALUE +5712300

0 1 2 3 4
35 37 31 32 43
01 NTC4 PIC SP9(7) VALUE -.09431726

0 1 2 3 4 5 6
39 34 33 31 37 32 4F
Signed Numeric DISPLAY (LEADING)

Signed numeric DISPLAY data items described with the SIGN IS LEADING clause are
formatted with the lowest addressed byte containing the operational sign combined with
the high-order digit. The hexadecimal values that result from this combination are listed
in Table C-2 on page C-9.
Because of the combined digit and sign, this format is sometimes called leading combined
sign. It is also sometimes called leading zoned sign because the sign is represented in a
manner consistent with a sign zone punch and digit punch on Hollerith punch cards.
Signed numeric DISPLAY data (LEADING) is designated as NLC. The valid picture
symbols are S, 9, V and P. Usage is always DISPLAY. The sign is always LEADING.

Numeric Data
Note that if an NLC data item is sent directly to a printer or display device, the position
that contains the combined sign and digit appears as a special character or letter. A
positive zero value appears as {. A negative zero value appears as }. Positive 1 through
9 values appear as A through I. Negative 1 through 9 values appear as J through R.
01 NLC1 PIC S9(3)V9(2) VALUE -731.24

SIGN LEADING DISPLAY.
0 1 2 3 4
50 33 31 32 34
01 NLC2 PIC S9V9(7) VALUE -2.9876

0 1 2 3 4 5 6 7
4B 39 38 37 36 30 30 30
01 NLC3 PIC S9(5)PP VALUE +5712300

0 1 2 3 4
45 37 31 32 33
01 NLC4 PIC SP9(7) VALUE +.09431726

0 1 2 3 4 5 6
49 34 33 31 37 32 36
Unsigned Numeric COMPUTATIONAL

For the default configuration, COMPUTATIONAL (or COMP) data items are formatted
as one binary coded decimal digit per byte.
Note The compiler can be configured to treat data items described as

COMPUTATIONAL (or COMP) as having been described as BINARY,

Numeric Data
PACKED-DECIMAL, or DISPLAY using the COMPUTATIONAL-TYPE keyword of
the COMPILER-OPTIONS configuration record. In those cases, the default format for
COMPUTATIONAL data items described here does not apply; please refer to the
corresponding section of this appendix if you have configured one of the other formats
for COMPUTATIONAL data.
The number is formatted as an integer aligned with the most significant digit at the lowest
address and the least significant digit at the highest address. The position of the implied
decimal point is maintained in a separate data descriptor.
Unsigned numeric COMPUTATIONAL data is designated as NCU. The valid picture

symbols are 9, V and P. Usage is always COMPUTATIONAL or COMP.
01 NCU1 PIC 9(3)V9(2) VALUE 731.24

COMPUTATIONAL.
0 1 2 3 4
07 03 01 02 04
01 NCU2 PIC 9(3)V9(4) VALUE 23.45

COMPUTATIONAL.
0 1 2 3 4 5 6
00 02 03 04 05 00 00
01 NCU3 PIC 9(5)PP VALUE 5712300

COMPUTATIONAL.
0 1 2 3 4
05 07 01 02 03
01 NCU4 PIC P9(7) VALUE .09431726

COMPUTATIONAL.
0 1 2 3 4 5 6
09 04 03 01 07 02 06

Numeric Data
Signed Numeric COMPUTATIONAL
For the default configuration, signed numeric COMPUTATIONAL (or COMP) data
items are formatted as one binary coded decimal digit per byte.
Note The compiler can be configured to treat data items described as

COMPUTATIONAL (or COMP) as having been described as BINARY,
PACKED-DECIMAL, or DISPLAY using the COMPUTATIONAL-TYPE keyword of
the COMPILER-OPTIONS configuration record. In those cases, the default format for
signed numeric COMPUTATIONAL data items described here does not apply; please
refer to the corresponding section of this appendix if you have configured one of the
other formats for COMPUTATIONAL data.
The operational sign occupies a separate byte following the least significant digit. A
negative sign is represented by the value 0Dh. A positive sign is normally represented
by a value of 0Ch. The COMPUTATIONAL-VERSION keyword of the
COMPILER-OPTIONS configuration record may alter the positive sign representation.
Selecting a value of RMCOBOL2 or RMCOS for COMPUTATIONAL-VERSION will
cause the positive sign to be represented by a value of 0Bh.
Signed COMPUTATIONAL data is designated as NCS, unpacked signed. The valid
picture symbols are S, 9, V and P. Usage is always COMPUTATIONAL or COMP.
01 NCS1 PIC S9(3)V9(2) VALUE -731.24

COMPUTATIONAL.
0 1 2 3 4 5
07 03 01 02 04 0D
01 NCS2 PIC S9(3)V9(4) VALUE 123.4567

COMPUTATIONAL.
0 1 2 3 4 5 6 7
01 02 03 04 05 06 07 0C

Numeric Data
01 NCS3 PIC S9(5)PP VALUE +5712300
COMPUTATIONAL.
0 1 2 3 4 5
05 07 01 02 03 0C
01 NCS4 PIC SP9(7) VALUE -.09431726

COMPUTATIONAL.
0 1 2 3 4 5 6 7
09 04 03 01 07 02 06 0D
Signed Numeric COMPUTATIONAL-1 Data

Signed numeric COMPUTATIONAL-1 (or COMP-1) data items are formatted as 2’s
complement binary words. The number of 9’s in the PICTURE character-string does not
affect the allocation size for COMPUTATIONAL-1 data items. Such data items are
always considered signed without regard to the presence or absence of an S in the
associated PICTURE character-string. COMP-1 usage is restricted to integer data items
without “P” scaling.
The number is formatted as a 2’s complement binary word with the most significant byte
at the lowest address and the least significant byte at the highest address.
The operational sign is indicated by the 2’s complement format. If the most significant
bit is zero, the number is positive. If this bit is one, the number is negative.
Signed numeric COMPUTATIONAL-1 data is designated as NBS, Binary Signed.

The valid picture symbols are S, 9 and V. Usage is always COMPUTATIONAL-1
or COMP-1.
01 NBS1-COMP-1 PIC S9(4) VALUE +1000

COMPUTATIONAL-1.
0 1
03 E8

Numeric Data
01 NBS2-COMP-1 PIC S9(4) VALUE -1000
COMPUTATIONAL-1.
0 1
FC 18
01 NBS3-COMP-1 PIC S9(5) VALUE -32768

COMPUTATIONAL-1.
0 1
80 00
01 NBS4-COMP-1 PIC S9(5) VALUE +32767

COMPUTATIONAL-1.
0 1
7F FF
Unsigned Numeric COMPUTATIONAL-3 Data

Unsigned numeric COMPUTATIONAL-3 (or COMP-3) and PACKED DECIMAL data
items are formatted as two binary coded decimal digits per byte, except for the highest
addressed byte which contains one digit followed by an operational sign. If the associated
PICTURE character-string contains an even number of 9’s, an additional high-order digit
is included in the storage allocated for the data item so as to complete an integral number
of bytes.
The operational sign is concatenated with the least significant digit in the highest
addressed byte. The high-order four bits of the byte is the least significant digit and the
low-order four bits of the byte is the operational sign. The sign is always Fh, denoting a
positive value.
Unsigned numeric COMPUTATIONAL-3 data is designated as NPP, packed unsigned.

The valid picture symbols are 9, V and P. Usage is COMPUTATIONAL-3, COMP-3
or PACKED-DECIMAL.

Numeric Data
01 NPP1 PIC 9(3)V9(3) VALUE 731.246

PACKED-DECIMAL.
0 1 2 3
07 31 24 6F
01 NPP2 PIC 9(8)V9(7) VALUE 123456.789

PACKED-DECIMAL.
0 1 2 3 4 5 6 7
00 12 34 56 78 90 00 0F
01 NPP3 PIC 9(5)PP VALUE 5712300

PACKED-DECIMAL.
0 1 2
57 12 3F
01 NPP4 PIC P9(7) VALUE .09431726

PACKED-DECIMAL.
0 1 2 3
94 31 72 6F

Signed numeric COMPUTATIONAL-3 (or COMP-3) and PACKED DECIMAL data
items are formatted as two binary coded decimal digits per byte, except for the highest
addressed byte, which contains one digit followed by an operational sign. If the
associated PICTURE character-string contains an even number of 9’s, an additional
high-order digit is included in the storage allocated for the data item so as to complete an
integral number of bytes.

Numeric Data
The operational sign is concatenated with the least significant digit in the highest
addressed byte. The high-order four bits of the byte is the least significant digit and the
low-order four bits of the byte is the operational sign. A negative sign is represented by
the value Dh. A positive sign is normally represented by a value of Ch. The
COMPUTATIONAL-VERSION keyword of the COMPILER-OPTIONS configuration
record may alter the positive sign representation. Selecting a value of RMCOBOL2 for
COMPUTATIONAL-VERSION causes the positive sign to be represented by a value of
Fh. Selecting a value of RMCOS for COMPUTATIONAL-VERSION causes the
positive sign to be represented by a value of Bh.
Signed numeric COMPUTATIONAL-3 data is designated as NPS, packed signed. The

valid picture symbols are S, 9, V and P. Usage is COMPUTATIONAL-3, COMP-3 or
PACKED-DECIMAL.
01 NPS1 PIC S9(3)V9(3) VALUE -731.246

PACKED-DECIMAL.
0 1 2 3
07 31 24 6D
01 NPS2 PIC S9(8)V9(7) VALUE 123456.789

PACKED-DECIMAL.
0 1 2 3 4 5 6 7
00 12 34 56 78 90 00 0C
01 NPS3 PIC S9(5)PP VALUE -5712300

PACKED-DECIMAL.
0 1 2
57 12 3D
01 NPS4 PIC SP9(7) VALUE -.09431726

PACKED-DECIMAL.
0 1 2 3
94 31 72 6D

Numeric Data
Unsigned numeric COMPUTATIONAL-4 (or COMP-4) and BINARY data items are
formatted as binary bytes. If the USAGE clause specified a binary allocation override,
the number of bytes allocated is the number specified in the binary allocation override.
Otherwise, the number of bytes depends on the number of 9's in the associated
PICTURE character-string and the setting of the BINARY-ALLOCATION and
BINARY-ALLOCATION-SIGNED keywords of the COMPILER-OPTIONS
configuration record according to Table C-3.
Note When BINARY-ALLOCATION=CUSTOM=integer-list is configured for the

compiler, then the compiler allocates the smallest number of bytes that support the
decimal precision indicated by the PICTURE character-string and that is an allowed size
in integer-list. See Table C-3 under BINARY-ALLOCATION=MF-RM for the smallest
number of bytes needed for an unsigned binary numeric data item of a given decimal
precision. However, if BINARY-ALLOCATION-SIGNED=YES is also configured for
the compiler, the number of byes allocated will be according to Table C-4 (on page C-22)
instead of Table C-3. If integer-list does not include a size large enough to support the
decimal precision, the compiler produces a warning and uses the default allocation sizes
shown for BINARY-ALLOCATION=RM.
The number is formatted as a binary integer with the most significant byte at the lowest
address and the least significant byte at the highest address. The position of the decimal
point is maintained in a separate data descriptor.
For unsigned binary items there is no operational sign. In particular, the most significant
bit is not indicative of the sign. The value is always interpreted as a positive number.
Unsigned numeric COMPUTATIONAL-4 data is designated as NBU, binary unsigned.
The valid picture symbols are 9, V and P. Usage is COMPUTATIONAL-4, COMP-4
or BINARY.

Numeric Data
Table C-3 Bytes Allocated for an Unsigned Binary Numeric Data Item
BINARY-ALLOCATION=RM (Default)
Number of 9's in PICTURE character-string Bytes Allocated
1-4 2
5-9 4
10-18 8
19-30 16
BINARY-ALLOCATION=RM1
1-2 1
3-4 2
5-9 4
10-18 8
19-30 16
BINARY-ALLOCATION=MF-RM
1-2 1
3-4 2
5-7 3
8-9 4
10-12 5
13-14 6
15-16 7
17-19 8
20-21 9
22-24 10
25-26 11
27-28 12
29-30 13

Numeric Data
01 NBU1 PIC 9(3)V9 VALUE 123.4

BINARY.
0 1
04 D2
01 NBU2 PIC 9(5)PP VALUE 5712300

BINARY.
0 1 2 3
00 00 DF 23
01 NBU3 PIC 9(18) VALUE 141824562226

BINARY.
0 1 2 3 4 5 6 7
00 00 00 21 05 67 14 32
01 NBU4 PIC P9(7) VALUE .09431726

BINARY.
0 1 2 3
00 8F EA AE
01 NBU5 PIC 9(5) VALUE 42034

BINARY(2).
0 1
A4 32

Numeric Data
Signed numeric COMPUTATIONAL-4 (or COMP-4) and BINARY data items are
formatted as 2’s complement binary bytes. If the USAGE clause specified a binary
allocation override, the number of bytes allocated is the number specified in the binary
allocation override. Otherwise, the number of bytes depends on the number of 9's in
the associated PICTURE character-string and the setting of the BINARY-ALLOCATION
keyword of the COMPILER-OPTIONS configuration record according to
Table C-4.
Note When BINARY-ALLOCATION=CUSTOM=integer-list is configured for the

compiler, then the compiler allocates the smallest number of bytes that support the
decimal precision indicated by the PICTURE character-string and that is an allowed size
in integer-list. See Table C-4 under BINARY-ALLOCATION=MF-RM for the smallest
number of bytes needed for a signed binary numeric data item of a given decimal
precision. If integer-list does not include a size large enough to support the decimal
precision, the compiler produces a warning and uses the default allocation sizes shown for
BINARY-ALLOCATION=RM.
The number is formatted as a binary integer with the most significant byte at the lowest
address and the least significant byte at the highest address. The position of the decimal
point is maintained in a separate data descriptor.
The operational sign is indicated by the 2’s complement format. If the most significant
bit is zero, the number is positive. If this bit is one, the number is negative.
Signed numeric COMPUTATIONAL-4 data is designated as NBS, binary signed. The

valid picture symbols are S, 9, V and P. Usage is COMPUTATIONAL-4, COMP-4
or BINARY.

Numeric Data
Table C-4 Bytes Allocated for a Signed Binary Numeric Data Item
BINARY-ALLOCATION=RM (Default)
1-4 2
5-9 4
10-18 8
19-30 16
BINARY-ALLOCATION=RM1
1-2 1
3-4 2
5-9 4
10-18 8
19-30 16
BINARY-ALLOCATION=MF-RM
1-2 1
3-4 2
5-6 3
7-9 4
10-11 5
12-14 6
15-16 7
17-18 8
19-21 9
22-23 10
24-26 11
27-28 12
29-30 13

Numeric Data
01 NBS1 PIC S9(3)V9 VALUE -123.4

BINARY.
0 1
FB 2E
01 NBS2 PIC S9(5)PP VALUE -5712300

BINARY.
0 1 2 3
FF FF 20 DD
01 NBS3 PIC S9(18) VALUE -141824562226

BINARY.
0 1 2 3 4 5 6 7
FF FF FF DE FA 98 EB CE
01 NBS4 PIC SP9(7) VALUE -.09431726

BINARY.
0 1 2 3
FF 70 15 52
01 NBS5 PIC S9(3) VALUE 95

BINARY(1).
0
5F

Numeric Data
Unsigned numeric COMPUTATIONAL-6 (COMP-6) data items are formatted as two
binary coded decimal digits per byte. If the picture contains an odd number of 9’s, an
additional high-order digit is included in the storage allocated for the item.
Unsigned numeric COMPUTATIONAL-6 data is designated as NPU, packed unsigned.

The valid picture symbols are 9, V and P. Usage is COMPUTATIONAL-6 or COMP-6.
01 NPU1 PIC 9(3)V9(2) VALUE 731.24

COMPUTATIONAL-6.
0 1 2
07 31 24
01 NPU2 PIC 9(8)V9(8) VALUE 123456.789

COMPUTATIONAL-6.
0 1 2 3 4 5 6 7
00 12 34 56 78 90 00 00
01 NPU3 PIC 9(5)PP VALUE 5712300

COMPUTATIONAL-6.
0 1 2
05 71 23
01 NPU4 PIC P9(6) VALUE .0943172

COMPUTATIONAL-6.
0 1 2
94 31 72

Numeric Data
Appendix D: Customizing
RM/COBOL for UNIX
This appendix provides information required to customize the runtime system portion of
RM/COBOL for UNIX and to relink other portions of the product. It also contains
information on adding C or assembly language subprograms to the runtime system.
Examples are provided.
Using the customiz Shell Script to Customize

RM/COBOL
This version of RM/COBOL includes a UNIX Bourne Shell script, customiz, that can be
used to generate a Makefile to customize various RM/COBOL products. The
RM/COBOL products that can be customized in this manner include the following:
• RM/COBOL runtime system
• RM/COBOL development system (compiler)
• RM/COBOL Indexed File Recovery utility program
• RM/COBOL Open File Manager
• RM/InfoExpress server
For some of these products, different variations can be built by including one or more of
the following software components:
• Termcap or terminfo terminal interfaces
• RM/InfoExpress client
• RM/plusDB
• Pop-Up Window Manager
• MCBA C language routines
• Flexgen C language routines
RM/COBOL User's Guide for 32-Bit Windows D-1

Using the customiz Shell Script to Customize RM/COBOL
• Enterprise CodeBench
• VanGui Interface Builder
The RM/COBOL runtime system also can be customized by adding C (or assembly)
language subprograms, a Message Control System (MCS), or a built-in configuration file
(see “Other Runtime Customizations” on page D-5).
Terminfo or Termcap Terminal Interfaces

The RM/COBOL runtime system is shipped with a default terminal interface driver
(normally terminfo) for your platform. If you want to change your configuration, you can
rebuild your runtime system either with the terminfo or with the termcap terminal
interface. To use the termcap terminal interface, invoke customiz, choose option 1
(runcobol), and type “2” at the following prompt:
Would you like Terminfo or Termcap terminal interface(1/2)?
Type “1” to use the terminfo terminal interface.
RM/InfoExpress Client
The RM/InfoExpress add-on product for RM/COBOL is designed to optimize
RM/COBOL data file access on various local area networks (LANs) and wide area
networks (WANs). It allows RM/COBOL programs to realize significant speed
improvements for sequential, relative, and indexed files over conventional network access
methods. To add the RM/InfoExpress client to your runtime system, invoke customiz,
choose option 1 (runcobol), and type “y” at the following prompt:
Would you like to build the RM/InfoExpress client (y/n)?
Type “n” not to include RM/InfoExpress.
When you answer “y” to the preceding prompt, the customiz program will ask for the
directory where the RM/InfoExpress server software is installed. See the RM/InfoExpress
User’s Guide for more information on installing RM/InfoExpress.
RM/InfoExpress also can be included with the RM/COBOL Open File Manager and
the RM/COBOL compiler in the same way. An RM/COBOL Open File Manager that is
linked with the RM/InfoExpress client can be used to access remote RM/COBOL data
files using the RM/InfoExpress server. Similarly, an RM/COBOL compiler that is linked
with the RM/InfoExpress client (running under UNIX or Windows) can be used to
compile a source program or access a library that is present on a machine running
RM/InfoExpress server software.
D-2 Customizing RM/COBOL for UNIX

RM/plusDB
RM/plusDB is an add-on product for RM/COBOL that enables an application to access
database systems such as Informix or Oracle with COBOL I/O statements. To add
RM/plusDB to your runtime system, invoke customiz, choose option 1 (runcobol), and
type “y” at the following prompt:
Would you like to build RM/plusDB (y/n)?
Type “n” not to include RM/plusDB.
When you answer “y” to the preceding prompt, the customiz program will prompt you for
the directory where the RM/plusDB software is installed. See the RM/plusDB User’s
Guide for more information about installing RM/plusDB.
RM/plusDB also can be included with the RM/InfoExpress server product by invoking
customiz, choosing option 5 (rmserver), and typing “y” at the prompt. (See Example 2
on page D-9.) RM/plusDB enables the remote RM/InfoExpress client applications
(running on UNIX and Windows machines) to access transparently the associated
database on a UNIX machine over the network.
Pop-Up Window Manager

The RM/COBOL runtime system is shipped with the Pop-Up Window Manager activated.
When the Pop-Up Window Manager is removed, it becomes unavailable to all
applications using the runtime system. This action may be desirable in some situations in
order to reduce the amount of memory used by the runtime system. If your application
does not use pop-up windows, screen I/O will be slightly faster with the Pop-Up Window
Manager removed.
To build a runtime system with the Pop-Up Window Manager removed, invoke customiz
(see Example 1 on page D-6), choose option 1 (runcobol), and type “n” at the following
prompt:
Would you like the Pop-Up Window Manager (y/n)?
Type “y” to include the Pop-Up Window Manager.

MCBA C Language Routines
C language subprograms can be acquired from MCBA, Inc. as an add-on product
for RM/COBOL. To add the MCBA C language subprograms to your runtime system,
invoke customiz, choose option 1 (runcobol), and type “y” at the following prompt:
Would you like the MCBA subroutines (y/n)?
Type “n” not to exclude the subprograms.
Flexgen C Language Routines

Easirun, USA, Inc.’s Flexgen C language subprograms can be requested from Liant as an
add-on product for RM/COBOL. To add the Flexgen C language subprograms to your
runtime system, invoke customiz, choose option 1 (runcobol), and type “y” at the
following prompt:
Would you like the Flexgen subroutines (y/n)?
Type “n” not to exclude the subprograms.
Enterprise CodeBench
Enterprise CodeBench is an add-on product for RM/COBOL that allows you to create,
edit, compile, debug, and run RM/COBOL applications on UNIX within the Windows
environment.
To add Enterprise CodeBench to your runtime system, invoke customiz, choose option 1
(runcobol), and type “y” at the following prompt:
Would you like Enterprise CodeBench (y/n)?
Type “n” to exclude Enterprise CodeBench.

VanGui Interface Builder
The add-on product, VanGui Interface Builder (referred to as VanGui), is designed to
allow you to use your choice of industry-standard GUI tools, such as Delphi or
Visual Basic, to update the client user interface of both Windows- and UNIX-based
RM/COBOL applications.
To add VanGui Interface Builder to your runtime system, invoke customiz, choose option
1 (runcobol), and type “y” at the following prompt:
Would you like VanGui Interface Builder (y/n)?
Type “n” to exclude VanGui.
Other Runtime Customizations

Three other customizations can be performed on the RM/COBOL runtime system:
1. Adding C (or assembly) language subprograms. The procedures for adding C (or
assembly) language subprograms begin on page D-12.
2. Adding a Message Control System (MCS). The Message Control System (MCS) is
discussed on page 8-65. To link your MCS with the runtime system, use the
customiz utility to generate a Makefile to build the runtime with the same
configuration as that of your current runtime system.
Use the following command:
make <product-name> MCS=mymcs.o
mymcs.o is the file containing the code for your MCS. The MCS parameter to the
make command can also be used with other runtime systems you build.
3. Adding a built-in configuration file. See Chapter 10, Configuration, for more
information.
Relinking the Same Product

Relinking the RM/COBOL product with the same configuration as originally delivered is
normally not performed. However, this can be achieved by using the customiz utility to
generate a Makefile to build the runtime with the same configuration as that of your
current runtime system. The only time that it should be necessary to relink RM/COBOL
is when the C library (libc.a) has been updated.

customiz Utility Examples
The following two examples demonstrate how to use the customiz utility to build
different products.
Example 1
This first example describes how to generate a Makefile to build a runtime system with
the termcap terminal interface, an RM/InfoExpress client, RM/plusDB, Enterprise
CodeBench, VanGui Interface Builder, and the Pop-Up Window Manager. It does not
include MCBA or Flexgen C language routines.
Note This example assumes that RM/InfoExpress, RM/plusDB, MCBA and Flexgen C
language routines, Enterprise CodeBench, and VanGui Interface Builder are supported on
your UNIX system. If that is not the case, the system prompts associated with these
products are not displayed.
1. To execute the customiz shell script, you must be in the directory where
RM/COBOL is installed. To invoke the shell script, type the following command:
customiz
If Makefile is present in the current directory, the following prompt is displayed:
Do you want to write over the existing Makefile (y/n)?
2. Type “n” to cause the program to exit without affecting the current status. Type “y”
to cause the program to erase the Makefile. Pressing the Interrupt key at any point
causes the program to remove the incomplete Makefile before exiting to the system.
The program displays the following screen:
RM/COBOL Customization
(Press system cancel to abort)
1. runcobol - RM/COBOL Runtime System

2. rmcobol - RM/COBOL Compiler
3. recover1 - RM/COBOL Indexed File Recovery Utility
4. ofm - RM/COBOL Open File Manager
5. rmserver - RM/InfoExpress Server
Enter product number:
Note Option 5 (rmserver) will not be displayed if RM/InfoExpress is not supported

on your UNIX system.

3. Choose option 1 (for runcobol) and press Enter.
The program responds with the following prompt, which will repeat until an
appropriate response is entered:
Building runcobol
-----------------
Would you like the Terminfo or Termcap terminal interface (1/2)?
4. Type “2” and press Enter to choose the termcap terminal interface.
The program responds with the following prompt:
Would you like to build the RM/InfoExpress client (y/n)?
5. Type “y” and press Enter.
The program displays the following prompt:
Enter the directory where RM/InfoExpress is installed

(Default is /usr/rminfox):
6. Type the complete pathname for the directory where RM/InfoExpress is installed.
customiz checks the system for the presence of the specified directory. If no
directory name is entered, the program uses /usr/rminfox as the default value.
Enter the directory where RM/plusDB is installed

(Default is /usr/rmdb):
directory name is entered, the program uses /usr/rmdb as the default value.
Would you like the Pop-Up Window Manager (y/n)?
8. Type “y” and press Enter. (The Pop-Up Window Manager is required for Enterprise
CodeBench, which is described in Step 10.)

The program then responds with the following prompt:
Would you like the MCBA C subroutines (y/n)?
9. Type “n” and press Enter.
Would you like the Flexgen C subroutines (y/n)?
10. Type “n” and press Enter.
Would you like the Enterprise CodeBench feature (y/n)?
Would you like the VanGui Interface Builder feature (y/n)?
customiz allows you to specify the executable filename of the linked product using
the following prompt:
Enter the product name (Default is <default name>):
13. Press Enter to use the default name or type the name of the final linked product.
The program builds the Makefile and displays the following prompt:
Makefile generation successful.

Would you like to build the product (y/n)?
a. If you want the program to build the product, type “y” and press Enter. The
program builds the product using the system make utility and the newly
generated make script specified in Makefile.
b. You may choose to run the make script yourself if you need to change the values
of the macros defined in the make script specified in Makefile. If you type “n”,
the program displays the following information and then exits:
Type ‘make’ to build the <product_name> product
Note If you look at the generated Makefile using any text editor, you will find
comments at the beginning about the configuration of the product built.

Example 2
The following example describes how to generate a Makefile to build an RM/InfoExpress

server with RM/plusDB.
Note This example assumes that RM/InfoExpress and RM/plusDB are supported on
your UNIX system.
1. Change to the directory where RM/COBOL is installed and type:
customiz
If Makefile is present in the current directory, the following prompt is displayed:
Do you want to write over existing Makefile (y/n)?
2. Type “n” to cause the program to exit without affecting the current status. Type “y”
to cause the program to erase the Makefile. Pressing the Interrupt key at any point
causes the program to remove the incomplete Makefile before exiting to the system.
The program displays the following screen:
RM/COBOL Customization
(Press system cancel to abort)
1. runcobol - RM/COBOL Runtime System

2. rmcobol - RM/COBOL Compiler
3. recover1 - RM/COBOL Indexed File Recovery Utility
4. ofm - RM/COBOL Open File Manager
5. rmserver - RM/InfoExpress Server
Enter product number:
3. Type “5” (for rmserver) and press Enter.
4. The program responds with the following prompt:
Building rmserver
-----------------
Enter the directory where RM/plusDB is installed

(Default is /usr/rmdb):

6. Type the complete pathname for the directory where RM/plusDB is installed.
directory name is entered, the program uses /usr/rmdb as the default value and
displays the following prompt:
Enter the directory where RM/InfoExpress is installed

(Default is /usr/rminfox):
7. Type the complete pathname for the directory where RM/InfoExpress is installed.
directory name is entered, the program uses /usr/rminfox as the default value.
The program responds with the following prompt, which allows you to specify the
name of the linked product:
Enter the product name (Default is <default name>):
8. Press Enter to use the default name or type the name of the final linked product.
customiz builds the Makefile and issues the following prompt:
Makefile generation successful.

Would you like to build the product (y/n)?
a. If you want the program to build the product, type “y” and press Enter. The
program builds the product using the system make utility and the newly
generated make script specified in Makefile.
b. You may choose to run the make script yourself if you need to change the values
of the macros defined in the make script specified in Makefile. If you type “n”,
the program displays the following information and then exits:
Type ‘make’ to build the <product_name> product
Note If you look at the generated Makefile using any text editor, you will find
comments at the beginning about the configuration of the product built.

Installing Your Customized Product
When you have finished customizing RM/COBOL, you need to install the product again.
1. Log in as root.
2. Change your working directory to the directory in which you initially installed
RM/COBOL.
For example:
cd rmc85_dir
3. Enter the following command:
./rminstall
During the execution of this command, messages appear periodically indicating the status
of the installation.

C (or Assembly) Language Subprograms
If you want to use C (or assembly) language subprograms, they must be linked into the
runtime system before you can call them. You must supply a table of routine names and
entry points to the runtime system during the linkage. The procedure for doing this is set
forth in the discussion of C subprogram preparation that begins on page D-19.
C Calling Sequence
The syntax (Format 2) for the CALL statement in the RM/COBOL program is as follows:
   identifier-2   
  [ BY REFERENCE ]  OMITTED   
     
   
   identifier-2   
     
  USING  BY CONTENT  literal-2    
    OMITTED    
 identifier-1       
CALL     identifier-2   
 literal-1    
    literal-2    
    OMITTED    
     
 
 
 
  GIVING  
  RETURNING  identifier-3 
   
[ ON EXCEPTION imperative-statement-1 ]
[ NOT ON EXCEPTION imperative-statement-2 ]

[ END - CALL ]
The value of the contents of the data item specified by identifier-1 or the value of
literal-1 is the program name of the subprogram to be called.
identifier-2 or literal-2 are one or more actual arguments to be passed to the called
program. If the BY CONTENT phrase applies to an argument, a temporary copy of
the item is passed, thus preventing the subprogram from modifying the original item.
identifier-3 is an actual argument to be passed to the called program for the purposes
of returning a result to the calling program.

The runtime system locates the subprogram with the program name specified by literal-1
or identifier-1. See the discussion of “Subprogram Loading” on page 8-34 for additional
information on locating subprograms.
The runtime system can locate the C subprograms only if their names appear in the
subprogram name table. The subprogram name table is an array of structures linked into
the runtime system. The name of this table must be LIBTABLE, and must be of the
following format:
struct PROCTABLE {
char *subname; /* name of subroutine as in call */
int (*ent_pnt)(); /* pointer to subroutine function */
};
/* define library header */
struct PROCTABLE LIBTABLE [] = {

{"SYSTEM", subsys },
{"RENAME", subren },
{"DELETE", subdel },
{(char *) 0, 0 }
};
Here, “SYSTEM”, “RENAME”, and “DELETE” are the program names. subsys, subren,
and subdel are the entry points into the routines. The last two entries in the table must be
zeroes.
Upon entry to the subprogram, all registers are volatile. The top of the stack contains the
following information:
long containing the return address

long containing a pointer to null terminated
string containing the subprogram name
integer containing the number of arguments (n)
long containing a pointer to argument entry table
integer containing the initial entry flag
The return address is used during the execution of the C return (x) statement, or during the
execution of the corresponding assembly instruction.

The remaining values on the stack are accessible as function parameters, as described
below. A sample C subprogram function declaration is as follows:
int subsys(name, arg_count, arg_vector, initial)

char *name;
int arg_count;
struct ARGUMENT_ENTRY arg_vector[];
int initial;
The pointer to the subprogram name (name) is used by the run unit to identify the
requested subprogram. This is a null-terminated ASCII string.
The number of the arguments (arg_count) describes the number of USING argument
entries in the actual argument entry table (arg_vector) pointed to by the next argument.
The initial entry flag (initial) contains zero to indicate that the subprogram is in its “initial
state,” which is the state a subprogram is in the first time it is called in the run unit, and a
non-zero value to indicate that it should be in its “last used state.”
In the initial state, all external and static automatic variables are initialized by the system
to the appropriate values. In the last used state, external and static variables are left in the
last state they were used. In either state, all automatic variables are reallocated on the
stack. It is your responsibility to initialize them to the desired values.
Once memory used by a subprogram has been linked into the runtime system, it cannot be
released.
Use of the CANCEL statement to cancel a routine linked with the runtime system sets the
initial flag to zero on the next entry into the subprogram. The CANCEL statement has no
effect on the values of the external and static variables used in the program.
The argument entry table (arg_vector) contains descriptions of the actual arguments
specified in the CALL statement. The arg_vector[0] entry describes the first actual
argument in the USING phrase of the CALL statement. The arg_vector[arg_count - 1]
entry describes the last actual argument in the USING phrase of the CALL statement.
The arg_vector[-1] entry describes the argument specified in the GIVING phrase of the
CALL statement. If the GIVING phrase is omitted from the CALL statement, or for any
actual argument specified as OMITTED in the USING phrase of the CALL statement, the
corresponding arg_vector entry contains a type value 32 (OMITTED, as shown in table
D-1) and the remaining fields are zero. C or assembly language subprograms that access
the GIVING argument in arg_vector[-1] will function correctly only for RM/COBOL 7.0
and later release runtimes because prior runtimes did not make a GIVING argument entry
available in arg_vector[-1].

An argument entry to a subprogram written in assembly language has the following
structure:
A_ADDRESS: .long | Address of argument

A_LENGTH: .long | Length of argument
A_TYPE: .word | Type of argument
A_DIGIT_COUNT: .byte | Number of digits in argument
A_SCALE: .byte | Position of implied/actual decimal point
A_PICTURE_ADDRESS: .long | Address of encoded picture
An argument entry on an Intel-based system has the following structure:
ARGUMENT_ENTRY STRUC
A_ADDRESS DD ? ; linear address of argument
A_LENGTH DW 2 DUP (?) ; length of argument
A_TYPE DB ? ; type of argument
DB ? ; reserved, set to zero
A_DIGIT_COUNT DB ? ; number of digits in argument
A_SCALE DB ? ; position of implied/actual decimal point
A_PICTURE_ADDRESS DD ? ; linear address of encoded picture
ARGUMENT_ENTRY ENDS
To a subprogram written in C, an argument entry can be defined with the following

structure:
struct ARGUMENT_ENTRY {
char *a_address; /* pointer to start of arg */
unsigned long a_length; /* length of argument */
short a_type; /* arg type see table below */
char a_digits; /* digit count 0x1-0x1E */
signed char a_scale; /* implied decimal location */
char *a_picture; /* pointer to edit DOPE */
}
;
a_address specifies the lowest address byte of the argument.
a_length specifies the number of bytes allocated to the argument.
a_type specifies the RM/COBOL data type as a number from Table D-1.
Note See also Table 9-2 on page 9-4 for an explanation of the data type abbreviations in
the following table and Appendix C, Internal Data Formats, for a description of
RM/COBOL data types.

Table D-1 Data Types as Numbers
Type RM/COBOL Type RM/COBOL

Number Data Type Number Data Type
0 NSE 12 NBU
1 NSU 16 ANS
2 NTS 17 ANS (justified right)
3 NTC 18 ABS
4 NLS 19 ABS (justified right)
5 NLC 20 ANSE
6 NCS 21 ABSE
7 NCU 22 GRP (fixed length)
8 NPP 23 GRPV (variable length)
9 NPS 25 PTR
10 NPU 32 OMITTED
11 NBS
Note The data type GRPV (23) occurs only when C$CARG is called with the formal
argument in the main program. In all other cases, RM/COBOL passes variable length
group actual arguments as if they were a fixed length group of the maximum length.
a_digits specifies the actual number of digits in a numeric data item (where the type of
argument is in the range 0 through 30). It is set to zero for nonnumeric data items.
a_scale specifies the power of 10 by which the digits in a numeric data item (where the
type of argument is in the range 1 through 12) must be multiplied to obtain the numeric
value of the data item. The power of 10 is represented as a signed, 2’s complement
number. It is set to zero for nonnumeric data items.
a_picture specifies the lowest addressed byte of the encoded picture for edited items (type
of argument equals 0, 20 or 21). It is set to zero for all other types.

For example, for a Motorola 68000-based computer, a CALL statement specifies one
argument in its USING list, a three-byte numeric unsigned (NSU) data item whose picture
is 99V9 located at address 0x12850. The argument entry will contain:
00 01 28 50 00 00 00 03 00 01 03 FF 00 00 00 00
picture address
implied decimal
digit count
type
argument length
argument address
For Intel-based computers, the memory organization is different, so the values for the
fields are different but the organization of the structure is the same. Using the same
example as above except that the argument address is 0xdf:0x2850, the argument entry
will contain:
50 28 DF 00 03 00 00 00 01 00 03 FF 00 00 00 00
picture address
implied decimal
digit count
type
argument length
argument address
The preceding examples apply to subprograms written in assembly language. However,

subprograms written in C are more portable because C masks the distinctions between the
microprocessors. The following is a diagram of the structure in C.
ptr to char
argument address
argument [3];
argument length 3
type 1
digit count 3
implied decimal -1
picture and address NULL

Upon exit from a C subprogram, the exit code must be returned using the return(x)
statement. The exit code may be set to zero to request a normal return to the calling
RM/COBOL program, or to non-zero to request an immediate STOP RUN with the
program exit code (see page 7-8) equal to the contents of x.
Assembly language subprograms are entered using the same methods as C programs.
Therefore, assembly language subprograms should return using the same conventions
as C. Precautions should be taken to leave the stack in the state it was in before the call.
C subprograms should return explicitly using the return(x) statement; otherwise, the C
subprogram will have an unknown value as the return code, which may be interpreted as a
STOP RUN request.
C subprograms should not exit with an exit( ) statement, as this will result in a premature
termination of the run unit.
Accessing C Subprograms
Two methods are available to access a C (or assembly) language subprogram that has
been linked to the runtime system: either each subprogram can be given a unique name
and entry point or each subprogram can be given a unique name and share the same entry
point. In the second case, it is necessary to determine which subprogram has been called.
Here is an example:
struct PROCTABLE LIBTABLE [] = {
{"SUBA", library },
{"SUBB", library },
{(char *) 0, 0 }
};
int library(name, arg_count, arg_vector, initial)
char *name;
int arg_count;
struct ARGUMENT_ENTRY arg_vector[];
int initial;
{
if (!strcmp ( "SUBA", name)) {
return( suba( arg_count, arg_vector, initial));
}
else
{
if (!strcmp ( "SUBB", name)) {
return( subb( arg_count, arg_vector, initial));
}
else
{
return( 1);/* error stop run */
}
}
}

Preparing C (or Assembly) Subprograms
C (or assembly) subprograms are compiled (or assembled) as if they were to be linked
with similar programs. Assembly language source files are assumed to be those with an
extension of .s; C source files are assumed to have an extension of .c and all object files
are assumed to have an extension of .o.
If a single source module is to be linked into the runtime system, ensure that LIBTABLE
is present (as described previously). The following commands automatically generate the
subprogram object file and link it with the runtime system:
make runcobol CLIBRARY=mysub.o
mysub.c is your C subprogram source file that will be automatically compiled to

produce mysub.o.
mysub.o is the C subprogram object file you want to link.
If you want to modify the routine (called sub.c) that is delivered with your system, you
would edit sub.c, making changes as appropriate, and then enter:
make runcobol
The make utility automatically compiles and links the default subprogram module sub.c.
You can link multiple subprograms into the runtime system. Only one LIBTABLE can be
declared, holding all the subprogram names and entry points. For example, if you want to
link three subprograms, you would enter these commands (assuming that one of the C
routines contains LIBTABLE):
make runcobol CLIBRARY="mysub1.o mysub2.o mysub3.o..."
mysubn.c is the name of the files that contain your C programs. These files will be
automatically compiled to produce mysubn.o.
Restrictions to C (or Assembly) Language Subprograms

The runtime system changes terminal characteristics before passing control to a C (or
assembly) language subprogram. If any processing requiring terminal I/O is done
(including operating system commands that use the terminal), you must reset the terminal
to its original state by making a call to the routine resetunit(). If resetunit() was called, a
call to setunit() must be made before control is returned to the run unit. Both functions
are part of the runtime system.

Debugging C (or Assembly) Language Subprograms
It is recommended that subprograms initially be tested using a C main program that sets
up the RM/COBOL argument entries and calls the subprogram. It is possible, however,
to use the adb or sdb utility. Using these commands on a newly created run unit allows
you to place a breakpoint at your function, and then run the program. The utility regains
control as soon as the run unit passes control to the subprogram.
C Subprogram Examples
The programs that have been provided with your distribution media as examples include
sub.c, subtest.cbl, subtype.c, and typetest.cbl.
Example 1
sub.c is the default subprogram library that is distributed and already linked into the
runtime system. This routine includes the following subprograms:
SYSTEM Submits operating system commands as if they were typed at a keyboard.

SYSTEM is called with one to three arguments. The first argument must
be the command to execute. The runtime system automatically calls
resetunit() before executing the command to place the terminal in a
“normal state” (the state before the runtime system was executed).
Following the execution of the command, the runtime system automatically
calls setunit() to return the terminal to the state that it requires for terminal
I/O, and also causes the terminal screen to be redrawn. However,
redrawing the screen may not always be desirable. For example, the
command executed might not change the screen. If all of the calls to
SYSTEM in a COBOL program do not change the screen, the
REDRAW-ON-CALL-SYSTEM keyword (see page 10-39) of the
TERM-ATTR configuration record may be set to NO and the runtime
system will not redraw the screen after every call to SYSTEM.
If some of the calls to SYSTEM in a COBOL program change the screen

contents, the redrawing of the screen can be controlled through the use of
the optional second argument to CALL “SYSTEM”. This argument may
have the value “Y” or “y” to redraw the screen, or “N” or “n” not to redraw
the screen. A blank or any other value defaults to the TERM-ATTR
configuration record REDRAW-ON-CALL-SYSTEM value.
Note If the second argument is “N”, or the REDRAW-ON-CALL-SYSTEM

configuration keyword value is NO, and the called program changes the
screen contents, unpredictable results occur on the next DISPLAY

statement because of the changed cursor position. CALL “SYSTEM”
output is not stored in the runtime system’s in-memory screen image.
The third parameter must be defined as PIC S9(4) BINARY and contains
the return code from the command when control is returned to the COBOL
program.
Note The OSSYSTEM function call in the subsys subroutine is

implemented as:
"return (wexitstatus(system(command))"
and returns the same value as returned by the call to SYSTEM.
DELETE Deletes a file. DELETE is called with one argument, which is the full or
relative pathname of the file to be deleted.
RENAME Renames a file. RENAME is called with one or two arguments. If one
argument is passed to the routine, the routine handles the request in the
same fashion as the RENAME subprogram in RM/COBOL (74) 2.n.
That is, the one argument contains both the source filename and the
target filename. If the subprogram is invoked this way, the argument
must be NULL terminated (that is, the last character must be
COBOL LOW-VALUES). If the subprogram is invoked with two
arguments, it uses the first argument as the source filename and the
second as the target filename. In this case, the names do not have to be
NULL terminated.
In all cases, except using RENAME in the RM/COBOL (74) 2.n fashion, the use of
literals in the CALL statement is supported. In the case of the RM/COBOL (74) 2.n
RENAME subprogram, it is not possible to have LOW-VALUES as part of a literal. Use
a Working-Storage Section variable. See subtest.cbl for examples of all calling
sequences.
subtest.cbl is an interactive program to call the subprograms in sub.c. To run

Example 1, enter the following commands:
rmcobol subtest
runcobol subtest

Example 2
subtype.c is a subprogram that returns the type of the first argument in the second
argument. The second argument must be declared as COMP-1.
typetest.cbl is an RM/COBOL program that calls subtype with many different types of
arguments, and tests that the proper value is returned. In order to run this test, you must
link this routine into the runtime system. To run Example 2, enter the following
commands:
cc -c subtype.c
make runcobol CLIBRARY=subtype.o
rmcobol typetest
runcobol typetest
Remember, by doing this you have replaced the default subprogram library, sub.o,
with this test subprogram. It is recommended that after you run this test, you relink the
default subprogram library into the runtime system, as described previously in
this appendix.

C Entry Points For COBOL Functions
RM/COBOL provides user-supplied C subprograms with entry points to some COBOL
functions. The following routines use the standard C calling and parameter passing
conventions:
• RmForget (int y1, int x1, int y2, int x2). This function marks the indicated area of
screen memory as unknown. By doing so, the next COBOL display to that area will
not be optimized based on the screen contents. This allows COBOL output to be
correctly displayed over linked C subprogram output, which is not stored in the
in-memory screen image.
This routine requires four int parameters (two line and position pairs), which specify
the upper-left (y1,x1) and lower-right (y2,x2) coordinates of the area of the screen to
be marked as unknown. Valid values range from 0 to the line or position limit of the
screen. Passing zero values mark the entire screen as being unknown. See the
“C$Forget” section in Appendix F, Subprogram Library, for more information.
• RmRepaintScreen(). This function causes the COBOL runtime system to redraw

the entire current screen from an in-memory image. C routine output is erased. This
function requires no parameters. See the REPAINT-SCREEN keyword of the
CONTROL phrase on page 8-18 for more information.
• RmRefreshCwd(). This function causes the COBOL runtime system to refresh its
internal copy of the current working directory. This internal copy is used to construct
complete file names from any filename that is not fully qualified. This function
should be called before returning to the COBOL program if a non-COBOL
subprogram changes the current working directory with the chdir() C library routine.
The RmRefreshCwd() routine has no parameters and does not return a value.

Appendix E: Windows Printing
The RM/COBOL for Windows runtime system supplies a P$ subprogram library that
allows access to Windows printing features. This appendix describes the required
RM/COBOL calling sequence and the USING list parameters for each P$ subprogram.
Note that failure to comply with the USING list requirements will halt the run unit with a
STOP RUN indication at the line containing the incorrect CALL statement.
The COBOL copy files that are supplied with an RM/COBOL development system
to facilitate Windows printing program development are described starting on
page E-44. Examples illustrating some common uses for the P$ subprograms begin
on page E-71.
In addition to the Windows printing subprogram library, this appendix also describes an
alternative means of printing under Windows using a set of RM/COBOL-specific escape
sequences (see page E-85).
P$ Subprogram Library
Note P$ subprogram names are case-insensitive. For readability, mixed case is used in
this document except in calling sequences and code fragments, where uppercase letters
are used.
The P$ subprograms can be logically grouped into the following categories that control:
• The standard Windows Print dialog box
• Drawing activities
• Text manipulation
• Activities common to both drawing and text manipulation
• Printer control activities
Table E-1 lists the subprograms alphabetically within each of these categories.
RM/COBOL User's Guide for 32-Bit Windows E-1

Table E-1 RM/COBOL Windows Printing Subprogram Library
Windows Print Dialog Box

Subprograms Function
P$ClearDialog Clears the standard Windows Print dialog box values
back to their default (unset) state. See page E-15.
P$DisplayDialog Invokes the standard Windows Print dialog box.
See page E-16.
P$EnableDialog Causes the standard Windows Print dialog box to
display automatically the next time the predefined
printer device, “PRINTER?”, is opened. See
page E-16.
P$GetDialog Retrieves values from the standard Windows Print
dialog box. See page E-17.
P$SetDialog Sets values for the standard Windows Print dialog box.
See page E-18.
Drawing
P$DrawBitmap Prints a bitmap file (.BMP). See page E-19.
P$DrawBox Draws a box. See page E-20.
P$DrawLine Draws a line. See page E-20.
P$GetPosition Retrieves the ending position of the last print operation.
See page E-20.
P$LineTo Draws a line starting at the current position.
See page E-21.
P$MoveTo Repositions the line-draw pen without drawing a line.
See page E-22.
P$SetBoxShade Sets shading color and percentage for a box.
See page E-22.
P$SetPen Sets the style, width, and color of the pen tool for a box
or a line. See page E-23.
P$SetPosition Sets a new position for the next print operation.
See page E-23.
E-2 Windows Printing

Table E-1 RM/COBOL Windows Printing Subprogram Library (Cont.)
Text Manipulation
P$ClearFont Clears font description values back to their default
(unset) state. See page E-24.
P$GetTextExtent Retrieves the bounding rectangle size for the text
passed to the function, calculated using the current font
size. The returned values can be used to draw boxes
around text. See page E-25.
P$GetTextMetrics Retrieves the characteristics of the current font.
See page E-25.
P$GetTextPosition Retrieves the ending position of the last print operation
adjusted to the top or bottom of the current font. See
page E-28.
P$SetDefaultAlignment Sets default alignment used in text positioning.
See page E-28.
P$SetFont Changes fonts for subsequent text print operations.
See page E-29.
P$SetLineExtendMode Concatenates output from two COBOL WRITE
statements on the same line. See page E-31.
P$SetPitch Sets normal, compressed, or expanded font pitch.
See page E-31.
P$SetTabStops Sets the tab stop increment. See page E-32.
P$SetTextColor Sets the color for text output. See page E-32.
P$SetTextPosition Sets a new position for the next print operation
adjusted from the top or bottom of the current font.
See page E-33.
P$TextOut Allows the program to control the position of the text.
This provides an alternative to using the COBOL
WRITE to print text. See page E-34.
Common Drawing and Text
Manipulation Subprograms Function
P$SetDefaultMode Sets default mode used in positioning and sizing
parameters. See page E-35.
P$SetDefaultUnits Sets default unit of measurement in positioning and
sizing parameters. See page E-36.
P$SetLeftMargin Sets left margin for subsequent printer output.
See page E-36.
P$SetTopMargin Sets the top margin for subsequent printer output.
See page E-37.

Table E-1 RM/COBOL Windows Printing Subprogram Library (Cont.)
Printer Control
P$ChangeDeviceModes Changes device mode (DEVMODE) values for the
standard Windows Print dialog box. Values take effect
beginning with the next page. See page E-37.
P$EnableEscapeSequences Enables RM/COBOL-specific escape sequences.
See page E-38.
P$GetDeviceCapabilities Retrieves the device capabilities of a P$ printer. See
page E-39.
P$GetHandle Retrieves the handle of the current P$ printer.
See page E-41.
P$GetPrinterInfo Retrieves detailed information about a P$ printer.
See page E-41.
P$SetHandle Changes the current P$ printer. See page E-43.
P$SetRawMode Bypasses Windows printer drivers, enabling printing
with escape sequences to a remote Windows NT
printer. See page E-43.
Overview
Prior to version 7 of RM/COBOL for Windows, a COBOL Windows application had
limited control of printing, as printer and font selection could only be specified using a
configuration record. The RM/COBOL 7 for Windows runtime provides enhanced
capabilities and flexibility when printing under Windows.
A new predefined printer device, “PRINTER?”, has been added to the RM/COBOL
runtime (see page 10-19). When this device is opened, a standard Windows Print dialog
box, as shown in Figure E-1, is presented to the user to allow dynamic selection of the
Windows printer.

Overview
Figure E-1 Standard Windows Print Dialog Box
A broad range of COBOL callable subprograms (P$) has been added to the runtime to
allow printer control, font control, drawing of bitmaps, lines, and boxes, color control,
positioning of printed objects, and other print-related functions.
These new functions can be applied to a single printer or, if the application uses multiple
printers, a printer “handle” is available to allow selection of an open printer on which
subsequent P$ subprograms will operate. The printer handle can be ignored by the
application if it opens only one printer at a time.
The C$SetDevelopmentMode subprogram may be used to enable expanded

error information reporting (known as “development mode”) for the P$ subprograms.
This may be useful during program development. Development mode may also
be used to bracket particular P$ calls by using both C$SetDevelopmentMode
and C$ClearDevelopmentMode. These programs are described in Appendix F,
Subprogram Library.
Note Some of the more advanced printer functions require knowledge of Windows
printing structures. Only limited documentation is given here because it is assumed that
the developer who requires advanced functions has access to the appropriate Windows
documentation.
WARNING Due to differences among printers and printer drivers, output produced
using P$ subprograms can vary from printer to printer. To avoid surprises after
application deployment, test your application on printers that you plan to support.

Overview
Using Windows Printing Functions
The basic steps for using the Windows printing functions are as follows:
1. Open a printer that selects the “PRINTER?” device using the standard COBOL
OPEN statement.
This allows the end-user to choose the desired P$ printer.
2. Optionally retrieve the printer handle by calling P$GetHandle (see page E-41).
Disregard this step if the application does not open more than one printer at a time.
3. Call various P$ subprograms to control the font, orientation, color, position, and so
on, of printed text or drawing objects.
If more than one printer is opened at one time, call the P$SetHandle subprogram
(see page E-43) to switch between them.
4. Intermix P$ subprogram calls with standard COBOL WRITE statements to the

printer to produce the desired output.
5. Close the COBOL printer file.
Returning to a "Normal" Font

In order to implement the concept of returning to a “normal” font (after using the
RM/COBOL-specific escape sequences, Shift In or Shift Out, to specify expanded or
compressed fonts), the RM/COBOL runtime keeps a copy of the normal font for each
printer. That normal font is updated whenever the P$SetFont subprogram (see page E-29)
or the Print Pitch or Font Height escape sequences (see page E-85) are used.

Overview
Common P$ Subprogram Arguments
Many of the P$ subprograms use similar arguments to control positioning, size, color, and
other common values. The arguments are described using the following terms: Position,
Size, Point, Amount and Increment, Mode, Units, Yes/No, and Color. The descriptions of
these types of arguments are given below, but are omitted from the individual subprogram
argument descriptions.
• Position. XPosition, YPosition, XPoint, and YPoint arguments can be any COBOL
numeric data type. The default value for these arguments is the current position. An
XPosition or XPoint argument must have a corresponding YPosition or YPoint
argument, respectively.
Note 1 For any of the P$Get subprograms receiving a Position argument, the
format of the receiving field's PICTURE clause varies, depending on the type of
Units being used. If Units is “Device-Units”, the format of the PICTURE clause
must be PIC S9(10). If Units is “Characters”, the format of the PICTURE clause
must be PIC S9(3). If Units is “Inches” or “Metric”, the format of the PICTURE
clause must be PIC S99v99.
Note 2 Position 0,0 is the upper-left corner of the printable area of the page.
• Alignment. Alignment arguments can be any alphabetic or alphanumeric COBOL

data type. Alignment arguments allow the application to specify “Top” alignment or
“Bottom” alignment of text positioning. The default mode is “Top” unless changed
by the P$SetDefaultAlignment call (see page E-28). Only the first letter of the value
is relevant, and it is case-insensitive. Possible values are contained in the
WINDEFS.CPY copy file (see page E-69).
• Size. Size arguments can be any COBOL numeric data type. Size arguments are
used to specify the width (SizeWidth) and height (SizeHeight) of objects. Except
when used with P$DrawBitmap (see page E-19), Size arguments have default
values of 1 for width and 1 for height.
Note For any of the P$Get subprograms receiving a Size argument, the format
of the receiving field's PICTURE clause varies, depending on the type of Units
being used. If Units is “Device-Units”, the format of the PICTURE clause must
be PIC 9(10). If Units is “Characters”, the format of the PICTURE clause must be
PIC 9(3). If Units is “Inches” or “Metric”, the format of the PICTURE clause must
be PIC 99v99.
• Amount and Increment. Amount and Increment arguments can be any COBOL
numeric data type. These arguments specify the value of an argument used in
subprogram calls.

Overview
• Mode. Mode arguments can be any alphabetic or alphanumeric COBOL data type.
Mode arguments allow the application to specify “Absolute” positioning (with 0,0
being the upper-left corner of the page) or “Relative” positioning (relative to the last
printed object or text). The default mode is “Absolute” unless changed by the
P$SetDefaultMode call (see page E-35). Only the first letter of the value is relevant,
and it is case-insensitive. Possible values are contained in the WINDEFS.CPY copy
file (see page E-69).
• Units. Units arguments can be any alphabetic or alphanumeric COBOL data type.
Units arguments allow the application to select one of four units of measurement:
“Inches”, “Metric”, “Characters”, and “Device-Units”. “Inches” are expressed in
inches with 2.5 meaning 2½ inches and have precision to 1/1000th of an inch.
“Metric” is expressed in centimeters and has precision to 1/1000th of a centimeter.
“Characters” are expressed in character cell row/column position (computed using
the current font). “Device-Units” are expressed in the low-level Windows device
unit measurement. The default value for Units is “Inches” unless changed by the
P$SetDefaultUnits call (see page E-36). Only the first letter of the value is relevant,
and it is case-insensitive. Possible values are contained in the WINDEFS.CPY copy
• Yes/No. Yes/No arguments can be any alphabetic or alphanumeric COBOL data

type. Only the first letter of the value is relevant, and it is case-insensitive. The
default value is N (no). For possible values to make the COBOL statement more
readable, see the WINDEFS.CPY copy file on page E-69.
• Color. Color arguments may be specified in one of two methods:
1. Color-name/Percentage method. Any COBOL alphabetic or alphanumeric

variable specifying the color-name. For possible values, see Table E-2 and the
WINDEFS.CPY copy file on page E-69. A second optional argument indicates
the percentage (intensity) to apply to the color value. For example, the following
code fragment sets the box shading color to 30 percent red:
CALL P$SetBoxShade USING ColorRed 30.
2. RGB (Red, Green, Blue) triplet method. These values may be any COBOL
numeric data items. Possible values for each data item are 0 through 255. See
Table E-2 for a list of default colors to use with RM/COBOL. Note that if you
use the RGB triplet method, you must specify a value for all three colors.

Overview
Table E-2 Default Colors Used With RM/COBOL
String 78-Level Value Red, Green, Blue Values

ColorBlack “Black” 000,000,000
ColorDarkBlue “Dark Blue” 000,000,127
ColorDarkGreen “Dark Green” 000,127,000
ColorDarkCyan “Dark Cyan” 000,127,127
ColorDarkRed “Dark Red” 127,000,000
ColorDarkMagenta “Dark Magenta” 127,000,127
ColorBrown “Brown” 127,127,000
ColorDarkGray “Dark Gray” 085,085,085
ColorLightGray “Light Gray” 192,192,192
ColorBlue “Blue” 000,000,255
ColorGreen “Green” 000,255,000
ColorCyan “Cyan” 000,255,255
ColorRed “Red” 255,000,000
ColorMagenta “Magenta” 255,000,255
ColorYellow “Yellow” 255,255,000
ColorWhite “White” (will not print) 255,255,255
Omitting P$ Subprogram Arguments

The COBOL CALL statement in RM/COBOL now supports the OMITTED keyword to
explicitly omit an argument in the USING list. See “CALL Statement” in the
RM/COBOL Language Reference Manual for more information.
The calling COBOL program may omit arguments by passing fewer arguments than
expected or passing the reserved word, OMITTED, for one or more arguments. The
following example illustrates how the OMITTED keyword may be used with P$
subprograms.
CALL P$SETPOSITION USING 5, 3, OMITTED, "Inches"
This example causes the next drawn object to appear at the specified coordinates. The
Mode argument (see the “Common P$ Subprogram Arguments” topic on page E-7) has
been omitted, which causes the RM/COBOL runtime to use the default value for Mode.

Overview
Windows Print Dialog Box Subprograms
The following subprograms control the configuration of the standard Windows Print
dialog box (see page E-5):
• P$ClearDialog
• P$DisplayDialog
• P$EnableDialog
• P$GetDialog
• P$SetDialog
Each subprogram is described in detail in this section beginning on page E-15.
Note 1 P$GetDialog and P$SetDialog use the printer dialog/device mode parameters
listed in Table E-3. In this table, the fields listed in the “Parameter Name” column
represent the string that must be passed to the P$ subprograms that use the
ParameterName/Value pairs calling sequence, which allows parameters to be set or
changed individually. Possible values are provided in the 78-level entries in the
PRINTDLG.CPY copy file, described on page E-51.
The description in the “PICTURE Clause” column indicates whether the field is numeric
or alphanumeric and its required number of digits or characters. When setting values
using P$SetDialog with the ParameterName/Value pairs calling sequence, there is no
minimum requirement on the number of digits or characters. When retrieving values
using P$GetDialog with the ParameterName/Value pairs calling sequence, the PICTURE
may specify BINARY and must specify at least the number of digits or characters shown.
Note 2 Some user selections in the Windows Print dialog box must be acted on by the
COBOL application, while others will be handled automatically by the device driver.
Still other user selections will vary from driver to driver. See “Printing Multiple Copies”
on page E-13 and “Printing Partial Reports” on page E-14 for more information.

Table E-3 Printer Dialog/Device Mode Parameters
PICTURE
Parameter Name Clause Description
Return PIC X Standard Windows Print dialog box status:
Y = OK
N = An error occurred (see Extended
Error below).
Extended Error PIC 9(5) Extended error code. See
PD-ExtendedErrorValue in
PRINTDLG.CPY (page E-51) for details.
All Pages Flag PIC X “All” radio button is selected.
Selection Flag PIC X “Selection” radio button is selected. See
“Printing Partial Reports” on page E-14.
Page Numbers Flag PIC X “Pages” radio button is selected.
No Selection Flag PIC X Disables the “Selection” radio button.
No Page Numbers Flag PIC X Disables the “Pages” radio button.
Collate Flag PIC X “Collate” check box is checked.
Print Setup Flag PIC X Displays the Print Setup dialog box rather
than the Print dialog box. The Print dialog
box has Print Range and Copies features
that are replaced by Paper and Orientation
features in the Print Setup dialog box.
Print to File Flag PIC X “Print to File” check box is checked.
No Warning Flag PIC X Prevents the warning message from being
displayed when there is no default printer.
Use Device Mode Copies Flag PIC X Indicates whether your application
supports multiple copies and collation.
See “Printing Multiple Copies” on
page E-13.
Disable Print to File Flag PIC X Disables the “Print to File” check box.
Hide Print to File Flag PIC X Hides the “Print to File” check box.
No Network Button Flag PIC X Hides and disables the “Network” button.
From Page PIC 9(5) First page to print.
To Page PIC 9(5) Last page to print.
Min Page PIC 9(5) Minimum value for From Page and To
Page. If Min Page equals Max Page, the
“Pages” radio button and the starting and
ending page edit controls are disabled. See
“Printing Partial Reports” on page E-14.

Table E-3 Printer Dialog/Device Mode Parameters (Cont.)
PICTURE
Max Page PIC 9(5) Maximum value for From Page and To
Page. See “Printing Partial Reports” on
page E-14.
Print Dialog Copies PIC 9(5) Initial number of copies for the Copies edit
control. If a value is specified for Device
Name (or any of the parameters following
Device Name in this table), the value
specified for Device Mode Copies
overrides the value specified for Print
Dialog Copies. See “Printing Multiple
Copies” on page E-13.
Device Name PIC X(31) Name of the printer selected by the user.
Fields Group Note This parameter is not available
when using the ParameterName/Value
pairs calling sequence because the pairs
calling sequence automatically sets the
appropriate Fields bits when setting Device
Mode fields. The Fields parameter is
available when using the
PrinterDialogDescription group data item
calling sequence. The developer is
responsible for setting the appropriate
Fields bits.
Orientation PIC 9(5) Portrait versus landscape.
Paper Size PIC 9(5) The size of the paper.
Paper Length PIC 9(5) Length of the paper (overrides Paper Size).
Paper Width PIC 9(5) Width of the paper (overrides Paper Size).
Scale PIC 9(5) Scale factor applied while printing,
expressed as a percentage. For example,
50 would print text and graphics at 50% of
their specified height and width.
Device Mode Copies PIC 9(5) The number of copies to print (overrides
Print Dialog Copies). See “Printing
Multiple Copies” on page E-13.
Default Source PIC 9(5) The default paper bin.
Print Quality PIC S9(5) High, medium, low, or draft.
Color PIC 9(5) Color versus monochrome.
Duplex PIC 9(5) One-sided versus two-sided printing.

Table E-3 Printer Dialog/Device Mode Parameters (Cont.)
PICTURE
Y Resolution PIC 9(5) Y-resolution of the printer specified in
dots-per-inch. If this parameter is set,
Print Quality specifies the X-resolution of
the printer in dots-per-inch.
True Type Option PIC 9(5) TrueType® rendering options.
Collate PIC X True or False. See “Printing Multiple
Copies” on page E-13.
ICM Method PIC 9(10) System-specific. See Microsoft
documentation.
ICM Intent PIC 9(10) System-specific. See Microsoft
documentation.
Media Type PIC 9(10) System-specific. See Microsoft
documentation.
Dither Type PIC 9(10) System-specific. See Microsoft
documentation.
Printing Multiple Copies

Creating multiple copies generally requires that the printer driver support printing
multiple copies. If the COBOL application is not prepared to generate multiple copies of
each page, the PD-UseDevModeCopiesFlag (see the definitions of the PRINTDLG.CPY
copy file beginning on page E-51) should be set to TRUE to indicate that the application
is depending on the printer driver to print multiple copies.
Not all printers, however, can print multiple copies. If the printer driver does not support
printing multiple copies, the “Copies” edit control on the standard Windows Print dialog
box (see Figure E-1 on page E-5) will be disabled. Similarly, if the printer driver does
not support collation, the “Collate” check box will be disabled. After the printer is
opened or the standard Windows Print dialog box is displayed, the application may use
P$GetDialog (see page E-17) to retrieve values set by the user in the Windows Print
dialog box. The application developer should first check the return information provided
by P$DisplayDialog (see page E-16) or by P$GetDialog to determine whether or not
the user canceled the Print dialog box. If the application set PD-UseDevModeCopiesFlag
to TRUE, P$GetDialog will return PD-Copies with a value of one and PD-CollateFlag
set to FALSE.

If the application is prepared to generate multiple copies of each page, the
PD-UseDevModeCopiesFlag should be set to FALSE to indicate that the application will
handle multiple copies if requested by the user. Similarly, if the
PD-UseDevModeCopiesFlag is set to FALSE, the application is responsible for collating
multiple copies.
Regardless of how the PD-UseDevModeCopiesFlag is set, an application can determine

from PD-Copies and PD-CollateFlag (obtained from P$GetDialog) how many copies
to generate and whether to simulate collation by generating the complete report
multiple times.
To preset the number of copies in the Windows Print dialog box to a number other than
one, the application should set DM-Copies to the desired number and, if not using the
ParameterName/Value pairs method, set DM-CopiesField to TRUE.
After the printer is opened or the Windows Print dialog box is displayed, the DM-Copies
and DM-CollateValue data items (obtained from P$GetDialog) contain the copies and
collate information used by the printer driver. If the PD-UseDevModeCopiesFlag is set
to FALSE, DM-Copies will contain the number of copies the printer will print, and
DM-CollateValue will be zero (FALSE). If the PD-UseDevModeCopiesFlag is set to
TRUE and the printer driver supports multiple copies, DM-Copies will contain the
number of copies requested by the user and, if the printer driver supports collation,
DM-CollateValue will indicate whether the user wants collation.
Remember, fields in the DEVMODE portion of the PRINTDLG.CPY copy file (that is,
those fields that begin with the DM- prefix) are meaningful only if the associated item in
DM-Fields is set to TRUE. Therefore, it is necessary to set the appropriate item in
DM-Fields in addition to setting such values as DM-Copies. Similarly, the application
should check the appropriate item in DM-Fields before referencing the associated item
after calling P$GetDialog. When using the ParameterName/Value pairs method,
although it is not necessary to set DM-Fields before using P$SetDialog (see page E-18),
it is necessary to check the Validity-Flag when using P$GetDialog.
The example code fragment, “Presetting the Print Dialog Box” on page E-75, illustrates
the proper way to set fields before calling P$SetDialog.
Printing Partial Reports

It is possible to print less than a full report, but in order to do this, the application must do
all the work. Neither the printer driver nor the RM/COBOL runtime will print partial
reports. The COBOL application must generate only the pages selected by the user.
If the application does not support generating partial reports, the

PD-NoPageNumbersFlag (see the definitions of the PRINTDLG.CPY copy file beginning

on page E-51) should be set to TRUE to disable the Pages radio button and the associated
edit controls on the Windows Print dialog box. Similarly, the PD-NoSelectionFlag may
be set to TRUE to disable the Selection radio button.
If the application does support generating partial reports (that is, the
PD-NoPageNumbersFlag is set to FALSE), the application should set PD-MinPage and
PD-MaxPage to specify the minimum and maximum values, respectively, allowed for the
page range specified in the From and To page edit controls. If PD-MinPage and
PD-MaxPage have the same value, the Pages radio button and the starting and ending
page edit controls are disabled. The application may specify the initial starting and
ending pages with PD-FromPage and PD-ToPage. These values must be within the range
of PD-MinPage and PD-MaxPage. If the user selects the Pages radio button, then the
PD-PageNumberFlag will be set to TRUE when the application calls P$GetDialog to
determine what the user selected. Remember to first check the return information
provided by P$DisplayDialog (see page E-16) or by P$GetDialog (see page E-17) to
determine whether or not the user canceled the Print dialog box. If the user selected a
range of pages to print, the range will be returned by P$GetDialog in the PD-FromPage
and PD-ToPage fields. It is then the application’s responsibility to generate only
those pages.
P$ClearDialog
P$ClearDialog is used to clear the standard Windows Print dialog box values back to
their default (unset) state.
For an example that includes P$ClearDialog, see “Presetting the Print Dialog Box” on
page E-75.
Calling Sequence
CALL "P$CLEARDIALOG"

P$DisplayDialog
P$DisplayDialog is used to invoke the standard Windows Print dialog box. After
choosing a printer with this dialog box, the next open of a “PRINTER?” device will use
the selected printer (and no dialog box will appear at that time). See also the discussion
of “PRINTER?” on page 10-19.
For an example that includes P$DisplayDialog, see “Checking the Return Code After
Displaying the Print Dialog Box” on page E-76.
Calling Sequence
CALL "P$DISPLAYDIALOG" GIVING DialogReturn
DialogReturn is a COBOL data item that receives the results of the Windows Print
dialog box return value. This allows the application to determine whether the dialog
was dismissed using the OK or Cancel button, or by an error condition. Possible
values are contained in the 78-level entries in the copy file, PRINTDLG.CPY under
the heading, “P$DisplayDialog Return Values.”
P$EnableDialog
P$EnableDialog is used to control the automatic invoking of the standard Windows Print
dialog box when opening a “PRINTER?” device. Normally, the Print dialog box is
presented only the first time a dynamic printer is opened. Calling P$EnableDialog causes
the Print dialog box to appear the next time a “PRINTER?” device is opened. See also
the discussion of “PRINTER?” on page 10-19.
For an example that includes P$EnableDialog, see “Opening and Writing to Separate
Printers” on page E-80.
Calling Sequence
CALL "P$ENABLEDIALOG"

P$GetDialog
P$GetDialog retrieves fields from the standard Windows Print dialog box. The two
calling sequences for this subprogram allow parameters to be retrieved either individually
or collectively. You can retrieve parameters individually by using
ParameterName/Value/Validity-Flag triplets. Retrieve parameters collectively using the
PrinterDialogDescription group data item.
Calling Sequences
CALL "P$GETDIALOG" USING PrinterDialogDescription
CALL "P$GETDIALOG" USING ParameterName-1 Value-1

Validity-Flag-1 [ParameterName-n Value-n
Validity-Flag-n...]
PrinterDialogDescription is a group data item, as defined in the PRINTDLG.CPY

copy file (see page E-51).
ParameterName is an alphanumeric data item that contains the name of the printer
dialog or device mode parameter to get (see Table E-3 on page E-11).
Value is a COBOL data item used to get the value of the parameter named by
ParameterName. Possible values are contained in the 78-level entries in the copy
file, PRINTDLG.CPY.
Validity-Flag is a returned numeric data item that indicates the validity of the
returned parameter value. A non-zero value indicates a valid parameter.
Note For a more complete discussion of printer dialog and device mode parameters, see
the Microsoft Windows documentation for the PRINTDLG and DEVMODE structures.
For web site information, see page E-51.

P$SetDialog
P$SetDialog initializes fields for the standard Windows Print dialog box.
The two calling sequences for this subprogram allow parameters to be set either
individually or collectively. Setting parameters individually using ParameterName/Value
pairs allows multiple calls to the subprogram to accumulate values for the standard
Windows Print dialog box. Setting parameters collectively using the
PrinterDialogDescription group data item sets all values, after which the
ParameterName/Value method can be used to modify values.
For examples that include P$SetDialog, see “Presetting the Print Dialog Box” on
page E-75 and “Checking the Return Code After Displaying the Print Dialog Box” on
page E-76.
Calling Sequences
CALL "P$SETDIALOG" USING PrinterDialogDescription
CALL "P$SETDIALOG" USING ParameterName-1 Value-1

[ParameterName-n Value-n...]

dialog or device mode parameter to set (see Table E-3 on page E-11).
Value is a COBOL data item used to set the value of the parameter named by
file, PRINTDLG.CPY.
Note For a more complete discussion of printer dialog and device mode parameters, see
the Microsoft Windows documentation for the PRINTDLG and DEVMODE structures.
For web site information, see page E-51.

Drawing Subprograms
The following subprograms control the drawing of objects on a printed page:
• P$DrawBitmap • P$MoveTo
• P$DrawBox • P$SetBoxShade
• P$DrawLine • P$SetPen
• P$GetPosition • P$SetPosition
• P$LineTo
Each subprogram is described in detail in this section.
P$DrawBitmap
P$DrawBitmap is used to print a bitmap file from an existing Windows bitmap file. For
an example that includes this subprogram, see “Printing a Bitmap” on page E-77.
Calling Sequence
CALL "P$DRAWBITMAP" USING Filename [XPosition

YPosition] [PositionMode] [PositionUnits]
[SizeWidth SizeHeight] [SizeUnits]
Filename can be any alphabetic or alphanumeric COBOL data type. It specifies the
pathname of the Windows bitmap file to draw.
XPosition/YPosition. See Position in “Common P$ Subprogram Arguments” on

page E-7.
PositionMode. See Mode in “Common P$ Subprogram Arguments.”
PositionUnits/SizeUnits. See Units in “Common P$ Subprogram Arguments.”
SizeWidth and SizeHeight are the values used to determine the size of the bitmap. If
you specify a value for SizeWidth, you must also specify a value for SizeHeight. A
value of 0,0 indicates that the new bitmap should be the same size as the original
bitmap. A value of 0 in one position but not in the other indicates that the new
bitmap should be scaled to match the proportions of the original bitmap. For
example, a non-zero SizeWidth value specifies the width and requests that SizeHeight
be determined by the original width/height ratio.

Drawing Subprograms
P$DrawBox
P$DrawBox is used to draw a box. For examples that include P$DrawBox, see
“Drawing Shaded Boxes with Colors” on page E-73 and “Drawing a Box Around Text”
on page E-73.
Calling Sequence
CALL "P$DRAWBOX" USING [XPosition YPosition]

[PositionMode] [PositionUnits] [SizeWidth
SizeHeight] [SizeUnits] [ShadeYesNo]

page E-7.
PositionMode. See Mode in “Common P$ Subprogram Arguments.”
PositionUnits/SizeUnits. See Units in “Common P$ Subprogram Arguments.”
SizeWidth/SizeHeight. See Size in “Common P$ Subprogram Arguments.”
ShadeYesNo is an alphanumeric data item that specifies a yes/no value (see Yes/No in
“Common P$ Subprogram Arguments”). It specifies whether or not to shade the
interior of the box using the current box shading color (set with P$SetBoxShade,
described on page E-22).
P$DrawLine
P$DrawLine is used to draw a line. For an example that includes P$DrawLine, see
“Drawing a Ruler” on page E-74.
Calling Sequence
CALL "P$DRAWLINE" USING [X1Point Y1Point]

[Point1Mode] [Point1Units] [X2Point Y2Point]
[Point2Mode] [Point2Units]
XnPoint/YnPoint. See Position in “Common P$ Subprogram Arguments” on

page E-7.
PointnMode. See Mode in “Common P$ Subprogram Arguments.”
PointnUnits. See Units in “Common P$ Subprogram Arguments.”

Drawing Subprograms
P$GetPosition
P$GetPosition is used to retrieve the ending position of the last print operation. For
instance, P$GetPosition could be used to return to a previous position after printing a
bitmap elsewhere on the page.
For an example that includes P$GetPosition, see “Setting Text Position” on page E-84.
Calling Sequence
CALL "P$GETPOSITION" USING XPosition YPosition [Units]

page E-7.
Units. See Units in “Common P$ Subprogram Arguments.”
P$LineTo
P$LineTo is used to draw a line starting at the current position.
For an example that includes P$LineTo, see “Drawing a Ruler” on page E-74.
Calling Sequence
CALL "P$LINETO" USING [XPoint YPoint] [Mode] [Units]
XPoint/YPoint. See Position in “Common P$ Subprogram Arguments” on page E-7.
Mode. See Mode in “Common P$ Subprogram Arguments.”

Drawing Subprograms
P$MoveTo
P$MoveTo is used to reposition the line-draw pen without drawing a line.
For an example that includes P$MoveTo, see “Drawing a Ruler” on page E-74.
Calling Sequence
CALL "P$MOVETO" USING [XPoint YPoint] [Mode] [Units]
XPoint/YPoint. See Position in “Common P$ Subprogram Arguments” on page E-7.
P$SetBoxShade
P$SetBoxShade is used to set color and density of the color used in P$DrawBox (see
page E-20) calls.
For an example that includes P$SetBoxShade, see “Drawing Shaded Boxes with Colors”
on page E-73.
Calling Sequence
CALL "P$SETBOXSHADE" USING [Color]
Color. See Color in “Common P$ Subprogram Arguments” on page E-7.

Drawing Subprograms
P$SetPen
P$SetPen is used to set the style, width, and color of the pen used in P$DrawBox (see
page E-20), P$DrawLine (see page E-20), and P$LineTo (see page E-21) calls.
For an example that includes P$SetPen, see “Drawing Shaded Boxes with Colors” on
page E-73.
Calling Sequence
CALL "P$SETPEN" USING Style [Width] [Color]
Style can be any COBOL numeric data type. It specifies the style of the pen.
Possible values are contained in the WINDEFS.CPY copy file (see page E-69).
Width can be any COBOL numeric data type. It specifies the pen width in logical
units. If Width is zero, the pen is a single pixel wide. The default value is 1.
Note If you specify a Width value greater than 1 for the pen styles, Dash, Dot,
DashDot, or DashDotDot, Windows will force Style to a value of Solid.
P$SetPosition
P$SetPosition is used to set a position for the next print operation.
For examples that include P$SetPosition, see “Drawing a Box Around Text” on
page E-73 and “Setting Text Position” on page E-84.
Calling Sequence
CALL "P$SETPOSITION" USING [XPosition YPosition]

[Mode] [Units]

page E-7.

Drawing Subprograms
Text Manipulation Subprograms
The following subprograms control the manipulation of text on a printed page:
• P$ClearFont • P$SetLineExtendMode
• P$GetTextExtent • P$SetPitch
• P$GetTextMetrics • P$SetTabStops
• P$GetTextPosition • P$SetTextColor
• P$SetDefaultAlignment • P$SetTextPosition
• P$SetFont • P$TextOut
P$ClearFont
P$ClearFont clears the font description values that were set using the P$SetFont
subprogram (see page E-29) and returns them to their default (unset) state. This
subprogram can be used to clear previous values before calling P$SetFont using the
ParameterName/Value method to set information for a new font.
Calling Sequence
CALL "P$CLEARFONT"

P$GetTextExtent
P$GetTextExtent is used to retrieve the bounding rectangle size for text passed to the
subprogram, calculated using the current font size. The returned values can be used to
draw boxes around text or determine whether the text will fit within a desired region (such
as the current line).
For examples that include P$GetTextExtent, see “Drawing a Box Around Text” on
page E-73, “Printing Text at the Top of a Page” on page E-81, and “Printing Text at the
Corners of a Page” on page E-82.
Calling Sequence
CALL "P$GETTEXTEXTENT" USING Text, SizeWidth,

SizeHeight [Units]
Text can be any alphabetic or alphanumeric COBOL data type, where n must be at
least 1. It specifies the text to use in calculating the bounding rectangle.
SizeWidth/SizeHeight. See Size in “Common P$ Subprogram Arguments” on

page E-7.
P$GetTextMetrics
P$GetTextMetrics is used to retrieve the characteristics of the current font. Figure E-2
illustrates some of these characteristics.
For examples that include P$GetTextMetrics, see “Drawing a Box Around Text” on
page E-73 and “Setting the Point Size for a Font” on page E-83.
Figure E-2 Text Metrics

The two calling sequences for this subprogram allow parameters to be retrieved either
individually or collectively. You can retrieve parameters individually by using
ParameterName/Value pairs. Retrieve parameters collectively using the
TextMetricDescription group data item.
Note The values retrieved by P$GetTextMetrics are available after opening a P$ printer.
All values returned by P$GetTextMetrics are in device units.
Calling Sequences
CALL "P$GETTEXTMETRICS" USING TextMetricDescription
CALL "P$GETTEXTMETRICS" USING ParameterName-1 Value-1

[ParameterName-n Value-n ...]
TextMetricDescription is a group data item as defined in the TXTMTRIC.CPY copy

ParameterName is an alphanumeric data item that contains the name of the font
parameter to get (see Table E-4).
Value is a COBOL data item used to receive the value of the parameter named by
file, TXTMTRIC.CPY.
Note For a more complete discussion of text metric parameters, see the Microsoft
Windows documentation for the TEXTMETRIC structure. For web site information, see
page E-65.

Table E-4 Text Metric Parameters
Parameter Name PICTURE Clause Description

Height PIC 9(10) Ascender line to descender line.
Ascent PIC 9(10) Ascender line to baseline.
Descent PIC 9(10) Baseline to descender line.
Internal Leading PIC 9(10) Point size of a font minus the physical size of
the font.
External Leading PIC 9(10) Extra space to be added between lines.
Average Character PIC 9(10) Average character width for a font.
Width
Maximum Character PIC 9(10) Width of the widest character.
Width
Weight PIC 9(10) Font weight.
Overhang PIC 9(10) Extra width added to some synthesized fonts.
Digitized Aspect X PIC 9(10) Horizontal aspect of the device for which the
font was designed.
Digitized Aspect Y PIC 9(10) Horizontal aspect of the device for which the
font was designed. The ratio of Digitized
Aspect X and Digitized Aspect Y is the aspect
ratio of the device for which the font was
designed.
First Character PIC X First character defined in the font.
Last Character PIC X Last character defined in the font.
Default Character PIC X Character that will be substituted for characters
that are not in the font.
Break Character PIC X Character that will be used for word breaks in
text justification.
Italic PIC X ‘Y’ if italic font; ‘N’ otherwise.
Underlined PIC X ‘Y’ if underlined font; ‘N’ otherwise.
Struck Out PIC X ‘Y’ if “struck-out” font; ‘N’ otherwise.
Pitch PIC 9(10) Pitch of the font.
Family PIC 9(10) Family of the font.
Character Set PIC 9(10) Character set of the font.

P$GetTextPosition
P$GetTextPosition is used to retrieve the ending position the last print operation adjusted
to the top or bottom of the current font.
For examples that include P$GetTextPosition, see “Drawing a Box Around Text” on
page E-73 and “Setting Text Position” on page E-84.
Calling Sequence
CALL "P$GETTEXTPOSITION" USING XPosition YPosition

[Alignment] [Units]

page E-7.
Alignment. See Alignment in “Common P$ Subprogram Arguments.”
Note The P$GetPosition subprogram (see page E-21) returns the ending “baseline”
position. P$GetTextPosition should be used when you need the ascender line (top) or
descender line (bottom) position of the current font.
P$SetDefaultAlignment
P$SetDefaultAlignment is used to set default alignment used in text positioning. Possible
values are “Top” and “Bottom”. The initial value is “Top”.
Calling Sequence
CALL "P$SETDEFAULTALIGNMENT" USING Alignment
Alignment. See Alignment in “Common P$ Subprogram Arguments” on page E-7.

P$SetFont
P$SetFont is used to change fonts. Selecting a font with this subprogram call causes the
next COBOL WRITE or OPEN operation on a P$ printer to use that newly selected font.
pairs allows multiple calls to the subprogram to accumulate values for the desired font.
Setting parameters collectively using the LogicalFontDescription group data item sets all
values, after which the ParameterName/Value method can be used to modify values.
For examples that include this subprogram, see "Printing a Watermark" on page E-73,
“Changing a Font While Printing” on page E-77, "Using the COBOL WRITE Statement
to Print Multiple Text Outputs on the Same Line" on page E-78, “Setting the Point Size
for a Font” on page E-83, and “Setting Text Position” on page E-84.
Note The values set by P$SetFont are available to P$GetTextMetrics (see page E-25)
after the OPEN for the printer. You can use P$ClearFont (see page E-24) to clear the
existing font description before calling P$SetFont using the ParameterName/Value
method to set information for a new font.
Calling Sequences
CALL "P$SETFONT" USING LogicalFontDescription
CALL "P$SETFONT" USING ParameterName-1 Value-1

LogicalFontDescription is a group data item as defined in the LOGFONT.CPY copy

ParameterName is an alphanumeric data item that contains the name of the font
parameter to set (see Table E-5).
Value is the COBOL data item used to set the value of the parameter named by
file, LOGFONT.CPY.
Note For a more complete discussion of font attribute parameters, see the Microsoft
Windows documentation for the LOGFONT structure. For web site information, see
page E-47.

Table E-5 Font Parameters
COBOL
Parameter Name Data Type Description
Height Any numeric Font height in logical units.
Width Any numeric Average font width in logical units.
Escapement Any numeric Angle, in tenths of degrees, for a string of
characters (relative to the X-axis of the device).
Orientation Any numeric Angle, in tenths of degrees, for individual
characters (relative to the X-axis of the device).
Weight Any numeric Font weight in the range 0 through 1000. For
example, 400 is normal and 700 is bold. If this
value is zero, a default weight is used.
Italic Any alphabetic or ‘Y’ if italic font; ‘N’ otherwise.
alphanumeric
Underline Any alphabetic or ‘Y’ if underlined font; ‘N’ otherwise.
alphanumeric
Strike Out Any alphabetic or ‘Y’ if “struck-out” font; ‘N’ otherwise.
alphanumeric
Char Set Any numeric Specifies the character set.
Out Precision Any numeric Specifies the output precision for font matching.
Clip Precision Any numeric Specifies the clipping precision for font
matching.
Quality Any numeric Specifies the output quality for font matching.
Pitch Any numeric Pitch of the font.
Family Any numeric Family of the font.
Face Name Any alphabetic or Windows typeface name.
alphanumeric

P$SetLineExtendMode
P$SetLineExtendMode is used to concatenate output from two COBOL WRITE
statements on the same line. This is useful for mixing fonts or styles. Specifically, by
using the COBOL WRITE statement, then calling P$SetLineExtendMode, and using
another WRITE statement with the ADVANCING phrase specifying 0 lines, the output
from the second WRITE statement will appear on the same line as the output from the
first WRITE statement.
For an example that includes P$SetLineExtendMode, see “Using the COBOL WRITE
Statement to Print Multiple Text Outputs on the Same Line” on page E-78.
Calling Sequence
CALL "P$SETLINEEXTENDMODE" USING SpaceAmount [Units]
SpaceAmount can be any COBOL numeric data type. It specifies the amount of
space to leave between the two sets of output. The default value is 0.
Units. See Units in “Common P$ Subprogram Arguments” on page E-7.
P$SetPitch
P$SetPitch is used to set normal, compressed, or expanded font pitch.
For an example that includes P$SetPitch, see “Changing Orientation and Pitch” on
page E-79.
Calling Sequence
CALL "P$SETPITCH" USING Type [Factor]
Type can be any alphabetic or alphanumeric COBOL data type. It specifies

“Normal”, “Expanded”, or “Compressed” font pitch. Only the first letter of the value
is relevant, and it is case-insensitive. Possible values are contained in the
78-level entries in the WINDEFS.CPY copy file (see page E-69).

Factor can be any numeric COBOL data type. It specifies the
compression/expansion ratio to apply to the current font pitch. The default values
are 1.65 for “Compressed” (1.65 times as many characters per inch) and 0.5 for
“Expanded” (half as many characters per inch). A Type value of “Normal” does not
allow the Factor argument, that is, “Normal” is the current font's normal pitch.
P$SetTabStops
P$SetTabStops sets the increment used for computing the next tab stop location. Tabs are
sent using the Horizontal Tab escape sequence (see Table E-9 on page E-85).
Calling Sequence
CALL "P$SETTABSTOPS" USING Increment [Units]
Increment. See Increment in “Common P$ Subprogram Arguments” on page E-7.
P$SetTextColor
P$SetTextColor is used to set the color of text for subsequent P$TextOut (see page E-34)
and COBOL WRITE statements.
For an example that includes P$SetTextColor, see “Printing a Watermark” on page E-73.
Calling Sequence
CALL "P$SETTEXTCOLOR" USING Color

P$SetTextPosition
P$SetTextPosition is used to set a new position for the next print operation adjusted from
the top or bottom of the current font.
For examples that include P$SetTextPosition, see “Printing Text at the Top of a Page” on
page E-81, “Printing Text at the Corners of a Page” on page E-82, and “Setting Text
Position” on page E-84.
Calling Sequence
CALL "P$SETTEXTPOSITION" USING XPosition YPosition

[Alignment] [Mode] [Units]

page E-7.
Alignment. See Alignment in “Common P$ Subprogram Arguments.”
Note 1 The P$SetPosition subprogram (see page E-23) should be used to set the
“baseline” for the next text print operation.
Note 2 To print a line of text in the top left corner of a page, without cutting off the top
of the characters, call P$SetTextPosition specifying a value of “Top” for Alignment. To
print a line of text in the bottom left corner of a page without cutting off the bottom of the
characters, call P$SetTextPosition specifying a value of “Bottom” for Alignment.

P$TextOut
P$TextOut is an alternative to using the COBOL WRITE statement to print text. It
allows the program to control the position of the text. The COBOL WRITE statement has
no positioning capabilities.
For examples that include P$TextOut, see “Drawing a Box Around Text” on page E-73,
“Changing a Font While Printing” on page E-77, “Changing Orientation and Pitch”
on page E-79, “Opening and Writing to Separate Printers” on page E-80, “Printing Text
at the Top of a Page” on page E-81, “Printing Text at the Corners of a Page” on
page E-82, and “Setting Text Position” on page E-84.
Calling Sequence
CALL "P$TEXTOUT" USING Text [XPosition YPosition]

[Mode] [Units] [BoxYesNo] [ShadeYesNo]
Text can be any COBOL alphanumeric data item. It specifies the text to be printed.

page E-7.
BoxYesNo can be any COBOL alphanumeric data item that specifies a yes/no value
(see Yes/No in “Common P$ Subprogram Arguments”). It specifies whether or not to
draw a box around the text.
ShadeYesNo can be any COBOL alphanumeric data item that specifies a yes/no value
(see Yes/No in “Common P$ Subprogram Arguments”). It specifies whether or not to
shade the interior of the box using the current box shading color (set with
P$SetBoxShade, described on page E-22).

Common Drawing and Text Manipulation
Subprograms
The following subprograms are common to both drawing and text manipulation activities:
• P$SetDefaultMode
• P$SetDefaultUnits
• P$SetLeftMargin
• P$SetTopMargin
P$SetDefaultMode
P$SetDefaultMode is used to control the default mode used in positioning and
sizing parameters. Possible values are “Relative” and “Absolute”. The initial value
is “Absolute”.
Calling Sequence
CALL "P$SETDEFAULTMODE" USING Mode
Mode. See Mode in “Common P$ Subprogram Arguments” on page E-7.

Common Drawing and Text Manipulation Subprograms
P$SetDefaultUnits
P$SetDefaultUnits is used to control the default unit of measurement in position
and sizing parameters. Possible values are “Inches”, “Metric”, “Characters”, and
“Device-Units”. The initial value is “Inches”.
For an example that includes P$SetDefaultUnits, see “Drawing a Ruler” on page E-74.
Calling Sequence
CALL "P$SETDEFAULTUNITS" USING Units
Units. See Units in “Common P$ Subprogram Arguments” on page E-7.
P$SetLeftMargin
P$SetLeftMargin is used to set a left margin (offset from left side of paper) for
subsequent COBOL WRITE statements. This margin will be cleared to zero at the
next page boundary. This subprogram is useful for generating columns of text.
Calling Sequence
CALL "P$SETLEFTMARGIN" USING SizeWidth [Units]
SizeWidth. See Size in “Common P$ Subprogram Arguments” on page E-7.

Common Drawing and Text Manipulation Subprograms
P$SetTopMargin
P$SetTopMargin is used to set a top margin (offset from top edge of paper) for
subsequent pages.
Calling Sequence
CALL "P$SETTOPMARGIN" USING SizeHeight [Units]
SizeHeight. See Size in “Common P$ Subprogram Arguments” on page E-7.
Printer Control Subprograms

The following subprograms are used to control various properties of a P$ printer:
• P$ChangeDeviceModes • P$GetPrinterInfo
• P$EnableEscapeSequences • P$SetHandle
• P$GetDeviceCapabilities • P$SetRawMode
• P$GetHandle
P$ChangeDeviceModes
P$ChangeDeviceModes changes the device mode (DEVMODE) values for the standard
Windows Print dialog box. The new values take effect beginning with the next page.
This subprogram is used for such tasks as changing the paper source or the orientation
of paper.
pairs allows multiple calls to the subprogram to accumulate values for the standard
Windows Print dialog box (see page E-5). Setting parameters collectively using the
PrinterDialogDescription group data item sets all values, after which the
ParameterName/Value method can be used to modify values.

Note Only DEVMODE fields of the PrinterDialogDescription can be changed by
this subprogram. These fields are defined in the PRINTDLG.CPY copy file and have
a DM- prefix.
For an example that includes P$ChangeDeviceModes, see “Changing Orientation and

Pitch” on page E-79.
Calling Sequences
CALL "P$CHANGEDEVICEMODES" USING PrinterDialogDescription
CALL "P$CHANGEDEVICEMODES" USING ParameterName-1 Value-1


dialog/device mode parameter to set (see Table E-3 on page E-11).
Value is the COBOL data item used to set the value of the parameter named by
file, PRINTDLG.CPY.
Note For a more complete discussion of device mode parameters, see the Microsoft
Windows documentation for the DEVMODE structure. For web site information, see
page E-51.
P$EnableEscapeSequences
P$EnableEscapeSequences is used to enable RM/COBOL-specific escape sequences,
as described on page E-85. (This subprogram is used in conjunction with the
ESCAPE-SEQUENCES keyword of the DEFINE-DEVICE configuration record.
See page 10-17 for more information.)
Calling Sequence
CALL "P$EnableEscapeSequences"

P$GetDeviceCapabilities
P$GetDeviceCapabilities is used to retrieve the device capabilities of a P$ printer. This
subprogram can be used to compute the printable area of the page to be printed.
individually or collectively. You can retrieve parameters individually using
DeviceCapabilitesDescription group data item.
Note The values retrieved by P$GetDeviceCapabilities are available after opening a

P$ printer.
For examples that include P$GetDeviceCapabilities, see “Setting the Point Size for a
Font” on page E-83, “Printing Text at the Top of a Page” on page E-81, and “Printing
Text at the Corners of a Page” on page E-82.
Calling Sequences
CALL "P$GETDEVICECAPABILITIES" USING TextMetricDescription
CALL "P$GETDEVICECAPABILITIES" USING ParameterName-1

Value-1 [ParameterName-n Value-n...]
DeviceCapabilitesDescription is a group data item, as defined in the

DEVCAPS.CPY copy file (see page E-45).
ParameterName is an alphanumeric data item that contains the name of the device
capability parameter (see Table E-6).
Value is the COBOL data item used to receive the value of the parameter named by
file, DEVCAPS.CPY.
Note For a more complete discussion of device capability parameters, see the Microsoft
Windows documentation for the GetDeviceCaps function. For web site information, see
page E-45.

Table E-6 Device Capability Parameters

Driver Version PIC 9(10) Device driver version.
Technology PIC 9(10) Device technology.
Horizontal Size PIC 9(10) Width of printable area, in millimeters.
Vertical Size PIC 9(10) Height of printable area, in millimeters.
Horizontal Resolution PIC 9(10) Width of printable area, in dots.
Vertical Resolution PIC 9(10) Height of printable area, in dots.
Logical Pixels X PIC 9(10) Horizontal dots-per-inch.
Logical Pixels Y PIC 9(10) Vertical dots-per-inch.
Aspect X PIC 9(10) Length of horizontal sides of a square.
Aspect Y PIC 9(10) Length of vertical sides of the same square.
Aspect XY PIC 9(10) Length of diagonal lines connecting opposite
vertices of the same square.
Physical Width PIC 9(10) Width of the printable area, in device units.
Physical Height PIC 9(10) Height of the printable area, in device units.
Physical Offset X PIC 9(10) Width of unprintable area (left and right edges)
in device units.
Physical Offset Y PIC 9(10) Height of unprintable area (top and bottom
edges) in device units.
Scaling Factor X PIC 9(10) X-axis scale factor.
Scaling Factor Y PIC 9(10) Y-axis scale factor.

P$GetHandle
P$GetHandle is used to retrieve the handle of the current P$ printer. This allows the
developer to use P$SetHandle (see page E-43) to change the printer for subsequent P$
print operations. These calls are not needed unless multiple “PRINTER?” devices are
open at the same time. See also the discussion of “PRINTER?” on page 10-19. For an
example that includes P$GetHandle, see “Opening and Writing to Separate Printers” on
page E-80.
Calling Sequence
CALL "P$GETHANDLE" USING Handle
Handle is a PICTURE 9(2) numeric data item. It specifies the variable to receive the
handle of the current P$ printer.
P$GetPrinterInfo
P$GetPrinterInfo is used to retrieve detailed information about a P$ printer.
individually or collectively. You can retrieve parameters individually using
PrinterInfoDescription group data item.
Calling Sequences
CALL "P$GETPRINTERINFO" USING PrinterInfoDescription
CALL "P$GETPRINTERINFO" USING ParameterName-1

Value-1 [ParameterName-n Value-n...]
PrinterInfoDescription is a group data item, as defined in the PRINTINF.CPY copy

ParameterName is an alphanumeric data item that contains the name of the device
capability parameter to get (see Table E-7).

Value is the COBOL data item used to receive the value of the parameter named by
file, PRINTINF.CPY.
Note For a more complete discussion of printer information parameters, see the
Microsoft Windows documentation for the PRINTER_INFO_2 structure. For web site
information, see page E-62.
Table E-7 Printer Information Parameters

Server Name PIC X(80) Name of the server that controls the printer.
Printer Name PIC X(80) Name of the printer.
Share Name PIC X(80) Shared name of the printer
Port Name PIC X(80) Port(s) used to transmit data to the printer.
Driver Name PIC X(80) Name of the printer driver.
Comment PIC X(80) A brief description of the printer.
Location PIC X(80) Physical location of the printer.
Sep File PIC X(80) Name of file used to create the separator page.
Print Processor PIC X(80) Name of the print processor used by the printer.
Data Type PIC X(80) Data type used to record the print job.
Parameters PIC X(80) Default print-processor parameters.
Attributes Group Note This parameter is not available when
using the ParameterName/Value pairs calling
sequence. It is available only when using the
PrinterInfoDescription group data item calling
sequence.
Priority PIC 9(10) Print spooler priority.
Default Priority PIC 9(10) Default spooler priority.
Start Time PIC 9(10) Earliest allowed print time, in minutes, after
midnight GMT.
Until Time PIC 9(10) Latest allowed print time, in minutes, after
midnight GMT.
Status Group Note This parameter is not available when
using the ParameterName/Value pairs calling
sequence. It is available only when using the
PrinterInfoDescription group data item calling
sequence.
Jobs PIC 9(10) Number of jobs in the print queue.
Average PPM PIC 9(10) Average print speed in pages-per-minute.

P$SetHandle
P$SetHandle is used to change the current P$ printer. This call is not needed unless
multiple “PRINTER?” devices are open at the same time. See also the discussion of
“PRINTER?” on page 10-19.
For an example that includes P$SetHandle, see “Opening and Writing to Separate
Printers” on page E-80.
Calling Sequence
CALL "P$SETHANDLE" USING Handle
Handle can be any COBOL numeric data item. It specifies the variable that contains
the handle of the printer to use in subsequent P$ calls.
P$SetRawMode
P$SetRawMode is used to set a raw mode output when the next printer is opened.
This subprogram allows completely raw byte-stream I/O in applications that require it.
It is intended to be used when a user is having problems sending escape sequences to
networked printers on a Windows NT server. The RAW keyword of the
DEFINE-DEVICE configuration record (see page 10-17) or the Printer Enable Raw
Mode property (see page 3-26) may also be used to set raw mode output for a printer.
Only the following P$ subprograms can be used for a raw mode printer:
• P$ClearDialog (see page E-13) • P$GetDeviceCapabilities (see page E-39)
• P$DisplayDialog (see page E-16) • P$GetHandle (see page E-41)
• P$EnableDialog (see page E-16) • P$GetPrinterInfo (see page E-41)
• P$GetDialog (see page E-17) • P$SetHandle (see page E-43)
• P$SetDialog (see page E-18)
Calling Sequence
CALL "P$SETRAWMODE"

Copy Files
The RM/COBOL development system supplies COBOL copy files to facilitate Windows
printing program development using P$ subprograms.
The following copy files are supplied:
• DEVCAPS.CPY, shown on page E-45, is associated with the

P$GetDeviceCapabilities subprogram (see page E-39).
• LOGFONT.CPY, shown on page E-47, is associated with the P$SetFont

subprogram (see page E-29).
• PRINTDLG.CPY, shown on page E-51, is associated with the following

subprograms:
− P$ChangeDeviceModes (see page E-37)
− P$GetDialog (see page E-17)
− P$SetDialog (see page E-18)
• PRINTINF.CPY, shown on page E-62, is associated with the P$GetPrinterInfo

• TXTMTRIC.CPY, shown on page E-65, is associated with the P$GetTextMetrics

• WINDEFS.CPY, shown on page E-69, contains miscellaneous items used by several

P$ subprograms. This copy file is also used with C$PlaySound subprogram (see
Appendix F, Subprogram Library).
WARNING We strongly recommend that you do not change these Liant-supplied copy
files, as unpredictable results may occur if the copy files are changed incorrectly. If you
must alter the files, please be aware that the names of the data items are the only thing that
can be changed. Do not alter the pictures, types, sizes, or order of the data items.

DEVCAPS.CPY
Information regarding the Microsoft Windows GetDeviceCaps function can be found on
the Internet at http://msdn.microsoft.com/library/. Periodically, Microsoft reorganizes the
MSDN information on the web site. Use the search capability to find information on the
requested topic.
The following search tree was accurate when this document went to print:
Platform SDK
Graphics and Multimedia Services
Windows GDI
Device Contexts
Device Context Reference
Device Context Functions
GetDeviceCaps
DEVCAPS.CPY contains the following definitions.

*
* Device Capabilities Definitions
*
01 DeviceCapabilities.
02 DC-DriverVersion Picture 9(10) Binary(4).
02 DC-TechnologyValue Picture 9 Binary(4).
88 DC-TechnologyIsPlotter Value 0.
88 DC-TechnologyIsRASDisplay Value 1.
88 DC-TechnologyIsRASPrinter Value 2.
88 DC-TechnologyIsRASCamera Value 3.
88 DC-TechnologyIsCharStream Value 4.
88 DC-TechnologyIsRASMetafile Value 5.
88 DC-TechnologyIsRASDispfile Value 6.
02 DC-HorzSize Picture 9(10) Binary(4).
02 DC-VertSize Picture 9(10) Binary(4).
02 DC-HorzRes Picture 9(10) Binary(4).
02 DC-VertRes Picture 9(10) Binary(4).
02 DC-LogPixelsX Picture 9(10) Binary(4).
02 DC-LogPixelsY Picture 9(10) Binary(4).
02 DC-AspectX Picture 9(10) Binary(4).
02 DC-AspectY Picture 9(10) Binary(4).
02 DC-AspectXY Picture 9(10) Binary(4).
02 DC-PhysicalWidth Picture 9(10) Binary(4).
02 DC-PhysicalHeight Picture 9(10) Binary(4).

DEVCAPS.CPY
02 DC-PhysicalOffsetX Picture 9(10) Binary(4).
02 DC-PhysicalOffsetY Picture 9(10) Binary(4).
02 DC-ScalingFactorX Picture 9(10) Binary(4).
02 DC-ScalingFactorY Picture 9(10) Binary(4).
*
* Technology Values
*
78 DC-TechnologyPlotter Value 0.
78 DC-TechnologyRASDisplay Value 1.
78 DC-TechnologyRASPrinter Value 2.
78 DC-TechnologyRASCamera Value 3.
78 DC-TechnologyCharStream Value 4.
78 DC-TechnologyRASMetafile Value 5.
78 DC-TechnologyRASDispfile Value 6.
*
* Parameter Name Values
*
78 DC-DriverVersionParam Value "Driver Version".
78 DC-TechnologyParam Value "Technology".
78 DC-HorizontalSizeParam Value "Horizontal Size".
78 DC-VerticalSizeParam Value "Vertical Size".
78 DC-HorizontalResolutionParam Value "Horizontal Resolution".
78 DC-VerticalResolutionParam Value "Vertical Resolution".
78 DC-LogicalPixelsXParam Value "Logical Pixels X".
78 DC-LogicalPixelsYParam Value "Logical Pixels Y".
78 DC-AspectXParam Value "Aspect X".
78 DC-AspectYParam Value "Aspect Y".
78 DC-AspectXYParam Value "Aspect XY".
78 DC-PhysicalWidthParam Value "Physical Width".
78 DC-PhysicalHeightParam Value "Physical Height".
78 DC-PhysicalOffsetXParam Value "Physical Offset X".
78 DC-PhysicalOffsetYParam Value "Physical Offset Y".
78 DC-ScalingFactorXParam Value "Scaling Factor X".
78 DC-ScalingFactorYParam Value "Scaling Factor Y".

DEVCAPS.CPY
LOGFONT.CPY
Information regarding the Microsoft Windows LOGFONT structure can be found on the
Internet at http://msdn.microsoft.com/library/. Periodically, Microsoft reorganizes the
requested topic.
Platform SDK
Windows GDI
Fonts and Text
Font and Text Reference
Font and Text Structures
LOGFONT
LOGFONT.CPY contains the following definitions.

*
* Logical Font Definitions
*
01 LogicalFont.
02 LF-Height Picture 9(5) Binary(2).
02 LF-Width Picture 9(5) Binary(2).
02 LF-Escapement Picture 9(5) Binary(2).
02 LF-Orientation Picture 9(5) Binary(2).
02 LF-WeightValue Picture 9(3) Binary(2).
88 LF-WeightIsDontCare Value 0.
88 LF-WeightIsThin Value 100.
88 LF-WeightIsExtraLight Value 200.
88 LF-WeightIsUltraLight Value 200.
88 LF-WeightIsLight Value 300.
88 LF-WeightIsNormal Value 400.
88 LF-WeightIsRegular Value 400.
88 LF-WeightIsMedium Value 500.
88 LF-WeightIsSemiBold Value 600.
88 LF-WeightIsDemiBold Value 600.
88 LF-WeightIsBold Value 700.
88 LF-WeightIsExtraBold Value 800.
88 LF-WeightIsUltraBold Value 800.
88 LF-WeightIsHeavy Value 900.
88 LF-WeightIsBlack Value 900.

LOGFONT.CPY
02 LF-ItalicValue Picture X.
88 LF-Italic Value 'Y' When False 'N'.
02 LF-UnderlineValue Picture X.
88 LF-Underline Value 'Y' When False 'N'.
02 LF-StrikeoutValue Picture X.
88 LF-Strikeout Value 'Y' When False 'N'.
02 LF-CharSetValue Picture 9(3) Binary(2).
88 LF-CharSetIsANSI Value 0.
88 LF-CharSetIsDefault Value 1.
88 LF-CharSetIsSymbol Value 2.
88 LF-CharSetIsMAC Value 77.
88 LF-CharSetIsShiftJIS Value 128.
88 LF-CharSetIsHangeul Value 129.
88 LF-CharSetIsJohab Value 130.
88 LF-CharSetIsChineseBig5 Value 136.
88 LF-CharSetIsGreek Value 161.
88 LF-CharSetIsTurkish Value 162.
88 LF-CharSetIsHebrew Value 177.
88 LF-CharSetIsArabic Value 178.
88 LF-CharSetIsBaltic Value 186.
88 LF-CharSetIsRussian Value 204.
88 LF-CharSetIsThai Value 222.
88 LF-CharSetIsEastEurope Value 238.
88 LF-CharSetIsOEM Value 255.
02 LF-OutPrecisValue Picture 9 Binary(2).
88 LF-OutPrecisIsDefault Value 0.
88 LF-OutPrecisIsString Value 1.
88 LF-OutPrecisIsStroke Value 3.
88 LF-OutPrecisIsTrueType Value 4.
88 LF-OutPrecisIsDevice Value 5.
88 LF-OutPrecisIsRaster Value 6.
88 LF-OutPrecisIsTruTypeOnly Value 7.
88 LF-OutPrecisIsOutline Value 8.
02 LF-ClipPrecisValue Picture 9(3) Binary(2).
88 LF-ClipPrecisIsDefault Value 0.
88 LF-ClipPrecisIsStroke Value 2.
88 LF-ClipPrecisIsLHAngles Value 16.
88 LF-ClipPrecisIsEmbedded Value 128.
02 LF-QualityValue Picture 9 Binary(2).
88 LF-QualityIsDefault Value 0.
88 LF-QualityIsDraft Value 1.
88 LF-QualityIsProof Value 2.
02 LF-PitchValue Picture 9 Binary(2).

LOGFONT.CPY
88 LF-PitchIsDefault Value 0.
88 LF-PitchIsFixed Value 1.
88 LF-PitchIsVariable Value 2.
02 LF-FamilyValue Picture 9 Binary(2).
88 LF-FamilyIsDontCare Value 0.
88 LF-FamilyIsRoman Value 1.
88 LF-FamilyIsSwiss Value 2.
88 LF-FamilyIsModern Value 3.
88 LF-FamilyIsScript Value 4.
88 LF-FamilyIsDecorative Value 5.
02 LF-FaceName Picture X(31).
*
* Font Weight Values
*
78 LF-WeightDontCare Value 0.
78 LF-WeightThin Value 100.
78 LF-WeightExtraLight Value 200.
78 LF-WeightUltraLight Value 200.
78 LF-WeightLight Value 300.
78 LF-WeightNormal Value 400.
78 LF-WeightRegular Value 400.
78 LF-WeightMedium Value 500.
78 LF-WeightSemiBold Value 600.
78 LF-WeightDemiBold Value 600.
78 LF-WeightBold Value 700.
78 LF-WeightExtraBold Value 800.
78 LF-WeightUltraBold Value 800.
78 LF-WeightHeavy Value 900.
78 LF-WeightBlack Value 900.
*
* Font Character Set Values
*
78 LF-CharSetANSI Value 0.
78 LF-CharSetDefault Value 1.
78 LF-CharSetSymbol Value 2.
78 LF-CharSetMAC Value 77.
78 LF-CharSetShiftJIS Value 128.
78 LF-CharSetHangeul Value 129.
78 LF-CharSetJohab Value 130.
78 LF-CharSetChineseBig5 Value 136.
78 LF-CharSetGreek Value 161.
78 LF-CharSetTurkish Value 162.
78 LF-CharSetHebrew Value 177.

LOGFONT.CPY
78 LF-CharSetArabic Value 178.
78 LF-CharSetBaltic Value 186.
78 LF-CharSetRussian Value 204.
78 LF-CharSetThai Value 222.
78 LF-CharSetEastEurope Value 238.
78 LF-CharSetOEM Value 255.
*
* Font Output Precision Values
*
78 LF-OutPrecisDefault Value 0.
78 LF-OutPrecisString Value 1.
78 LF-OutPrecisStroke Value 3.
78 LF-OutPrecisTrueType Value 4.
78 LF-OutPrecisDevice Value 5.
78 LF-OutPrecisRaster Value 6.
78 LF-OutPrecisTruTypeOnly Value 7.
78 LF-OutPrecisOutline Value 8.
*
* Font Clipping Precision Values
*
78 LF-ClipPrecisDefault Value 0.
78 LF-ClipPrecisStroke Value 2.
78 LF-ClipPrecisLHAngles Value 16.
78 LF-ClipPrecisEmbedded Value 128.
*
* Font Quality Values
*
78 LF-QualityDefault Value 0.
78 LF-QualityDraft Value 1.
78 LF-QualityProof Value 2.
*
* Font Pitch Values
*
78 LF-PitchDefault Value 0.
78 LF-PitchFixed Value 1.
78 LF-PitchVariable Value 2.
*
* Font Family Values
*
78 LF-FamilyDontCare Value 0.
78 LF-FamilyRoman Value 1.
78 LF-FamilySwiss Value 2.
78 LF-FamilyModern Value 3.

LOGFONT.CPY
78 LF-FamilyScript Value 4.
78 LF-FamilyDecorative Value 5.
*
*
78 LF-HeightParam Value "Height".
78 LF-WidthParam Value "Width".
78 LF-EscapementParam Value "Escapement".
78 LF-OrientationParam Value "Orientation".
78 LF-WeightParam Value "Weight".
78 LF-ItalicParam Value "Italic".
78 LF-UnderlineParam Value "Underline".
78 LF-StrikeOutParam Value "Strike Out".
78 LF-CharSetParam Value "Char Set".
78 LF-OutPrecisionParam Value "Out Precision".
78 LF-ClipPrecisionParam Value "Clip Precision".
78 LF-QualityParam Value "Quality".
78 LF-PitchParam Value "Pitch".
78 LF-FamilyParam Value "Family".
78 LF-FaceNameParam Value "Face Name".
PRINTDLG.CPY
Information regarding the Microsoft Windows PRINTDLG and DEVMODE structures
can be found on the Internet at http://msdn.microsoft.com/library/. Periodically,
Microsoft reorganizes the MSDN information on the web site. Use the search capability
to find information on the requested topic.
The following search trees were accurate when this document went to print:
For PRINTDLG:
Platform SDK
User Interface Services
Windows User Interface
User Input
Common Dialog Box Library
Common Dialog Box Reference
Common Dialog Box Structures
PRINTDLG

PRINTDLG.CPY
For DEVMODE:
Platform SDK
Windows GDI
Printing and Print Spooler
Printing and Print Spooler Reference
Printing and Print Spooler Structures
DEVMODE
PRINTDLG.CPY contains the following definitions.

*
* Print Dialog Definitions
*
01 PrintDialog.
02 PD-ReturnValue Picture X.
88 PD-OKReturn Value 'Y' When False 'N'.
02 PD-ExtendedErrorValue Picture 9(5) Binary(2).
88 PD-ExtErrIsCanceled Value 0.
88 PD-ExtErrIsStructSize Value 1.
88 PD-ExtErrIsInitialization Value 2.
88 PD-ExtErrIsNoTemplate Value 3.
88 PD-ExtErrIsNoHInstance Value 4.
88 PD-ExtErrIsLoadStrFailure Value 5.
88 PD-ExtErrIsFindResFailure Value 6.
88 PD-ExtErrIsLoadResFailure Value 7.
88 PD-ExtErrIsLockResFailure Value 8.
88 PD-ExtErrIsMemAllocFailure Value 9.
88 PD-ExtErrIsMemLockFailure Value 10.
88 PD-ExtErrIsNoHook Value 11.
88 PD-ExtErrIsRegisterMsgFail Value 12.
88 PD-ExtErrIsSetupFailure Value 4097.
88 PD-ExtErrIsParseFailure Value 4098.
88 PD-ExtErrIsRetDefFailure Value 4099.
88 PD-ExtErrIsLoadDrvFailure Value 4100.
88 PD-ExtErrIsGetDevModeFail Value 4101.
88 PD-ExtErrIsInitFailure Value 4102.
88 PD-ExtErrIsNoDevices Value 4103.
88 PD-ExtErrIsNoDefaultPrn Value 4104.
88 PD-ExtErrIsDNDMMismatch Value 4105.
88 PD-ExtErrIsCreateICFailure Value 4106.
88 PD-ExtErrIsPrinterNotFound Value 4107.
88 PD-ExtErrIsDefaultDifferent Value 4108.

PRINTDLG.CPY
88 PD-ExtErrIsDialogFailure Value 65535.
02 PD-Flags.
03 PD-AllPagesFlagValue Picture X.
88 PD-AllPagesFlag Value 'Y' When False 'N'.
03 PD-SelectionFlagValue Picture X.
88 PD-SelectionFlag Value 'Y' When False 'N'.
03 PD-PageNumbersFlagValue Picture X.
88 PD-PageNumbersFlag Value 'Y' When False 'N'.
03 PD-NoSelectionFlagValue Picture X.
88 PD-NoSelectionFlag Value 'Y' When False 'N'.
03 PD-NoPageNumbersFlagValue Picture X.
88 PD-NoPageNumbersFlag Value 'Y' When False 'N'.
03 PD-CollateFlagValue Picture X.
88 PD-CollateFlag Value 'Y' When False 'N'.
03 PD-PrintSetupFlagValue Picture X.
88 PD-PrintSetupFlag Value 'Y' When False 'N'.
03 PD-PrintToFileFlagValue Picture X.
88 PD-PrintToFileFlag Value 'Y' When False 'N'.
03 PD-NoWarningFlagValue Picture X.
88 PD-NoWarningFlag Value 'Y' When False 'N'.
03 PD-UseDevModeCopiesFlagValue Picture X.
88 PD-UseDevModeCopiesFlag Value 'Y' When False 'N'.
03 PD-DisablePrintToFileFlagValue Picture X.
88 PD-DisablePrintToFileFlag Value 'Y' When False 'N'.
03 PD-HidePrintToFileFlagValue Picture X.
88 PD-HidePrintToFileFlag Value 'Y' When False 'N'.
03 PD-NoNetworkButtonFlagValue Picture X.
88 PD-NoNetworkButtonFlag Value 'Y' When False 'N'.
02 PD-FromPage Picture 9(5) Binary(2).
02 PD-ToPage Picture 9(5) Binary(2).
02 PD-MinPage Picture 9(5) Binary(2).
02 PD-MaxPage Picture 9(5) Binary(2).
02 PD-Copies Picture 9(5) Binary(2).
02 DM-DeviceName Picture X(31).
02 DM-Fields.
03 DM-OrientationFieldValue Picture X.
88 DM-OrientationField Value 'Y' When False 'N'.
03 DM-PaperSizeFieldValue Picture X.
88 DM-PaperSizeField Value 'Y' When False 'N'.
03 DM-PaperLengthFieldValue Picture X.
88 DM-PaperLengthField Value 'Y' When False 'N'.
03 DM-PaperWidthFieldValue Picture X.
88 DM-PaperWidthField Value 'Y' When False 'N'.

PRINTDLG.CPY
03 DM-ScaleFieldValue Picture X.
88 DM-ScaleField Value 'Y' When False 'N'.
03 DM-CopiesFieldValue Picture X.
88 DM-CopiesField Value 'Y' When False 'N'.
03 DM-PaperSourceFieldValue Picture X.
88 DM-PaperSourceField Value 'Y' When False 'N'.
03 DM-PrintQualityFieldValue Picture X.
88 DM-PrintQualityField Value 'Y' When False 'N'.
03 DM-ColorFieldValue Picture X.
88 DM-ColorField Value 'Y' When False 'N'.
03 DM-DuplexFieldValue Picture X.
88 DM-DuplexField Value 'Y' When False 'N'.
03 DM-YResolutionFieldValue Picture X.
88 DM-YResolutionField Value 'Y' When False 'N'.
03 DM-TrueTypeOptionFieldValue Picture X.
88 DM-TrueTypeOptionField Value 'Y' When False 'N'.
03 DM-CollateFieldValue Picture X.
88 DM-CollateField Value 'Y' When False 'N'.
03 DM-ICMMethodFieldValue Picture X.
88 DM-ICMMethodField Value 'Y' When False 'N'.
03 DM-ICMIntentFieldValue Picture X.
88 DM-ICMIntentField Value 'Y' When False 'N'.
03 DM-MediaTypeFieldValue Picture X.
88 DM-MediaTypeField Value 'Y' When False 'N'.
03 DM-DitherTypeFieldValue Picture X.
88 DM-DitherTypeField Value 'Y' When False 'N'.
02 DM-OrientationValue Picture 9 Binary(2).
88 DM-OrientationIsPortrait Value 1.
88 DM-OrientationIsLandscape Value 2.
02 DM-PaperSizeValue Picture 9(2) Binary(2).
88 DM-PaperSizeIsLetter Value 1.
88 DM-PaperSizeIsLetterSmall Value 2.
88 DM-PaperSizeIsTabloid Value 3.
88 DM-PaperSizeIsLedger Value 4.
88 DM-PaperSizeIsLegal Value 5.
88 DM-PaperSizeIsStatement Value 6.
88 DM-PaperSizeIsExecutive Value 7.
88 DM-PaperSizeIsA3 Value 8.
88 DM-PaperSizeIsA4Small Value 10.
88 DM-PaperSizeIsB4 Value 12.
88 DM-PaperSizeIsB5 Value 13.

PRINTDLG.CPY
88 DM-PaperSizeIsFolio Value 14.
88 DM-PaperSizeIsQuarto Value 15.
88 DM-PaperSizeIs10x14 Value 16.
88 DM-PaperSizeIs11x17 Value 17.
88 DM-PaperSizeIsNote Value 18.
88 DM-PaperSizeIsEnv9 Value 19.
88 DM-PaperSizeIsCSheet Value 24.
88 DM-PaperSizeIsDSheet Value 25.
88 DM-PaperSizeIsESheet Value 26.
88 DM-PaperSizeIsEnvDl Value 27.
88 DM-PaperSizeIsEnvC5 Value 28.
88 DM-PaperSizeIsEnvB4 Value 33.
88 DM-PaperSizeIsEnvItaly Value 36.
88 DM-PaperSizeIsEnvMonarch Value 37.
88 DM-PaperSizeIsEnvPersonal Value 38.
88 DM-PaperSizeIsFanFoldUS Value 39.
88 DM-PaperSizeIsFanFoldStdGerman Value 40.
88 DM-PaperSizeIsFanFoldLglGerman Value 41.
02 DM-PaperLength Picture 9(5) Binary(2).
02 DM-PaperWidth Picture 9(5) Binary(2).
02 DM-Scale Picture 9(5) Binary(2).
02 DM-Copies Picture 9(5) Binary(2).
02 DM-PaperSourceValue Picture 9(2) Binary(2).
88 DM-PaperSourceIsUpper Value 1.
88 DM-PaperSourceIsOnlyOne Value 1.
88 DM-PaperSourceIsLower Value 2.
88 DM-PaperSourceIsMiddle Value 3.
88 DM-PaperSourceIsManual Value 4.
88 DM-PaperSourceIsEnvelope Value 5.
88 DM-PaperSourceIsEnvManual Value 6.
88 DM-PaperSourceIsAuto Value 7.
88 DM-PaperSourceIsTractor Value 8.
88 DM-PaperSourceIsSmallFmt Value 9.

PRINTDLG.CPY
88 DM-PaperSourceIsLargeFmt Value 10.
88 DM-PaperSourceIsLargeCapacity Value 11.
88 DM-PaperSourceIsCassette Value 14.
88 DM-PaperSourceIsFormSource Value 15.
02 DM-ResolutionValue Picture S9 Binary(2).
88 DM-ResolutionIsDraft Value -1.
88 DM-ResolutionIsLow Value -2.
88 DM-ResolutionIsMedium Value -3.
88 DM-ResolutionIsHigh Value -4.
02 DM-ColorValue Picture 9 Binary(2).
88 DM-ColorIsMonochrome Value 1.
88 DM-ColorIsColor Value 2.
02 DM-DuplexValue Picture 9 Binary(2).
88 DM-DuplexIsSimplex Value 1.
88 DM-DuplexIsVertical Value 2.
88 DM-DuplexIsHorizontal Value 3.
02 DM-YResolution Picture 9(5) Binary(2).
02 DM-TrueTypeValue Picture 9 Binary(2).
88 DM-TrueTypeIsBitmap Value 1.
88 DM-TrueTypeIsDownload Value 2.
88 DM-TrueTypeIsSubDev Value 3.
02 DM-CollateValue Picture 9 Binary(2).
88 DM-CollateIsFalse Value 0.
88 DM-CollateIsTrue Value 1.
02 DM-ICMMethodValue Picture 9 Binary(4).
88 DM-ICMMethodIsNone Value 1.
88 DM-ICMMethodIsSystem Value 2.
88 DM-ICMMethodIsDriver Value 3.
88 DM-ICMMethodIsDevice Value 4.
02 DM-ICMIntentValue Picture 9 Binary(4).
88 DM-ICMIntentIsSaturate Value 1.
88 DM-ICMIntentIsContrast Value 2.
88 DM-ICMIntentIsColorMetric Value 3.
02 DM-MediaTypeValue Picture 9 Binary(4).
88 DM-MediaTypeIsStandard Value 1.
88 DM-MediaTypeIsTransparency Value 2.
88 DM-MediaTypeIsGlossy Value 3.
02 DM-DitherTypeValue Picture 99 Binary(4).
88 DM-DitherTypeIsNone Value 1.
88 DM-DitherTypeIsCoarse Value 2.
88 DM-DitherTypeIsFine Value 3.
88 DM-DitherTypeIsLineArt Value 4.
88 DM-DitherTypeIsErrorDiffusion Value 5.

PRINTDLG.CPY
88 DM-DitherTypeIsGrayScale Value 10.
*
* Print Dialog Extended Error Values
*
78 PD-ExtErrCanceled Value 0.
78 PD-ExtErrStructSize Value 1.
78 PD-ExtErrInitialization Value 2.
78 PD-ExtErrNoTemplate Value 3.
78 PD-ExtErrNoHInstance Value 4.
78 PD-ExtErrLoadStrFailure Value 5.
78 PD-ExtErrFindResFailure Value 6.
78 PD-ExtErrLoadResFailure Value 7.
78 PD-ExtErrLockResFailure Value 8.
78 PD-ExtErrMemAllocFailure Value 9.
78 PD-ExtErrMemLockFailure Value 10.
78 PD-ExtErrNoHook Value 11.
78 PD-ExtErrRegisterMsgFail Value 12.
78 PD-ExtErrSetupFailure Value 4097.
78 PD-ExtErrParseFailure Value 4098.
78 PD-ExtErrRetDefFailure Value 4099.
78 PD-ExtErrLoadDrvFailure Value 4100.
78 PD-ExtErrGetDevModeFail Value 4101.
78 PD-ExtErrInitFailure Value 4102.
78 PD-ExtErrNoDevices Value 4103.
78 PD-ExtErrNoDefaultPrn Value 4104.
78 PD-ExtErrDNDMMismatch Value 4105.
78 PD-ExtErrCreateICFailure Value 4106.
78 PD-ExtErrPrinterNotFound Value 4107.
78 PD-ExtErrDefaultDifferent Value 4108.
78 PD-ExtErrDialogFailure Value 65535.
*
* Device Mode Orientation Values
*
78 DM-OrientationPortrait Value 1.
78 DM-OrientationLandscape Value 2.
*
* Device Mode Paper Size Values
*
78 DM-PaperSizeLetter Value 1.
78 DM-PaperSizeLetterSmall Value 2.
78 DM-PaperSizeTabloid Value 3.
78 DM-PaperSizeLedger Value 4.
78 DM-PaperSizeLegal Value 5.

PRINTDLG.CPY
78 DM-PaperSizeStatement Value 6.
78 DM-PaperSizeExecutive Value 7.
78 DM-PaperSizeA3 Value 8.
78 DM-PaperSizeA4Small Value 10.
78 DM-PaperSizeB4 Value 12.
78 DM-PaperSizeB5 Value 13.
78 DM-PaperSizeFolio Value 14.
78 DM-PaperSizeQuarto Value 15.
78 DM-PaperSize10x14 Value 16.
78 DM-PaperSize11x17 Value 17.
78 DM-PaperSizeNote Value 18.
78 DM-PaperSizeEnv9 Value 19.
78 DM-PaperSizeCSheet Value 24.
78 DM-PaperSizeDSheet Value 25.
78 DM-PaperSizeESheet Value 26.
78 DM-PaperSizeEnvDl Value 27.
78 DM-PaperSizeEnvC5 Value 28.
78 DM-PaperSizeEnvB4 Value 33.
78 DM-PaperSizeEnvItaly Value 36.
78 DM-PaperSizeEnvMonarch Value 37.
78 DM-PaperSizeEnvPersonal Value 38.
78 DM-PaperSizeFanFoldUS Value 39.
78 DM-PaperSizeFanFoldStdGerman Value 40.
78 DM-PaperSizeFanFoldLglGerman Value 41.
*
* Device Mode Paper Source Values
*
78 DM-PaperSourceUpper Value 1.
78 DM-PaperSourceOnlyOne Value 1.
78 DM-PaperSourceLower Value 2.
78 DM-PaperSourceMiddle Value 3.

PRINTDLG.CPY
78 DM-PaperSourceManual Value 4.
78 DM-PaperSourceEnvelope Value 5.
78 DM-PaperSourceEnvManual Value 6.
78 DM-PaperSourceAuto Value 7.
78 DM-PaperSourceTractor Value 8.
78 DM-PaperSourceSmallFmt Value 9.
78 DM-PaperSourceLargeFmt Value 10.
78 DM-PaperSourceLargeCapacity Value 11.
78 DM-PaperSourceCassette Value 14.
78 DM-PaperSourceFormSource Value 15.
*
* Device Mode Resolution Values
*
78 DM-ResolutionDraft Value -1.
78 DM-ResolutionLow Value -2.
78 DM-ResolutionMedium Value -3.
78 DM-ResolutionHigh Value -4.
*
* Device Mode Color Values
*
78 DM-ColorMonochrome Value 1.
78 DM-ColorColor Value 2.
*
* Device Mode Duplex Values
*
78 DM-DuplexSimplex Value 1.
78 DM-DuplexVertical Value 2.
78 DM-DuplexHorizontal Value 3.
*
* Device Mode True Type Values
*
78 DM-TrueTypeBitmap Value 1.
78 DM-TrueTypeDownload Value 2.
78 DM-TrueTypeSubDev Value 3.
*
* Device Mode Collate Values
*
78 DM-CollateFalse Value 0.
78 DM-CollateTrue Value 1.
*
* Device ICM Method Values
*
78 DM-ICMMethodNone Value 1.

PRINTDLG.CPY
78 DM-ICMMethodSystem Value 2.
78 DM-ICMMethodDriver Value 3.
78 DM-ICMMethodDevice Value 4.
*
* Device ICM Type Values
*
78 DM-ICMTypeSaturate Value 1.
78 DM-ICMTypeContrast Value 2.
78 DM-ICMTypeColorMetric Value 3.
*
* Device Mode Media Type Values
*
78 DM-MediaTypeStandard Value 1.
78 DM-MediaTypeTransparency Value 2.
78 DM-MediaTypeGlossy Value 3.
*
* Device Mode Dither Type Values
*
78 DM-DitherTypeNone Value 1.
78 DM-DitherTypeCoarse Value 2.
78 DM-DitherTypeFine Value 3.
78 DM-DitherTypeLineArt Value 4.
78 DM-DitherTypeErrorDiffusion Value 5.
78 DM-DitherTypeGrayScale Value 10.
*
* P$DisplayDialog Return Values
*
78 PD-ReturnParam Value 0.
78 PD-ReturnCancelled Value 1.
78 PD-ReturnError Value 2.
*
*
78 PD-ReturnParam Value "Return".
78 PD-ExtendedErrorParam Value "Extended Error".
78 PD-AllPagesFlagParam Value "All Pages Flag".
78 PD-SelectionFlagParam Value "Selection Flag".
78 PD-PageNumbersFlagParam Value "Page Numbers Flag".
78 PD-NoSelectionFlagParam Value "No Selection Flag".
78 PD-NoPageNumbersFlagParam Value "No Page Numbers Flag".
78 PD-CollateFlagParam Value "Collate Flag".
78 PD-PrintSetupFlagParam Value "Print Setup Flag".
78 PD-PrintToFileFlagParam Value "Print To File Flag".

PRINTDLG.CPY
78 PD-NoWarningFlagParam Value "No Warning Flag".
78 PD-UseDevModeCopiesFlagParam Value
"Use Device Mode Copies Flag".
78 PD-DisablePrintToFileFlagParam Value
"Disable Print To File Flag".
78 PD-HidePrintToFileFlagParam Value "Hide Print To File Flag".
78 PD-NoNetworkButtonFlagParam Value "No Network Button Flag".
78 PD-FromPageParam Value "From Page".
78 PD-ToPageParam Value "To Page".
78 PD-MinPageParam Value "Min Page".
78 PD-MaxPageParam Value "Max Page".
78 PD-PrintDialogCopiesParam Value "Print Dialog Copies".
78 DM-DeviceNameParam Value "Device Name".
78 DM-OrientationParam Value "Orientation".
78 DM-PaperSizeParam Value "Paper Size".
78 DM-PaperLengthParam Value "Paper Length".
78 DM-PaperWidthParam Value "Paper Width".
78 DM-ScaleParam Value "Scale".
78 DM-DeviceModeCopiesParam Value "Device Mode Copies".
78 DM-DefaultSourceParam Value "Default Source".
78 DM-PrintQualityParam Value "Print Quality".
78 DM-ColorParam Value "Color".
78 DM-DuplexParam Value "Duplex".
78 DM-YResolutionParam Value "Y Resolution".
78 DM-TrueTypeOptionParam Value "True Type Option".
78 DM-CollateParam Value "Collate".
78 DM-ICMMethodParam Value "ICM Method".
78 DM-ICMIntentParam Value "ICM Intent".
78 DM-MediaTypeParam Value "Media Type".
78 DM-DitherTypeParam Value "Dither Type".

PRINTDLG.CPY
PRINTINF.CPY
Information regarding the Microsoft Windows PRINTER_INFO_2 structure can be found
on the Internet at http://msdn.microsoft.com/library/. Periodically, Microsoft reorganizes
the MSDN information on the web site. Use the search capability to find information on
the requested topic.
Platform SDK
Windows GDI
Printing and Print Spooler
Printing and Print Spooler Reference
Printing and Print Spooler Structures
PRINTER_INFO_2
PRINTINF.CPY contains the following definitions.

*
* Printer Information Definitions
*
01 PrinterInformation.
02 PI-ServerName Picture X(80).
02 PI-PrinterName Picture X(80).
02 PI-ShareName Picture X(80).
02 PI-PortName Picture X(80).
02 PI-DriverName Picture X(80).
02 PI-Comment Picture X(80).
02 PI-Location Picture X(80).
02 PI-SepFile Picture X(80).
02 PI-PrintProcessor Picture X(80).
02 PI-DataType Picture X(80).
02 PI-Parameters Picture X(80).
02 PI-Attribute.
03 PI-QueuedAttributeValue Picture X.
88 PI-QueuedAttribute Value 'Y' When False 'N'.
03 PI-DirectAttributeValue Picture X.
88 PI-DirectAttribute Value 'Y' When False 'N'.
03 PI-DefaultAttributeValue Picture X.
88 PI-DefaultAttribute Value 'Y' When False 'N'.
03 PI-SharedAttributeValue Picture X.
88 PI-SharedAttribute Value 'Y' When False 'N'.

PRINTINF.CPY
03 PI-NetworkAttributeValue Picture X.
88 PI-NetworkAttribute Value 'Y' When False 'N'.
03 PI-HiddenAttributeValue Picture X.
88 PI-HiddenAttribute Value 'Y' When False 'N'.
03 PI-LocalAttributeValue Picture X.
88 PI-LocalAttribute Value 'Y' When False 'N'.
03 PI-EnableDEVQAttributeValue Picture X.
88 PI-EnableDEVQAttribute Value 'Y' When False 'N'.
03 PI-KeepPrintedAttributeValue Picture X.
88 PI-KeepPrintedJobsAttribute Value 'Y' When False 'N'.
03 PI-DoComplete1stAttributeValue Picture X.
88 PI-DoCompleteFirstAttribute Value 'Y' When False 'N'.
03 PI-WorkOfflineAttributeValue Picture X.
88 PI-WorkOfflineAttribute Value 'Y' When False 'N'.
03 PI-EnableBIDIAttributeValue Picture X.
88 PI-EnableBIDIAttribute Value 'Y' When False 'N'.
02 PI-Priority Picture 9(10) Binary(4).
02 PI-DefaultPriority Picture 9(10) Binary(4).
02 PI-StartTime Picture 9(10) Binary(4).
02 PI-UntilTime Picture 9(10) Binary(4).
02 PI-Status.
03 PI-PausedStatusValue Picture X.
88 PI-PausedStatus Value 'Y' When False 'N'.
03 PI-ErrorStatusValue Picture X.
88 PI-ErrorStatus Value 'Y' When False 'N'.
03 PI-PendingDeletionStatusValue Picture X.
88 PI-PendingDeletionStatus Value 'Y' When False 'N'.
03 PI-PaperJamStatusValue Picture X.
88 PI-PaperJamStatus Value 'Y' When False 'N'.
03 PI-PaperOutStatusValue Picture X.
88 PI-PaperOutStatus Value 'Y' When False 'N'.
03 PI-ManualFeedStatusValue Picture X.
88 PI-ManualFeedStatus Value 'Y' When False 'N'.
03 PI-PaperProblemStatusValue Picture X.
88 PI-PaperProblemStatus Value 'Y' When False 'N'.
03 PI-OfflineStatusValue Picture X.
88 PI-OfflineStatus Value 'Y' When False 'N'.
03 PI-IOActiveStatusValue Picture X.
88 PI-IOActiveStatus Value 'Y' When False 'N'.
03 PI-BusyStatusValue Picture X.
88 PI-BusyStatus Value 'Y' When False 'N'.
03 PI-PrintingStatusValue Picture X.
88 PI-PrintingStatus Value 'Y' When False 'N'.

PRINTINF.CPY
03 PI-OutputBinFullStatusValue Picture X.
88 PI-OutputBinFullStatus Value 'Y' When False 'N'.
03 PI-NotAvailableStatusValue Picture X.
88 PI-NotAvailableStatus Value 'Y' When False 'N'.
03 PI-WaitingStatusValue Picture X.
88 PI-WaitingStatus Value 'Y' When False 'N'.
03 PI-ProcessingStatusValue Picture X.
88 PI-ProcessingStatus Value 'Y' When False 'N'.
03 PI-IntializingStatusValue Picture X.
88 PI-InitializingStatus Value 'Y' When False 'N'.
03 PI-WarmingUpStatusValue Picture X.
88 PI-WarmingUpStatus Value 'Y' When False 'N'.
03 PI-ToneLowStatusValue Picture X.
88 PI-TonerLowStatus Value 'Y' When False 'N'.
03 PI-NoTonerStatusValue Picture X.
88 PI-NoTonerStatus Value 'Y' When False 'N'.
03 PI-PagePuntStatusValue Picture X.
88 PI-PagePuntStatus Value 'Y' When False 'N'.
03 PI-UserInterventionStatusValue Picture X.
88 PI-UserInterventionStatusValue 'Y' When False 'N'.
03 PI-OutOfMemoryStatusValue Picture X.
88 PI-OutOfMemoryStatus Value 'Y' When False 'N'.
03 PI-DoorOpenStatusValue Picture X.
88 PI-DoorOpenStatus Value 'Y' When False 'N'.
03 PI-ServerUnknownStatusValue Picture X.
88 PI-ServerUnknownStatus Value 'Y' When False 'N'.
03 PI-PowerSaveStatusValue Picture X.
88 PI-PowerSaveStatus Value 'Y' When False 'N'.
02 PI-Jobs Picture 9(10) Binary(4).
02 PI-AveragePPM Picture 9(10) Binary(4).
*
*
78 PI-ServerNameParam Value "Server Name".
78 PI-PrinterNameParam Value "Printer Name".
78 PI-ShareNameParam Value "Share Name".
78 PI-PortNameParam Value "Port Name".
78 PI-DriverNameParam Value "Driver Name".
78 PI-CommentParam Value "Comment".
78 PI-LocationParam Value "Location".
78 PI-SepFileParam Value "Sep File".
78 PI-PrintProcessorParam Value "Print Processor".
78 PI-DataTypeParam Value "Data Type".

PRINTINF.CPY
78 PI-ParametersParam Value "Parameters".
78 PI-PriorityParam Value "Priority".
78 PI-DefaultPriorityParam Value "Default Priority".
78 PI-StartTimeParam Value "Start Time".
78 PI-UntilTimeParam Value "Until Time".
78 PI-JobsParam Value "Jobs".
78 PI-AveragePPMParam Value "Average PPM".
TXTMTRIC.CPY
Information regarding the Microsoft Windows TEXTMETRIC structure can be found on
the Internet at http://msdn.microsoft.com/library/. Periodically, Microsoft reorganizes the
requested topic.
Platform SDK
Windows GDI
Fonts and Text
Font and Text Reference
Font and Text Structures
TEXTMETRIC
TXTMTRIC.CPY contains the following definitions.

*
* Text Metric Definitions
*
01 TextMetrics.
02 TM-Height Picture 9(10) Binary(4).
02 TM-Ascent Picture 9(10) Binary(4).
02 TM-Descent Picture 9(10) Binary(4).
02 TM-InternalLeading Picture 9(10) Binary(4).
02 TM-ExternalLeading Picture 9(10) Binary(4).
02 TM-AveCharWidth Picture 9(10) Binary(4).
02 TM-MaxCharWidth Picture 9(10) Binary(4).
02 TM-WeightValue Picture 9(3) Binary(4).
88 TM-WeightIsDontCare Value 0.
88 TM-WeightIsThin Value 100.
88 TM-WeightIsExtraLight Value 200.
88 TM-WeightIsUltraLight Value 200.

TXTMTRIC.CPY
88 TM-WeightIsLight Value 300.
88 TM-WeightIsNormal Value 400.
88 TM-WeightIsRegular Value 400.
88 TM-WeightIsMedium Value 500.
88 TM-WeightIsSemiBold Value 600.
88 TM-WeightIsDemiBold Value 600.
88 TM-WeightIsBold Value 700.
88 TM-WeightIsExtraBold Value 800.
88 TM-WeightIsUltraBold Value 800.
88 TM-WeightIsHeavy Value 900.
88 TM-WeightIsBlack Value 900.
02 TM-Overhang Picture 9(10) Binary(4).
02 TM-DigitizedAspectX Picture 9(10) Binary(4).
02 TM-DigitizedAspectY Picture 9(10) Binary(4).
02 TM-ItalicValue Picture X.
88 TM-Italic Value 'Y' When False 'N'.
02 TM-UnderlinedValue Picture X.
88 TM-Underlined Value 'Y' When False 'N'.
02 TM-StruckOutValue Picture X.
88 TM-StruckOut Value 'Y' When False 'N'.
02 TM-FirstChar Picture X.
02 TM-LastChar Picture X.
02 TM-DefaultChar Picture X.
02 TM-BreakChar Picture X.
02 TM-PitchValue Picture 9 Binary(2).
88 TM-PitchIsFixedPitch Value 1.
88 TM-PitchIsVector Value 2.
88 TM-PitchIsTrueType Value 4.
88 TM-PitchIsDevice Value 8.
02 TM-FamilyValue Picture 9 Binary(2).
88 TM-FamilyIsDontCare Value 0.
88 TM-FamilyIsRoman Value 1.
88 TM-FamilyIsSwiss Value 2.
88 TM-FamilyIsModern Value 3.
88 TM-FamilyIsScript Value 4.
88 TM-FamilyIsDecorative Value 5.
02 TM-CharSetValue Picture 9(3) Binary(2).
88 TM-CharSetIsANSI Value 0.
88 TM-CharSetIsDefault Value 1.
88 TM-CharSetIsSymbol Value 2.
88 TM-CharSetIsMAC Value 77.
88 TM-CharSetIsShiftJIS Value 128.
88 TM-CharSetIsHangeul Value 129.

TXTMTRIC.CPY
88 TM-CharSetIsJohab Value 130.
88 TM-CharSetIsChineseBig5 Value 136.
88 TM-CharSetIsGreek Value 161.
88 TM-CharSetIsTurkish Value 162.
88 TM-CharSetIsHebrew Value 177.
88 TM-CharSetIsArabic Value 178.
88 TM-CharSetIsBaltic Value 186.
88 TM-CharSetIsRussian Value 204.
88 TM-CharSetIsThai Value 222.
88 TM-CharSetIsEastEurope Value 238.
88 TM-CharSetIsOEM Value 255.
*
* Weight Values
*
78 TM-WeightDontCare Value 0.
78 TM-WeightThin Value 100.
78 TM-WeightExtraLight Value 200.
78 TM-WeightUltraLight Value 200.
78 TM-WeightLight Value 300.
78 TM-WeightNormal Value 400.
78 TM-WeightRegular Value 400.
78 TM-WeightMedium Value 500.
78 TM-WeightSemiBold Value 600.
78 TM-WeightDemiBold Value 600.
78 TM-WeightBold Value 700.
78 TM-WeightExtraBold Value 800.
78 TM-WeightUltraBold Value 800.
78 TM-WeightHeavy Value 900.
78 TM-WeightBlack Value 900.
*
* Pitch Values
*
78 TM-PitchFixedPitch Value 1.
78 TM-PitchVector Value 2.
78 TM-PitchTrueType Value 4.
78 TM-PitchDevice Value 8.
*
* Family Values
*
78 TM-FamilyDontCare Value 0.
78 TM-FamilyRoman Value 1.
78 TM-FamilySwiss Value 2.
78 TM-FamilyModern Value 3.

TXTMTRIC.CPY
78 TM-FamilyScript Value 4.
78 TM-FamilyDecorative Value 5.
*
* Character Set Values
*
78 TM-CharSetANSI Value 0.
78 TM-CharSetDefault Value 1.
78 TM-CharSetSymbol Value 2.
78 TM-CharSetMAC Value 77.
78 TM-CharSetShiftJIS Value 128.
78 TM-CharSetHangeul Value 129.
78 TM-CharSetJohab Value 130.
78 TM-CharSetChineseBig5 Value 136.
78 TM-CharSetGreek Value 161.
78 TM-CharSetTurkish Value 162.
78 TM-CharSetHebrew Value 177.
78 TM-CharSetArabic Value 178.
78 TM-CharSetBaltic Value 186.
78 TM-CharSetRussian Value 204.
78 TM-CharSetThai Value 222.
78 TM-CharSetEastEurope Value 238.
78 TM-CharSetOEM Value 255.
*
*
78 TM-HeightParam Value "Height".
78 TM-AscentParam Value "Ascent".
78 TM-DescentParam Value "Descent".
78 TM-InternalLeadingParam Value "Internal Leading".
78 TM-ExternalLeadingParam Value "External Leading".
78 TM-AverageCharacterWidthParam Value "Average Character Width".
78 TM-MaximumCharacterWidthParam Value "Maximum Character Width".
78 TM-WeightParam Value "Weight".
78 TM-OverhangParam Value "Overhang".
78 TM-DigitizedAspectXParam Value "Digitized Aspect X".
78 TM-DigitizedAspectYParam Value "Digitized Aspect Y".
78 TM-FirstCharacterParam Value "First Character".
78 TM-LastCharacterParam Value "Last Character".
78 TM-DefaultCharacterParam Value "Default Character".
78 TM-BreakCharacterParam Value "Break Character".
78 TM-ItalicParam Value "Italic".
78 TM-UnderlinedParam Value "Underlined".
78 TM-StruckOutParam Value "Struck Out".

TXTMTRIC.CPY
78 TM-PitchParam Value "Pitch".
78 TM-FamilyParam Value "Family".
78 TM-CharacterSetParam Value "Character Set".
WINDEFS.CPY
Information regarding the Microsoft Windows PlaySound function and LOGPEN
structure can be found on the Internet at http://msdn.microsoft.com/library/. Periodically,
Microsoft reorganizes the MSDN information on the web site. Use the search capability
to find information on the requested topic.
The following search trees were accurate when this document went to print:
For PlaySound:
Platform SDK
Windows Multimedia
Multimedia Reference
Multimedia Functions
PlaySound
For LOGPEN:
Platform SDK
Windows GDI
Pens
Pen Reference
Pen Structures
LOGPEN
WINDEFS.CPY contains the following definitions.

*
* Miscellaneous Windows Definitions
*
*
* C$PlaySound Options
*
78 SoundSync Value 0.
78 SoundAsync Value 2 ** 0.
78 SoundNoDefault Value 2 ** 1.
78 SoundNoStop Value 2 ** 4.

WINDEFS.CPY
78 SoundPurge Value 2 ** 6.
78 SoundApplication Value 2 ** 7.
78 SoundNoWait Value 2 ** 13.
78 SoundAlias Value 2 ** 16.
78 SoundFilename Value 2 ** 17.
78 SoundAliasId Value (2 ** 16) + (2 ** 20).
*
* Pen Style Values
*
78 PenStyleSolid Value 0.
78 PenStyleDash Value 1.
78 PenStyleDot Value 2.
78 PenStyleDashDot Value 3.
78 PenStyleDashDotDot Value 4.
78 PenStyleNull Value 5.
*
* Position Alignment Argument Values
*
78 PositionIsTop Value "Top".
78 PositionIsBottom Value "Bottom".
*
* Position Mode Argument Values
*
78 ModeIsAbsolute Value "Absolute".
78 ModeIsRelative Value "Relative".
*
* Position Unit Argument Values
*
78 UnitsAreInches Value "Inches".
78 UnitsAreMetric Value "Metric".
78 UnitsAreCharacters Value "Characters".
78 UnitsAreDeviceUnits Value "Device Units".
*
* Yes/No Argument Values
*
78 DrawBoxWithShading Value "Yes".
78 DrawBoxWithoutShading Value "No".
78 DrawBoxNoShading Value "No".
78 TextOutWithBox Value "Yes".
78 TextOutWithoutBox Value "No".
78 TextOutNoBox Value "No".
78 TextOutWithShading Value "Yes".
78 TextOutWithoutShading Value "No".

WINDEFS.CPY
78 TextOutNoShading Value "No".
78 WithBox Value "Yes".
78 WithoutBox Value "No".
78 NoBox Value "No".
78 WithShading Value "Yes".
78 WithoutShading Value "No".
78 NoShading Value "No".
*
* Color Argument Values
*
78 ColorBlack Value "Black".
78 ColorDarkBlue Value "Dark Blue".
78 ColorDarkGreen Value "Dark Green".
78 ColorDarkCyan Value "Dark Cyan".
78 ColorDarkRed Value "Dark Red".
78 ColorDarkMagenta Value "Dark Magenta".
78 ColorBrown Value "Brown".
78 ColorDarkGray Value "Dark Gray".
78 ColorLightGray Value "Light Gray".
78 ColorBlue Value "Blue".
78 ColorGreen Value "Green".
78 ColorCyan Value "Cyan".
78 ColorRed Value "Red".
78 ColorMagenta Value "Magenta".
78 ColorYellow Value "Yellow".
78 ColorWhite Value "White".
*
* Pitch Name Values
*
78 PitchNormal Value "Normal".
78 PitchExpanded Value "Expanded".
78 PitchCompressed Value "Compressed".
Example Code Fragments

The code fragments in this section illustrate the use of P$ subprograms to facilitate
Windows printing program development. Table E-8 provides a quick reference for the
tasks performed in the code fragment examples. These code fragments can be found in
pexample.cbl in the Samples directory.

Note Additional comprehensive examples using P$ subprograms can be found in the
Samples directory. These samples may clarify any remaining questions you might have
about using the P$ subprogram library.
Table E-8 Task Reference List
To See Example
Change a font while printing Changing a Font While Printing (see page E-77)
Change the print orientation Presetting the Print Dialog Box (see page E-75) and
Changing Orientation and Pitch (see page E-79)
Change the pitch of a font Changing Orientation and Pitch (see page E-79)
Change the print resolution Presetting the Print Dialog Box (see page E-75)
Check the return code value Checking the Return Code After Displaying the Print
Dialog Box (see page E-76).
Draw a box around text Drawing a Box Around Text (see page E-73)
Draw a shaded box with colors Drawing Shaded Boxes with Colors (see page E-73)
Draw a box using “relative” Drawing Shaded Boxes with Colors (see page E-73)
positioning
Draw a ruler Drawing a Ruler (see page E-74)
Open three separate printers and Opening and Writing to Separate Printers (see
write to each one page E-80
Print text at corners of a page Printing Text at the Corners of a Page (see page E-82)
Print text at the top of a page Printing Text at the Top of a Page (see page E-81)
Print a bitmap file Printing a Bitmap (see page E-77)
Print multiple copies Presetting the Print Dialog Box (see page E-75)
Print multiple text outputs on the Using the COBOL WRITE Statement to Print Multiple
same line Text Outputs on the Same Line (see page E-78)
Print a word in italics Using the COBOL WRITE Statement to Print Multiple
Text Outputs on the Same Line (see page E-78)
Print a word in boldface type Using the COBOL WRITE Statement to Print Multiple
Print a word underlined Using the COBOL WRITE Statement to Print Multiple
Print a watermark Printing a Watermark (see page E-73)
Set the point size for a font Setting the Point Size for a Font (see page E-83)
Set text position Setting Text Position (see page E-84)

Printing a Watermark
The following code fragment illustrates printing a watermark diagonally across a page.
The font is set to a large point size with a 45-degree angle (Escapement). The color is set
to a light gray, and the text is positioned with metric measurements.
CALL "P$SETFONT" USING LF-HeightParam 500, LF-EscapementParam, 450.

CALL "P$SETTEXTCOLOR" USING ColorLightGray.
CALL "P$TEXTOUT" USING "Example", 5.08, 17.78, "Absolute", "Metric".
Drawing Shaded Boxes with Colors

The following code fragment illustrates drawing two boxes. The first box is drawn with
a thick pen, shaded with ten-percent gray, positioned at 2,2 inches on the page, and is
one-inch square. The second box is positioned using “relative” positioning so that the
lower-right corner of the first box is connected to the upper-left corner of the second box.
It is drawn with a thin, dashed red line, no shading, and is 1.5-inches square.
CALL "P$SETPEN" USING PenStyleSolid, 5.

CALL "P$SETBOXSHADE" USING ColorBlack, 10.
CALL "P$DRAWBOX" USING 2.00, 2.00, "Absolute", "Inches",
1.00, 1.00, "Inches", WithShading.
CALL "P$SETPEN" USING PenStyleDash, 1, ColorRed.
CALL "P$DRAWBOX" USING 0, 0, "Relative", "Inches",
1.50, 1.50, "Inches".
Drawing a Box Around Text

The following code fragment illustrates drawing a box centered around a line of text. The
box allows one-half the average character width of the current font before and after the
text. The top of the box is positioned at the top alignment of the current font. The height
of the box is the height of the current font plus external leading.
CALL "P$GETTEXTMETRICS" Using TextMetrics.

CALL "P$SETPOSITION" USING 0.5, 5.50, "Absolute", "Inches".
CALL "P$GETTEXTPOSITION" USING X-POS, Y-POS, "Top", "Device-Units".
CALL "P$GETTEXTEXTENT" USING "AAaaGGggYYyyTTttH",
WIDTH, HEIGHT, "Device-Units".
COMPUTE X-POS = X-POS - (TM-AveCharWidth / 2).
COMPUTE WIDTH = WIDTH + TM-AveCharWidth.
COMPUTE HEIGHT = TM-ExternalLeading + TM-Height.
CALL "P$DRAWBOX" USING X-POS, Y-POS, "Absolute", "Device-Units",
WIDTH, HEIGHT, "Device-Units".
CALL "P$TEXTOUT" USING "AAaaGGggYYyyTTttH",
0.5, 5.50, "Absolute", "Inches".

The following code fragment performs the same task as the previous part of this example,
but allows the runtime to compute the size and position of the box as well as draw the
box. For top, bottom, left, and right margins, the box allows one-quarter the average
character width of the current font.
CALL "P$TEXTOUT" USING "AAaaGGggYYyyTTttH", 0.5, 6.00,

"Absolute", "Inches", WithBox.
Drawing a Ruler
The following code fragment draws a 5-centimeter ruler.
Centimeter-Ruler.
MOVE 0.0 TO WS-X, WS-Y, WS-Y2.
MOVE 5.0 TO WS-X2.
MOVE 0 to WS-CENT-COUNT.
CALL "P$SETDEFAULTUNITS" USING "Metric".
*Draw a Line 5 Centimeters Long.

CALL "P$DRAWLINE" USING WS-X, WS-Y, "Absolute", "Metric",
WS-X2, WS-Y2.
PERFORM VARYING WS-X FROM 0 BY 0.1 UNTIL WS-X > 5
EVALUATE TRUE
WHEN WS-CENT-COUNT = 5
MOVE .4 TO WS-Y
WHEN WS-CENT-COUNT = 10 OR 0
MOVE .7 TO WS-y
WHEN OTHER
MOVE .2 TO WS-Y
END-EVALUATE
CALL "P$MOVETO" USING WS-X, WS-Y
CALL "P$LINETO" USING WS-X, WS-Y2
IF WS-CENT-COUNT = 10
MOVE 1 TO WS-CENT-COUNT
ELSE
ADD 1 TO WS-CENT-COUNT
END-IF
END-PERFORM.

Presetting the Print Dialog Box
The following code fragment causes two copies of the output to be printed with high
resolution. The orientation of the print will be in landscape mode. When the Windows
Print dialog box appears, the All Pages option button will be selected, the Page Numbers
option button and associated edit control will be disabled, the Selection button will be
disabled, and the Print to File check box will be hidden.
Note The example code fragment shown below sets the collate flag to false, that is,
printed pages will not be collated. Some printers do not support printing multiple
copies with the pages collated. For more information, see “Printing Multiple Copies”
on page E-13.
INITIALIZE PrintDialog.
CALL "P$CLEARDIALOG".
SET PD-AllPagesFlag TO TRUE. *>Sets All Pages
*>option on
SET PD-NoPageNumbersFlag TO TRUE. *>Disable Pages
*>option button and
*>associated edit
*>controls
SET PD-NoSelectionFlag TO TRUE. *>Disables Selection
*>button
SET PD-CollateFlag TO FALSE. *>Don’t check Collate
*>check box
SET PD-HidePrintToFileFlag TO TRUE. *>Hides Print To File
*>checkbox
SET DM-CopiesField TO TRUE.
MOVE 2 TO DM-Copies.
SET DM-OrientationField TO TRUE.
SET DM-OrientationIsLandscape TO TRUE.
SET DM-PrintQualityField TO TRUE.
SET DM-ResolutionIsHigh TO TRUE.
CALL "P$SETDIALOG" USING PrintDialog.
OPEN OUTPUT PFILE.
WRITE FD-RECORD FROM
"Example 5: Presetting the Printer Dialog Box Page 1"
AFTER PAGE.
"Example 5: Text After CALLING P$SETDIALOG".
"Example 5: This should be printed in landscape mode.".
"Example 5: There should be two copies printed.".
CLOSE PFILE.

Checking the Return Code After Displaying the Print Dialog
Box
The following code fragment will set the printer device, display the Windows Print dialog
box, and check the return code value. If the value is zero, the user pressed the OK button.
If the value is 1, the user pressed the Cancel button or closed the dialog box. If the value
is 2, an error occurred while displaying the dialog box and the error code is checked by
making a call to P$GetDialog.
Set PD-NoWarningFlag To True.
CALL "P$SetDialog" Using DM-DeviceNameParam, DM-DeviceName.
CALL "P$DisplayDialog" Giving Dialog-Return.
Evaluate True
When Dialog-OK *> Value zero
Display "OK Button Pressed" Line 13 Col 1
Perform Open-Printer-Para
When Dialog-Cancel *> Value one
Display "Cancel Button Pressed" Line 13 Col 1
Perform Printer-Canceled-Para
When Dialog-Error *> Value two
Display "Error in Dialog" Line 13 Col 1
Perform Printer-Error-Para
When Other *> Value other
Display "Invalid Value: " Line 13 Col 1 Dialog-Return
End-Evaluate.
STOP RUN.
Open-Printer-Para.
Open Output Printer-File.
Write Fd-Record From
"Checking the Printer Dialog Box " After Page.
Close Pfile.
Printer-Canceled-Para.
Display "Printer Dialog Canceled" Line 22 Col 3 Reverse Erase Eol.
Printer-Error-Para.
CALL "P$GetDialog" Using PD-ExtendedErrorParam,
PD-ExtendedErrorValue,
Validity-Flag.
If PD-ExtErrIsPrinterNotFound
Display "Printer Not Found!" Line 22 Col 3 Reverse
Erase Eol
Else
Display "Printer Dialog Had Error" Line 22 Col 3 Reverse
PD-ExtendedErrorValue Convert
Erase Eol
End-If.

Printing a Bitmap
The following code fragment prints a bitmap at location 2,2 (inches). The bitmap will be
two inches wide, and the height will be scaled to match the original width/height ratio.
CALL "P$DRAWBITMAP" USING "rmlogo.bmp", 2, 2, "Absolute",

"Inches", 2, 0, "Inches".
Changing a Font While Printing

The following code fragment prints the text, "Original FONT" in the current font, then
switches to Monotype Corsiva and prints the text, "Monotype Corsiva FONT Italic".
CALL "P$TEXTOUT" USING "Original FONT", 0.5, 3.50, "Absolute",

"Inches".
CALL "P$SETFONT" USING LF-FaceNameParam, "Monotype Corsiva",
LF-ItalicParam, "Y".
CALL "P$TEXTOUT" USING "Monotype Corsiva FONT Italic", 0.5,
4.50, "Absolute", "Inches".

Using the COBOL WRITE Statement to Print Multiple Text
Outputs on the Same Line
The following code fragment causes multiple outputs to appear on a single line. The
COBOL WRITE statement is used with the ADVANCING phrase and the
P$SetLineExtendMode subprogram to produce the following line of text:
Printing a word in Italic, Underline, or Bold on the same line is no problem with RM/COBOL.
INITIALIZE LogicalFont.
CALL "P$SETFONT" USING LF-HeightParam 50,
LF-WeightParam 10,
LF-FaceNameParam "Arial".
WRITE PRINT-RECORD FROM "Printing a word in".
CALL "P$SETLINEEXTENDMODE" USING 1, "Characters".
CALL "P$SETFONT" USING LF-ItalicParam, "Y".
WRITE PRINT-RECORD FROM "Italic", AFTER ADVANCING ZERO.
CALL "P$SETFONT" USING LF-ItalicParam, "N", LF-UnderlineParam, "Y".
WRITE FD-RECORD FROM "Underline," AFTER ADVANCING ZERO.
CALL "P$SETFONT" USING LF-WeightParam, LF-WeightBold,
LF-UnderlineParam, "N".
WRITE PRINT-RECORD FROM "or Bold" AFTER ADVANCING ZERO.
CALL "P$SETFONT" USING LF-WeightParam, LF-WeightNormal.
WRITE PRINT-RECORD FROM
"on the same line is no problem with RM/COBOL."
AFTER ADVANCING ZERO.

Changing Orientation and Pitch
The following code fragment demonstrates how to change the print orientation from
portrait to landscape and how to change the font pitch from normal to compressed.
CALL "P$TEXTOUT" USING "This is Orientation Portrait Normal

Pitch" 0, 1.50, "Absolute", "Inches".
CALL "P$SETPITCH" USING PitchCompressed.
CALL "P$CHANGEDEVICEMODES" USING DM-OrientationParam,
DM-OrientationLandscape.
WRITE FD-RECORD FROM SPACES AFTER PAGE.
CALL "P$TEXTOUT" USING
"This is printed with the Orientation
"Landscape with a Compressed Type Size",
0, 1.50, "Absolute”, “Inches".
CALL "P$SETPITCH" USING PitchNormal.
CALL "P$CHANGEDEVICEMODES" USING DM-OrientationParam,

DM-OrientationPortrait.
WRITE FD-RECORD FROM SPACES AFTER PAGE.
CALL "P$TEXTOUT" USING
"This is back to Portrait using the Normal Pitch Size",
0, 1.50, "Absolute", "Inches".

Opening and Writing to Separate Printers
The following code fragment demonstrates how to open three separate printers and write
to each one.
OPEN OUTPUT PFILE1.

CALL "P$GETHANDLE" USING HANDLE-1.
CALL "P$ENABLEDIALOG".
OPEN OUTPUT PFILE2.
CALL "P$ENABLEDIALOG".
OPEN OUTPUT PFILE3.
CALL "P$SETHANDLE" USING HANDLE-3.

CALL "P$TEXTOUT" USING "Text written to PRINTER 3".


CLOSE PFILE1, PFILE2, PFILE3.

Printing Text at the Top of a Page
The following code fragment demonstrates how to position and print text at the top center
of the page.
CALL "P$GetDeviceCapabilities" Using DC-HorizontalSizeParam,

DC-HorzSize.
CALL "P$GetTextExtent" Using "Top Center",
Ws-Text-Width,
Ws-Text-Height,
UnitsAreMetric.
* Divide by 10 to convert millimeters to centimeters.
Compute Ws-X-M = ((DC-HorzSize / 10) / 2) - (Ws-Text-Width / 2).
Move Zero to Ws-Y-M.
CALL "P$SetTextPosition" USING Ws-X-M, Ws-Y-M,
PositionIsTop,
ModeIsAbsolute,
UnitsAreMetric.
CALL "P$TextOut" Using "Top Center".

Printing Text at the Corners of a Page
The following code fragment demonstrates how to position and print text at the top left
corner and bottom right corner of the page.
* Position Text Top Left.

CALL "P$SetTextPosition" Using 0, 0,
PositionIsTop,
ModeIsAbsolute,
UnitsAreDeviceUnits.
CALL "P$TextOut" Using "Top Left".
* Position Text Bottom Right.

CALL "P$GetTextExtent" Using "Bottom Right",
Ws-Text-Width,
Ws-Text-Height,
UnitsAreMetric.
CALL "P$GetDeviceCapabilities" Using DC-HorizontalSizeParam,

DC-HorzSize,
DC-VerticalSizeParam,
DC-VertSize.
* Divide by 10 to convert millimeters to centimeters.

Compute Ws-X-M = (DC-HorzSize / 10) - Ws-Text-Width.
Compute Ws-Y-M = (DC-VertSize / 10).
CALL "P$SetTextPosition" Using Ws-X-M, Ws-Y-M,
PositionIsBottom,
ModeIsAbsolute,
UnitsAreMetric.
CALL "P$TextOut" Using "Bottom Right".

Setting the Point Size for a Font
The following code fragment demonstrates how to set the point size for a specified font.
Open Output PrintFile.

CALL "P$GetDeviceCapabilities" Using DC-LogicalPixelsYParam,
DC-LogPixelsY.
* Compute Font Height for desired Point-Size.

* If Point-Size is 72, this produces a 1-inch high font, including
* Internal Leading.
Compute LF-Height Rounded = (Point-Size * Dc-LogPixelsY) / 72.
Move "Times New Roman" To LF-FaceName.

CALL "P$SetFont" Using LF-FaceNameParam, LF-FaceName,
LF-HeightParam, LF-Height.
CALL "P$GetTextMetrics" Using TextMetrics.
* Add bias for Internal Leading.

* If Point-Size is 72, this adjustment produces a 1-inch high font
* excluding Internal Leading.
Compute LF-Height = (LF-Height * TM-Height) /
(TM-Height - TM-InternalLeading).
* Set Font with computed LF-Height

CALL "P$SetFont" Using LF-HeightParam, LF-Height.
Write Printer-Record from "Greetings" After Advancing 1.

Setting Text Position
The following code fragment will print large "Greetings" followed by three smaller
"Greetings" positioned by top alignment, base line alignment and bottom alignment.
* Print initial Greetings in a Large Font Size.

CALL "P$SetFont" Using LF-HeightParam, 330.
CALL "P$TextOut" Using "Greetings", 0.25, 2,
ModeIsAbsolute,
UnitsAreInches.
* Get the Top Text Position.
CALL "P$GetTextPosition" Using Ws-X-D, Ws-Top,
PositionIsTop,
* Get the Bottom Text Position.
CALL "P$GetTextPosition" Using Ws-XB-D, Ws-Bottom,
PositionIsBottom,
* Get the Base Line Position.
CALL "P$GetPosition" Using Ws-XP-D, Ws-Base,
CALL "P$SetFont" Using LF-HeightParam, 50.
* Set the Top Text Position and print, get next X Position.
CALL "P$SetTextPosition" Using Ws-X-D, Ws-Top,
PositionIsTop,
ModeIsAbsolute,
CALL "P$TextOut" Using "Greetings".
CALL "P$GetPosition" Using Ws-X-D, Ws-Dummy,
* Set the Base Line Position and print, get next X Position.
CALL "P$SetPosition" Using Ws-X-D, Ws-Base,
ModeIsAbsolute,
CALL "P$GetPosition" Using Ws-X-D, Ws-Dummy,
* Set the Bottom Position and print.
CALL "P$SetTextPosition" Using Ws-X-D, Ws-Bottom,
PositionIsBottom,
ModeIsAbsolute,

RM/COBOL-Specific Escape Sequences
The typical COBOL application written for Windows makes use of the various Windows
printer drivers to control printing functions. Many legacy COBOL programs, however,
contain embedded or programmatic escape sequences and thus cannot take advantage of
Windows printer drivers. To accommodate these programs, the RM/COBOL runtime has
been enhanced to implement a set of RM/COBOL-specific escape sequences to control
printing. These escape sequences, which are similar to the Hewlett Packard PCL (Print
Command Language) commands, are then mapped by the runtime to the correct printer
driver GDI (Graphics Device Interface) calls to accomplish the desired function.
Table E-9 lists the available printing functions and their escape sequences and options.
The “Options” column of the table describes the permissible values for certain variables
in an escape sequence that are represented by the characters #, ##, or ###. These
variables are always binary values, that is, they are not ASCII characters representing
the values.
Table E-9 RM/COBOL-Specific Escape Sequences
Options
Function ASCII Decimal Hex (#, ##, or ###)
Reset <Esc>E 027 069 1B 45 Clears the margins, clears line
spacing, clears line extend mode,
resets text length, sets
page orientation back to portrait,
sets paper source back to
DMBIN_ONLYONE, and sets the
font back to default font.
Left <Esc>&a#L 027 038 097 ### 1B 26 61 ## Size of left margin, in characters
Margin 076 4C (calculated using current font).
Set Tab <Esc>&k#H 027 038 107 ### 1B 26 6B ## Horizontal increment in characters
Stops 072 48 (calculated using current font).
Line <Esc>&l#D 027 038 108 ### 1B 26 6C ## Lines per inch.
Spacing 068 44
Top Margin <Esc>&l#E 027 038 108 ### 1B 26 6C ## Size of top margin, in lines
069 45 (calculated using current font).
Text <Esc>&l#F 027 038 108 ### 1B 26 6C ## Length of page, in lines (calculated
Length 070 46 using current font).

Table E-9 RM/COBOL-Specific Escape Sequences (Cont.)
Options
Function ASCII Decimal Hex (#, ### or ##)
Paper <Esc>&l#H 027 038 108 ### 1B 26 6C ## 1 - DMBIN_ONLYONE
Source 072 48 2 - DMBIN_LOWER
3 - DMBIN_MIDDLE
4 - DMBIN_MANUAL
5 - DMBIN_ENVELOPE
6 - DMBIN_ENVMANUAL
7 - DMBIN_AUTO
8 - DMBIN_TRACTOR
9 - DMBIN_SMALLFMT
10 - DMBIN_LARGEFMT
11 - DMBIN_LARGECAPACITY
14 - DMBIN_CASSETTE
15 - DMBIN_FORMSOURCE
Orientation <Esc>&l#O 027 038 108 ### 1B 26 6c ## 0 - Portrait
079 4F 1 - Landscape
Print Pitch <Esc>(s#H 027 040 115 ### 1B 28 73 ## Characters per horizontal inch.
072 48
Style <Esc>(s#S 027 040 115 ### 1B 28 73 ## 0 - Normal
083 53 1 - Italic
2 - Bold
4 - Underline
8 - Compressed
16 - Expanded
Font Height <Esc>(s#V 027 040 115 ### 1B 28 73 ## Characters per vertical inch.
086 56
Clear <Esc>9 027 057 1B 39 Clear left and top margin.
Margins
Null <NUL> 000 00 See Note below.*
Horizontal <HT> 009 09 Position to next tab stop.
Tab
Shift Out <SO> 014 0E Shifts normal font to expanded
font. Shifts compressed font to
normal. Stays in effect until start
of new line.
Shift In <SI> 015 0F Shifts normal font to compressed
font. Shifts expanded font to
normal font. Stays in effect until
start of new line.
Note RM/COBOL normally changes nulls to spaces before sending them to the printer.
This behavior may be changed by setting the property “Printer Enable Null Esc. Seq.”
value to Yes.

Appendix F: Subprogram Library
This appendix describes the subprograms that are supplied with the RM/COBOL runtime
system. It also describes the required RM/COBOL calling sequence and the USING list
parameters. Failure to comply with the USING list requirements will halt the run unit
with a STOP RUN indication at the line containing the incorrect CALL statement.
Note Subprogram names are case insensitive. For readability, mixed case is used in this
document when subprogram names are lengthy. Uppercase letters are used for short
subprogram names, in calling sequences, and in code fragments.
Subprogram Library
Table F-1 lists the subprograms alphabetically and gives a brief description.
Table F-1 RM/COBOL Subprogram Library
Subprogram Function
C$Bitmap Sets the name of a bitmap file for a program.
C$BTRV Calls Btrieve directly from an RM/COBOL program.
C$CARG Returns information about a passed argument.
C$Century Facilitates updating RM/COBOL programs to handle the
year 2000.
C$ClearDevelopmentMode Disables expanded error information reporting (known as
“development mode”) for many of the C$ and P$
subprograms.
C$Delay Relinquishes the CPU for a specified length of time.
C$Forget Marks an area of the runtime system’s in-memory screen
image as unknown.
C$GetEnv Retrieves environment variables.
C$GetLastFileName Retrieves the last file used in a COBOL I/O statement.
C$GetLastFileOp Retrieves information about the last COBOL I/O operation.
C$GetRMInfo Retrieves RM/COBOL runtime system information.
C$GetSyn Retrieves the values of RM/COBOL synonyms from the
Windows registry file.
C$GetSysInfo Retrieves operating system information
RM/COBOL User's Guide for 32-Bit Windows F-1

Subprogram Library
Table F-1 RM/COBOL Subprogram Library (Cont.)
Subprogram Function
C$GUICFG Changes the RM/COBOL graphical user interface (GUI)
properties.
C$MBar Sets the menu bar for a program.
C$MemoryAllocate Allocates dynamic memory.
C$MemoryDeallocate Deallocates (frees) dynamic memory.
C$NARG Returns the number of arguments passed to the called
subprogram.
C$OSLockInfo Returns the process ID of the process that performed the last
lock operation.
C$PlaySound Plays Windows predefined sound events or sound files.
C$RBMenu Sets the pop-up menu for a program that is displayed when
the right mouse button is pressed.
C$RERR Returns expanded completion status for the last I/O
operation.
C$SBar Sets the status bar for a program.
C$SCRD Allows the contents of the screen to be read into an
alphanumeric data item.
C$SCWR Allows the quick display of a large amount of screen data
containing various attributes.
C$SetDevelopmentMode Enables expanded error information reporting (known as
“development mode”) for many of the C$ and P$
subprograms.
C$SetEnv Sets environment variables.
C$SetSyn Sets the values of RM/COBOL synonyms in the Windows
registry file.
C$Show Sets the show state of the main RM/COBOL window.
C$ShowArgs Displays the list of arguments used to call C$ShowArgs.
C$TBar Sets the toolbar for a program.
C$TBarEn Enables and disables buttons on the toolbar.
C$TBarSeq Sets the bitmap sequence of buttons on the toolbar.
C$Title Sets the title displayed for the RM/COBOL window.
C$WRU Returns the location from which a subprogram was called.
SYSTEM Allows an arbitrary operating system command to be
executed.
F-2 Subprogram Library

Subprogram Library
C$Bitmap
C$Bitmap is used to display a bitmap file on the RM/COBOL window.
To use this subprogram, the runtime system must be able to locate the c$bitmap.dll file.
The following example illustrates how to add this DLL to the Runtime Command line
with the L Option:
runcobol program-name L=C$BITMAP.DLL
Other Runtime Command Options can be used (see Chapter 7, Running).
Note This subprogram is supported only under Windows.
Calling Sequence
CALL "C$BITMAP" USING filename
filename is an alphanumeric data item that contains the name of an existing Windows
bitmap (.bmp) file. The file will be located using the runtime system search path.
C$BTRV
C$BTRV is used to call Btrieve directly from an RM/COBOL program.
To use this subprogram, the runtime system must be able to locate the c$btrv.dll file. In
addition, Btrieve, available from Pervasive Software, must be installed on the computer.
Note This subprogram is supported only under 32-bit Windows.
Calling Sequence
CALL "C$BTRV" USING o p c o d e , status, position-block,

data-buffer, buffer-length, key-buffer, k e y - n u m b e r
opcode is any unsigned numeric data item that contains the desired Btrieve operation
code value.

C$Bitmap
status is any signed numeric data item that receives the Btrieve status code result of
the operation.
position-block is a 128-byte alphanumeric data item that is used by many of the
Btrieve operations and should not be modified by the COBOL program.
data-buffer is an alphanumeric data item that contains the data associated with the
Btrieve operation. The contents may be input and/or output depending upon the
given Btrieve operation.
buffer-length is any unsigned numeric data item that contains the length of the data in
the data buffer. This value may be input and/or output depending upon the given
Btrieve operation.
key-buffer is a 256-byte alphanumeric data item that contains the key value
associated with the Btrieve operation. The contents may be input and/or output
depending upon the given Btrieve operation.
key-number is any signed numeric data item into which the key number or special
option value is stored depending upon the given Btrieve operation.
Note This subprogram uses the CodeBridge parameter conversion facility for the four
numeric arguments to allow maximum flexibility in their definition. See the CodeBridge
documentation for more details.
Examples
The following is a typical DATA DIVISION description of the arguments (the data buffer
item can be any size that is appropriate for the operation being performed):
01 B-OPCODE PIC 9(5).

01 B-STATUS PIC S9(5).
01 B-POSITION-BLOCK PIC X(128).
01 B-DATA-BUFFER PIC X(10000).
01 B-BUFFER-LENGTH PIC 9(5).
01 B-KEY-BUFFER PIC X(256).
01 B-KEY-NUMBER PIC S9(3).
The following is a typical PROCEDURE DIVISION call of C$BTRV using the

arguments described above:
CALL "C$BTRV" USING B-OPCODE, B-STATUS, B-POSITION-BLOCK,

B-DATA-BUFFER, B-BUFFER-LENGTH,
B-KEY-BUFFER, B-KEY-NUMBER.
Refer to your Btrieve Programmer’s Manual for a complete description of the parameters
sent from and returned to the application for each Btrieve operation.

C$BTRV
The following specific example, using the Btrieve Version (26) operation, also will work:
01 B-OP-VERSION PIC 99 VALUE 26.

01 B-STATUS PIC S9(5) SIGN LEADING SEPARATE.
01 B-POSITION-BLOCK PIC X(128).
01 B-VERSION-BUFFER PIC X(30).
01 B-VER-BUF-LEN PIC 99 VALUE 30.
01 B-KEY-BUFFER PIC X(256)
VALUE "\\RM1\VOL2\USERS\BTRV.FIL".
01 B-KEY-NUMBER PIC S9 VALUE 0.
CALL "C$BTRV" USING B-OP-VERSION, B-STATUS, B-POSITION-BLOCK,

B-VERSION-BUFFER, B-VER-BUF-LEN,
B-KEY-BUFFER, B-KEY-NUMBER.
C$CARG
C$CARG returns information about the actual parameter that corresponds to a formal
parameter in the USING or GIVING phrases in the Procedure Division header of a
subprogram. This information identifies the type and length of the argument and, when
the argument is numeric, the number of digits and scale factor for the argument.
Calling Sequence
CALL "C$CARG" USING okay, a r g u m e n t - n a m e ,

argument-description
okay is a one-character alphanumeric data item into which the ASCII character Y is
stored if C$CARG successfully identifies the argument named by argument-name;
otherwise, the ASCII character N is stored in the data item.
argument-name is the name of a Linkage Section data item named in the Procedure
Division header USING list.

C$CARG
argument-description is a ten-character group data item into which the
desired information about argument-name is stored. A typical description for
argument-description is as follows:
01 ARGUMENT-DESCRIPTION BINARY(2).
02 ARGUMENT-TYPE PIC 9(2).
02 ARGUMENT-LENGTH PIC 9(8) BINARY(4).
02 ARGUMENT-DIGIT-COUNT PIC 9(2).
02 ARGUMENT-SCALE PIC S9(2).
Note The argument-description group item will only have the correct length if
ARGUMENT-TYPE, ARGUMENT-DIGIT-COUNT, and ARGUMENT-SCALE
are allocated as two-byte binary and ARGUMENT-LENGTH is allocated as
four-byte binary. Use of the BINARY-ALLOCATION compiler configuration
keyword (see page 10-6) can change the allocation of binary numeric data items such
that this requirement is not met. For example, if BINARY-ALLOCATION=RM1,
the default allocation for a data item described with PIC 9(2) is one byte. The
example shown specifies a binary allocation override for each binary item to
guarantee the right allocation regardless of the configured binary allocation scheme.
The binary allocation override is not necessary if BINARY-ALLOCATION=RM.
The binary allocation override would also not be necessary for binary allocation
schemes RM1 and MF-RM if all three 9(2) entries were changed to 9(3) entries.
A description of the values that may be stored in ARGUMENT-TYPE is found in

Table D-1 on page D-16. The number of character positions occupied by
ARGUMENT-NAME is stored in ARGUMENT-LENGTH. If ARGUMENT-TYPE
indicates that ARGUMENT-NAME is a nonedited numeric data item, the number of
digits defined in the picture character-string for the data item is stored in
ARGUMENT-DIGIT-COUNT and the power of 10 scale factor (that is, the position of
the implied decimal point) is stored in ARGUMENT-SCALE.
Note If a calling program passes a called program two arguments that begin at the same
location (either through redefinition, with reference modification, or because one is a
group that contains the other), when the called program asks C$CARG for the parameter
descriptions, it always receives that of the first actual argument passed.

C$CARG
C$Century
C$Century facilitates updating RM/COBOL programs to handle the year 2000 issue. It
retrieves the first two digits of the current year. For example, for the year 1999, it will
return 19; for the year 2000, it will return 20.
Note A number of changes have been made to the Format 2 ACCEPT statement related
to improving the way dates and times are handled. These changes provide additional
ways of writing Y2K-compliant COBOL. New phrases include CENTURY-DATE,
CENTURY-DAY, DATE-AND-TIME, and DAY-AND-TIME. See the RM/COBOL
Language Reference Manual for more information.
Calling Sequence
CALL "C$CENTURY" USING value-buffer
value-buffer is a data item with a format of either unsigned numeric display (NSU) or
alphanumeric display (ANS).
C$ClearDevelopmentMode
C$ClearDevelopmentMode is used to disable expanded error information reporting
(known as “development mode”) for many of the C$ and P$ subprograms. (The P$
subprograms are discussed in Appendix E, Windows Printing.) When development mode
is enabled (see “C$SetDevelopmentMode” on page F-33), more verbose error reporting is
performed to assist the COBOL developer in implementing these subprogram calls.
Calling Sequence
CALL "C$CLEARDEVELOPMENTMODE"

C$Century
C$Delay
C$Delay is used to relinquish the CPU for a length of time specified in seconds. Calling
C$Delay will allow other programs to run while the original program waits. The amount
of delay is not exact. It depends upon the particular machine configuration and the load
on the machine.
Calling Sequence
CALL "C$DELAY" USING s e c o n d s
seconds is a PICTURE 9(n) BINARY, where n can be a digit from 1 to 9. It

specifies the length of time, in seconds, to delay. Delays longer than one day are not
normally meaningful and should not be used.
C$Forget
C$Forget marks an area of the runtime system’s in-memory screen image as unknown.
The next COBOL output to the unknown area will not be optimized based on the screen
contents. This allows COBOL output to be displayed correctly over linked C subprogram
output, which is not stored in the in-memory screen image.
Note This subprogram is supported only under UNIX.
Calling Sequence
CALL "C$FORGET" [USING u pper-left-line, upper-left-position,

lower-right-line lower-right-position ]
upper-left-line and upper-left-position are optional, three-digit, COMP-4 (BINARY)

data items that describe the upper-left corner of the area of the screen to be marked as
unknown. Valid values range from 0 to the limit of the screen line or position.
lower-right-line and lower-right-position are optional, three-digit, COMP-4
(BINARY) data items that describe the lower-right corner of the area of the screen
to be marked as unknown. Valid values range from 0 to the limit of the screen line
or position.

C$Delay
If you call C$Forget with no parameters, the entire screen is marked as unknown. The
same result can be achieved by passing parameters with a value of 0. When a pop-up
window is displayed and then removed over an unknown area, the original screen contents
are replaced with spaces, except for the pop-up window borders and titles, which are not
stored in the in-memory screen image.
Linked C subprograms also can use C$Forget by calling RmForget() with four int
parameters specifying the area to be marked as unknown. (See the section “C Entry
Points For COBOL Functions” on page D-23 in Appendix D, Customizing RM/COBOL
for UNIX.)
C$GetEnv
C$GetEnv is used to retrieve the values of environment variables.
Calling Sequence
CALL "C$GETENV" USING n a m e , value [, return ]
name is an alphanumeric data item that contains the name of the environment
variable to retrieve.
value is an alphanumeric data item that contains the value of the environment
variable upon return from the call.
return is a PICTURE 9(n) BINARY, where n can be a digit from 1 to 9. It is set to 0
if the call was successful and non-zero if it failed.

C$GetEnv
C$GetLastFileName
C$GetLastFileName is used to retrieve the last file-name and pathname used in a COBOL
I-O statement (including OPEN and CLOSE).
Calling Sequence
CALL "C$GETLASTFILENAME" USING filename [, p a t h n a m e ]
filename is an alphanumeric data item that will contain the COBOL file-name
specified in the most recently executed I-O statement. For REWRITE and WRITE
statements, the COBOL file-name associated with the specified file record-name is
provided. The alphanumeric data item should be 30 characters long. If the COBOL
file-name is longer than the length of the data item, it will be truncated on the right.
pathname is an alphanumeric data item that will contain the name of the last used
pathname (complete file-name). The value SPACES indicates that no name is
available (the last file used in an I/O operation was probably closed or no file has
been opened). The alphanumeric data item should be at least 64 characters long. If
the complete file access name is longer than the length of the data item, it will be
truncated on the right.
C$GetLastFileOp
C$GetLastFileOp is used to retrieve information about the last COBOL I/O operation
performed. The function returns the COBOL operation performed, and the line number
and the intraline number where the operation was done. The intended use of this library
subprogram is within a declarative procedure after an I/O error has occurred.
Calling Sequence
CALL "C$GETLASTFILEOP" USING operation

[, prog-line [, prog-intraline ]]
operation is an alphanumeric data item that will contain the name of the last COBOL
I/O operation performed (see the list below for possible values). The value SPACES
indicates that no operation is available (the file was probably never opened). The

C$GetLastFileName
alphanumeric data item should be 20 characters long. If the operation value is longer
than the length of the data item, it will be truncated on the right.
• “Close” • “ReadRandom”
• “CloseUnit” • “Rewrite”
• “Delete” • “RewriteRandom”
• “DeleteFile”” • “Start”
• “DeleteRandom” • “Unlock”
• “Open” • “Write”
• “ReadNext” • “WriteRandom”
• “ReadPrevious”
prog-line is a BINARY data item with the picture PIC 9(6), which will contain the
line number of the most recent COBOL I/O operation. If the program that contains
the I/O operation was compiled with the Q Compile Command Option (see Chapter
6, Compiling), the value stored in prog-line is the segment offset of the statement.
Use the values from the Debug heading of the program listing to locate the statement.
prog-intraline is a BINARY data item with the picture PIC 9(2), which will contain
the intraline number of the I/O operation. See page 9-3 for a description of Debug
line and intraline numbers. If the program that contains the I/O operation was
compiled with the Q Option, the value stored in prog-intraline is zero.
Note The PROGRAM-ID special register may be used to obtain the program-name
of the COBOL program that performed the COBOL I/O operation. For more
information about the PROGRAM-ID special register, see Chapter 1, Language
Structure, of the RM/COBOL Language Reference Manual.
C$GetRMInfo
C$GetRMInfo is used to retrieve information about the RM/COBOL runtime system.
Calling Sequence
CALL "C$GETRMINFO" USING R M I n f o G r o u p

C$GetRMInfo
RMInfoGroup is a group data item as defined in the following copy file,
RMINFO.CPY. The RMINFO.CPY copy file is supplied with an RM/COBOL
development system.
*
* RM/COBOL Information Definitions
*
01 RMInformation.
02 RM-BinaryVersionNumber.
03 RM-MajorVersion Picture 9(5) Binary(2).
03 RM-MinorVersion Picture 9(5) Binary(2).
03 RM-PointVersion Picture 9(5) Binary(2).
02 RM-VersionNumber Picture X(8).
02 RM-RegistrationNumber.
03 RM-ProductCode Picture XX.
03 RM-Filler Picture X.
03 RM-ADRNumber Picture 9(4).
03 RM-SerialNumber Picture 9(5).
03 RM-UseCount Picture 9(4).
02 RM-UseCountLimit Picture 9(5) Binary(2).
02 RM-UseCountInUse Picture 9(5) Binary(2).
02 RM-MainProgramName Picture X(30).
02 RM-ApplRegistrationNumber Picture X(16).
02 RM-BuildPlatform Picture X(80).
02 RM-InterfaceValue Picture 9 Binary(2).
88 RM-InterfaceIsTermcap Value 1.
88 RM-InterfaceIsTerminfo Value 2.
88 RM-InterfaceIsVMS Value 3.
88 RM-InterfaceIsDOS Value 4.
88 RM-InterfaceIsBIOS Value 5.
88 RM-InterfaceIsRAM Value 6.
88 RM-InterfaceIsJBIOS Value 7.
88 RM-InterfaceIsJRAM Value 8.
88 RM-InterfaceIsGUI Value 9.
02 RM-TerminalInterface Picture X(10).
02 RM-ConfigurationValue Picture X.
88 RM-ConfigurationIsBuiltIn Value 'Y' When False 'N'.
02 RM-WindowMangerValue Picture X.
88 RM-WindowManagerIsPresent Value 'Y' When False 'N'.
02 RM-EnterpriseCodeBnchValue Picture X.
88 RM-EnterpriseCodeBnchIsPresent Value 'Y' When False 'N'.
02 RM-VGIBValue Picture X.
88 RM-VGIBIsPresent Value 'Y' When False 'N'.

C$GetRMInfo
02 RM-INFOXValue Picture X.
88 RM-INFOXIsPresent Value 'Y' When False 'N'.
02 RM-plusDBValue Picture X.
88 RM-plusDBIsPresent Value 'Y' When False 'N'.
02 RM-MCBAValue Picture X.
88 RM-MCBAIsPresent Value 'Y' When False 'N'.
02 RM-FlexGenValue Picture X.
88 RM-FlexGenIsPresent Value 'Y' When False 'N'.
02 RM-RPCValue Picture X.
88 RM-RPCIsPresent Value 'Y' When False 'N'.
02 RM-CGIXValue Picture X.
88 RM-CGIXIsPresent Value 'Y' When False 'N'.
02 RM-OFMValue Picture X.
88 RM-OFMIsPresent Value 'Y' When False 'N'.
02 RM-Reserved Picture X(21).
C$GetSyn
C$GetSyn is used to retrieve the values of RM/COBOL synonyms from the Windows
registry file.
Calling Sequence
CALL "C$GETSYN" USING n a m e , value, p r o g r a m
name is an alphanumeric data item that contains the name of the synonym to retrieve.
value is an alphanumeric data item that contains the value of the synonym upon
return from the call.
program is an alphanumeric data item that indicates the name of the program whose
synonym properties are being retrieved. A value of SPACES indicates to use the
“Defaults” properties.

C$GetSyn
C$GetSysInfo
C$GetSysInfo is used to retrieve information about the operating system on which the
RM/COBOL runtime system is running. Under UNIX, this information is retrieved
directly from the operating system. Under DOS and Windows, information that is not
available from the operating system is instead retrieved from the environment.
Calling Sequence
CALL "C$GETSYSINFO" USING S y s t e m I n f o G r o u p
SystemInfoGroup is a group data item as defined in the following copy file,

SYSINFO.CPY. The SYSINFO.CPY is supplied with an RM/COBOL development
system.
*
* System Information Definitions
*
01 SystemInformation.
02 Sys-Name Picture X(20).
02 Sys-Version.
03 Sys-MajorVersion Picture 9(5) Binary(2).
03 Sys-MinorVersion Picture 9(5) Binary(2).
02 Sys-NodeName Picture X(20).
02 Sys-Machine Picture X(20).
02 Sys-UserName Picture X(20).
02 Sys-UserID Picture 9(10) Binary(4).
02 Sys-GroupName Picture X(20).
02 Sys-GroupID Picture 9(10) Binary(4).
02 Sys-StationName Picture X(20).
02 Sys-ProcessID Picture 9(10) Binary(4).
02 Sys-IsMultiUserValue Picture X.
88 Sys-IsMultiUser Value 'Y' When False 'N'.
02 Sys-Reserved Picture X(23).

C$GetSysInfo
Value Meaning
Sys-Name Contains the name of the operating system. Under
Windows, it may be “Windows 95”, “Windows 98”,
“Windows NT”, “Windows 2000”, or “Windows
Unknown”. Under UNIX, it is the name of the operating
system.
Sys-Version Contains the major and minor version number of the
operating system.
Sys-NodeName Contains the NETBIOS computer name established at
system startup.
Sys-Machine Contains the identity of the processor. It is set to “Intel
386”, “Intel 486”, “Intel Pentium”, “MIPS R4000”,
“Alpha 21064”, or “Unknown nnnnn”, where nnnnn is the
raw processor value returned by the operating system.
Sys-UserName Contains the name of the user. This is obtained by
querying the following three sources, in the following
order:
1. The name of the currently logged-in user.
2. The NAME environment variable.
3. The USER environment variable.
If none of the above are set, the field is set to “USER”.
Sys-UserID Contains the numeric ID assigned to this user. Under
Windows, this item is set to the numeric contents of the
USERID environment variable, or 0 if this variable is not
set or is non-numeric.
Sys-GroupName Contains the name of the group to which the user belongs.
Under Windows, this item is set to the contents of the
GROUP environment variable, or “GROUP” if this
variable is not set.
Sys-GroupID Contains the numeric ID assigned to the group to which
this user belongs. Under Windows, this item is set to the
numeric contents of the GROUPID environment variable,
or 0 if this variable is not set or is non-numeric.
Sys-StationName Contains the name of the terminal. Under Windows, this
item is set to the contents of the STATION environment
variable, or “CON” if not set. Under UNIX, this item is
set to the name of the current tty.
Sys-ProcessID Contains the numeric ID of the current process.
Sys-IsMultiUserValue Indicates if this runtime is running in single or in
multiuser mode. This will normally be multiuser mode
unless the FORCE-USER-MODE configuration option
has been specified.
Sys-Reserved Reserved for future expansion.

C$GetSysInfo
C$GUICFG
C$GUICFG is used to dynamically manipulate certain graphical user interface (GUI)
settings. The settings changes are temporary until the next access of the Windows
registry file. The registry entries remain unchanged. To use this subprogram, the runtime
system must be able to locate the c$guicfg.dll file.
Calling Sequence
CALL "C$GUICFG" USING settingstr [, settingstr

… ], exit-code
settingstr is an alphanumeric data item that contains the settings modification

information. The settings are in the form of item=value where item is one of the
properties listed below. (The descriptions of the items and values are described in
the “Setting Miscellaneous Properties” section on page 3-19 in Chapter 3,
Installation and System Considerations for Microsoft Windows.)
• Auto Paste • Printer Dialog Always

• Auto Scale • Printer Dialog Never
• Enable Close • Remove Trailing Blanks
• Enable Properties Dialog • Sizing Priority
• Full OEM To ANSI Conversions • Status Bar
• Icon File • SYSTEM Window Type
• Mark Alphanumeric • Toolbar
• Paste Termination • Update Timeout
• Persistent
exit-code is a PICTURE 9(n) BINARY, where n can be a digit from 1 to 9.

C$GUICFG
C$MBar
C$MBar is used to display a menu bar in the RM/COBOL window.
To use this subprogram, the runtime system must be able to locate the rmbars.dll file.
with the L Option:
runcobol program-name L=RMBARS.DLL
Calling Sequence
CALL "C$MBAR" [USING menustring [, menustring

… ], exit-c o d e ]
menustring is an alphanumeric data item that contains the menu text, as described in
the section “Setting Menu Bar Properties” on page 3-34.
Note Calling C$MBar with no arguments turns off the menu bar.

C$MBar
C$MemoryAllocate
C$MemoryAllocate is used to allocate dynamic memory.
Calling Sequence
CALL "C$MEMORYALLOCATE" USING memory-pointer,

memory-size
memory-pointer must be a pointer data item (USAGE POINTER) that will contain
the address of the allocated memory area upon successful completion of the call. A
null pointer value is returned if the call is not successful.
memory-size must be a numeric data item that specifies the size of the area to allocate
in bytes. The maximum value for memory-size is approximately 2,147,483,611,
depending on the size of overhead structures. If the maximum value is exceeded, the
allocation request will be unsuccessful and a null pointer will be returned. A null
pointer will likely be returned for much smaller values since the operating system
will be unable to satisfy the request. If the COBOL data item used to specify
memory-size supports 10 or more decimal digits, a large value in memory-size may
be truncated upon conversion internal to C$MemoryAllocate. In this case, an area
may be allocated that is smaller than the requested size or the run unit terminated
with an error in C$MemoryAllocate.
If the memory allocation is successful, the allocated memory is initialized to spaces.
The allocated memory belongs to the run unit and may be accessed by any program in the
run unit that has access to the pointer data item memory-pointer or a copy of that pointer
data item. Upon termination of the run unit, all dynamically allocated memory will be
freed.
The pointer returned by C$MemoryAllocate may be used to set the base address of a
based linkage item in a Format 5 SET statement. The memory area may then be accessed
by references to the based linkage item or data items subordinate to the based linkage
item. References to based linkage items are slower than references to Working-Storage
items, so if the program makes frequent references to the based linkage item (for
example, in a PERFORM loop), it is a good idea to move the based linkage item to a
Working-Storage item.

C$MemoryAllocate
C$MemoryDeallocate
C$MemoryDeallocate is used to deallocate (free) dynamic memory allocated by a
previous call to C$MemoryAllocate.
Calling Sequence
CALL "C$MEMORYDEALLOCATE" USING m e m o r y - p o i n t e r
memory-pointer must be a pointer data item (USAGE POINTER) that points to a

memory area previously allocated by a call to C$MemoryAllocate. If the pointer
does not point to such a memory area, the call does nothing. If the pointer does point
to such a memory area and the memory is successfully freed, then the value of
memory-pointer is set to a null pointer value.
After memory has been deallocated, the program should not make any references to based
linkage items whose base address was set to the area of memory that was deallocated until
those based linkage items are reassigned to a new valid base address in a Format 5 SET
statement. If the program does reference the deallocated memory, an error may occur or
undefined data may be accessed, either from the original memory area while it is still on
the free memory list or after the memory has been reallocated for a different use. It is the
programmer's responsibility to manage pointer data items and the setting of based linkage
base addresses to avoid such conditions.
It is not necessary to call C$MemoryDeallocate. The runtime will free any dynamically
allocated memory upon termination of the run unit.
C$NARG
C$NARG returns the number of parameters passed in the CALL statement USING list to
the subprogram that contains the call to C$NARG. The GIVING argument is not
included in the count. Arguments specified explicitly as OMITTED in the USING list of
the CALL statement are included in the count. An RM/COBOL subprogram may be
called with a variable number of actual parameters if it does not attempt, during its
execution, to reference formal parameters for which no actual parameters exist.

C$MemoryDeallocate
Calling Sequence
CALL "C$NARG" USING parameter-count
parameter-count is a BINARY, COMPUTATIONAL-4 or COMPUTATIONAL-1

data item with the PICTURE 9(3) into which is stored the number of parameters in
the USING list on the CALL statement that called the subprogram that called
C$NARG.
Note The restriction on a reference to a formal argument for which no corresponding
actual argument exists does not apply to a reference in an ADDRESS OF identifier-1
special register. Thus, the calling program's omission of the GIVING argument or
omission of an embedded USING argument (by use of the OMITTED keyword) can
be detected by using IF ADDRESS OF identifier-1 IS EQUAL TO NULL, where
identifier-1 refers to the appropriate formal argument. The restriction also does not apply
to Linkage Section 01 or 77 data items specified in the USING or GIVING phrase of a
CALL statement.
C$OSLockInfo
C$OSLockInfo returns the process ID of the process that has the record locked when a
lock request fails. This subprogram should be called immediately after a lock request has
failed.
Note This subprogram is available only under UNIX and only if the system uses the
fcntl() system call to perform record locking.
Calling Sequence
CALL "C$OSLOCKINFO" USING processid
processid is a four-byte, unsigned COMP-4 numeric item.

C$OSLockInfo
C$PlaySound
C$PlaySound is used to play Windows predefined sound events or sound files, that is,
files with the .wav extension.
Calling Sequence
CALL "C$PLAYSOUND" USING so u n d , flags
sound is an alphanumeric data item that contains the name of a Windows sound event
or .wav sound file to play.
flags is a numeric data item that contains flags to use when playing the sound. The
possible values are provided below and in the 78-level entries in the WINDEFS.CPY
copy file (see page E-69), and may be combined by adding them together.
Value Meaning
SoundSync Synchronous playback of a sound event.
SoundAsync Sound is played asynchronously.
SoundNoDefault No default sound event is used.
SoundNoStop The specified sound event will yield to another
sound event that is already playing.
SoundPurge Sounds are to be stopped for the calling task.
SoundApplication The sound is played using an application-specific
association.
SoundNoWait If the driver is busy, return immediately without
playing the sound.
SoundAlias sound is a system-event alias in the Windows
registry file or the win.ini file.
SoundFilename sound is a filename.
SoundAliasId sound is a predefined sound identifier.
Example
The following code fragment plays the default Windows 95 Chimes.wav:
Call "C$PlaySound" Using "Chimes.wav".

C$PlaySound
C$RBMenu
C$RBMenu is used to display a pop-up menu in the RM/COBOL window when the right
mouse button is pressed.
with the L Option:
Calling Sequence
CALL "C$RBMENU" [USING menustring [, menustring

… ], exit-c o d e ]
menustring is an alphanumeric data item that contains the menu text, as described in
the “Setting Pop-up Menu Properties” section on page 3-36.
Note Calling C$RBMenu with no arguments turns off the pop-up menu.
C$RERR
C$RERR returns the expanded I-O completion status shown beginning on page A-11. It
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. When the COBOL I-O status for the last operation is
represented differently under ANSI COBOL 1985 and 1974, the value returned conforms
to ANSI COBOL 1974 when the calling program is compiled in 1974 mode (that is, when
the 7 Compile Command Option is specified, as described in Chapter 6, Compiling). The
value returned conforms to ANSI COBOL 1985 when the calling program is compiled in
1985 mode.

C$RBMenu
Calling Sequence
CALL "C$RERR" USING extended-status
extended-status is either a four-character or an eleven-character alphanumeric data

item into which the expanded I/O completion status is stored in ASCII characters.
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 Appendix A, Error Messages, shows only two digits for a status, the last two
character positions will contain ASCII zeroes. Although most statuses contain only the
decimal digits 0 through 9, note that the hexadecimal digits A through F are possible in
some character positions (for example, 39,3A through 39,3F, as shown on page A-17).
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 as shown on pages A-11 and A-14), character position
three contains an ASCII comma, character positions four and five contain a two-digit OS
code (see Table F-2), character position six contains an ASCII comma, and character
positions seven through eleven contain a five-digit, OS-specific error code. Although
most statuses contain only the decimal digits 0 through 9, note that the hexadecimal digits
A through F are possible in some character positions (for example, 39,3A through 39,3F
shown on page A-17).

C$RERR
Table F-2 Two-Digit OS Codes
Code Description
00 Unknown OS error.
01 File Manager Detected error.
02 MS-DOS error.
03 OS/2 error.
04 UNIX error.
05 RM/COS error.
06 Btrieve error.
07 Informix error.
08 Oracle error.
09 AmigaDos error.
10 Open File Manager error.
11 Runtime Library error.
12 MS-Windows error.
13 NetWare error.
14 VMS error.
15 RM/InfoExpress Server error.
16 RM/InfoExpress Client error.
17 RM/InfoExpress TLI error.
18 RM/InfoExpress TLISYS error.
19 RM/InfoExpress NetBIOS error.
20 RM/InfoExpress SPX error.
21 RM/InfoExpress WinSock error.

C$RERR
Examples
The following examples illustrate the difference between four-character and

eleven-character expanded I-O completion status codes.
Four-character Eleven-character Meaning
0000 00 Successful.
1000 10 At end.
0405 04,05 Record read shorter than minimum.
395A 39,5A Key length mismatch (alt. key #10).
3010 30,06,01002 Btrieve error 1002 (memory).
3010 30,21,10054 Windows Sockets error 10054 (reset).
C$SBar
C$SBar is used to display a status bar in the RM/COBOL window.
with the L Option:
Calling Sequence
CALL "C$SBAR" [USING status-text ]
status-text is an alphanumeric data item that contains the text to be displayed on the
status line. See “Status Bar Text” property on page 3-27 for more information.
Note Calling C$SBar with no arguments turns off the status bar.

C$SBar
C$SCRD
C$SCRD allows the contents of the screen to be read into an alphanumeric data item.
Calling Sequence
CALL "C$SCRD" USING screen-buffer [, buffer-size [,

screen-line [, screen-position ]]]
screen-buffer is an alphanumeric data item that will receive the characters read from
the terminal display screen.
buffer-size is an optional COMP-1 data item that specifies the number of
characters to be read. If the value is 0 or the parameter is omitted, the actual size
of screen-buffer is used.
screen-line is a COMP-1 data item that specifies the line where the cursor is to be
placed prior to the screen read. If omitted, a value of 1 is used. If a pop-up window
is active, screen-line is window-relative, not screen-relative.
screen-position is a COMP-1 data item that specifies the position where the cursor is
to be placed prior to the screen read. If omitted, a value of 1 is used. If a pop-up
window is active, screen-position is window-relative, not screen-relative.
Note The three optional arguments, buffer-size, screen-line, and screen-position,
may be explicitly omitted by specifying the keyword OMITTED in the corresponding
position in the USING list.
The cursor position after the call obeys the rules for the ACCEPT and DISPLAY
statements. No errors are returned.
If this function is requested to read characters past the end of the screen or window, as
many actual characters as possible are returned. The remainder of the buffer is set to
spaces.
It is not possible to retrieve attribute information from the display. Only the actual
character values are returned.
If graphic characters have been written to the display using the GRAPHICS keyword of
the CONTROL phrase of the ACCEPT and DISPLAY statements, and this call is used to
read such characters, the characters returned are the displayed characters, not the values
used by the program in the ACCEPT or DISPLAY statement that originally wrote the

C$SCRD
characters. For more information, see the description of the GRAPHICS keyword of the
CONTROL phrase on page 8-13.
C$SCWR
C$SCWR allows a COBOL program to display quickly a large amount of information
containing multiple display attributes.
Calling Sequence
CALL "C$SCWR" USING d isplay-description, text-characters

[, attribute-codes, palette-table ]
display-description is a required, 8- to 14-character group data item into which the

location and size of the display are stored. The COBOL description is as follows:
01 DISPLAY-DESCRIPTION USAGE BINARY (2).
02 DISPLAY-VERSION PIC 9(4) VALUE 0.
02 DISPLAY-UNIT PIC 9(4) VALUE 0.
02 DISPLAY-LINE PIC 9(4).
02 DISPLAY-POSITION PIC 9(4).
02 DISPLAY-LENGTH PIC 9(4).
02 DISPLAY-EXCEPTION-CODE PIC 9(4).
02 DISPLAY-EXCEPTION-VALUE PIC 9(4).
DISPLAY-VERSION (required, input) is reserved for future use and must be set
to a value of 0.
DISPLAY-UNIT (required, input) is the unit number of the terminal to which
the display is directed. Under UNIX, specifying a value of 0 causes output to be
written to the terminal from which the runtime system was started. Under
Windows, this value must be set to 0.
DISPLAY-LINE (required, input) is the one-relative line number in the current
window where the text is to be displayed. If set to a value of 0, the display
begins on the current line (as described in the “Determining Line and Position”
section of the DISPLAY statement in Chapter 6, Procedure Division Statements,
of the RM/COBOL Language Reference Manual).
DISPLAY-POSITION (required, input) is the one-relative column number in the
current window where the text is to be displayed. If set to a value of 0, the
display begins at the current column (as described in the “Determining Line and

C$SCWR
Position” of the DISPLAY statement in Chapter 6, Procedure Division
Statements, of the RM/COBOL Language Reference Manual).
DISPLAY-LENGTH (optional, input) is the number of characters of text to
display. If set to a value of 0 or omitted, the actual length of text-characters is
used (see text-characters below).
DISPLAY-EXCEPTION-CODE (optional, output) is set to a value of 0 if this
function succeeds. Otherwise, one of the exception codes, described beginning
on page F-31, is returned. Notice that some exception codes are merely
warnings.
DISPLAY-EXCEPTION-VALUE (optional, output) is set to a value of 0 if this
function succeeds. Otherwise, it contains a value that provides more details on
the exception that occurred (see page F-31 for more information on the
exception codes).
Note display-description will only have the correct length if four-digit binary data
items are allocated with two bytes of storage. The example shown specifies a binary
allocation override to guarantee the right allocation regardless of the configured
binary allocation scheme. The binary allocation override is not necessary if
BINARY-ALLOCATION=RM, RM1, or MF-RM.
text-characters is a required alphanumeric data item that contains the characters
to be displayed. The number of characters to be displayed is controlled by
DISPLAY-LENGTH. If DISPLAY-LENGTH is set to a value of 0, all of
text-characters is displayed. If DISPLAY-LENGTH is less than the length of
text-characters, the first DISPLAY-LENGTH characters are displayed. Otherwise,
text-characters is displayed padded with spaces to DISPLAY-LENGTH characters.
attribute-codes is an optional alphanumeric data item that contains the attribute codes
used to display text-characters. Each attribute code occupies a single character and
controls the character at the same relative position in text-characters. The value of
each attribute code is a one-relative indicator of an entry in palette-table (described
below). An attribute code of X’00’ causes the preceding code in attribute-codes
to be used again. If there is no preceding code, the colors currently in effect
(set by the preceding ACCEPT, DISPLAY, or C$SCWR) are used with all
PALETTE-ATTRIBUTE-VALUES set to off.
If attribute-codes is omitted, or the length of attribute-codes is less than the actual
DISPLAY-LENGTH (as described previously), attribute-codes is internally padded
with X’00’. If attribute-codes is longer than the actual DISPLAY-LENGTH, the
excess attribute codes are ignored.
If attribute-codes is specified, palette-table must also be specified.

C$SCWR
palette-table is an optional group data item that is used to interpret attribute-codes.
The table consists of 1 to 255 entries. Each palette-table entry describes a
combination of colors and attributes.
Here are two possible COBOL descriptions for palette-table:
01 PALETTE-TABLE-1.
03 PALETTE-TABLE-ENTRIES.
05 PALETTE-TABLE-ENTRY-1.
07 FOREGROUND-COLOR-1 PIC X.
07 BACKGROUND-COLOR-1 PIC X.
07 ATTRIBUTE-VALUE-1 PIC 9(4) BINARY(2).
07 FILL-CHARACTER-1 PIC X.

01 PALETTE-TABLE-2.
03 PALETTE-TABLE-ENTRIES.
05 PALETTE-TABLE-ENTRY OCCURS 255 TIMES.
07 FOREGROUND-COLOR-VALUE PIC X.
07 BACKGROUND-COLOR-VALUE PIC X.
07 ATTRIBUTE-VALUE PIC 9(4) BINARY(2).
07 FILL-CHARACTER PIC X.
In the following description of color values, FOREGROUND-COLOR-VALUE

contains a value from PALETTE-COLOR-VALUES that indicates the text
color; BACKGROUND-COLOR-VALUE contains a value from
PALETTE-COLOR-VALUES that indicates the background color. Both
FOREGROUND-COLOR-VALUE and BACKGROUND-COLOR-VALUE are
ignored with a warning unless a color monitor is being used or the USE-COLOR
keyword of the TERM-ATTR configuration record is set to YES (see page 10-40).

C$SCWR
The permitted color values are listed below. Using a value not included in this list
results in undefined behavior.
01 PALETTE-COLOR-VALUES USAGE DISPLAY.
03 PALETTE-UNSPECIFIED-1 PIC X VALUE SPACE.
03 PALETTE-UNSPECIFIED-2 PIC X VALUE X"00".
03 PALETTE-BLACK PIC X VALUE "0".
03 PALETTE-RED PIC X VALUE "1".
03 PALETTE-GREEN PIC X VALUE "2".
03 PALETTE-YELLOW PIC X VALUE "3".
03 PALETTE-BLUE PIC X VALUE "4".
03 PALETTE-MAGENTA PIC X VALUE "5".
03 PALETTE-CYAN PIC X VALUE "6".
03 PALETTE-WHITE PIC X VALUE "7".
PALETTE-UNSPECIFIED-1 or PALETTE-UNSPECIFIED-2 cause the last

color output to be used.
ATTRIBUTE-VALUE contains a value that specifies what attributes are to be
applied. The value is produced by summing together the desired values from
PALETTE-ATTRIBUTE-VALUES, listed below. Values omitted from the
following table are reserved and must not be set.
01 PALETTE-ATTRIBUTE-VALUES USAGE BINARY(2).
03 INTENSITY-HIGH PIC 9(4) VALUE 1.
03 BLINK-ON PIC 9(4) VALUE 2.
03 REVERSE-ON PIC 9(4) VALUE 4.
03 UNDERLINE-ON PIC 9(4) VALUE 8.
03 GRAPHICS-ON PIC 9(4) VALUE 16.
03 FILL-CHARACTER-ON PIC 9(4) VALUE 32.
With the exception of FILL-CHARACTER-ON, the meaning of each attribute is

the same as if the attribute were specified in the CONTROL phrase of a
DISPLAY statement. To combine multiple attributes, sum the values together.
The FILL-CHARACTER-ON attribute specifies a character to be used instead of
the character specified in the text-characters.
FILL-CHARACTER contains a character to be displayed if
PALETTE-ATTRIBUTE-VALUES indicate FILL-CHARACTER-ON.
The FILL-CHARACTER is optional and is needed only when the
FILL-CHARACTER-ON attribute has been set.
Because the palette-table contains both alphanumeric and numeric fields, use the
INITIALIZE statement to remove all colors and attributes from the table. To
reset the example palette tables, enter:
INITIALIZE PALETTE-TABLE-1, PALETTE-TABLE-2.

C$SCWR
Usage Notes
If this function is requested to write characters past the end of the screen (or window, if
pop-up windows are active), the screen or window is scrolled.
The current line and current position after the call obey the rules for the ACCEPT and
DISPLAY statements.
Colors set by this function also affect subsequent ACCEPT and DISPLAY operations if
those operations do not specify an FCOLOR or BCOLOR keyword in the CONTROL
phrase (see page 8-12).
Fatal Errors
The runtime system terminates if the C$SCWR function is called with any of the
following four conditions:
1. C$SCWR is called with other than two or four parameters, or any one of the
parameters is a simple numeric parameter.
2. The length of DISPLAY-DESCRIPTION is less than six characters.
3. The length of text-characters is zero.
4. The size of any passed data item exceeds 65535 bytes.
Exception Codes
The following exception codes are stored in the DISPLAY-EXCEPTION-CODE
variable. The C$SCWR function reports three types of exception codes: error,
warning, and informational. Lower-numbered exception codes are reported before
higher-numbered exception codes. These codes and their associated definitions are
listed in Table F-3.
Note Error codes take precedence over warning and informational codes. If multiple
exceptions occur, the first occurring exception at a given level is returned. If warnings
are returned, the display is performed, but the results may not be as expected.

C$SCWR
Table F-3 C$SCWR Exception Codes
Code Type Description

0 No error detected.
1 Error An invalid DISPLAY-VERSION was specified. This
data item must be set to a value of 0.
2 Error An I/O error occurred while the write operation was
being performed. DISPLAY-EXCEPTION-VALUE
contains the RM/COBOL I/O error code.
3 Error DISPLAY-LINE is greater than the number of lines on
the window or screen. The display was not performed.
DISPLAY-EXCEPTION-VALUE contains the
number of lines on the window or on the screen. An
out-of-range line specification is diagnosed before an
out-of-range position specification.
4 Error DISPLAY-POSITION is greater than the number of
columns on the screen. The display was not performed.
DISPLAY-EXCEPTION-VALUE contains the number
of columns on the window or on the screen.
5 Error The specified palette is invalid. DISPLAY-
EXCEPTION-VALUE indicates either (a) the palette
table does not contain complete palette entries, or (b) the
table contains more than 255 entries.
20 Warning An out-of-range palette index was specified.
offending palette index. The palette specification is
ignored and treated as if unspecified.
21 Warning The palette contains an invalid foreground color
specification. DISPLAY-EXCEPTION-VALUE
contains the offending palette index. The color is
22 Warning The palette contains an invalid background color
specification. DISPLAY-EXCEPTION-VALUE
contains the offending palette index. The color is
23 Warning The palette contains an invalid foreground
and background color specification.
offending palette index. The color is ignored and
treated as if unspecified.

C$SCWR
Table F-3 C$SCWR Exception Codes (Cont.)
Code Type Description

24 Warning The palette contains an invalid attribute value.
offending palette index. The entire attribute code is
40 Informational A monochrome display is in use, or USE-COLOR=N
was configured. The specified foreground and
background colors are not validated and are ignored.
This condition cannot be detected under all
circumstances. However, in all cases,
DISPLAY-EXCEPTION-VALUE contains the palette
index of the offending attribute.
C$SetDevelopmentMode
C$SetDevelopmentMode is used to enable expanded error information reporting (known
as “development mode”) for many of the C$ and P$ subprograms. (P$ subprograms are
discussed in Appendix E, Windows Printing.) When development mode is enabled, more
verbose error reporting is performed to assist the COBOL developer in implementing
these subprogram calls. See also “C$ClearDevelopmentMode” on page F-7.
Calling Sequence
CALL "C$SETDEVELOPMENTMODE"
Development mode also may be set at program startup with the RM_DEVELOPMENT_MODE
environment variable:
RM_DEVELOPMENT_MODE=[Y|y|N|n]
Specify Y or y to enable development mode. Specify N or n, or omit the variable, to

disable development mode. All other values are undefined.

C$SetDevelopmentMode
C$SetEnv
C$SetEnv is used to set or clear the values of environment variables.
Calling Sequence
CALL "C$SETENV" USING n a m e , value [, return ]
name is an alphanumeric data item that contains the name of the environment
variable to set or clear.
value is an alphanumeric data item that contains the value to which the environment
variable is set. A value of SPACES indicates that the environment variable should be
deleted.
return is a PICTURE 9(n) BINARY, where n can be a digit from 1 to 9. It is set to 0
if the call was successful and non-zero if it failed.
C$SetSyn
C$SetSyn is used to set the values of RM/COBOL synonyms in the Windows registry file.
Note This subprograms are supported only under Windows.
Calling Sequence
CALL "C$SETSYN" USING n a m e , value, p r o g r a m
name is an alphanumeric data item that contains the name of the synonym to set or
clear.
value is an alphanumeric data item that contains the value to which the synonym is
set. A value of SPACES indicates that the synonym should be deleted.
program is an alphanumeric data item that indicates the name of the program whose
synonym properties is being changed. A value of SPACES indicates to use the
“Defaults” properties.

C$SetEnv
C$Show
C$Show is used to set the show state of the main RM/COBOL window.
Calling Sequence
CALL "C$SHOW" USING flag
flag is a numeric data item that contains one of the values described below:
01 WIN-SHOW-STYLES.
03 SW-HIDE PIC 9(4) BINARY VALUE 0.
03 SW-MINIMIZE PIC 9(4) BINARY VALUE 6.
03 SW-RESTORE PIC 9(4) BINARY VALUE 9.
03 SW-SHOW PIC 9(4) BINARY VALUE 5.
03 SW-SHOWMAXIMIZED PIC 9(4) BINARY VALUE 3.
03 SW-SHOWMINIMIZED PIC 9(4) BINARY VALUE 2.
03 SW-SHOWMINNOACTIVE PIC 9(4) BINARY VALUE 7.
03 SW-SHOWNA PIC 9(4) BINARY VALUE 8.
03 SW-SHOWNOACTIVATE PIC 9(4) BINARY VALUE 4.
03 SW-SHOWNORMAL PIC 9(4) BINARY VALUE 1.
Value Meaning
SW-HIDE Hides the window and passes activation to another
window.
SW-MINIMIZE Minimizes the specified window and activates the
top-level window in the system’s list.
SW-RESTORE Activates and displays a window. If the window
is minimized or maximized, Windows restores
it to its original size and position (same as
SW_SHOWNORMAL).
SW-SHOW Activates a window and displays it in its current
size and position.
SW-SHOWMAXIMIZED Activates a window and displays it as a maximized
window.
SW-SHOWMINIMIZED Activates a window and displays it as an icon.

C$Show
Value Meaning
SW-SHOWMINNOACTIVE Displays a window as an icon. The window that is
currently active remains active.
SW-SHOWNA Displays a window in its current state. The
window that is currently active remains active.
SW-SHOWNOACTIVATE Displays a window in its mores recent size and
position. The window that is currently active
remains active.
SW-SHOWNORMAL Activates and displays a window. If the window
is minimized or maximized, Windows restores
it to its original size and position (same as
SW-RESTORE.
Examples
The following code fragment hides the main window:

CALL "C$SHOW" USING SW-HIDE.
The following code fragment shows the main window:

CALL "C$SHOW" USING SW-SHOW.
C$ShowArgs
C$ShowArgs displays the list of arguments that were used to call C$ShowArgs. This
facility is useful during development of non-COBOL subprograms.
Note This subprogram is supported only under UNIX and performs no operation when
called under Windows.
Calling Sequence
CALL "C$SHOWARGS" [USING a r g u m e n t [, argument [, … ]]]
argument is any data item. C$ShowArgs will print its own name, the number of
arguments, and the initial state flag. Then, for each argument, C$ShowArgs prints
the address of the argument using hexadecimal notation, the size of the argument, the

C$ShowArgs
numeric type of the argument, three or four character-strings indicating the type of
the argument, and finally, the number of digits and the scale of the argument.
Note This subprogram is most useful when it is used to replace another subprogram
temporarily, thereby allowing the actual arguments that are being passed to be inspected.
Example
Name="C$SHOWARGS", Args= 3, Initial=65535

Arg # 1 Ptr=0041DBA8 Size=12 Type=16 ANS Digits= 0 Scale= 0
Arg # 2 Ptr=0041DBB4 Size=10 Type= 3 NTC Digits= 10 Scale=-2
Arg # 3 Ptr=0041DBBE Size=4 Type=11 NBS Digits= 8 Scale= 0
C$TBar
C$TBar is used to display a toolbar in the RM/COBOL window.
with the L Option:
Calling Sequence
CALL "C$TBAR" [USING buttonstr [, buttonstr … ], exit-code ]
buttonstr is an alphanumeric data item that contains the button definition. The syntax
is as follows:
buttonname["prompt"]=string
buttonname is the name of the icon stored in the filename specified by the Icon
File property (see page 3-21).

C$TBar
prompt is an optional text string that is displayed if the status bar is on (see
Status Bar property on page 3-27) and whenever the cursor is placed on the
toolbar icon that is specified by buttonname.
string is an ASCII text string. However, it also can contain special characters for
the Return, Tab, Escape, or Function keys. If the first character is a greater than
character (>), then the characters that follow are executed as a command. The
special characters are described in Table 3-2 on page 3-33. (These characters
are interpreted by the COBOL ACCEPT statement, as described in Table 8-2
beginning on page 8-6.)
Note Calling C$TBar with no arguments turns off the toolbar.
C$TBarEn
C$TBarEn is used to enable and disable buttons on the toolbar.
with the L Option:
If the toolbar button bitmap contains three frames instead of the normal two, the third
bitmap will be displayed while the button is disabled.
Calling Sequence
CALL "C$TBAREN" USING b u t t o n n a m e , flag,

b u t t o n n a m e , flag, …
buttonname is the name of the icon stored in the filename specified by the Icon File
property (see page 3-21).
flag is a numeric data item with the value of 1 for enable and 0 for disable.

C$TBarEn
C$TBarSeq
C$TBarSeq is used to set the bitmap sequence to use for buttons on the toolbar.
with the L Option:
Calling Sequence
CALL "C$TBARSEQ" USING b u t t o n n a m e , seq,

b u t t o n n a m e , seq, …
buttonname is the name of the icon stored in the filename specified by the Icon File
property (see page 3-21).
seq is a numeric data item that contains a value of 0 through 9 indicating the
sequence number to use for displaying the named button. See the “Toolbar Editor”
section on page 3-37 for more information.
C$Title
C$Title is used to set the window title for the RM/COBOL window.
To use this subprogram, the runtime system must be able to locate the c$title.dll file. The
following example illustrates how to add this DLL to the Runtime Command line with the
L Option:
runcobol program-name L=C$TITLE.DLL

C$TBarSeq
Calling Sequence
CALL "C$TITLE" USING string
string is the text to be placed in the window title.

Note The Title Text property (see page 3-28) also can be used to set the text of the title
for the RM/COBOL window.
C$WRU
C$WRU returns the program identification, line number, and intraline number of the
CALL statement, which called the subprogram that contains the call to C$WRU.
Calling Sequence
CALL "C$WRU" USING p r o g r a m - n a m e , prog-line,

prog-intraline
program-name is a 30-character alphanumeric data item into which the program-id of

the calling subprogram is stored. If the first subprogram of the run unit (that is, the
main program) calls C$WRU, the value “RUNCOBOL” will be stored in
PROGRAM-NAME, and zeroes are stored in prog-line and prog-intraline.
prog-line is a BINARY data item with the picture PIC 9(6) into which the line
number containing the CALL statement is stored. If the program that contains the
call to the subprogram that called “C$WRU” was compiled with the Q Compile
Command Option (see Chapter 6, Compiling), the value stored in prog-line is the
segment offset of the original CALL statement. Use the values from the Debug
heading of the program listing to locate the statement.
prog-intraline is a BINARY data item with the picture PIC 9(2) into which the
intraline number of the CALL statement is stored. See page 9-3 for a description of
Debug line and intraline numbers. If the program that contains the call to the
subprogram that called “C$WRU” was compiled with the Q Option, the value stored
in prog-intraline is zero.

C$WRU
SYSTEM
SYSTEM allows an arbitrary operating system command to be executed.
Calling Sequence
CALL "SYSTEM" USING c o m m a n d - l i n e [repaint-screen ]

[exit-code ]
command-line is an alphanumeric data item that contains the command line to be

passed to the operating system. Trailing spaces are stripped from command-line
before the command is executed. To execute a command line that contains trailing
spaces, place a NULL character after the last embedded space.
Note Under Windows, the command line is restricted to 130 characters. On most
UNIX systems, the longest command line that can be executed is 4096 characters.
repaint-screen is an optional, one-byte, alphanumeric data item that controls
whether the screen is redrawn after execution of the command. A value of Y or y
causes the screen to be redrawn. A value of N or n does not redraw the screen. A
blank or any other value defaults to the TERM-ATTR configuration record
REDRAW-ON-CALL-SYSTEM value (see page 10-39).
Note This parameter is ignored under Windows.
exit-code is an optional numeric data item that contains the exit code of the command
upon return from the operating system. exit-code must be declared as
PIC S9(4) BINARY. The value returned in exit-code is dependent on the underlying
operating system. A value of 0, however, indicates success and a non-zero value
indicates an error.
If the argument count is incorrect or the arguments are of the wrong type, the run unit is
stopped with the message “COBOL STOP RUN at line ? in SYSTEM ...”.

SYSTEM
UNIX Considerations
A command-line that contains either a single NULL character or all blanks starts a new
instance of the shell.
The command is executed with the system() library function call. For a null or all space
command-line, the environment variable SHELL is used to locate the shell processor. To
return to the calling COBOL program, type:
ctrl+d.
Windows Considerations
A command-line that contains either a single NULL character or all blanks starts a new
instance of the command processor.
The command-line parameter may be used to specify either a DOS or Windows program.
The execution of the calling COBOL program is suspended until the called program
terminates. For a null or all space command-line, the environment variable COMSPEC is
used to locate the command processor. To return to the calling COBOL program, type:
EXIT
The style of the window used for Windows programs is controlled with the SYSTEM
Window Type property (see page 3-28). The SYSTEM Window Type property also can
be set with the C$GUICFG non-COBOL subprogram as described on page F-16.
In order to execute a DOS internal command, it is necessary to specify completely the

command processor on the command line. For example, to execute a dir command, enter
the following:
C:\DOS\COMMAND.COM /C DIR
This example assumes that the command processor is located on drive C: in the directory
DOS.
You can configure whether a DOS program runs in a full screen or in a window by
modifying the MS-DOS Prompt Properties. This can be done by right-clicking the
MS-DOS Prompt icon and selecting Properties from the pop-up menu.

SYSTEM
Appendix G: Utilities
RM/COBOL provides a wide range of file conversion, management, and manipulation
facilities. The majority of these utilities allow you to specify the required parameters
either in the initial invocation command line or interactively during the course of
execution.
This appendix describes the set of utilities provided for file conversion, management, and
manipulation.
Organization
The utilities described in this appendix are as follows:
1. The RM/COBOL Conversion utilities provide an easy method of converting

RM/COBOL (74) versions 1 and 2 indexed (rmifca and rmifcb), relative (rmcrl1
and rmcrl2), and sequential (rmcseq) files to an RM/COBOL-compatible format.
2. The Combine Program utility (rmpgmcom) creates a program file by combining

other program files and eliminating duplicate programs. It is used to create object
program libraries.
3. The Map Program File utility (rmmappgm) produces a report describing the
contents of an object program file created by the RM/COBOL compiler or the
rmpgmcom utility.
4. The Map Indexed File utility (rmmapinx) produces a report describing the structure
of an indexed file created by an RM/COBOL program or by the rmdefinx utility
(described in the following item).
5. The Define Index File utility (rmdefinx) precreates an indexed file for use by
RM/COBOL programs, or modifies some of the characteristics of an existing indexed
file.
6. The Indexed File Recovery utility (recover1) is used to recover the data in an
indexed file.
The Indexed File Unload utility (recover2) is used to unload an indexed file to a
sequential file. This utility is no longer needed to recover indexed files.
RM/COBOL User's Guide for 32-Bit Windows G-1

Organization
7. The Attach Configuration utility (rmattach), available only under Windows, is used
to attach configuration files to runcobol.exe, rmcobol.exe and recover1.exe.
8. The Initialization File to Windows Registry Conversion utility (ini2reg), available

only under Windows, converts an RM/COBOL for Windows initialization file and
places its contents into the Windows registry database.
9. The RM/COBOL Configuration utility (rmconfig), available only under Windows, is

used to modify the configuration options for one or more RM/COBOL programs.
Utilities Delivered on Media

The programs and files required to execute the utilities described in this appendix are
provided with your RM/COBOL product. The actual number of files and programs
depends on the specific version of the product you purchased and whether you purchased
a development or a runtime system. The delivered media contains one or more README
files that list the actual files and programs delivered. Please check these README files
after you have installed the product to make sure that you have received all of the
appropriate files and programs.
The utility programs and files may be placed in one directory. Be sure that the compiler
and runtime system directory search sequences (see page 2-4 for UNIX and page 3-11 for
Windows) include the directory in which these files are placed.
General Considerations
Files with an extension of .cob were created with the RM/COBOL compiler, and are
executed with the RM/COBOL Runtime Command. Files with an extension of .cbl are
RM/COBOL source files, which are used as examples for relative file conversion and as a
copy file-driven, configurable index file conversion utility.
The programs rmmapinx, rmmappgm, rmpgmcom, and recover1 generate reports that
are written to a file named PRINTER. Under UNIX, the line printer spooler is used.
Under Windows, the runtime system assigns this by default to the Windows default
printer.
If you want to discard the report under UNIX, set an environment variable using the
following commands:
PRINTER=/dev/null ; export PRINTER
G-2 Utilities
Utilities Delivered on Media
If you want to discard the report under Windows, set the following synonym:
PRINTER=NUL
If you want the report to go to a disk file under UNIX, set an environment variable using
the following commands:
PRINTER=filename ; export filename
If you want the report to go to a disk file under Windows, set the following synonym:
PRINTER=filename
If you want the report to go to the console under UNIX, set an environment variable using
the following commands:
PRINTER=/dev/tty ; export PRINTER
If you want the report to go to the console under Windows, set the following synonym:
PRINTER=CON
Installing the Utility Programs

The RM/COBOL installation section (see the appropriate installation and system
considerations chapter of this user’s guide for your specific operating system) contains
complete instructions on installing the utility programs. If you did not install the utilities
when you installed RM/COBOL, refer to these instructions.
Where necessary, compile the utility programs with the RM/COBOL Compile
Command, rmcobol.

General Considerations
Indexed File Conversion Utilities (rmifca and
rmifcb)
The rmifca and rmifcb utilities convert an RM/COBOL (74) version 1 or version 2
indexed file to the RM/COBOL format.
rmifca and rmifcb require the following:
1. RM/COBOL compiler and runtime system.
2. Object file rmifca.cob.
3. Source file rmifcb.cbl.
4. RM/COBOL (74) version 1 or version 2 indexed file to be converted.
5. Available disk space for the creation of the new RM/COBOL indexed file. The new
file size typically will be smaller than or equal to the original.
Indexed File Naming Conventions

RM/COBOL (74) version 1 and RM/COBOL maintain data and index information in a
single file. No special index file naming conventions are required.
RM/COBOL (74) version 2 supports a dual-file format. In the dual-file format, both the
data file and the index file (which contains both header and indexes) have the same name.
The data file has the default filename extension, and the index file always has a filename
extension of .inx. For example, if the data filename is inxfl.dat, the file that contains the
header and indexes is named inxfl.inx. This requires that you make certain you include
the .inx filename extension when specifying a version 2, dual-file indexed file format.
Using the Utility

Follow these steps to convert RM/COBOL (74) versions 1 and 2 indexed files to
RM/COBOL format:
1. Execute rmifca using the following command:
runcobol rmifca
The program will prompt for the information required to convert the file.
G-4 Utilities
Indexed File Conversion Utilities (rmifca and rmifcb)
2. In response to the first prompt, enter the name of the indexed file to be converted. If
you are converting a version 2 indexed file, be sure to include the .inx filename
extension as part of the filename.
If you specify a version 2 dual-file indexed file, you will be requested to enter the
filename of the data file portion of the indexed file.
3. The next prompts deal with the BLOCK and RECORD sizes. In order to answer
correctly, you may need to refer to the RM/COBOL (74) source program in which
the file is described.
a. Describe the BLOCK CONTAINS clause. Enter the number of RECORDS or

CHARACTERS in the block, and indicate whether the number you entered
applies to RECORDS or CHARACTERS.
b. Describe the RECORD CONTAINS clause. If the file you are converting is a
version 2 indexed file, the maximum record length will be filled in. You need
only specify the minimum record size if it is a variable-length record. If the file
you are converting is a version 1 indexed file, you must specify both the
minimum and maximum record sizes.
c. Enter the name of the RM/COBOL indexed file to be created.
Once all the information has been supplied, rmifca generates the copy files necessary
to describe the conversion process to the actual conversion utility rmifcb.
4. Compile and execute rmifcb. The program displays what it is going to do and asks
for confirmation to proceed. The program attempts to estimate processing time.
rmifcb.cob can be renamed and saved for use as a standalone conversion program
for versions 1 and 2 indexed files. If you are an application developer, this should
ease the process of getting your users converted from a version 1 or version 2 system
to the current RM/COBOL environment.
The process described above applies only to copying data records from RM/COBOL
(74) version 1 or 2 to RM/COBOL indexed files on an “as is” basis. However, since
each data record is available during the execution of rmifcb, you may wish to
customize a copy of rmifcb to provide data conversions, such as changing separate
signs to combined signs on numeric USAGE display items. Comments in the source
file rmifcb.cbl suggest where customized code may be placed.

Indexed File Conversion Utilities (rmifca and rmifcb)
Relative File Conversion Utility: Version 1.5
to RM/COBOL (rmcrl1)
The rmcrl1 utility converts RM/COBOL (74) version 1.5 relative files to the
RM/COBOL format.
Using the Utility

To convert a version 1.5 relative file to the RM/COBOL format, follow these steps:
1. Copy rmcrl1.cbl from the installation directory to a working directory.
2. Edit the source program, replacing—where indicated—the record size for the
RM/COBOL (74) version 1.5 input and the RM/COBOL output relative files.
3. Enter the RM/COBOL Compile Command (rmcobol) to compile the program.
4. Under UNIX, set environment variables to assign file pathnames for the version 1.5
relative file to INPUT, and the RM/COBOL relative file to OUTPUT. For example:
INPUT=/dir1/rel1.5 ; export INPUT
OUTPUT=/dir2/rel85 ; export OUTPUT
Under Windows, use synonyms to assign the file pathnames. Setting synonyms is
described in Chapter 3, Installation and System Considerations for Windows.
Note The source RM/COBOL (74) version 1 pathname and destination

RM/COBOL pathname must specify different files, that is, the conversion cannot be
made in place.
5. Enter the RM/COBOL Runtime Command (runcobol) to execute the program.
G-6 Utilities
Relative File Conversion Utility: Version 1.5 to RM/COBOL (rmcrl1)
Relative File Conversion Utility: Version 2 to
RM/COBOL (rmcrl2)
There are two source programs for converting version 2 relative files: rmcrl2l.cbl and
rmcrl2s.cbl. These programs can be used to convert RM/COBOL (74) version 2 relative
files to RM/COBOL format. rmcrl2s.cbl converts files with record sizes less than 512
bytes. rmcrl2l.cbl converts files with larger record sizes.
Using the Utility

To convert a version 2 relative file to RM/COBOL format, follow these steps:
1. Copy the appropriate source program from the installation directory to a working
directory.
2. Edit the source program, replacing—where indicated—the record size for the
RM/COBOL (74) version 2 input and the RM/COBOL output relative files.
3. Enter the RM/COBOL Compile Command (rmcobol) to compile the program.
4. Under UNIX, set environment variables to assign the file pathnames for the
version 2 relative file to INPUT, and the RM/COBOL relative file to OUTPUT. For
example:
INPUT=/dir1/rel2.0 ; export INPUT
OUTPUT=/dir2/rel85 ; export OUTPUT
Under Windows, use synonyms to assign the file pathnames. Setting synonyms is
described in Chapter 3 of this user’s guide.

made in place.
5. Enter the RM/COBOL Runtime Command (runcobol) to execute the program.

Relative File Conversion Utility: Version 2 to RM/COBOL (rmcrl2)
Sequential File Conversion Utility (rmcseq)
Variable-length binary sequential files must be converted from RM/COBOL (74)
version 2 format to RM/COBOL format. Line sequential and fixed-length binary
sequential files do not require conversion. These files may be used directly by
RM/COBOL programs. See the appropriate installation and system considerations
chapter for your specific operating system to determine which of the sequential files are
variable-length binary sequential files.
Using the Utility

1. Execute the rmcseq.cob program using the following command:
runcobol rmcseq
2. Respond to the first prompt by entering an I to indicate an Intel (reversed byte)

format, or an N (not reversed) to indicate all others. Check your hardware operations
manual if you are unsure which response is appropriate.
3. Respond to the second prompt by entering the properly qualified pathname of the
RM/COBOL (74) version 2 variable-length binary sequential file to be converted.
4. Respond to the third prompt by entering the pathname of the RM/COBOL

variable-length binary sequential file to be produced.
5. The program should then execute, displaying a count of the records being converted.
If conversion terminates without error, the following message appears:
Convert file complete
Other messages indicate an error in conversion, most likely caused by an attempt to

convert a file that is not a variable-length binary sequential file.

made in place.
G-8 Utilities
Sequential File Conversion Utility (rmcseq)
Combine Program Utility (rmpgmcom)
The rmpgmcom utility combines multiple RM/COBOL object files into a single program
file library. RM/COBOL allows programs to be placed in the same file. This simplifies
software distribution and provides a more consistent and logical representation of
software. The rmpgmcom utility builds a Table of Contents (TOC) at the end of the
output program file library. A Table of Contents speeds up runcobol library initialization
while very slightly increasing the size of the library file.
The compiler allows several source programs to be contained in the same file. The
program file generated has as many object files as the source file defines. rmpgmcom,
on the other hand, allows source modules to be contained in separate files, and the
contents of the resulting object files to be combined into one file.
rmpgmcom.cob is required to use this utility. This file is delivered in object form.
Using the Utility

The Combine Program utility is executed with this command:
runcobol rmpgmcom [ A= '[PRINTER,] [STRIP,] out-file,

file-1 [ , file-2, … , file-n ] ' ]
PRINTER, if present, requests a copy of the report to be written to the printer

specified with the synonym, PRINTER.
STRIP, if present, removes COBOL symbol table and debug line table information,
produced by the compiler Y Option, from object files. This is useful to reduce the
size of a program library after debugging is complete.
out-file is the name of the new program file being created. If a filename extension is
not specified, .cob is used.
file-1, file-2, . . ., file-n are the names of the program files being combined to form
out-file. For each name, if a filename extension is not specified, .cob is used. If the
file does not exist with a filename extension of .cob, the name is used with no
filename extension.
If the argument list is not specified, rmpgmcom prompts first for whether or not to copy
the report to the PRINTER, second for the STRIP option, third for the output filename,
and then for the input filenames. rmpgmcom adds the programs in each input file to the

output file, and then prompts for another input file. To terminate the program, press Enter
without typing a name when prompted for an input file.
If the filenames are specified through the command line, the command line argument is
limited to no more than 100 characters. Combining more than 100 characters of
filenames requires direct operator input, use of input redirection, or multiple executions of
the program.
As a precaution, if the output file exists before execution, rmpgmcom terminates,

preventing accidental erasure of a good program file.
In most cases, an error does not terminate the program. If the program terminates
abnormally, assume that the output file is not in a valid state and cannot be used to
execute programs.
The same program name can occur in more than one input program file. If this is the
case, rmpgmcom uses the first one encountered and ignores subsequent programs with
the same names. This can be very useful when you want to replace one program in a
program file with a new version. Instead of having to recreate the file, you could use
commands similar to the following.
Note rmpgmcom can combine more than 500 programs, but only the first 500 are
guaranteed to have unique names. You may want to limit your program libraries to no
more than 500 programs for this reason.
For UNIX:
mv rmutil.lib, rmutil.bak
For Windows, use the Explorer or open a DOS box and use:
RENAME rmutil.lib rmutil.bak
For all operating systems:
runcobol rmpgmcom A='rmutil.lib, rmmappgm.cob, rmutil.bak'
rmutil.bak is the name of a program file containing multiple programs (including

rmmappgm.cob).
rmmappgm.cob is the name of the program file containing the program to be updated.
rmmappgm.cob is loaded into rmutil.lib, after which the programs in rmutil.bak (which
is the previous version of rmutil.lib) are loaded into rmutil.lib. The previous version of
rmmappgm.cob in rmutil.bak is ignored.
G-10 Utilities
Execution of Programs Within Libraries
To execute programs within the created library, the L Runtime Command Option is used.
For example:
runcobol rmmappgm L=rmutil.lib
Refer to Chapter 7, Running, for additional information.
Examples
Here is sample input to rmpgmcom:

Copy to PRINTER (y/n)? Y
Output File: rmutil.lib
Input File: rmmappgm
The following programs are copied from rmmappgm.cob:
MAP-PGM 1999/03/21 14:42:05
Input File: rmpgmcom
The following programs are copied from rmpgmcom.cob:
PGM-COM 1999/03/21 14:37:15
Input File: rmmapinx
The following programs are copied from rmmapinx.cob:
MAP-INX 1999/03/21 14:40:26
Input File: rmdefinx
The following programs are copied from rmdefinx.cob:
DEF-INX 1999/03/21 14:39:36
Input File: (press ENTER)
Here is sample output from rmpgmcom.

The following programs are copied from rmmappgm.cob:
MAP-PGM 1999/03/21 14:42:05
The following programs are copied from rmpgmcom.cob:
PGM-COM 1999/03/21 14:37:15
The following programs are copied from rmmapinx.cob:
MAP-INX 1999/03/21 14:40:26
The following programs are copied from rmdefinx.cob:
DEF-INX 1999/03/21 14:39:36

The rmpgmcom utility allows for redirected input under UNIX. To redirect the input,
follow these steps.
1. At the command line under UNIX, enter:
ls *.cob > file.txt
where file.txt is a valid file access name.
2. Edit file.txt using any text editor and enter Y (Yes) or N (No) as the first line of the
file. (A response of Y requests a copy of the report to be written to the PRINTER.)
Add the library name as the second line of the file.
3. At the command line prompt, enter:
runcobol rmpgmcom < file.txt
Map Program File Utility (rmmappgm)

The rmmappgm utility reports information related to the object file created by the
RM/COBOL compiler and the program library created by the rmpgmcom utility. This
utility reports on all unnested programs contained in an object file and reports when a
program library Table of Contents (TOC) is present. It also reports when a program is a
demo version.
rmmappgm.cob is required to use the mapping utility. The file is delivered in object
form.
Using the Utility

The Map Program File utility is executed with this command:
runcobol rmmappgm [A='file-name [, PRINTER]']
file-name is the name of the program file to be processed. If no filename extension is

specified, .cob is used. If the file does not exist with a filename extension of .cob,
the name is used with no filename extension.

G-12 Utilities
If the argument list is not specified, rmmappgm prompts first for the name of a file to be
processed and then prompts for whether or not to copy the report to the printer. This
continues after each report until you press Enter without typing a name.
The report generated by this program is always written to the screen and is also written to
the printer only if the PRINTER option is specified. The information in the report is as
follows:
PROGRAM NAME Corresponds to the PROGRAM-ID value of the program.
SIZES Indicates the size in bytes of the memory needed for the fixed
procedure area, the data area, and the overlay area, as well as
the total of these three.
# ARG Indicates the number of arguments required by the program.
# FILE Indicates the number of data files defined in the program,

including any nested programs.
COMPILED Indicates the date and time the program was compiled, the
compiler options chosen, as well as the version of the compiler
used and the operating system under which the program was
compiled.
OBJ VERS Indicates the object version of the program (see Appendix H,
Object Versions, for details).
Examples
Here is sample input to rmmappgm.
Object File: rmmappgm.cob

Object File: (press ENTER)
Here is a partial sample of output from rmmappgm.

-----------SIZES----------- # # --------------------COMPILED---------------------------OBJ
PROGRAM NAME PROCEDURE DATA OVLY TOTAL ARG FILE DATE TIME VERSION SYSTEM OPTS VERS
File: rmmappgm.cob
RMMAPPGM 2170 1778 0 3948 1 2 1999/03/21 12:10:15 RM/COBOL 7.0n.00 Windows E 7

Map Indexed File Utility (rmmapinx)
The rmmapinx utility reports information related to an indexed file.
Note In order to report information related to a Btrieve file, use the Btrieve File
Manager (either the Windows interactive version, wbmanage.exe, or the command line
version, butil.exe). Refer to the Btrieve for Windows NT/Windows 95/Windows 98
Installation and Operation manual for complete information about the utility.
Using the Utility

The Map Indexed File utility is executed with the following command:
runcobol rmmapinx [A='file-name [, DETAIL][, PRINTER]']
file-name is the name of the file to be mapped.
DETAIL, if present, requests a more detailed report.

If the optional information is not specified, you are prompted for file-name, DETAIL, and
PRINTER, as follows:
Indexed File:
Detail Information (y/n)?
Copy to PRINTER (y/n)?
Enter the name of the file to be used in response to the first prompt line. A response of Y
to the second prompt requests detailed information (described in the “Detailed
Information Report” section on page G-16) for the file. A response of N requests only the
basic information (see the following paragraphs). When in prompt mode, the user is
prompted again after each file report is processed. To exit the program when in prompt
mode, press Enter without typing a name when prompted for a filename. A response of Y
to the third prompt requests a copy of the report to be written to the printer.
G-14 Utilities
Basic File Information Display
Basic file information is always reported for each existing file entered, without respect to
the presence or absence of the DETAIL option.
• File status. If the file was created by the rmdefinx program (described on
page G-19) and has never been opened for output, a file status line indicating this fact
appears. Also, if this status is indicated, only the disk block size and data and key
compression status (with compression characters) appear. Detail information,
described in the next section, is reported if the detailed report is requested.
• Record length. Record length is reported in one of two formats. For fixed-length
records, it is shown as a specific value:
Records are fixed length = size
size is the actual record size. If variable-length records are defined for the file, this is
shown as a range of values:
Records vary in length from min to max bytes
min and max are the minimum and maximum record lengths.
• Disk block size. Disk block size is the number of bytes actually allocated to one
block on disk.
• User block size. User block size is the number of records or bytes specified by the
user in the FD statement used when creating this file.
• Data compression status. Data compression status may be either compressed or

uncompressed. If compressed, the data space and zero characters also appear.
• Key compression status. Key compression status may be either compressed or

uncompressed. If compressed, the key space character also appears.
• Number of keys. This is the actual number of keys (including the prime key)
defined for the file.
• Number of segments. This is the total number of segments in all keys defined for
the file. If the file has no split keys, the number of segments is equal to the number
of keys.
• Number of records. This is the actual number of data records contained in the file.
• Number of blocks. This is the actual number of logical blocks allocated to the file.
• Number of empty blocks. This is the number of unused blocks allocated to the file.

• Number of blocks required for a rewrite. This is the maximum number of empty
blocks required if a rewrite were to relocate the modified record in the file.
• Key information. See “Key Descriptor Information Display” on page G-17.
• Last error. This is the last error received when accessing the file. It includes the
date and time the error occurred. Only errors with class of 30, or a class of 98 with a
suberror greater than 2, are remembered.
• Open For Modify Count. This is a count, held in the file, of the number of times
the file is currently open. If this count is not zero, and there are actually no current
opens, it is an indication that the file may be corrupted because of an incomplete
close operation.
Detailed Information Report

The following information is reported when the detailed report is requested, either by
specifying DETAIL in the command line when invoking the utility, or by responding Y to
the detailed report prompt.
• File version information. The file version number indicates any advanced features
used in the file. The minimum read version number and the minimum write version
number are used to prevent previous versions of RM/COBOL from reading or
modifying files with features unavailable to them.
• First unused empty block. The first unused empty block will be displayed only for
files with a version number of 2 or greater. It is the block number of an empty block
that has never been used and that is followed only by other unused empty blocks.
• File lock limit. The largest address where a lock may be applied to this file is
displayed only for files with a version number of 3 or greater. See the description of
the LARGE-FILE-LOCK-LIMIT keyword on page 10-28 for more information.
• Disk block increment. Disk block increment is the difference in the disk addresses
of consecutive blocks of the file. It is always greater than or equal to the disk block
size.
• Allocation increment. Allocation increment is the number of disk blocks that are
allocated when the file is first created and whenever the file increases in its physically
allocated size.
• Recoverability/Performance Strategy summary. This is a summary of the
recoverability and performance strategy options, either set by the runtime system
when the file was created, or set when the file was created or modified by the
rmdefinx utility (see page G-19).
G-16 Utilities
Key Descriptor Information Display
If the file has been opened for output, the attributes of each key are reported one key
segment per line. The information reported is as follows:
• Key number. The first key is labeled prime, with alternate keys numbered starting
with 1.
• Segment number. The segment number within the key. The first segment of a key
is number 1.
• Starting position. This is the position in the record where the key segment starts.
The leftmost position in a record is position 1.
• Segment length. This is the number of bytes that the key segment occupies in the
record.
• Key length. This is the total number of bytes that the entire key occupies in the
record. It is the sum of the segment lengths of all of the segments of the key. This
value is shown only on the final segment line of a split key since it applies to the
entire key.
• Tree height. This is the maximum number of disk accesses that could be required to
locate a record containing the key. Additional disk accesses may be required to read
or modify the record. This value is shown only on the final segment line of a split
key since it applies to the entire key.
• Duplicates permitted. This value is either yes or no. Yes indicates that the key
allows duplicate key values to be present. This value is shown only on the final
segment line of a split key since it applies to the entire key.
Additionally, a blank line is displayed between keys when any of the keys of the file is a
split key. If the file has no split keys, there is one line per key with no intervening blank
lines.
Examples
Here is sample input to rmmapinx. Each file listed is also described with
RM/COBOL SELECT and FD statements.
Indexed File: file1

Detail Information (y/n)? y
Indexed File: (press ENTER)

Here is sample output from rmmapinx.
RM/COBOL Map Key Utility - 7.0 03-21-1999 12:59:17 Page 1

File Information:
file1 is an Indexed File.
Records are fixed length = 134 Bytes.
Disk Block Size = 512 Bytes, User Block Size = not specified.
Data Records are compressed, Keys are compressed.
Data Block Space Character Value = 32.
Data Block Zero Character Value = 48.
Key Block Space Character Value = 32.
File has 3 Keys and 6 Segments.
File contains 1 Record and occupies 16 Blocks.
There are 11 empty Blocks.
12 empty Blocks may be needed for a rewrite.
The last error was 98,38, at 12:57 on 03-21-1999.

Open For Modify Count = 0.
Detail Information:
File version number = 3.
Minimum read version number = 3.
Minimum write version number = 3.
First unused empty block = 5.
File Lock Limit = 64 GB.
Disk Block Increment Size = 512 Bytes.
Allocation Increment = 8 Blocks.
Recoverability/Performance Strategy:
Data are forced to the system only when necessary.
Force Write Data Blocks = No.
Force Write Index Blocks = No.
Force to Disk = No.
Force File Closed = No.
Key Information:
Key Segment Starting Segment Key Tree Duplicates
Number Number Position Length Length Height Permitted?
Prime 1 1 30
Prime 2 90 5 35 1 No
1 1 31 3 3 1 No
2 1 34 10
2 2 84 6
2 3 95 20 36 1 Yes
G-18 Utilities
Define Indexed File Utility (rmdefinx)
The rmdefinx utility precreates an indexed file in order to alter the default characteristics
assigned by RM/COBOL programs. The utility also can modify some of those
characteristics on files created by RM/COBOL programs.
rmdefinx.cob is required to use the define indexed file utility. The file is delivered in
object form.
Note 1 When using the rmdefinx utility on an indexed file larger than 16 bytes,
rmdefinx must be executed with a configuration file with the following entry:
RUN-SEQ-FILES USE-LARGE-FILE-LOCK-LIMIT=YES
Note 2 In order to precreate a Btrieve file, use the Btrieve File Manager (either the
Windows interactive version, wbmanage.exe, or the command line version, butil.exe).
Refer to the Btrieve for Windows NT/Windows 95/Windows 98 Installation and Operation
manual for complete information about the utility.
Using the Utility

The Define Indexed File utility is executed by issuing the following command:
runcobol rmdefinx [A='file-name ']
file-name is the name of the file to be defined or altered.
You may omit the argument list. In this case, the program prompts for file-name in the
following manner:
Indexed File:
The name of the file to be used is supplied in response to this prompt.
File Precreation
The following prompts are issued when a file is being precreated:
Disk Block Size (in bytes):

Disk Block Increment (in bytes):
Allocation Increment (in blocks):

These queries deal with the manner in which space is allocated and used in the file. Disk
block size is the actual number of bytes used in each physical block. A physical block
size is indicated by the disk block increment size. These two sizes should be identical.
The number of blocks allocated each time more space is required in the file is controlled
by the allocation increment.
The next prompt is as follows:
Data Compression (y/n)?
This controls the amount of space taken up by logical records in the file. If you want
logical records to be stored without compression, enter N. Otherwise, enter Y, and then
respond to the following two prompts:
Space Character Value:

Zero Character Value:
These control the manner in which data compression takes place. Respond with the
decimal value of the characters to be interpreted by the compression algorithm as a space
and a zero. For example, the ASCII space and zero have decimal values of 32 and 48,
respectively; the EBCDIC space and zero have decimal values of 64 and 240,
respectively.
The next two prompts are as follows:
Key Compression (y/n)?

Space Character Value:
These queries control key compression in a manner similar to data compression, except
that only trailing spaces are compressed.
The next prompts are as follows:
Force Write Data Blocks (y/n)?

Force Write Index Blocks (y/n)?
Force to Disk (y/n)?
Force File Closed (y/n)?
These prompts determine recoverability/performance strategies for the file being

processed. To select a strategy option, enter Y in response to the appropriate prompt. To
omit a strategy option, enter N. See the discussion of data recoverability of indexed files
in Chapter 8, RM/COBOL Features.
Version number (0, 2, or 3)? 2
G-20 Utilities
This prompt sets the version number of the file. Valid version numbers are shown in the
following chart.
Version Version Version
Feature Number 0 Number 2 Number 3
Improved Empty Block List Algorithm ✔ ✔

Use LARGE-FILE-LOCK-LIMIT ✔
File Lock Limit (in GB)?
This prompt is shown only if the file version number has been set to 3. It allows you to
specify the location of the largest lock to be placed on this file. For more information,
see Chapter 10, Configuration, for descriptions of the LARGE-FILE-LOCK-LIMIT
keyword (RUN-FILES-ATTR configuration record) and the DEFAULT-FILE-
VERSION-NUMBER keyword (RUN-INDEX-FILES configuration record).
File Modification
When the file specified already exists, the utility allows you to change the allocation
increment, described previously, and offers you the option to alter the key compression,
the recoverability/performance strategy, the file version number, and the file lock limit.
The prompt to change the key compression is as follows:
Change key compression (y/n)?
If you enter Y, you are prompted for whether the key compression should be enabled and
for the value of the key compression space character, as described on the previous page.
If the key compression or the key compression space character is changed, the file is
marked as needing recovery. After you run the Indexed File Recovery utility (recover1),
described on page G-23, the indexed trees are built with the requested key compression.
If the current key compression and key compression space character are unchanged, you
are not forced to recover the index structure.
The prompt to change the recoverability or performance strategy is as follows:
Change Recoverability/Performance Strategy (y/n)?
If you enter Y, you are prompted for the four options discussed previously. If you enter
N, the strategy is unchanged.

The prompt to change the file version number is as follows:
Change file version number (y/n)?
If you enter Y, you are prompted for the file version number discussed on page G-20. If
you specify the file version number as 3, you are prompted for the file lock limit. If the
version number is changed from 0 to another version, or changed from another version
to 0, the file is marked as needing recovery, and the Indexed File Recovery utility
(recover1) must be run before the file can be used. After you run the Indexed File
Recovery utility (recover1), the empty block list is built with the correct algorithm. If the
file version number is unchanged, you are not forced to recover the empty block list.
If you attempt to change the file version number to 0 of a file that contains split keys or
duplicate prime keys, a message is displayed indicating that you cannot do so; files using
these features cannot be converted to version number 0 files. Also, files with a version
number of 3 may have grown too large to be changed back to version 0 or 2. For more
information on indexed file version numbers, see Chapter 8.
After all questions have been answered, the following prompt appears:
OK (y/n)?
If you enter Y, the file is updated and the program either terminates (if a filename was
specified on the command line) or prompts you for another filename.
Note The rmdefinx utility does not cause the file to “exist” in the COBOL sense. An
OPEN OUTPUT (or OPEN I-O or EXTEND if SELECT OPTIONAL is used) must be
successfully executed before other open modes become valid.
Example
Here is sample input to rmdefinx.

Indexed File: file1
New File.
Disk Block Size (in bytes): 1024
Disk Block Increment (in bytes): 1024
Allocation Increment (in blocks): 10
Data Compression (y/n)? n
Key Compression (y/n)? n
Define Recoverability/Performance Strategy
Force Write Data Blocks (y/n)? y
Force Write Index Blocks (y/n)? y
Force to Disk (y/n)? y
Force File Closed (y/n)? y
Set file version number
Version number (0,2, or 3)? 3
File Lock Limit (in GB)? 64
OK (y/n)? y
G-22 Utilities
Indexed File Recovery Utility (recover1)
The recover1 utility recovers data stored in an RM/COBOL indexed file. It is a
standalone program; that is, it does not require use of the Runtime Command (runcobol)
to be executed.
Note 1 In order to recover data stored in a Btrieve file, use the Btrieve File Manager
(either the Windows interactive version, wbmanage.exe, or the command line version,
butil.exe). Refer to the Btrieve for Windows NT/Windows 95/Windows 98 Installation
and Operation manual for complete information about the utility.
Note 2 Unless specifically stated otherwise, the name recover1 refers to both the UNIX
(recover1) and Windows (recover1.exe) versions of the recover1 program.
Note 3 If the output window of the Windows version of the recover1 program
disappears upon successful completion and you want that window to remain visible, set
the Persistent property to TRUE for the recover1.exe program (see page 3-24 for details).
Use of the Recover1 Program

The Indexed File Recovery utility (recover1) is executed by issuing the following
command:
recover1 file-1 file-2 [-i ] [-k [file-3 ]] [-l [file-4 ]]

[-m M B -of -m e m o r y ] [-q ] [-t ] [-y ] [-z ]
file-1 is the filename of the indexed file to be recovered.
file-2 is the name of the file where recover1 places any unrecoverable records found
in the indexed file (see page G-25).
The -i option causes recover1 to test only the file integrity and then stop. The file
will not be modified in any way. Specifying -i causes both the -t and -z options to be
ignored. If no problems are discovered, the return code is set to 0. If a problem is
discovered, the return code is set to 1.
Note The integrity scan is a quick test of the file and is not comprehensive. Some
problems, such as records with invalid duplicate keys, will not be detected. Files
with no errors detected by the integrity scan may still receive “98” errors or other
errors.
The -k option is used to indicate that the Key Information Block (KIB) should be
assumed to be invalid. If no file-3 is specified, the user will be prompted either for a

template file or for enough information to rebuild the KIB. If file-3 is specified, it
should be the name of a valid indexed file with the same format as the file being
recovered. This file will be used as a template. The required KIB information is
read from the KIB of the template. The template file can be a backup copy of the file
being recovered, if the backup occurred before the file was damaged, or, it can be a
file created by performing an OPEN OUTPUT with the proper FD. An OPEN
OUTPUT must have been performed on the template file, but it need not contain any
records. A template file must be specified if the KIB is corrupt and the file uses
either an enumerated code set or an enumerated collating sequence.
The -l option is used to write information about errors encountered while recovering
the file to the log file file-4. Only the first 100 errors will be logged. If file-4
specifies a synonym name, the synonym will be resolved before opening the log file;
this allows the use of the name PRINTER to send the log information to the print
device. The default value of file-4 is PRINTER.
The –m option specifies the number of megabytes of memory to allocate to the sort
algorithm used in phase 4, build node blocks (see page G-25). Allocating more
memory generally results in faster execution of recover1 and causes fewer node
blocks to be built. If this option is not specified, a suitable number will be computed.
The minimum value is 0 which requests that a minimum amount of memory be used.
The maximum value is 100. Note Specifying a number that is too large for your
system may result in very poor system performance.
The -t option is used to indicate that unused space should be truncated, and returned
to the operating system. Note Some versions of UNIX do not support the operating
system call required to truncate a file.
The -q option causes recover1 to perform its work without displaying information or
asking the operator questions. If the file is marked as needing recovery, or has a non-
zero Open For Modify Count (see “Basic File Information Display” on page G-15),
then it will be recovered. Otherwise, no action occurs. This behavior can be
modified by using the -y option.
The -y option causes recover1 to assume that the operator wants to answer “y” to all
possible questions and therefore does not stop to wait for a response. Using the “-y”
option will cause a file to be recovered even if it is not marked for recovery.
The -z option is used to reset the Open For Modify Count to zero (see “Basic File
Information Display” on page G-15), without performing a full recovery. If the file is
marked as needing recovery, this option is ignored. Note Use the -z option with
caution. Resetting the Open For Modify Count to zero without performing a full
recovery may leave the file in a corrupted state.
If the recover1 program is successful, the exit code is set to 0. If the recover1 program
is canceled by the operator, the exit code is set to 2. Otherwise, the exit code is set to 1.
G-24 Utilities
The recover1 program attempts to recover the indexed file in place; that is, the program
rebuilds the internal file structure in the actual file being recovered. If necessary, the Key
Information Block (KIB) is rebuilt and any corrupted data blocks are repaired. Corrupt
data blocks may result in loss of some data records. Because of this feature, it is strongly
recommended that you either backup the file or copy the indexed file to be recovered to
some other directory or pathname as additional security. Any records that cannot be
successfully reindexed into the file due to invalid duplicate key values, or invalid record
sizes, are decompressed (if compression is selected for the file), converted to the native
code set, and then written to file-2. recover1 should be able to handle most kinds of
indexed file corruption problems, but some fatal errors may still cause the recovery to
fail. Any fatal error is displayed and causes the program to terminate. Broken hardware
should be suspected in many of these cases.
file-2 can be in fixed- or variable-length format; this is set by recover1 based on whether
file-1 is fixed- or variable-length format. Records placed in file-2 were those undergoing
change at the time of the system failure that required recovery or have invalid record
sizes. Investigate any records appearing in file-2 and make the appropriate corrections to
file-1.
The recover1 program's processing consists of up to four separate phases, which are run
in the following order:
1. Integrity Scan. If the -q option or -y option is specified, the Integrity Scan phase is
disregarded unless it is forced to occur by the specification of the -i option or -l
option. This phase reads the entire file in a forward direction checking for simple
errors, and produces a summary report showing the state of the file and an estimate of
the number of records recover1 can recover. The indexed file is not modified during
this phase.
2. Repair Blocks. The Repair Blocks phase, which is always run, reads and writes the
file in a backward direction repairing corrupt data blocks, converting non-data blocks
to empty blocks, and rebuilding some internal file structures.
3. Move Data Blocks. The Move Data Blocks phase is run only when the truncate
file option (-t) is specified. This phase reads and writes parts of the file moving
high-numbered data blocks (near the end of the file) to lower-numbered available
blocks to maximize the amount of space at the end of the file that can be truncated
and returned to the operating system when recover1 finishes.
4. Build Node Blocks. The Build Node Blocks phase, which is always run, reads data
blocks and writes node blocks in the file in a forward direction rebuilding the entire
node structure for each key of the file.

Note 1 After the Integrity Scan phase, if the Estimated Recoverable records value is zero
or very low, and the number of corrupt data blocks is very close to the total number of
data blocks found, the number of keys that allow duplicates may be incorrect, either
because the KIB is corrupt or the user provided incorrect key information to recover1.
Note 2 After the Integrity Scan phase, if most of the blocks are invalid, the Disk Block
Size or the Disk Block Increment may have been incorrectly specified or the KIB may be
corrupt.
Note 3 During the Repair Blocks phase, a count of blocks which could be read but not
written may be displayed. This count may indicate the presence of a hardware problem
with your disk.
Recover1 Message File Processing Errors

During initialization, the recover1 utility locates and reads its message file. If it cannot
find its message file or the message file is corrupt, one of the following messages appears:

The recover1 utility compares its version number and product code with those in the
message file. If they do not match, one or both of the following messages appears:
Recover1: Message file version mismatch, expected 7.0n.nn, found n.nn.nn

Recover1: Message file product mismatch, expected XX, found YY
When any of the above messages appear, the recover1 utility terminates with the
following message:
Error invoking mismatched recover1 and message file.
The recover1 utility message file may have the wrong name or be in the wrong directory.
The recover1 utility message file must have the name rec.msg (REC.MSG under
UNIX). The recover1 utility attempts to find the message file in the directory that
contains the recover1 executable file, the current directory, or through the PATH
directory search sequence (see page 2-4 for UNIX or page 3-11 for Windows).
Note On some versions of UNIX, it is impossible to determine which directory contains

the executable file when that directory is specified on the command line.
G-26 Utilities
Example
An example run through the Indexed File Recovery utility is described in Figures G-1
through G-4. The recovery session is started in this example by the following command:
recover1 master.inx dropout1
Figure G-1 on page G-28 shows information about the file master.inx.
Under the name of the file to be recovered, a description of the state of the file is
displayed. Any of the following messages may appear:
• This file has not been marked as needing recovery!
• The Open For Modify Count for this file is not zero: count
• File has been marked as corrupted due to a previous error.
• KIB is corrupt. Using template file: file-3
• KIB is corrupt. Enter a template filename (press Enter for manual entry).
If the KIB is corrupt, and a template filename is not entered, recover1 will prompt the
user for the required KIB information before continuing.
If more keys exist than can appear on this screen, as many as possible appear, after which
you are asked if you want to see the remaining key descriptors. This continues until all
keys are shown. You are then asked to verify that this is the file you want to recover.
Entering N terminates the program. Entering Y continues the program.

Figure G-1 Indexed File Recovery Utility: File Recovery Verification
Indexed File Recovery Utility

Recover1 Version 7.0n.00
Index File: master.inx

This file has not been marked as needing recovery!
Disk Block Size: 498 Minimum Record Length: 80

Disk Block Increment: 498 Maximum Record Length: 80
Number of Index Blocks: 170 Number of Records: 150
Key Position Size Remarks

PRIME 1 8
1 9 8
2 17 8 duplicates allowed
Is this the file you wish to recover (y/n)?
G-28 Utilities
Figure G-2 shows a summary of the information that is gathered during the file integrity
scan. You are then asked if you would like to proceed with the recovery process.
Entering N terminates the program. Entering Y continues the program.
The "Average record length" is computed by adding the length of all the records in the
file and dividing by the number of records. The "Average data size" is computed by
adding the size that the record actually occupies in the file and dividing by the number of
records. This size allows you to determine how much your data can be compressed.
Figure G-2 Indexed File Recovery Utility: recover1 Summary


Drop File: dropout1

Phase: Integrity Scan Estimated Recoverable: 150
| Total | Total | First | Last |

Block Type | Found | Corrupt | Corrupt | Corrupt |
KIB | 1 | 0 | | |
Data | 102 | 0 | | |
Node | 61 | 0 | | |
Empty | 6 | 0 | | |
Invalid | 0 | 0 | | |
Unreadable | 0 | 0 | | |
Average data size: 14, Average record length: 80
Do you wish to proceed with recovery (y/n)?

Figure G-3 shows the information that is displayed while recover1 is rebuilding the node
blocks for the prime key.
Figure G-3 Indexed File Recovery Utility: recover1 Statistics


Drop File: dropout1

Phase: Build Node Blocks Estimated Recoverable: 150
Key being processed: PRIME

Records recovered: 100
Records written to drop file:
Block being processed: 13
Number of data blocks moved (for truncate): 5
G-30 Utilities
Figure G-4 shows the information that is displayed after recover1 terminates
successfully. The two lines regarding truncation are shown only when the -t option is
specified.
Figure G-4 Indexed File Recovery Utility: recover1 Finished Successfully


Drop File: dropped

Phase: Build Node Blocks Estimated Recoverable: 100
Key being processed: PRIME

Records recovered: 100
Records written to drop file:
Block being processed: 120
Truncate option specified - number of data blocks moved: 4
Truncate action successful - new Number of Index Blocks: 112
Recovery successful.

In the example shown in Figure G-5, the KIB of the file has been corrupted, and key
information must be entered for the file to be recovered. Key information can be obtained
from the output of the Map Indexed File utility (see page G-14 for more information).
Underlined characters have been entered by the user.
The recovery session is started by the following command:
recover1 master.inx dropout1 -k
Note Entering incorrect information about how many keys, or which keys, can have
duplicate values may cause unpredictable results.
Figure G-5 Indexed File Recovery Utility: Entering Key Information

Last error was 98,38 at 9:29 on 03-21-1999
Are any of the keys in this file segmented (split) (y/n)? y

Key #: PRIME Segment #: 2 Starting Position? 10 Length? 5
Another Segment (y/n)? n
Total Key Length = 13 Duplicates Permitted (y/n)? n
Another Key (y/n)? n
G-32 Utilities
Figure G-6 shows an example of entering the remainder of the KIB information.
Underlined characters have been entered by the user.
Figure G-6 Indexed File Recovery Utility: Entering KIB Information

Last error was 98,38 at 9:29 on 03-21-1999
Minimum Record Length (in bytes)? 80
Maximum Record Length (in bytes)? 80
Disk Block Size (in bytes)? 498
Data Compression (y/n)? y Space Character Value? 32 Zero Character Value? 48
Key Compression (y/n)? y Space Character Value? 32
File Version Number (0, 2, or 3)? 2
Disk Block Increment (in bytes)? 498
Allocation Increment (in blocks)? 8
Force Write Data Blocks (y/n)? n Force Write Index Blocks (y/n)? n
Force to Disk (y/n)? n Force File Closed (y/n)? n
Code Set (1=none/2=ASCII/3=EBCDIC)? 1
Collating Sequence (1=none/2=ASCII/3=EBCDIC)? 1
Is this information correct (y/n)? y
After the key and KIB information has been successfully entered, the recovery process
proceeds the same as before, beginning with , as illustrated in Figure G-1 on page G-28.
If a template file had been specified on the command line or a template filename had been
entered when prompted, the screens prompting for the key and KIB information would
not have been displayed. A template file must be specified if the KIB is corrupt and the
file uses either an enumerated code set or an enumerated collating sequence.

Recover1 Program Error Messages
Error status initializing file manager
recover1 was unable to initialize the RM/COBOL file management system for the reason
indicated by status. The usual cause for this error is that a buffer pool has been
configured that is too large to be allocated. See the BUFFER-POOL-SIZE keyword of
the RUN-FILES-ATTR configuration record on page 10-26 for instructions on changing
the buffer pool size.
Truncate option not supported
recover1 detected that the truncated function was not supported on the system when the
user requested file truncation. Truncation of the file is not possible.
recovery terminating - no records recoverable!
recover1 detected corruption in the indexed file and no records could be recovered. In
this case, recover1 terminates at the end of the integrity scan to protect the user from
erroneously deleting all the records from the file. This error may indicate that the block
size, the block size increment, or the number of keys that allow duplicates has been
incorrectly specified or the KIB may be corrupt.
Error status on template file
recover 1 detected an error in the KIB of the template file specified by the user. The user
may enter another template file, may enter the KIB information manually, or may enter a
Ctrl-C to terminate recover 1.
Cannot write near end of file - check "ulimit"
recover1 detected that blocks near the end of the file can be read but not written, but
other blocks of the file may be both read and written. This error may indicate that the
operating system file size limit (ulimit) may be smaller than the size of the file. Correctly
set the file size limit or use an account with sufficient privileges and run recover1 again.
G-34 Utilities
Standalone Use of the Recover2 Program
The recover2 utility program can be used to unload an indexed file to a sequential file.
The recover2 program is no longer needed to recover indexed files. It is invoked by
entering the command:
runcobol recover2 K [A='file-1 [, [file-2 ][,option ]']
file-1 is the filename of the indexed file to be unloaded. recover2 does not use the
directory search sequence to locate file-1.
file-2 is the filename of the sequential file into which recover2 unloads the indexed
file records.
option can be either SUB or NOSUB, depending on whether or not you want
recover2 to trust the overhead information in the file. NOSUB indicates that the
overhead information in the indexed file (record size, block size, and so forth) is
correct and can be used to unload the file. SUB indicates that the overhead
information may not be correct and needs to be verified and possibly altered. The
overhead information appears and you are given the opportunity to alter the
information before processing of the file begins. You must enter the value for the
"Number of Keys that allow Duplicates".
file-1, file-2 and option can be omitted, and recover2 prompts you for a value.
For example, entering the command:

runcobol recover2 K A='file-1, option'
causes recover2 to prompt you for the file-2 filename. Entering the command:
runcobol recover2 K A='file-1, file-2'
causes recover2 to prompt you for the option to use.
recover2 also produces a log duplicating the overhead information appearing on the
screen to the printer specified with the synonym, PRINTER.
If an error occurs, recover2 displays a message, then continues to attempt to recover the
file. The exit code is set to 1.
If no errors occur, the recovery is successful and the exit code is set to 0.

Figure G-7 shows the main screen associated with the data unload program (recover2).
In the first attempt, the NOSUB Option is specified and all of the fields shown are filled
in by the program. If the file cannot be unloaded with the NOSUB Option, an error
message appears and a second attempt is made with the SUB Option specified, causing
recover2 to prompt you for the values by first displaying what is in the file. To select the
displayed value, press Enter or Tab. Otherwise, type a new value and press Enter.
Note When using the SUB Option, the value for the number of keys that allow
duplicates must be entered by the user since there is no default.
Figure G-7 Indexed File Recovery Utility: recover2 Main Screen
Copy all data records to dropped record file

Drop File: drop
Option: nosub
Disk Block Size: 498 Maximum Record Length: 80

Disk Block Increment: 498 Minimum Record Length: 80
Number of Keys that allow Duplicates: 1
Data Record Compression (y/n)? Y
SPACE Character Value: 32
ZERO Character Value: 48
Records Written to Drop File:
Block being Processed: 8
G-36 Utilities
Figure G-8 shows the OK prompt you see during the second attempt. Responding N to
this prompt causes the program to restart the prompts for file information. Responding Y
indicates that secondary data recovery should start.
Figure G-8 Indexed File Recovery Utility: Secondary Recovery
Copy all data records to dropped record file

Drop File: drop
Option: sub
Disk Block Size: 498 Maximum Record Length: 80

Disk Block Increment: 498 Minimum Record Length: 80
Number of Keys that allow Duplicates: 1
Data Record Compression (y/n)? Y
SPACE Character Value: 32
ZERO Character Value: 48
Record Written to Drop File:
Block being Processed:
OK (y/n)?
Recover2 Program Error Messages
File: index-filename - Open Error status.
recover2 was unable to open the indexed file for the reason indicated by status. The
execution of recover2 terminates.
File: index-filename - Input Error status.
recover2 encountered the error indicated by status while reading the indexed file. If the
NOSUB Option was chosen, execution terminates. If the SUB Option was chosen, the
operator is given the option to continue execution.
File: index-filename - Premature end of file encountered.
recover2 encountered the end of file in an unexpected place while reading the indexed
file, and recover2 may reasonably recover. If the SUB Option was chosen, the operator
may be given the option to continue. Otherwise, execution terminates.

File: index-filename - File has never been opened for output.
The indexed file has never been opened for output and therefore cannot contain any data
records.
File: index-filename - may not be an Indexed file.
The overhead structures in the indexed file are not consistent. If the NOSUB Option was
chosen, execution terminates. If the SUB Option was chosen, the operator may continue
execution. Values that appear for block size and record size should be carefully verified.
File: index-filename - Block Size is too big for recover2 program.
The block size specified is larger than 65280 bytes, which is the largest block size
supported by recover2. Execution terminates.
File: index-filename - Invalid compressed data

in block/record block number/record-label.
recover2 has encountered a compressed data record that is inconsistent with the version
of recover2 being executed or with the compressed data record length. The indicated
record and subsequent records in the block are not written to the unload file. Processing
continues with the next block.
File: index-filename - Record length mismatch.
The minimum record size is greater than the maximum record size or the block size is too
small for the worst-case record size (due to data compression). It is checked when the
NOSUB Option is chosen. Execution terminates.
File: index-filename - Bad block overhead in block block number.
recover2 has encountered a data block with inconsistent overhead structures. No records
from the block are written to the unload file. Processing continues with the next block.
File: index-filename - Bad record overhead

after block/record block number/record label.
recover2 has encountered a data record with inconsistent overhead structures. Any
records in the block subsequent to the indicated record are not written to the unload file.
Processing continues with the next block.
G-38 Utilities
File: index-filename - Record size {< minimum | > maximum}
for block/record block number/record label.
recover2 has encountered a data record that does not conform to the constraints of
minimum or maximum record length but is otherwise consistent. The indicated record is
written to the unload file. Processing continues with the next record.
File: unload-filename - Record Size is too big for recovery program.
The maximum record length specified is too large for recover2. The maximum record
length is 65280 bytes. Execution terminates.
File: unload-filename Error: status.
The indicated error was encountered during an I/O operation on the unload file.
Execution terminates.
Attach Configuration Utility (rmattach)

The Attach Configuration utility (rmattach) attaches a configuration file (described in
Chapter 10) to an RM/COBOL command processor .exe file and creates a new command
processor file. The following processors can be configured in this manner:
• runtime system (runcobol.exe)
• compiler (rmcobol.exe)
• Indexed File Recovery utility (recover1.exe)
Note The rmattach utility will work only with the Windows version of RM/COBOL.
Using the Utility

The rmattach utility is executed with this command:
rmattach input-exe-file output-exe-file config-file
input-exe-file is the name of the command processor file to be configured. This file
will not be modified.
Note The RUNPATH directory search sequence is not used to open this file. If
input-exe-file is not in the current directory, the entire pathname must be entered.

Attach Configuration Utility (rmattach)
output-exe-file is the name of the newly configured .exe file. If a file with the same
name already exists, it is overwritten. output-exe-file must not have the same name
as that specified for input-exe-file. output-exe-file should have a filename extension
of .exe.
config-file is the name of a line sequential file containing the desired configuration
records (see Chapter 10). If a configuration file is already attached to input-exe-file,
it will be replaced by the contents of config-file.
rmattach does no syntax checking of the configuration file. The .exe file will diagnose
errors during its initialization.
Here is an example of an rmattach command:
rmattach runcobol.exe runcfg.exe setting.cfg
Initialization File to Windows Registry

Conversion Utility (ini2reg)
The Initialization File to Windows Registry Conversion utility (ini2reg) converts an
RM/COBOL Windows initialization file (.ini) and places its contents into the Windows
registry database.
Previous versions of RM/COBOL stored program configuration information for the

compiler, runtime, and Indexed File Recovery utility (recover1.exe) programs in .ini
files. Beginning with version 6.5, RM/COBOL uses the Windows registry database to
store this information. With this utility, earlier .ini files can be converted and current
initialization information can be distributed to users via a .reg file that can be exported
from the Windows registry database.
Note This utility is available only under Windows.
Using the Utility

The ini2reg utility is executed by clicking on the INI to Registry icon or typing
the command:
ini2reg [-q ] [file-name ]
G-40 Utilities
Initialization File to Windows Registry Conversion Utility (ini2reg)
By default, the ini2reg utility program converts text in the initialization file from the
OEM character set to the ANSI character set. If the initialization file already used an
ANSI character set, use the -q option to disable this conversion.
file-name is the name of the initialization file to be merged into the Windows registry
database. If no file is specified, an Open File dialog box appears in order to browse
the file system for the proper file. file-name must be specified with a proper path.
This utility does not search the PATH or RUNPATH environment variables.
RM/COBOL Configuration Utility (rmconfig)

The RM/COBOL Configuration utility (rmconfig) provides a way to modify the
configuration options for one or more COBOL programs. These options are specific to
the RM/COBOL system running under Windows.
A modified version of the rmconfig property sheet can be displayed for a single COBOL
program by right-clicking the program icon, Registry Configuration, and choosing
Properties.
Note This utility is available only under Windows.
Using the Utility

The rmconfig utility is executed by clicking on the Registry Configuration icon or typing
the command:
rmconfig [-r |-c |-1 ] [file ]
-r indicates that you will be configuring properties to be used while running

programs.
-c indicates that you will be configuring properties to be used while compiling

programs.
-1 indicates that you will be configuring properties to be used while recovering data
files with recover1.exe (see page G-23).
file is the name of the file that you wish to configure.

Figure G-9 shows the rmconfig.exe tab of the Properties dialog box. The Select File tab
allows the specification of configuration options for a certain COBOL program
(Individual File option) or for all programs (Default Properties option). Changes made on
the other Properties tabs will affect the configuration of the program or programs selected
here. See Chapter 3, Installation and System Considerations for Microsoft Windows, for
descriptions of the other Properties tabs.
Figure G-9 Select File Tab
G-42 Utilities
Appendix H: Object Versions
This appendix lists the new object features that are incompatible with earlier releases of
RM/COBOL-8X and RM/COBOL.
Level Numbers
The object version level number in a RM/COBOL object file identifies the earliest release
of the RM/COBOL product that supports the features required by the program. The set of
features available in the first release of the product, RM/COBOL-8X, has been assigned
object version 1. When new features have been added in subsequent releases of
RM/COBOL, these have been assigned successive object version numbers. The
RM/COBOL compiler marks each object file with the object version number of the latest
features actually used in the source program.
Every release of the RM/COBOL runtime system supports features up to some object
version level. Object files with a higher object version level number cannot be run.
When a program is named in the Runtime Command or in a CALL statement, the runtime
system searches for an object file containing a program with the specified name. If during
this search, the runtime system finds an object program that has an object version level
number which exceeds that accepted by the runtime system, that object program is not
considered valid and the runtime system continues its search. If no valid program with
the specified name is found, the ON EXCEPTION phrase of the CALL statement is taken
or the Runtime Command fails.
The RM/COBOL compiler has an object version level option to control the object version
level number placed in the object file. When the option is specified, any language
features used in the source program requiring a higher object version cause a source
diagnostic, and the program is not compiled. The object version level number placed in
the resulting object file is no higher than the value specified in the compiler option. If the
object version level option is not specified, the default value is the highest value accepted
by the compiler, thus allowing all features supported by the compiler. Since the compiler
marks the object program with the value of the latest feature actually used in the source
program, the resulting object program may still be executable on earlier releases of the
runtime system.
Table H-1 enumerates past RM/COBOL product releases and the highest object version
level number they accept.
RM/COBOL User's Guide for 32-Bit Windows H-1

Level Numbers
Table H-1 Object Version Numbers by Product
Object
Product Platform Releases Level Number
RM/COBOL-8X DOS 1.nn 1
RM/COBOL DOS 2.nn 2
UNIX 2.0n 2
RM/COBOL AS/400 3
RM/COBOL DOS 4.nn 4
UNIX 4.0n 4
RM/COBOL DOS 5.nn 5
UNIX 5.nn 5
RM/COBOL DOS 5.2n 6
UNIX 5.2n 6
RM/COBOL UNIX 6.nn 7
Windows 6.nn 7
RM/COBOL UNIX 7.nn 8
Windows 7.nn 8
In most cases, the object version is of no concern to the user. However, when compiling
programs intended for distribution to other users, the object version may be of concern. If
these other users do not have the current release of the runtime system, Compile
Command Option Z (see page 6-14) should be specified to restrict the object version
level. The object version level number specified to the compiler should be the highest
value that does not exceed the level accepted by any of the runtime systems used by the
intended recipients. When the object version level number is limited by use of Option Z,
the compiler suppresses any optimizations and diagnoses all source language features not
supported by earlier runtime systems.
The features associated with each object version are described in the following sections.
Object Version 1
The RM/COBOL-8X compiler and runtime system versions 1.nn support features in
object version 1. These product releases implement the high subset of ANSI COBOL
1974.
If the object version level number is limited to 1 by use of Compile Command Option Z,
the resulting object program is executable on any released RM/COBOL-8X or
RM/COBOL runtime system.
H-2 Object Versions

Object Version 1
Object Version 2
The RM/COBOL compiler and runtime system versions 2.nn support object
version 2. These product releases implement the intermediate subset of ANSI COBOL
1985. The RM/COBOL version 2.nn runtime systems support the language features of
both object version 1 and object version 2.
Several new language features were added in object version 2 that are not supported by
previous versions. Unless the object version is limited to 1 by Compile Command
Option Z, programs with the following features will not execute on runtime systems with
a version number less than 2:
1. A source program with a simple INSPECT statement.
A simple INSPECT statement is one with single-character control operands and only
a single CHARACTERS, ALL, LEADING or FIRST phrase per TALLYING or
REPLACING phrase. A simple INSPECT statement may have both a TALLYING
and REPLACING phrase and both a BEFORE and AFTER INITIAL phrase.
The RM/COBOL version 2.nn and later compilers generate optimized code for
simple INSPECT statements. The optimized code is not supported by earlier runtime
systems. If the Compile Command options specify object version 1, the previous
unoptimized code is generated for a simple INSPECT statement.
2. A source program with a NUMERIC class condition which has an unsigned numeric
display operand.
The RM/COBOL version 2.nn and later compilers generate optimized code for a
NUMERIC class condition the operand of which is an unsigned numeric display data
item. The optimized code is not supported by earlier runtime systems. If the
Compile Command options specify object version 1, the previous unoptimized code
is generated for such a class condition.
3. In COBOL-85 compatibility mode, FILE STATUS clauses imply that ANSI COBOL
1985 I-O status values are expected. RM/COBOL-8X version 1.nn runtime systems
never produce ANSI COBOL 1985 I-O status values.
If the Compile Command options specify object version 1 and do not specify ANSI
COBOL 1974 compatibility mode, FILE STATUS clauses are diagnosed as an object
version incompatibility and are ignored.

Object Version 2
4. The following RM/COBOL new language features require new runtime system
support for their implementation. If the Compile Command options specify object
version 1, these language features are diagnosed as an object version incompatibility
and are compiled:
a. Reference modification
b. The PADDING CHARACTER clause
c. The RECORD DELIMITER clause
d. The VALUE clause with or subordinate to OCCURS clauses
e. A class-name, ALPHABETIC-LOWER, or ALPHABETIC-UPPER class
condition
f. A CD FOR I-O referenced in a DISABLE, ENABLE, RECEIVE or SEND
statement
g. An ACCEPT . . . FROM DAY-OF-WEEK phrase
h. A CALL . . . USING phrase which references a subscripted identifier
i. A DISPLAY . . . WITH NO ADVANCING phrase
j. An INSPECT . . . CONVERTING phrase
k. A MERGE . . . GIVING phrase which specifies two or more files
l. An OPEN EXTEND phrase which references a relative or indexed organization
file
m. The PURGE statement
n. A SEND . . . REPLACING LINE phrase
o. A SORT . . . WITH DUPLICATES IN ORDER phrase
p. A SORT . . . GIVING phrase which specifies two or more files
Note Several important language features added in the version 2.0n releases of
RM/COBOL do not generate object version 2 code for their implementation. Examples
of such features are EVALUATE, INITIALIZE and the NOT conditional phrases (NOT
AT END, NOT ON SIZE ERROR, and so forth). These new language features may be
used whether or not the object version is restricted to object version 1 without affecting
the object version of the resulting object program.
H-4 Object Versions

Object Version 2
Object Version 3
version 3. These product releases implement the high subset of ANSI COBOL 1985.
The RM/COBOL version 3.nn runtime systems support the language features of object
versions 1, 2, and 3.
Two language features were added in object version 3 that are not supported by the earlier
versions. These are as follows:
1. The EXTERNAL clause in file-description-entries and Working-Storage Section

record-description entries.
2. Nested programs, including the PROGRAM IS COMMON clause, the GLOBAL file
description entry clause, the GLOBAL data description entry clause and the
GLOBAL phrase of the USE statement.
Note Programs with either of these two features will not execute on runtime
version 1.nn or 2.nn systems. Since these features required new runtime system support,
you cannot compile them if the object version level is restricted to 1 or 2 with Compile
Command Option Z. If the object version level is restricted to 1 or 2, the RM/COBOL
compiler diagnoses these features as an object version incompatibility.
The new language feature CALL . . . USING BY CONTENT does not generate new
object code. Programs using this feature can be compiled when the object version level is
restricted to 1 or 2 on Compile Command Option Z.
When compiling a sequence of programs not separated by END PROGRAM headers, you
must restrict the object version level to 1 or 2. Versions 3.00 and later of the
RM/COBOL compiler interpret such a sequence as nested programs.
Object Version 4
version 4. These product releases extend the high subset of ANSI COBOL 1985 with the
X/Open Screen Section. The RM/COBOL version 4.nn runtime systems support the
language features of object versions 1 through 4.

Object Version 3
Four language features were added in object version 4 that are not supported by the
earlier versions. These are as follows:
1. ACCEPT or DISPLAY statements that reference screen-names defined in the new

Screen Section of the Data Division.
2. ACCEPT statements that specify the FROM ESCAPE KEY or the FROM
EXCEPTION STATUS phrase.
3. CALL PROGRAM statement.
4. DELETE FILE statement.
Note Programs with any of these four features will not execute on runtime version 3.nn
or earlier systems. Since these features required new runtime system support, you cannot
compile them if the object version level is restricted to 3 or less with Compile Command
Option Z. If the object version level is restricted to 3 or less, the RM/COBOL compiler
diagnoses these features as an object version incompatibility.
Object Version 5
version 5. The RM/COBOL version 5.nn runtime systems support the language features
of object versions 1 through 5.
Two language features were added in object version 5 that are not supported by the earlier
1. A READ statement that specifies the PREVIOUS phrase for a relative or indexed
organization file.
2. A START statement that specifies a KEY IS LESS, a KEY IS NOT GREATER, or a

KEY IS LESS OR EQUAL relation.
version 4.nn or earlier systems. Since these features required new runtime system
support, you cannot compile them if the object version level is restricted to 4 or less with
Compile Command Option Z. If the object version level is restricted to 4 or less, the
RM/COBOL compiler diagnoses these features as an object version incompatibility.
H-6 Object Versions

Object Version 5
Object Version 6
The RM/COBOL compiler and runtime system versions 5.2n support object
version 6. The RM/COBOL version 5.2n runtime systems support the language features
of object versions 1 through 6.
Two language features were added in object version 6 that are not supported by earlier
1. An ACCEPT statement that specifies the TIME phrase.
2. A START statement that specifies an identifier in the SIZE phrase. Even though the
SIZE phrase is supported only by the 5.2n compiler, a literal specified in the SIZE
phrase of the START statement is supported by all RM/COBOL runtime system.
version 5.1n or earlier systems. Since these features require new runtime system support,
you cannot compile them if the object version level is restricted to 5 or less with Compile
Command Option Z. If the object version level is restricted to 5 or less, the
RM/COBOL compiler diagnoses these features as an object version incompatibility.
In addition, performance enhancements for certain existing language features require

runtime systems that support object version 6. Most programs compiled with the
version 5.2n compiler result in object files that require object version 6 support unless the
object version is restricted to 5 or less. The performance enhancements requiring object
version 6 are the following:
1. Adding a literal value in the range –128 to +127 to an integer binary data item that is
within the first 65280 bytes of the program local data area. The addition can be the
result of an ADD statement, an INSPECT statement TALLYING phrase, a
PERFORM statement VARYING or AFTER phrase, a SEARCH statement
VARYING phrase or an UNSTRING statement TALLYING phrase.
2. Subtracting a literal value in the range –127 to +128 from an integer binary data item
that is within the first 65280 bytes of the program local data area. The subtraction
can be the result of a SUBTRACT statement or a PERFORM statement VARYING
or AFTER phrase.
3. PERFORM statement with the TIMES phrase when the local data area for the
program, including compiler-generated temporary data items, is less than 65280
bytes in length.
4. Subscripted operands 255 characters or less in length that are elements of tables
within the first 65280 bytes of the program local data area that are specified in

Object Version 6
INITIALIZE, MOVE, READ, RELEASE, RETURN, REWRITE, SET or WRITE
statements.
5. Operands, subscripted or not, 255 characters or less in length that are within the first
65280 bytes of the program local data area specified in ACCEPT, CALL, CALL
PROGRAM, CANCEL, DISABLE, DISPLAY, ENABLE, INITIALIZE, INSPECT,
MOVE, READ, RECEIVE, RELEASE, RETURN, REWRITE, SEND, SET,
START, STOP, STRING, UNSTRING and WRITE statements or in class or relation
conditions.
6. Nonnumeric relations where the subject and object operands are different length data
items, neither operand is subscripted or reference modified other than by literals,
both operands are 255 characters or less in length, and both operands are within the
first 65280 bytes of the program local data area.
7. GO TO statements in the fixed permanent segments of a program that generates

between 32512 and 65280 bytes of object code for the fixed permanent segments.
Note The program local data area is the area of storage reserved for File Section,
Working-Storage, Communication, and Screen Section data items not described with the
external attribute. Linkage Section data items and data items described with the
EXTERNAL clause are not part of the program local data area.
Object Version 7
version 7. In addition, runtime system version 6.nn supports the language features of
object versions 1 through 7.
New language features were added in object version 7 that are not supported by earlier
1. A compiler configuration option allows for computational sign representations that

are compatible with COBOL-74 data types.
2. Thirty digits of precision are available for numeric data items.
3. The compiler and runtime system provide support for the START statement to
specify the FIRST or LAST KEY phrase. For example, START file-name KEY IS
FIRST key-name.
4. The compiler and runtime system provide support for duplicate prime record keys
(WITH DUPLICATES may be specified for the RECORD KEY phrase).
H-8 Object Versions

Object Version 7
5. The compiler and runtime system provide support for split keys. The RECORD
KEY phrase and the ALTERNATE RECORD KEY phrase may define split keys.
6. The compiler and runtime system provide support for multiple record locks in the
same file. The LOCK MODE clause of the file control entry may now specify the
LOCK ON MULTIPLE RECORDS phrase.
Note Programs that use any of these features will not execute on runtime versions 5.n
or earlier systems. Since these features require new runtime system support, you cannot
Object Version 8
version 8. In addition, runtime system version 7.nn supports the language features of
object versions 1 through 8.
New language features were added in object version 8 that are not supported by earlier
1. BINARY, COMPUTATIONAL-4 and COMP-4 usage data items allocated as other

than two- four-, eight-, or sixteen-bytes as a result of the BINARY-ALLOCATION
keyword specification in the COMPILER-OPTIONS configuration record or
the binary allocation override specification in the source. If a binary data item
is allocated as sixteen bytes because of these new features, object version 7 will
be required and generated since it was the first object version that supported
sixteen-byte binary.
2. Pointer data items (USAGE POINTER), the figurative constant NULL (NULLS), the
ADDRESS special register, and Formats 5 and 6 of the SET statement for
manipulating pointer data items.
3. The GIVING or RETURNING phrase in the Procedure Division header or in a

CALL statement.
4. The CENTURY-DATE, CENTURY-DAY, DATE-AND-TIME, or

DAY-AND-TIME options in the ACCEPT statement.
5. The OMITTED option for an argument in the USING phrase of a CALL statement.

Object Version 8
6. A source program that refers to linkage records (01 or 77 level data items defined in
the Linkage Section) in the USING phrase of a CALL statement or with reference
modification.
The RM/COBOL version 7.00 and later compilers generate code to reference the
data item on which the linkage record is based, that is, the actual argument passed by
the calling program or the area of memory referenced by a SET ADDRESS OF
statement. This new code is not supported by earlier runtime systems. If the
Compile Command options specify object version 7 or lower, then the previous code
is generated that uses the description of the data item in the linkage section of the
called program.
7. A source program may now use more than 64K of name space (unique spellings of
user-defined words), but object versions less than 8 support a maximum of 64K of
name space for the object symbol table. If the Compile Command Option Y is
specified to place the symbol table in the object file for debugging purposes and
more than 64K of name space has been used, object version 8 is required and will be
generated regardless of the maximum object version setting specified in the Compile
Command Option Z. The compiler generates a diagnostic message in this event.
Note 1 Programs that use any of these features will not execute on runtime versions 6.n
or earlier systems. Since these features require new runtime system support, you cannot
Note 2 Several important language features added in the version 7.0 releases of
RM/COBOL do not generate object version 8 code for their implementation. These
include level-number 78 constant-name declarations, constant-name references, the
DATE-COMPILED option in the ACCEPT statement, in-line comments, a numeric literal
specified in the VALUE clause for a numeric edited data item, and the COUNT,
COUNT-MAX, COUNT-MIN, LENGTH, and PROGRAM-ID special registers. A
binary allocation override that specifies two-, four-, or eight-byte allocation may be used
for any object version. A binary allocation override that specifies sixteen-byte allocation
may be used for object version 7.
H-10 Object Versions

Object Version 8
Appendix I: Extension, Obsolete,
and Subset Language Elements
RM/COBOL supports the extension, obsolete, and subset language elements discussed in
this appendix. Each language element is only briefly described in order to identify it. For
further information on each language element, refer to the RM/COBOL Language
Reference Manual.
The extension language elements are RM/COBOL extensions to the American National
Standard COBOL X3.23-1985. Extensions such as the ACCEPT and DISPLAY screen
control syntax simplify the use of COBOL in an interactive environment. Other
extensions relax some of the rules of COBOL to simplify program writing.
The obsolete language elements are language features declared obsolete in ANSI COBOL
1985. The standard has declared certain features as obsolete to indicate that they will be
removed in the next full revision of COBOL. The features declared obsolete are ones,
such as the ALTER statement, that have been identified as contributing to poor
programming practices. Obsolete features should be avoided in new programs and
removed from existing programs when they are revised.
The subset language elements are language features that are required only when more
than the minimum COBOL language is implemented. Above minimum COBOL, there
are two additional subsets defined by the standard: intermediate and high. In addition,
RM/COBOL supports two standard optional modules: segmentation and communication.
Each of these optional modules is further divided into a level 1 and level 2 subset, where
the level 2 subset includes the level 1 subset.
Compile Command Option F (see page 6-15) contains a flagging option to cause flagging
of the occurrence of any of the items in the following lists. Each of the lists is preceded
by an explanation of the flagging message produced for items on that list.
RM/COBOL User's Guide for 32-Bit Windows I-1

Extension Elements
Extension Elements
The warning message:
W 69: FIPS NONCONFORMING NONSTANDARD
is produced for each of the following language elements if they appear in a source
program compiled with the F=EXTENSION Compile Command Option (see page 6-15).
Each item on the list is an RM/COBOL extension to the American National Standard
COBOL X3.23-1985 language features and may, therefore, not be available in other
COBOL implementations.
Many extensions noted for RM/COBOL-8X do not appear below. These extensions have
not been deleted, but have been incorporated as standard features in the American
National Standard COBOL X3.23-1985.
The extensions are as follows:
1. More than seven subscripts.
2. In-line comments (*>comment-entry).
3. integer-1 + integer-2 as a subscript (literal subscript with relative offset) or zero

used for relative offset in a subscript.
4. Numeric literals with more than 18 digits.
5. Numeric data items with more than 18 digits of precision.
6. Nonnumeric literals greater than 160 characters in length.
7. Text-names and library-names specified as nonnumeric literals.
8. COPY statement within a copied file.
9. User-defined word ending in a hyphen.
10. Reserved words used as system-names (the ASSIGN clause in the file control
entry, the VALUE OF clause in the file description entry, and the ENTER
statement).
11. Use of an index-name in subscripting a table other than the one with which it is
associated.
12. Apostrophe used as a delimiter for nonnumeric literals.
13. ALL [ALL] . . . literal form of a figurative constant.
I-2 Extension, Obsolete, and Subset Language Elements

Extension Elements
14. Procedure-name that is the same as a data-name or index-name.
15. NULL or NULLS figurative constants.
16. Hexadecimal literal.
17. ADDRESS special register.
18. COUNT, COUNT-MAX, and COUNT-MIN special registers.
19. LENGTH special register.
20. PROGRAM-ID special register.
21. constant-name reference (a constant-name is defined in a level-number 78 data

description entry).
22. RETURN-CODE special register.
23. ID abbreviation for IDENTIFICATION.
24. Identification Division optional paragraphs out of order.
25. Program-name specified as a nonnumeric literal.
26. REMARKS paragraph in the Identification Division.
27. OBJECT-COMPUTER paragraph optional clauses out of order.
28. ALPHABET keyword missing in the SPECIAL-NAMES paragraph when an

alphabet-name appears.
29. Repeated character in an ALPHABET literal.
30. ALPHABET literal THRU phrase on ALSO phrase.
31. ALPHABET literal ALSO phrase on THRU phrase.
32. SYMBOLIC CHARACTERS clause specified as SYMBOLIC CHARACTER,

that is, CHARACTER used as a synonym for CHARACTERS.
33. CURRENCY SIGN literal specified as a figurative constant.
34. ASSIGN TO clause with data-name specified for file-access-name.
35. CODE-SET clause in the file control entry.
36. COLLATING SEQUENCE clause in the file control entry.
37. ORGANIZATION clause that specifies LINE or BINARY.

Extension Elements
38. RESERVE clause that specifies NO or ALTERNATE.
39. RECORD KEY clause that specifies the DUPLICATES phrase.
40. RECORD KEY clause that specifies the split-key-name option.
41. ALTERNATE RECORD KEY clause that specifies that split-key-name option.
42. LOCK MODE clause in the file control entry.
43. Optional word IS in POSITION phrase of MULTIPLE FILE TAPE clause.
44. SCREEN SECTION in the Data Division.
45. CODE-SET clause that refers to an alphabet-name defined with the literal phrase.
46. CODE-SET clause specified for a relative or indexed file.
47. LINAGE clause integer operand with a positive sign explicitly specified.
48. Qualification of the data-name in the RECORD IS VARYING DEPENDING ON

clause.
49. Level-number with three or more digits.
50. Level-number 78 data description entry.
51. DEPENDING phrase specified in OCCURS clause that omits [TO integer-2].
52. More than 30 characters in a PICTURE character-string.
53. PICTURE character-string that ends in a comma or period and is not immediately
followed by a period space separator.
54. REDEFINES of last name on same level, even though it is also a REDEFINES.
55. REDEFINES not first clause in a data description entry.
56. SYNCHRONIZED clause specified with USAGE INDEX in a data description

entry.
57. USAGE COMP-1, COMP-3, COMP-4, COMP-6, COMPUTATIONAL-1,

COMPUTATIONAL-3, COMPUTATIONAL-4, and COMPUTATIONAL-6.
58. USAGE POINTER.
59. USAGE clause that specifies a binary allocation override (integer-3).
60. VALUE clause in a data description entry that specifies the WHEN SET TO
FALSE phrase.

Extension Elements
61. VALUE clause in a data item data description entry in the File Section or Linkage
Section or in other than the first record description entry subordinate to a
communication description entry in the Communication Section that is included in
the resultant source program as the result of a COPY statement.
62. VALUE clause in a data item data description entry in an external record in the
Working-Storage Section record that is included in the source program as the
result of a COPY statement.
63. VALUE clause that specifies a numeric literal for a numeric edited data item.
64. Procedure Division header that specifies the GIVING or RETURNING phrase.
65. END PROGRAM specified without a program-name.
66. END PROGRAM header that specifies a nonnumeric literal for the program-name.
67. Segment-numbers greater than 99.
68. Optional word THEN used as a statement connective.
69. Both operands of a relation being literals.
70. An index-name as one operand in a relation and an arithmetic expression as the

other operand.
71. Pointer data item used in a relation condition.
72. Literal specified in a class condition.
73. Literal specified in a sign condition.
74. Nondisplay data item specified in a NUMERIC class condition.
75. ACCEPT . . . FROM CONSOLE when CONSOLE not defined as a

mnemonic-name in the SPECIAL-NAMES paragraph.
76. ACCEPT . . . FROM SYSIN when SYSIN not defined as a mnemonic-name in the
SPECIAL-NAMES paragraph.
77. ACCEPT … FROM CENTURY-DATE.
78. ACCEPT … FROM CENTURY-DAY.
79. ACCEPT … FROM DATE-AND-TIME.
80. ACCEPT … FROM DATE-COMPILED.
81. ACCEPT … FROM DAY-AND-TIME.

Extension Elements
82. ACCEPT . . . FROM ESCAPE KEY statement.
83. ACCEPT . . . FROM EXCEPTION STATUS statement.
84. ACCEPT operand series.
85. ACCEPT statement that specifies a screen-name.
86. ACCEPT with screen control (LINE, POSITION, SIZE, CURSOR, CONTROL,
ERASE, TAB, UNIT, PROMPT, UPDATE, ECHO, BLINK, REVERSE, HIGH,
LOW, OFF, CONVERT, NO BEEP, ON EXCEPTION, NOT ON EXCEPTION,
END-ACCEPT, BEFORE TIME).
87. CALL PROGRAM statement.
88. CALL . . . USING literal.
89. CALL … USING pointer data item.
90. CALL … USING OMITTED.
91. CALL … GIVING/RETURNING phrase.
92. CLOSE statement that specifies the NO REWIND phrase with either the REEL or
UNIT phrase.
93. DELETE FILE statement.
94. DISABLE statement without INPUT, OUTPUT or I-O phrase.
95. DISPLAY . . . UPON CONSOLE when CONSOLE is not defined as a

mnemonic-name in the SPECIAL-NAMES paragraph.
96. DISPLAY . . . UPON SYSOUT when SYSOUT not defined as a mnemonic-name

in the SPECIAL-NAMES paragraph.
97. DISPLAY statement that specifies a screen-name.
98. DISPLAY with screen control (LINE, POSITION, SIZE, CONTROL, ERASE,
UNIT, BLINK, REVERSE, HIGH, LOW, CONVERT, BEEP).
99. ENABLE statement without INPUT, OUTPUT or I-O phrase.
100. ENTER statement not ended by a period.
101. EVALUATE statement that specifies an index-name or index data item as a

selection subject or selection object.
102. GOBACK statement.

Extension Elements
103. IF statement that specifies END-IF and NEXT SENTENCE.
104. INSPECT . . . TALLYING . . . FOR FIRST phrase.
105. INSPECT statement that refers to an ALL literal as a control operand.
106. INSPECT statement that refers to a group data item as a control operand.
107. MOVE CORRESPONDING statement with a receiving operand series.
108. OPEN EXCLUSIVE phrase.
109. OPEN EXTEND statement that refers to a file described with the LINAGE clause.
110. OPEN . . . WITH LOCK phrase.
111. PERFORM integer-1 TIMES statement where integer-1 is zero or signed.
112. In-line PERFORM VARYING statement with AFTER phrases.
113. READ . . . PREVIOUS phrase.
114. READ statement that specifies the WITH NO LOCK or WITH LOCK phrase.
115. RELEASE . . . FROM literal.
116. REWRITE . . . FROM literal.
117. SEARCH statement that specifies END-SEARCH and NEXT SENTENCE.
118. SEND . . . FROM literal.
119. SET statement (Format 1) that specifies more than one TO phrase.
120. SET statement (Format 2) that specifies more than one UP/DOWN BY phrase.
121. SET {condition-name} . . . TO FALSE statement.
122. SET statement that specifies more than one instance of the TO TRUE phrase.
123. SET statement (Formats 5 and 6) that refers to a pointer data item.
124. START statement with LESS THAN, LESS THAN OR EQUAL, or equivalent
relations.
125. START statement that specifies the SIZE phrase.
126. START statement in which the FIRST or LAST option is specified in the KEY
phrase.
127. STOP statement that specifies an identifier instead of the literal phrase.

Extension Elements
128. STOP RUN statement with RETURN-CODE specified.
129. UNLOCK statement.
130. WRITE . . . FROM literal.
131. WRITE . . . ADVANCING TO LINE phrase.
Obsolete Elements
W 71: FIPS OBSOLETE
program compiled with the F=OBSOLETE Compile Command Option (see
page 6-15). Each item on the list is identified in the American National Standard COBOL
X3.23-1985 as being an obsolete language element which will be deleted
from the next full revision of the COBOL standard.
1. ALL literal, where literal has a length greater than 1 if associated with a numeric
or numeric edited data item.
2. AUTHOR, INSTALLATION, DATE-WRITTEN, DATE-COMPILED and

SECURITY paragraphs.
3. MEMORY SIZE clause.
4. RERUN clause.
5. MULTIPLE FILE TAPE clause.
6. LABEL RECORDS clause.
7. VALUE OF clause.
8. DATA RECORDS clause.
9. ALTER statement.
10. KEY phrase of the DISABLE statement.
11. KEY phrase of the ENABLE statement.
12. ENTER statement.
13. GO TO statement with omitted procedure-name-1.

Obsolete Elements
14. REVERSED phrase of the OPEN statement.
15. STOP literal phrase.
16. Segment-numbers and the SEGMENT-LIMIT clause.
Subset Elements
W 70: FIPS NONCONFORMING STANDARD
program compiled with the appropriate F Compile Command Option (see page 6-15).
The keyword which causes the language element to be flagged is shown in parentheses
after each element description. Note that HIGH elements will be flagged if
F=INTERMEDIATE or F=HIGH is specified, COM2 elements will be flagged if
F=COM1 or F=COM2 is specified, and SEG2 elements will be flagged if F=SEG1 or
F=SEG2 is specified.
If obsolete element flagging is also enabled, any obsolete element from the following
list will only be flagged as obsolete even when the other keyword is also specified in
the F Compile Command Option. That is, obsolete flagging takes precedence over
subset flagging.
1. Segment-number (SEG1, OBSOLETE).
2. Noncontiguous segments with same segment-number (SEG2, OBSOLETE).
3. Symbolic-character (HIGH).
4. ALL literal figurative constant (HIGH).
5. LINAGE-COUNTER special register (HIGH).
6. Qualification (HIGH).
7. More than three subscripts (HIGH).
8. Reference modification (HIGH).
9. Continuation of a COBOL word, numeric literal or PICTURE character-string

(HIGH).
10. IDENTIFICATION DIVISION header of a contained program (HIGH).

Subset Elements
11. END PROGRAM header (HIGH).
12. COMMON clause in PROGRAM-ID paragraph (HIGH).
13. INITIAL clause in PROGRAM-ID paragraph (HIGH).
14. DATE-COMPILED paragraph (HIGH, OBSOLETE).
15. COPY statement (INTERMEDIATE).
16. COPY . . . OF/IN library-name (HIGH).
17. COPY . . . REPLACING phrase (HIGH).
18. REPLACE statement (HIGH).
19. SEGMENT-LIMIT clause (SEG2, OBSOLETE).
20. ALPHABET clause literal phrase (HIGH).
21. SYMBOLIC CHARACTERS clause (HIGH).
22. OPTIONAL phrase in file control entry (HIGH).
23. ACCESS MODE RANDOM clause (INTERMEDIATE).
24. ACCESS MODE DYNAMIC clause (HIGH).
25. RELATIVE KEY phrase (INTERMEDIATE).
26. ALTERNATE RECORD KEY clause (HIGH).
27. ORGANIZATION RELATIVE clause (INTERMEDIATE).
28. ORGANIZATION INDEXED clause (INTERMEDIATE).
29. PADDING CHARACTER clause (HIGH).
30. RECORD DELIMITER clause (HIGH).
31. RECORD KEY clause (INTERMEDIATE).
32. RESERVE AREA clause (HIGH).
33. MULTIPLE FILE TAPE clause (HIGH, OBSOLETE).
34. SAME RECORD AREA clause (HIGH).
35. SAME SORT/SORT-MERGE AREA clause INTERMEDIATE).
36. SD level indicator (INTERMEDIATE).

Subset Elements
37. BLOCK CONTAINS integer-1 TO integer-2 RECORDS/CHARACTERS
(HIGH).
38. LINAGE clause (HIGH).
39. RECORD VARYING IN SIZE clause (HIGH).
40. VALUE OF clause which specifies a data-name (HIGH, OBSOLETE).
41. COMMUNICATION SECTION header (COM1).
42. CD level indicator (COM1).
43. INITIAL clause in a CD entry (COM2).
44. SYMBOLIC SUB-QUEUE-1, SUB-QUEUE-2 and SUB-QUEUE-3 clauses in a

CD entry (COM2).
45. Data-name series in a CD entry (COM2).
46. DESTINATION TABLE clause in a CD entry (COM2).
47. Level-number 66 data description entry (HIGH).
48. Level-number 88 data description entry (HIGH).
49. EXTERNAL clause (HIGH).
50. GLOBAL clause (HIGH).
51. OCCURS clause ASCENDING/DESCENDING KEY phrase (HIGH).
52. OCCURS clause integer-1 TO integer-2 TIMES DEPENDING ON phrase

(HIGH).
53. REDEFINES clauses nested (HIGH).
54. REDEFINES clause that refers to a table item (HIGH).
55. RENAMES clause (HIGH).
56. Procedure Division header USING phrase with more than five operands (HIGH).
57. Condition-name condition (HIGH).
58. Sign condition (HIGH).
59. Logical operators AND, OR, NOT (HIGH).
60. Arithmetic expression operators + – * / ** (HIGH).

Subset Elements
61. ACCEPT statement FROM phrase (HIGH).
62. ACCEPT MESSAGE COUNT statement (COM1).
63. ADD statement CORRESPONDING phrase (HIGH).
64. ALTER statement procedure-name series (HIGH, OBSOLETE).
65. CALL statement with identifier-1 (HIGH).
66. CALL statement USING phrase with more than five operands (HIGH).
67. CALL statement USING BY CONTENT or BY REFERENCE phrase (HIGH).
68. CALL statement ON OVERFLOW phrase (HIGH).
69. CALL statement ON EXCEPTION phrase (HIGH).
70. CALL statement NOT ON EXCEPTION phrase (HIGH).
71. CANCEL statement (HIGH).
72. CLOSE statement FOR REMOVAL phrase (HIGH).
73. CLOSE statement WITH NO REWIND phrase (HIGH).
74. CLOSE statement WITH LOCK phrase (HIGH).
75. COMPUTE statement (HIGH).
76. DELETE statement (INTERMEDIATE).
77. DISABLE statement (COM2).
78. DISPLAY statement UPON phrase (HIGH).
79. DISPLAY statement WITH NO ADVANCING phrase (HIGH).
80. DIVIDE statement REMAINDER phrase (HIGH).
81. ENABLE statement (COM2).
82. EVALUATE statement (HIGH).
83. GO TO statement with omitted procedure-name (HIGH, (OBSOLETE).
84. IF statement that contains a conditional statement (HIGH).
85. INITIALIZE statement (HIGH).
86. INSPECT statement with multicharacter data item (HIGH).

Subset Elements
87. INSPECT statement BEFORE/AFTER phrase series (HIGH).
88. INSPECT statement TALLYING phrase series (HIGH).
89. INSPECT statement REPLACING phrase series (HIGH).
90. INSPECT statement CONVERTING phrase (HIGH).
91. MERGE statement (INTERMEDIATE).
92. MOVE statement CORRESPONDING phrase (HIGH).
93. MOVE statement de-editing of numeric edited items (HIGH).
94. OPEN statement WITH NO REWIND phrase (HIGH).
95. OPEN statement REVERSED phrase (HIGH, OBSOLETE).
96. OPEN statement EXTEND phrase (HIGH).
97. PERFORM statement TEST BEFORE/AFTER phrase (HIGH).
98. PERFORM statement VARYING phrase (HIGH).
99. PURGE statement (COM2).
100. READ statement NEXT phrase (HIGH).
101. READ statement KEY phrase (HIGH).
102. READ statement INVALID KEY phrase (INTERMEDIATE).
103. READ statement NOT INVALID KEY phrase (INTERMEDIATE).
104. RECEIVE statement (COM1).
105. RECEIVE statement SEGMENT phrase (COM2).
106. RELEASE statement (INTERMEDIATE).
107. RETURN statement (INTERMEDIATE).
108. REWRITE statement INVALID KEY phrase (INTERMEDIATE).
109. REWRITE statement NOT INVALID KEY phrase (INTERMEDIATE).
110. SEARCH statement (HIGH).
111. SEND statement (COM1).
112. SEND statement Format 1 (COM2).

Subset Elements
113. SEND statement WITH identifier phrase (COM2).
114. SEND statement WITH ESI phrase (COM2).
115. SEND statement BEFORE/AFTER ADVANCING mnemonic-name phrase

(COM2).
116. SEND statement REPLACING LINE phrase (COM2).
117. SET statement condition-name TO TRUE (HIGH).
118. SORT statement (INTERMEDIATE).
119. START statement (HIGH).
120. STRING statement (HIGH).
121. SUBTRACT statement CORRESPONDING phrase (HIGH).
122. UNSTRING statement (HIGH).
123. USE statement GLOBAL phrase (HIGH).
124. USE statement ON file-name series (HIGH).
125. USE statement ON EXTEND (HIGH).
126. WRITE statement BEFORE/AFTER ADVANCING mnemonic-name phrase

(HIGH).
127. WRITE statement AT END-OF-PAGE/EOP phrase (HIGH).
128. WRITE statement NOT AT END-OF-PAGE/EOP phrase (HIGH).
129. WRITE statement INVALID KEY phrase (INTERMEDIATE).
130. WRITE statement NOT INVALID KEY phrase (INTERMEDIATE).

Subset Elements
Appendix J: Code-Set Translation
Tables
The following tables describe the translation between ASCII and EBCDIC character sets.
The ASCII to EBCDIC translation is identical to that described by IBM in the document,
Systems Network Architecture Format and Protocol Reference Manual: Architecture
Logic (SC30-3112-0). The EBCDIC to ASCII translation is the inverse of the ASCII to
EBCDIC mapping, with the addition that EBCDIC characters with no ASCII equivalent
are assigned values in the range X‘80’ to X‘FF’.
Character abbreviations are defined in Table J-3 beginning on page J-15.
Table J-1 ASCII to EBCDIC Conversion
ASCII Code ASCII Code EBCDIC Code

(Decimal) (Hexadecimal) U.S. Character (Hexadecimal) U.S. Character
0 00 NUL 00 NUL
1 01 SOH 01 SOH
2 02 STX 02 STX
3 03 ETX 03 ETX
4 04 EOT 37 EOT
5 05 ENQ 2D ENQ
6 06 ACK 2E ACK
7 07 BEL 2F BEL
8 08 BS 16 BS
9 09 HT 05 HT
10 0A LF 25 LF
11 0B VT 0B VT
12 0C FF 0C FF
13 0D CR 0D CR
14 0E SO 0E SO
15 0F SI 0F SI
16 10 DLE 10 DLE
17 11 DC1 14 ENP
RM/COBOL User's Guide for 32-Bit Windows J-1

Table J-1 ASCII to EBCDIC Conversion (Cont.)

18 12 DC2 24 INP
19 13 DC3 04 SEL
20 14 DC4 15 NL
21 15 NAK 3D NAK
22 16 SYN 32 SYN
23 17 ETB 26 ETB
24 18 CAN 18 CAN
25 19 EM 19 EM
26 1A SUB 3F SUB
27 1B ESC 27 ESC
28 1C FS 1C IFS
29 1D GS 1D IGS
30 1E RS 1E IRS
31 1F US 1F IUS
32 20 Space 40 Space
33 21 ! 4F |
34 22 ” 7F ”
35 23 # 7B #
36 24 $ 5B $
37 25 % 6C %
38 26 & 50 &
39 27 ’ 7D ’
40 28 ( 4D (
41 29 ) 5D )
42 2A * 5C *
43 2B + 4E +
44 2C , 6B ,
45 2D - 60 -
46 2E . 4B .
47 2F / 61 /
J-2 Code-Set Translation Tables


48 30 0 F0 0
49 31 1 F1 1
50 32 2 F2 2
51 33 3 F3 3
52 34 4 F4 4
53 35 5 F5 5
54 36 6 F6 6
55 37 7 F7 7
56 38 8 F8 8
57 39 9 F9 9
58 3A : 7A :
59 3B ; 5E ;
60 3C < 4C <
61 3D = 7E =
62 3E > 6E >
63 3F ? 6F ?
64 40 @ 7C @
65 41 A C1 A
66 42 B C2 B
67 43 C C3 C
68 44 D C4 D
69 45 E C5 E
70 46 F C6 F
71 47 G C7 G
72 48 H C8 H
73 49 I C9 I
74 4A J D1 J
75 4B K D2 K
76 4C L D3 L
77 4D M D4 M


78 4E N D5 N
79 4F O D6 O
80 50 P D7 P
81 51 Q D8 Q
82 52 R D9 R
83 53 S E2 S
84 54 T E3 T
85 55 U E4 U
86 56 V E5 V
87 57 W E6 W
88 58 X E7 X
89 59 Y E8 Y
90 5A Z E9 Z
91 5B [ 4A ¢
92 5C \ E0 \
93 5D ] 5A !
94 5E ^ 5F ¬
95 5F _ 6D _
96 60 ‘ 79 ‘
97 61 a 81 a
98 62 b 82 b
99 63 c 83 c
100 64 d 84 d
101 65 e 85 e
102 66 f 86 f
103 67 g 87 g
104 68 h 88 h
105 69 I 89 i
106 6A j 91 j
107 6B k 92 k


108 6C l 93 l
109 6D m 94 m
110 6E n 95 n
111 6F o 96 o
112 70 p 97 p
113 71 q 98 q
114 72 r 99 r
115 73 s A2 s
116 74 t A3 t
117 75 u A4 u
118 76 v A5 v
119 77 w A6 w
120 78 x A7 x
121 79 y A8 y
122 7A z A9 z
123 7B { C0 {
124 7C | 6A |
125 7D } D0 }
126 7E ~ A1 ~
127 7F DEL 07 DEL

Table J-2 EBCDIC to ASCII Conversion
EBCDIC Code EBCDIC Code ASCII Code

0 00 NUL 00 NUL
1 01 SOH 01 SOH
2 02 STX 02 STX
3 03 ETX 03 ETX
4 04 SEL 13 DC3
5 05 HT 09 HT
6 06 80
7 07 DEL 7F DEL
8 08 81
9 09 82
10 0A 83
11 0B VT 0B VT
12 0C FF 0C FF
13 0D CR 0D CR
14 0E SO 0E SO
15 0F SI 0F SI
16 10 DLE 10 DLE
17 11 84
18 12 85
19 13 86
20 14 ENP 11 DC1
21 15 NL 14 DC4
22 16 BS 08 BS
23 17 87
24 18 CAN 18 CAN
25 19 EM 19 EM
26 1A 88
27 1B 89
28 1C IFS 1C FS
29 1D IGS 1D GS

Table J-2 EBCDIC to ASCII Conversion (Cont.)

30 1E IRS 1E RS
31 1F IUS 1F US
32 20 8A
33 21 8B
34 22 8C
35 23 8D
36 24 INP 12 DC2
37 25 LF 0A LF
38 26 ETB 17 ETB
39 27 ESC 1B ESC
40 28 8E
41 29 8F
42 2A 90
43 2B 91
44 2C 92
45 2D ENQ 05 ENQ
46 2E ACK 06 ACK
47 2F BEL 07 BEL
48 30 93
49 31 94
50 32 SYN 16 SYN
51 33 95
52 34 96
53 35 97
54 36 98
55 37 EOT 04 EOT
56 38 99
57 39 9A
58 3A 9B
59 3B 9C


60 3C 9D
61 3D NAK 15 NAK
62 3E 9E
63 3F SUB 1A SUB
64 40 Space 20 Space
65 41 9F
66 42 A0
67 43 A1
68 44 A2
69 45 A3
70 46 A4
71 47 A5
72 48 A6
73 49 A7
74 4A ¢ 5B [
75 4B . 2E .
76 4C < 3C <
77 4D ( 28 (
78 4E + 2B +
79 4F | 21 !
80 50 & 26 &
81 51 A8
82 52 A9
83 53 AA
84 54 AB
85 55 AC
86 56 AD
87 57 AE
88 58 AF
89 59 B0


90 5A ! 5D ]
91 5B $ 24 $
92 5C * 2A *
93 5D ) 29 )
94 5E ; 3B ;
95 5F ¬ 5E ^
96 60 - 2D -
97 61 / 2F /
98 62 B1
99 63 B2
100 64 B3
101 65 B4
102 66 B5
103 67 B6
104 68 B7
105 69 B8
106 6A 7C
107 6B , 2C ,
108 6C % 25 %
109 6D _ 5F _
110 6E > 3E >
111 6F ? 3F ?
112 70 B9
113 71 BA
114 72 BB
115 73 BC
116 74 BD
117 75 BE
118 76 BF
119 77 C0


120 78 C1
121 79 ‘ 60 ‘
122 7A : 3A :
123 7B # 23 #
124 7C @ 40 @
125 7D ’ 27 ’
126 7E = 3D =
127 7F ” 22 ”
128 80 C2
129 81 a 61 a
130 82 b 62 b
131 83 c 63 c
132 84 d 64 d
133 85 e 65 e
134 86 f 66 f
135 87 g 67 g
136 88 h 68 h
137 89 i 69 i
138 8A C3
139 8B C4
140 8C C5
141 8D C6
142 8E C7
143 8F C8
144 90 C9
145 91 j 6A j
146 92 k 6B k
147 93 l 6C l
148 94 m 6D m
149 95 n 6E n


150 96 o 6F o
151 97 p 70 p
152 98 q 71 q
153 99 r 72 r
154 9A CA
155 9B CB
156 9C CC
157 9D CD
158 9E CE
159 9F CF
160 A0 D0
161 A1 ~ 7E ~
162 A2 s 73 s
163 A3 t 74 t
164 A4 u 75 u
165 A5 v 76 v
166 A6 w 77 w
167 A7 x 78 x
168 A8 y 79 y
169 A9 z 7A z
170 AA D1
171 AB D2
172 AC D3
173 AD D4
174 AE D5
175 AF D6
176 B0 D7
177 B1 D8
178 B2 D9
179 B3 DA


180 B4 DB
181 B5 DC
182 B6 DD
183 B7 DE
184 B8 DF
185 B9 E0
186 BA E1
187 BB E2
188 BC E3
189 BD E4
190 BE E5
191 BF E6
192 C0 { 7B {
193 C1 A 41 A
194 C2 B 42 B
195 C3 C 43 C
196 C4 D 44 D
197 C5 E 45 E
198 C6 F 46 F
199 C7 G 47 G
200 C8 H 48 H
201 C9 I 49 I
202 CA E7
203 CB E8
204 CC E9
205 CD EA
206 CE EB
207 CF EC
208 D0 } 7D }
209 D1 J 4A J


210 D2 K 4B K
211 D3 L 4C L
212 D4 M 4D M
213 D5 N 4E N
214 D6 O 4F O
215 D7 P 50 P
216 D8 Q 51 Q
217 D9 R 52 R
218 DA ED
219 DB EE
220 DC EF
221 DD F0
222 DE F1
223 DF F2
224 E0 \ 5C \
225 E1 F3
226 E2 S 53 S
227 E3 T 54 T
228 E4 U 55 U
229 E5 V 56 V
230 E6 W 57 W
231 E7 X 58 X
232 E8 Y 59 Y
233 E9 Z 5A Z
234 EA F4
235 EB F5
236 EC F6
237 ED F7
238 EE F8
239 EF F9


240 F0 0 30 0
241 F1 1 31 1
242 F2 2 32 2
243 F3 3 33 3
244 F4 4 34 4
245 F5 5 35 5
246 F6 6 36 6
247 F7 7 37 7
248 F8 8 38 8
249 F9 9 39 9
250 FA FA
251 FB FB
252 FC FC
253 FD FD
254 FE FE
255 FF FF

Character abbreviations are defined in Table J-3.
Table J-3 Character Abbreviations
Abbreviation Meaning
ACK Acknowledgment
BEL Bell
BS Backspace
CAN Cancel
CR Carriage Return
DC1 Device Control 1
DEL Delete
DLE Data Link Escape
EM End of Medium
ENP Enable Presentation
ENQ Enquiry
EOT End of Transmission
ESC Escape
ETB End of Transmission Block
ETX End of Text
FF Form Feed
FS File Separator
GS Group Separator
HT Horizontal Tab
IFS Interchange File Separator
IGS Interchange Group Separator
INP Inhibit Presentation
IRS Interchange Record Separator
IUS Interchange Unit Separator
LF Line Feed
NAK Negative Acknowledgment

Table J-3 Character Abbreviations (Cont.)
Abbreviation Meaning
NL New Line
NUL Null
RS Record Separator
SEL Select
SI Shift In
SO Shift Out
SOH Start of Heading
STX Start of Text
SUB Substitute
SYN Synchronous Idle
US Unit Separator
VT Vertical Tab

Index
2 ACCEPT statement, Terminal I-O. See also

ACCEPT and DISPLAY statements,
2 Compile Command Option, 6-14, 6-16, 10-15
operating-system specific information;
DISPLAY statement
7 BEFORE TIME phrase, 8-21
7 Compile Command Option, 6-14, 10-9, F-22 CHARACTER-TIMEOUT keyword,
TERM-ATTR configuration
A record, 10-36
configuration
A (Address Stop) Command, Debug option, 9-20
ACCEPT-FIELD-FROM-SCREEN
A Compile Command Option, 6-9, 6-22, 9-1,
keyword, RUN-ATTR
9-9, 10-12
record, 8-1, 10-23
A Runtime Command Option, 7-5
ACCEPT-INTENSITY keyword,
RUN-ATTR record, 10-23
operating-system specific information,
ACCEPT-PROMPT-CHAR keyword,
8-1–8-21. See also ACCEPT statement,
RUN-ATTR record, 10-24
Terminal I-O; DISPLAY statement
ACCEPT-SUPPRESS-CONVERSION
cursor types, 2-9, 3-43
keyword, COMPILER-OPTIONS
defined keys, 8-2
record, 10-6
edit keys
B keyword, RUN-OPTION record, 10-33
backspace, 8-3
BCOLOR keyword, TERM-ATTR
delete character, 8-3
record, 10-36, 10-40
erase entire, 8-4
BEEP keyword, RUN-ATTR record, 10-24
erase remainder, 8-4
BLINK keyword, RUN-ATTR
insert character, 8-4
record, 10-24
left arrow, 8-3
CHARACTER-TIMEOUT keyword,
right arrow, 8-3
TERM-ATTR record, 10-36
initial contents of a screen field, 8-1
COLUMNS keyword, TERM-ATTR
keys that generate field termination codes, 8-5
record, 10-37
redirection of input and output, 2-22, 8-1
FCOLOR keyword, TERM-ATTR
standard error, 2-25
record, 10-39, 10-40
standard input, 2-22
M keyword, RUN-OPTION record, 10-34
standard output, 2-24–2-25, 6-18
REDRAW-ON-CALL-SYSTEM keyword,
terminal attributes, 2-9
TERM-ATTR record, 10-39
terminal interfaces, 2-9
REVERSE keyword, RUN-ATTR
ACCEPT FROM EXCEPTION STATUS
record, 10-25
statement, 8-30
ROWS keyword, TERM-ATTR
ACCEPT MESSAGE COUNT statement, 8-65
record, 10-39
RM/COBOL User's Guide for 32-Bit Windows X-1

ACCEPT statement, Terminal I-O ACCEPT statement, Terminal I-O (Cont.)
configuration (Cont.) SIZE phrase, 2-23, 2-25, 8-17, 8-20
RUN-OPTION record, 10-33 TAB phrase, 8-17
SCREEN-CONTENT-OPTIMIZE TIME phrase. See BEFORE TIME phrase
keyword, TERM-ATTR record, 10-40 UPDATE phrase, 8-1
SUPPRESS-NULLS keyword, ACCEPT-FIELD-FROM-SCREEN keyword,
TERM-ATTR record, 10-40 RUN-ATTR configuration record,
TAB keyword, RUN-ATTR record, 10-26 8-1, 10-23
TERM-INPUT record, 10-41 ACCEPT-INTENSITY keyword, RUN-ATTR
TERM-INTERFACE record, 10-49 configuration record, 10-23
TERM-UNIT record, 10-49 ACCEPT-PROMPT-CHAR keyword,
examples, default configuration RUN-ATTR configuration record, 10-24
files, 10-51 ACCEPT-SUPPRESS-CONVERSION keyword,
UNDERLINE keyword, RUN-ATTR COMPILER-OPTIONS configuration
record, 10-26 record, 10-6
USE-COLOR keyword, TERM-ATTR ACTION keyword, TERM-INPUT configuration
record, 10-40 record, 10-41
CONTROL phrase, 8-11 ADVANCING phrase
BCOLOR keyword, 2-21, 3-31, 8-12, SEND statement, 8-69
8-24, 10-40 WRITE statement (sequential I-O), 8-45
valid color names, 8-13 Allocation map listing, 6-18, 6-22, 10-12
FCOLOR keyword, 2-21, 3-31, 8-12, ALLOCATION-INCREMENT keyword, RUN-
8-24, 10-40 INDEX-FILES configuration record, 10-31
valid color names, 8-13 ALLOCATION-MAP value, LISTING-
GRAPHICS keyword, 2-21, 3-41, ATTRIBUTES keyword, 6-22, 10-12
8-13, 8-17 ALLOW-EXTENDED-CHARS-IN-
MASK keyword, xlii, 8-2, 8-3, 8-14 FILENAMES keyword, RUN-FILES-ATTR
PROMPT keyword, xlvii, 8-18 configuration record, 10-26
REPAINT-SCREEN keyword, 8-18, D-23 Alphabet-name, user-defined word type, 6-22
SCREEN-COLUMNS keyword, 8-18 analysis program. See Instrumentation
TAB keyword, 8-17 ANSI insertion mode
CONVERT phrase, 2-23, 2-25 field editing, 10-45
RESET-ANSI-INSERTION value, 10-46
CURSOR phrase, 2-23, 8-17
SET-ANSI-INSERTION value, 10-47
ECHO phrase, 2-23
TOGGLE-ANSI-INSERTION value, 10-48
ERASE phrase, 8-19
Argument passing, 7-5
HIGH phrase, 8-17, 8-19 ASCII, translation, J-1–J-5
LOW phrase, 8-17, 8-19 character abbreviations, J-15
OFF phrase, 8-17, 8-20 ATOMIC-TRANSFER-SIZE keyword, RUN-
ON EXCEPTION phrase, 2-22–2-24, 8-5, 8-21 INDEX-FILES configuration record, 10-31
PROMPT phrase, 8-1, 8-3, 8-17 Attach Configuration utility (rmattach), xlv,
REVERSE phrase, 8-20 10-2, G-39
SECURE phrase, 8-17, 8-20 AUTO-LINE-FEED keyword, PRINT-ATTR
configuration record, 10-21
X-2 Index
B
Block size, 10-26
B (Breakpoint) Command, Debug option, 9-21
indexed files, xlvii, 8-53, 8-56
B Compile Command Option, 6-8, 10-15
relative files, 8-48
B keyword, RUN-OPTION configuration
sequential files, 8-42
record, 10-33
BLOCK-SIZE keyword
B Runtime Command Option, 7-4, 8-20, 10-33
RUN-FILES-ATTR configuration
Backspace key, 8-3
record, 10-26
BACKSPACE value, ACTION keyword,
RUN-INDEX-FILES configuration
10-41, 10-45
record, 10-31
BCOLOR keyword
RUN-REL-FILES configuration record, 10-34
CONTROL phrase, ACCEPT and DISPLAY
RUN-SEQ-FILES configuration record, 10-34
statements, 2-21, 3-31, 8-12, 8-24, 10-40
Boolean, 2-10, 2-12, 2-19–2-20, 3-17
TERM-ATTR configuration record, 10-36
Bourne Shell script, xlvii, D-1
BEEP keyword
BPS keyword, TERM-UNIT configuration
CONTROL phrase, DISPLAY statement, 8-24
record, 10-49
RUN-ATTR configuration record, 10-24
Btrieve MicroKernel Database Engine (MKDE).
BEEP phrase
See Btrieve, system considerations for
ACCEPT and DISPLAY statements, 10-24
Btrieve, system considerations for, xliv, 4-1
DISPLAY statement, 8-23
C$BTRV subprogram, xxviii, F-3
BEFORE TIME phrase, ACCEPT
components
statement, 8-21
Btrieve MicroKernel Database Engine
(MKDE), 4-4, 4-5
configuration and installation, 4-7
BELL phrase. See BEEP phrase
limitations with RM/COBOL indexed
Binary allocation, 10-6, 10-9, C-18, C-21
files, 4-19
Binary sequential files
types of
configuring, 10-15, 10-35
client-based, 4-4
record delimiting technique, 6-8, 8-42
server-based, 4-4
BINARY-ALLOCATION keyword,
Btrieve requester for Windows
COMPILER-OPTIONS configuration
NT/Windows 95/Windows 98,
record, 10-6, C-18, C-21, F-6
4-4, 4-5
BINARY-ALLOCATION-SIGNED keyword,
NetWare, 4-4
COMPILER-OPTIONS configuration RM/COBOL development system, 4-4, 4-5
record, 10-9, C-18 RM/COBOL runtime system, 4-4, 4-5
BLINK keyword RM/COBOL-to-Btrieve Adapter (rmbtrv32)
CONTROL phrase, DISPLAY statement, 8-24 program, xliv, 4-1, 4-4, 4-5, 4-7, 10-20
RUN-ATTR configuration record, 10-24 dynamic link libraries, 4-5, 4-18
BLINK phrase file management system, RM/COBOL, 4-6
ACCEPT and DISPLAY statements, 10-24 files
DISPLAY statement, 8-23 split keys, 4-7
Blinking attribute, 2-20, 8-23 system considerations, 4-7
BLOCK CONTAINS clause, file description versus RM/COBOL indexed file
performance, 4-8
entry, xlvii, 8-42, 8-48, 8-53, 8-56

Btrieve, system considerations for (Cont.) C$OSLockInfo subprogram, F-20
limitations with RM/COBOL indexed C$PlaySound subprogram, xxvii, E-44, F-21
files, 4-19 C$RBMenu subprogram, xliv, 3-36, 3-43, F-22
local area networks (LANs), 4-1, 4-4, 4-9 C$RERR subprogram, xlvi, F-22
software, required, 3-2, 4-4 C$SBar subprogram, 3-27, 3-42, F-25
starting, 4-18 C$SCRD subprogram, 10-8, F-26
Buffer pool, 6-43, 8-40, 8-49, 8-54, 8-60, 10-26 C$SCWR subprogram, F-27
Buffer size, with ACCEPT and DISPLAY C$SetDevelopmentMode
statements, 2-23, 7-4, 8-20 subprogram, xxviii, F-33
BUFFER-POOL-SIZE keyword, RUN-FILES- C$SetEnv subprogram, xxvii, F-34
ATTR configuration record, 6-43, 8-40, C$SetSyn subprogram, xxvii, F-34, F-35
8-60, 10-26, A-7, A-28, G-34 C$ShowArgs subprogram, xxviii, F-36
C$TBar subprogram, 3-22, 3-32, 3-43, F-37
C C$TBarEn subprogram, xliv, F-38
C$TBarSeq subprogram, xliv, 3-37, F-39
C (Clear) Command, Debug option, 9-22
C$Title subprogram, 3-28, 3-43, F-39
C (or assembly) language subprograms, D-5,
C$WRU subprogram, F-40
D-12, D-19–D-20
CALL "SYSTEM", 3-45, 6-44, 7-8, D-20, F-41.
initial entry flag, D-14 See also SYSTEM subprogram
C Compile Command Option, 6-9, 6-20, 10-13 CALL statement, 8-33–8-38, 10-8
C entry points for COBOL functions external objects, 8-36
RmForget(int y1, int x1, int y2, int x2), D-23 initial entry flag, D-14
RmRefreshCwd(), D-23 linking C (or assembly) language subprograms
RmRepaintScreen(), D-23 into the runtime system, D-12
C Runtime Command Option, 7-3, 10-1, A-38 printing from Windows, E-9
C$BitMap subprogram, F-3 subprogram loading, 8-34
C$BTRV subprogram, xxviii, F-3 Called program summary, 6-18, 6-27
C$CARG subprogram, 10-8, F-5 Calling non-COBOL programs from
C$Century subprogram, xlvi, F-7 RM/COBOL programs, D-12
C$ClearDevelopmentMode CCD. See Communications Descriptor
subprogram, xxvii, F-7 Cd-name, user-defined word type, 6-24
C$Delay subprogram, xxvii, F-8 Character sequence specifications, 10-42
C$FORGET subprogram, D-23, F-8 CHARACTERS clause, 8-43, 8-49, 8-53
C$GetEnv subprogram, xxvii, F-9 CHARACTER-TIMEOUT keyword
C$GetLastFileName subprogram, xxvii, F-10 BEFORE TIME phrase, ACCEPT
statement, 8-21
C$GetLastFileOp subprogram, xxvii, F-10
C$GetRMInfo subprogram, xxvii, F-11
CHARACTER-WIDTH keyword, TERM-UNIT
C$GetSyn subprogram, xxvii, F-13 configuration record, 10-50
C$GetSysInfo subprogram, xxvii, F-14 Class-name, user-defined word type, 6-22
C$GUICFG subprogram, xliv, 3-19–3-28, F-16 CLOSE statement
C$MBar subprogram, 3-22, 3-34, 3-42, F-17 REEL and UNIT phrases
C$MemoryAllocate subprogram, xxvii, F-18 (sequential I-O), 8-45
C$MemoryDeallocate subprogram, xxvii, F-19 WITH NO REWIND phrase
C$NARG subprogram, F-19 (sequential I-O), 8-45
X-4 Index
COBOL-74 keyword, COMPILER-OPTIONS Compatibility between RM/COBOL (74) 2.n and
configuration record, 10-9 RM/COBOL-85, 6-14, 6-16
Cobol-CGI, 1-3 Compatibility with earlier version of
Cobol-RPC, 1-3 RM/COBOL, object versions, H-1
Cobol-WOW, 1-3 Compilation. See also Compile Command;
CODE keyword, TERM-INPUT configuration Compiler
record, 10-41 Compile Command, 6-3
CodeBridge, xxvi, 1-2, F-4. See also libraries, 6-3
CodeBridge documentation listings, 6-18
CODE-SET clause, 8-37, 8-44, 8-49, 8-54 process, 6-1
Code-set translation tables, J-1 system files
character abbreviations, J-15 listing, 6-2, 6-18, 10-19, 10-20
CodeWatch, xxvi, 1-2, 3-4, 6-13. See also object, 6-2
CodeWatch documentation source, 6-2
COLLATING SEQUENCE clause, 8-37, Compile Command, 6-3
8-54, 8-55 error marker and diagnostics, 6-31
Color terminal support, 8-24 error recovery, 6-32
TERM-ATTR configuration record error threading, 6-33
BCOLOR keyword, 10-36 format of, 6-4
FCOLOR keyword, 10-39 invoking, 6-1
USE-COLOR keyword, 10-40 messages
with ACCEPT and DISPLAY statements, banner, 6-33
2-21, 3-31, 8-11–8-13 compiler configuration errors, 6-35, 6-42
with pop-up windows, 2-21, 8-24 compiler exit codes, 6-44
COLUMN and COL phrases. See POSITION compiler status, 6-34
phrase options, 6-5
COLUMNS keyword allocation map (A), 6-9, 6-22, 9-1,
PRINT-ATTR configuration record, 10-21 9-9, 10-12
TERM-ATTR configuration record, 10-37 alternate usage of COMP data items (U),
Combine Program utility (rmpgmcom), 3-4, 6-3, 6-7, 10-10
6-13, 10-11, 10-16, G-9 and the negation character ~, 6-5
Combined sign ANSI COBOL 1974 or 1985 semantics (7),
leading, C-10 6-14, 10-9, F-22
trailing, C-9 binary sequential files (B), 6-8, 10-15
Comma, EDIT-COMMA keyword, 10-24 compiler configuration (G), 6-6, 10-1, A-38
Commands compiler configuration supplement (H),
compile, 6-3 6-6, 10-1, A-38
debug, 9-2 compiler memory (W), 6-7, 10-16
runtime, 7-1 create smaller COBOL object files (Q),
Commit File function, 10-27 6-13, 9-1, 11-3, A-2, F-11, F-40
Communications descriptor (CCD), 8-68 cross reference map (X), 6-11, 6-28, 10-13
COMP. See COMPUTATIONAL language element flagging (F), 6-15, 10-12,
I-2, I-8, I-9

Compile Command Compiler. See also Compile Command;
options (Cont.) Compilation
line sequential files (V), 6-8, 6-16, 10-15 banner message, Compile Command, 6-33
listing file on disk (L), 6-9, 6-18, 6-33, configuration errors, 6-35, 6-42
10-13, 10-14, 11-1 configuration options, Compile Command, 6-6
output the debug line table (Y), 6-13, 9-1, error marker and diagnostic format, 6-31
9-5, 9-6, 10-11, G-9, H-10 error recovery messages, 6-32
output the symbol table (Y), xxxiii, 6-13, error threading facility, 6-33
9-1, 9-5, 9-6, 10-11, 10-16, G-9, H-10 exit codes, 6-44
print listing (P), 6-10, 6-18, 6-33, initialization errors, 6-43
6-41, 10-13 input/output errors, 6-35
RM/COBOL 2.n programs (2), 6-14, overlay file, 2-5, 3-12
6-16, 10-15 status messages, 6-34
separate sign in the absence of a SIGN syntax errors, 6-31
clause (S), 6-7, 6-16, 10-15, C-7, C-9 Compiler configuration options, Compile
sequentially numbered listing (R), Command, 6-6
6-10, 10-15 COMPILER-OPTIONS configuration
specified in configuration files, 6-5 record, 10-6
specified on the compile command line, 6-5 ACCEPT-SUPPRESS-CONVERSION
specify object file pathname (O), keyword, 10-6
6-12, 10-14 BINARY-ALLOCATION keyword, 10-6,
specify the RM/COBOL object version (Z), C-18, C-21, F-6
6-14, H-2 BINARY-ALLOCATION-SIGNED
suppress automatic conversion in certain keyword, 10-9, C-18
ACCEPT and DISPLAY statements COBOL-74 keyword, 10-9
(M), 2-23, 6-11, 10-6 COMPUTATIONAL-AS-BINARY
suppress banner message and terminal error keyword, 10-9
listing (K), 6-7, 6-18, 10-13 COMPUTATIONAL-TYPE
suppress copied text (C), 6-9, 6-20, 10-13 keyword, 10-10, C-12, C-13
suppress object program (N), 6-11 COMPUTATIONAL-VERSION
suppress source program listing (E), keyword, 10-10, C-13, C-17
6-9, 6-20, 10-13 DEBUG keyword, 10-11
with debugging mode (D), 6-15, 10-11 DEBUG-TABLE-OUTPUT keyword,
write a copy of the listing to a standard xxxiii, 10-11
output device (T), 6-11, 6-18, 6-33, DERESERVE keyword, 10-12
6-41, 10-13 FLAGGING keyword, 10-12
samples of valid and invalid, 6-17 LISTING-ATTRIBUTES keyword,
types of options 6-22, 6-28, 10-12
compiler configuration, 6-6 LISTING-DATE-FORMAT keyword, 10-13
data item, 6-7 LISTING-DATE-SEPARATOR
file type, 6-8
keyword, 10-14
listing, 6-8
LISTING-PATHNAME keyword, 10-14
object program, 6-11
source program, 6-15
X-6 Index
COMPILER-OPTIONS configuration Configuration files
record (Cont.) ini2reg utility, xliii, 3-4, 3-16, G-40
LISTING-TIME-SEPARATOR recover1.ini, 3-16
keyword, 10-14 rmcobol.ini, 3-16
OBJECT-PATHNAME keyword, 10-14 runcobol.ini, 3-16
OBJECT-VERSION keyword, 10-14 Configuration records, 6-5, 10-3
RESEQUENCE-LINE-NUMBERS attached configuration file, xlv, 10-2, G-39
keyword, 10-14 built-in configuration file, xlv, 10-2, D-5
RMCOBOL-2 keyword, 10-15 COMPILER-OPTIONS, 10-6
SEPARATE-SIGN keyword, 10-15 DEFINE-DEVICE, 10-16
SEQUENTIAL-FILE-TYPE keyword, 10-15 errors, 10-3
SUPPRESS-NUMERIC-OPTIMIZATION EXTENSION-NAMES, 10-19
keyword, 10-15 EXTERNAL-ACCESS-METHOD,
SYMBOL-TABLE-OUTPUT keyword, 10-16 xlvii, 4-9, 10-20
WORKSPACE-SIZE keyword, 10-16 list of, 10-3
Compressed files, UNIX installation, 2-2 PRINT-ATTR, 10-20
Compression. See DATA-COMPRESSION RUN-ATTR, 10-23
keyword; KEY-COMPRESSION keyword RUN-FILES-ATTR, xlii, 10-26
COMPUTATIONAL data format, 6-16 RUN-INDEX-FILES, 4-16, 10-31
type option, Compile Command, 6-7 RUN-OPTION, 10-33
COMPUTATIONAL-1 data format, 6-16 RUN-REL-FILES, xlii, 10-34
COMPUTATIONAL-3 data format, 6-16 RUN-SEQ-FILES, xlii, 10-34
COMPUTATIONAL-AS-BINARY keyword, RUN-SORT, 10-36
COMPILER-OPTIONS configuration TERM-ATTR, 10-36
record, 10-9 TERM-INPUT, 10-41
COMPUTATIONAL-TYPE keyword, TERM-INTERFACE, 10-49
COMPILER-OPTIONS configuration TERM-UNIT, 10-49
record, 10-10, C-12, C-13 Constant-name, user-defined word type, 6-27
COMPUTATIONAL-VERSION keyword, Control characters, DEFINE-CONTROL-
COMPILER-OPTIONS configuration CHARACTERS keyword, 10-50
record, 10-10, C-13, C-17 CONTROL phrase
Condition-name, user-defined word type, 6-24 ACCEPT and DISPLAY statements, 8-11
config.sys BUFFERS command, 8-60 BCOLOR keyword, 8-12
config.sys FILES command, 8-60 DISPLAY statement, 8-24, 8-26
Configuration errors, 6-35, 6-42, 10-3, A-1, A-37 FCOLOR keyword, 8-12
Configuration file options, 6-5 GRAPHICS keyword, 8-13, 8-17
negating, 6-5 MASK keyword, 8-2, 8-3, 8-14
Configuration file structure, 10-1 PASS-THRU keyword, 8-17
termcap default configuration example, 10-51 PROMPT keyword, 8-18
terminfo default configuration example, 10-54 REPAINT-SCREEN keyword, 8-18
Windows default configuration example, SCREEN-COLUMNS keyword, 8-18
10-57 TAB keyword, 8-17
with the Compile Command options, 6-5 terminfo strings, 2-21

CONTROL-BREAK value, ACTION keyword, Customizing RM/COBOL for UNIX, D-1
10-41, 10-45 C entry points for COBOL functions, D-23
Conventions and symbols, xxxvii installing the customized product, D-11
Conversion. See ACCEPT-SUPPRESS- Makefile, xlvii, D-1, D-5, D-6, D-9
CONVERSION keyword; CONVERT relinking the same product, D-5
phrase terminal interfaces, 2-9
CONVERT phrase, ACCEPT and DISPLAY using
statements, 2-23, 2-25 customiz utility, xlvii, D-1
Copy file, default extension, 10-19 C language subprograms
Copy files, printing from Windows (MCBA and Flexgen), D-4
DEVCAPS.CPY, E-39, E-44, E-45 Enterprise CodeBench, 1-3, D-4
list of, E-44 examples, D-6
LOGFONT.CPY, E-29, E-44, E-47 Pop-Up Window Manager, D-3
PRINTDLG.CPY, E-17, E-18, E-38, RM/InfoExpress, 1-3, 10-20, D-2
E-44, E-52 RM/plusDB, 10-20, D-3
PRINTINF.CPY, E-41, E-44, E-62 terminfo or termcap terminal
TXTMTRIC.CPY, E-26, E-44, E-65 interfaces, D-2
WINDEFS.CPY, E-7, E-8, E-23, E-31, VanGui Interface Builder, 1-3, D-5
E-44, E-69 other customizations
COPY keyword, EXTENSION-NAMES adding a Message Control System
configuration record, 10-19 (MCS), 8-65, D-5
COPY statement, 8-31 adding C (or assembly) language
listing, 6-9, 6-20 subprograms, D-5, D-12
CREATE-FILES keyword, EXTERNAL- accessing C subprograms, D-18
ACCESS-METHOD configuration C subprogram examples, D-20
record, 10-20 calling sequence, D-12
Creating pop-up windows, 8-22 debugging C (or assembly) language
Cross reference listing, 6-18, 6-28, 10-13 subprograms, D-20
CROSS-REFERENCE value, LISTING- preparing C (or assembly)
ATTRIBUTES keyword, 6-28, 10-13 subprograms, D-19
CURRENCY SIGN clause, 10-25, C-2, I-3 restrictions to C (or assembly)
Currency symbol, EDIT-CURRENCY-SYMBOL language subprograms, D-19
keyword, 10-24, 10-25. See also Dollar built-in configuration file, xlv, 10-2, D-5
sign
CURSOR phrase, ACCEPT statement, 2-23, 8-17 D
Cursor positioning, 2-9, 3-43
D (Display) Command, Debug option, 9-23
Cursor types, 2-9, 3-43
D Compile Command Option, 6-15, 10-11
customiz utility, xlvii, 10-2, D-1, D-6
D Runtime Command Option, 7-3, 9-1
Data address development, 9-6
Data characters, 10-37
Data compression, 8-63
Data item options, Compile Command, 6-7
X-8 Index
DATA keyword, TERM-INPUT configuration Debug (Cont.)
record, 10-42 error messages, 9-13
DATA-CHARACTERS keyword, TERM-ATTR general concepts, 9-2
configuration record, 10-37 breakpoints, 9-3
DATA-COMPRESSION keyword, RUN- data types, 9-4
INDEX-FILES configuration record, 10-31 debug values, 9-4
Data-name, user-defined word type, 6-24 execution counts, 9-3
Date intraline numbers, 9-3, F-11, F-40
listing format configuration, 10-13 line numbers, 9-3
listing separator configuration, 10-14 statements, 9-2
DBCS characters, xlii, 8-15, 10-37 stepping, 9-3
DBCS-CHARACTERS keyword, TERM-ATTR traps, 9-3
configuration record, xlii, 10-37 invoking, 9-1
Debug output debugging information (Y Compile
command summary, 9-2 Command Option), xxxiii, 6-13, G-9
commands regaining control, 9-11
clear breakpoints (C), 9-22 screen positions, 9-5
clear data traps (U), 9-40 DEBUG keyword, COMPILER-OPTIONS
display set breakpoints (B), 9-21 configuration record, 10-11
display the value of a data item (D), 9-23. Debugging, symbolic
See also Data address development configuration, 10-16
end a Debug session (E), 9-27 Y Compile Command Option, xxxiii, 6-13, G-9
modify the value of a specified data DEBUG-TABLE-OUTPUT keyword,
item (M), 9-28 COMPILER-OPTIONS configuration
resume program execution at a specified record, xxxiii, 10-11
location (R), 9-34, A-2 Decimal point, EDIT-DECIMAL keyword, 10-25
set a breakpoint and clear once DEFAULT-FILE-VERSION-NUMBER
satisfied (A), 9-20 keyword, RUN-INDEX-FILES
set a breakpoint and do not clear once configuration record, 10-31
satisfied (B), 9-21 DEFAULT-TYPE keyword, RUN-SEQ-FILES
specify a screen line for Debug configuration record, 10-35
displays (L), 9-28 Define Indexed File utility (rmdefinx), 3-4, 8-50,
step through individual statements (S), 9-35 8-56, 8-64, 8-65, A-31, G-19
stop program execution (Q), 9-33 DEFINE-CONTROL-CHARACTERS keyword,
trap a data item when its value TERM-UNIT configuration record, 10-50
changes (T), 9-36 DEFINE-DEVICE configuration record, 10-16
data address development, 9-6 DEVICE keyword, 10-16
address-size format, 9-9 ESCAPE-SEQUENCES keyword, 3-25,
alias format, 9-11 10-17, E-38
identifier format, 9-6 PATH keyword, 10-17
debug references PIPE keyword, 10-17
in the data item, 9-5 RAW keyword, 3-26, 10-17, E-43
in the program area, 9-5 Windows printers, 10-18

Delete Character key, 8-3 DISPLAY statement
DELETE-CHARACTER value, ACTION configuration (Cont.)
keyword, 10-41, 10-45 BLINK keyword, RUN-ATTR
DERESERVE keyword, COMPILER-OPTIONS record, 10-24
configuration record, 10-12 COLUMNS keyword, TERM-ATTR
DESTINATION TABLE OCCURS clause, 8-69 record, 10-37
DEVICE keyword, DEFINE-DEVICE DISPLAY-INTENSITY keyword,
configuration record, 10-16 RUN-ATTR record, 10-24
Device support, 8-46 FCOLOR keyword, TERM-ATTR record,
named pipe, 8-47 10-39, 10-40
printer, 8-46 K keyword, RUN-OPTION record, 10-33
tape, 8-47 M keyword, RUN-OPTION record, 10-34
DEVICE-SLEWING-RESERVE keyword, PASS-THRU-ESCAPE keyword,
RUN-SEQ-FILES configuration record, 10-35 TERM-ATTR record, 10-39
Diagnostic undermark, 6-31 REDRAW-ON-CALL-SYSTEM keyword,
Directory search sequences TERM-ATTR record, 10-39
compiler, 6-4, 6-10, 6-12, 6-35, 6-41, 8-32 REVERSE keyword, RUN-ATTR
NetWare search paths, 3-13 record, 10-25
under UNIX, 2-4 ROWS keyword, TERM-ATTR
under Windows, 3-11 record, 10-39
recover1 utility, G-26 SCREEN-CONTENT-OPTIMIZE
runtime, 8-35 keyword, TERM-ATTR record, 10-40
NetWare search paths, 3-13 SUPPRESS-NULLS keyword,
under UNIX, 2-4 TERM-ATTR record, 10-40
under Windows, 3-11 TERM-INPUT record, 10-41
synonyms, setting properties, 3-11, 3-29 TERM-INTERFACE record, 10-49
using Btrieve files, 4-11 TERM-UNIT record, 10-49
DISABLE statement, 8-65, 8-69 examples, default configuration
DISABLE-COMMIT-FILE keyword, RUN- files, 10-51
FILES-ATTR configuration record, 10-27 UNDERLINE keyword, RUN-ATTR
DISPLAY statement. See also ACCEPT and record, 10-26
DISPLAY statements, operating-system USE-COLOR keyword, TERM-ATTR
specific information; ACCEPT statement, record, 10-40
Terminal I-O CONTROL phrase, 8-11, 8-24
BEEP phrase, 8-23 BCOLOR keyword, 2-21, 3-31, 8-12,
BLINK phrase, 8-23 8-24, 10-40
configuration valid color names, 8-13
B keyword, RUN-OPTION record, 10-33 BEEP keyword, 8-24
BCOLOR keyword, TERM-ATTR record, BLINK keyword, 8-24
10-36, 10-40 ERASE keyword, 8-24
BEEP keyword, RUN-ATTR FCOLOR keyword, 2-21, 3-31, 8-12,
record, 10-24 8-24, 10-40
valid color names, 8-13
X-10 Index
DISPLAY statement E
CONTROL phrase (Cont.)
E (End) Command, Debug option, 9-27
GRAPHICS keyword, 2-21, 3-41,
E Compile Command Option, 6-9, 6-20, 10-13
8-13, 8-17
EBCDIC code-name, translation, J-5–J-14
HIGH keyword, 8-24
character abbreviations, J-15
LOW keyword, 8-24
ECHO phrase, ACCEPT statement, 2-23
MASK keyword, xlii, 8-14
Edit keys
NO BEEP keyword, 8-24
backspace, 8-3
NO BLINK keyword, 8-24
delete character, 8-3
NO ERASE keyword, 8-24
erase entire, 8-4
NO REVERSE keyword, 8-24
erase remainder, 8-4
PASS-THRU keyword, 8-17
insert character, 8-4
REPAINT-SCREEN keyword, 8-18, D-23
left arrow, 8-3
REVERSE keyword, 8-24
masked input processing, 8-3
SCREEN-COLUMNS keyword, 8-18
right arrow, 8-3
CONVERT phrase, 2-23, 2-25
EDIT-COMMA keyword, RUN-ATTR
ERASE phrase, 8-19, 8-24
HIGH phrase, 8-17, 8-19, 8-25
EDIT-CURRENCY-SYMBOL keyword,
LINE phrase, 8-25
LOW phrase, 8-17, 8-19, 8-25
EDIT-DECIMAL keyword, RUN-ATTR
pop-up windows, creating, 8-22
POSITION phrase, 8-25
EDIT-DOLLAR keyword, RUN-ATTR
REVERSE phrase, 8-20, 8-25
SIZE phrase, 2-23, 2-25, 8-17, 8-20
ENABLE statement, 8-65, 8-69
UNIT phrase, 8-26
ENABLE-LOGGING keyword, RUN-OPTION
DISPLAY-INTENSITY keyword, RUN-ATTR
ENABLE-OLD-DOS-FILENAME-HANDLING
DLL. See Dynamic link libraries
keyword, RUN-FILES-ATTR configuration
Dollar sign, EDIT-DOLLAR keyword, 10-25.
record, 10-27
See also Currency symbol
Enhancements to RM/COBOL
Double-byte character set characters, xlii, version 6.5, xliii
8-15, 10-37 version 6.6, xli
DUPLICATES phrase, RECORD KEY version 7, xxv
clause, H-8 Enterprise CodeBench, 1-3, D-4
Dynamic link libraries, 3-12, 8-35 Environment variables
16-bit and 32-bit implementations, xliii for NetWare search paths, 3-13
Btrieve requester for Windows, 4-5 HOME, 2-3
RM/COBOL-to-Btrieve Adapter (rmbtrv32) PATH, 2-4, 3-12, 6-35, 6-41, 8-36, G-26
program, 4-18 resolution of program names, xlvii
RMPATH, 2-4, 3-11–3-13, 3-30, 8-32
RUNPATH, 2-4, 3-11–3-13, 3-30, 4-10, 8-35
TERM, 2-11, 8-18
TERMCAP, 2-10
TERMINFO, 2-11

Erase Entire key, 8-4 EXTENSION-NAMES configuration
ERASE EOL and ERASE EOS. See ERASE record, 10-19. See also Extensions
phrase COPY keyword, 10-19
ERASE keyword, CONTROL phrase, DISPLAY LISTING keyword, 10-19
statement, 8-24 OBJECT keyword, 10-19
ERASE phrase SOURCE keyword, 10-19
ACCEPT and DISPLAY statements, 8-19 Extensions
DISPLAY statement, 8-24 configuring, 10-19
Erase Remainder key, 8-4 defaults, 1-4, 3-10, 6-2, 7-1, 8-32, 10-19
ERASE-ENTIRE value, ACTION resolution of program names, xlvii
keyword, 10-41, 10-46 Windows 95 and Windows NT, xliii
ERASE-REMAINDER value, ACTION EXTERNAL clause, 8-36
keyword, 10-41, 10-46 External objects
Error classes, 6-32 data records, 8-37
Error messages. See Messages file connectors, 8-37
ERROR-MESSAGE-DESTINATION keyword, indexes, 8-38
RUN-ATTR configuration record, 2-25 EXTERNAL-ACCESS-METHOD configuration
ERROR-ONLY-LIST value, LISTING- record, xlvii, 4-9, 10-20
ATTRIBUTES keyword, 10-13 CREATE-FILES keyword, 10-20
Escape. See SCREEN-ESCAPE value NAME keyword, 10-20
Escape sequences, RM/COBOL-specific, 3-25, OPTIONS keyword, 10-20
10-17, E-43, E-85
raw mode-byte I/O, E-43, E-85 F
ESCAPE-SEQUENCES keyword,
F Compile Command Option, 6-15, 10-12,
DEFINE-DEVICE configuration record,
I-2, I-8, I-9
3-25, 10-17, E-38
FATAL-RECORD-LOCK-TIMEOUT
ESCAPE-TO-COMMAND value, ACTION
keyword, RUN-FILES-ATTR configuration
keyword, 10-41, 10-46
record, 10-27
ESCAPE-TO-OS value, ACTION
FCOLOR keyword
keyword, 10-41, 10-46
CONTROL phrase, ACCEPT and DISPLAY
Exception codes, keys used, 8-5
statements, 2-21, 3-31, 8-12, 8-24, 10-40
EXCEPTION keyword, TERM-INPUT
Features. See Enhancements to RM/COBOL
Exit codes
Field editing actions, 10-45
compiler, 6-44
Field termination codes, 8-5
program, 7-8, 8-33
FIELD-HOME value, ACTION
EXPANDED-PATH-SEARCH keyword,
keyword, 10-41, 10-46
RUN-FILES-ATTR configuration
File access names, 2-5, 3-13
record, 2-3, 3-10, 10-27
locating RM/COBOL files
EXTEND phrase, 6-16
under UNIX, 2-3
under Windows, 3-10, 3-29
printer support, 2-7
tape support, 2-7
X-12 Index
File allocation, in indexed files, 8-56 File types and structure
File buffering, 6-43, 8-40, 8-49, 8-54, indexed files (Cont.)
8-60, 10-26 file allocation increment, 8-56, 10-31,
File control entry G-16, G-20
CODE-SET clause, 8-37, 8-49, 8-54 file size estimation, 8-56
COLLATING SEQUENCE clause, 8-37, 8-55 file version number, 8-56, 10-31,
RECORD KEY clause, H-8 G-16, G-22
File description entry RECORD clause, 8-52
BLOCK CONTAINS clause, 8-42, 8-48, 8-53 RESERVE clause, 8-54
CODE-SET clause, 8-37, 8-44, 8-49, 8-54 WITH NO LOCK phrase, 8-55
LINAGE clause, 8-43 relative files, 8-47
RECORD clause, 8-42, 8-48, 8-52 BLOCK CONTAINS clause, 8-48
File lock facility, 2-8 CODE-SET clause, 8-49
File lock limit, xlii, 10-28, G-16 RECORD clause, 8-48
File management system, RM/COBOL, 4-6 RESERVE clause, 8-49
File naming conventions, RM/COBOL, WITH NO LOCK phrase, 8-49
1-4, 10-19 sequential files, 8-41
File organization ADVANCING mnemonic-name
indexed, 8-50 phrase, 8-45
relative, 8-47 ADVANCING ZERO LINES phrase, 8-45
sequential, 8-41 binary sequential, 6-8, 8-42, 10-15, 10-35
File performance, indexed files, 8-59 BLOCK CONTAINS clause, 8-42
File sharing, 8-38 CODE-SET clause, 8-44
FILE STATUS clause, file control entry, device support, 8-46
10-27, 10-30 LINAGE clause, 8-43
File status data item line sequential, 6-8, 8-41, 10-15, 10-35
indexed file, 8-55 printer support, 8-46
relative file, 8-50 RECORD clause, 8-42
sequential file, 8-44 REEL and UNIT phrases, 8-45
File type options, Compile Command, 6-8 RESERVE clause, 8-44
File types and structure, 8-40 REVERSED phrase, 8-44
indexed files, 8-50 tape support, 8-47
and Btrieve, 4-1, 4-4, 4-8 WITH NO LOCK phrase, 8-44
BLOCK CONTAINS clause, 8-53, 8-62, WITH NO REWIND phrase, 8-45
10-31, G-15, G-20 File version number, in indexed files, xlii, 8-56,
block sizes, xlvii, 8-56 8-64, 10-31, G-16, G-22
CODE-SET clause, 8-54 FILE-CONTROL-PARAGRAPH
COLLATING SEQUENCE clause, 8-55 indexed file control entry, 8-54
data compression, 8-50, 8-63, 10-31, relative file control entry, 8-49
10-32, G-15, G-20 sequential file control entry, 8-44
data recoverability, 8-51, 8-63, 10-32, FILE-HANDLE-LIMIT keyword, RUN-FILES-
G-16, G-20 ATTR configuration record, 10-27

FILE-LOCK-LIMIT keyword, RUN-FILES- H
ATTR configuration record, 10-28
H Compile Command Option, 6-6, 10-1, A-38
Filename extension. See Extensions
HIGH keyword, CONTROL phrase, DISPLAY
File-name, user-defined word type, 6-24
statement, 8-24
FILE-PROCESS-COUNT keyword, RUN-
HIGH phrase
FILES-ATTR configuration record, 10-28
Files
8-17, 8-19
copy, 10-19
libraries, 6-3, 7-2
High-intensity attribute, 2-20, 8-12, 8-25
listing, 6-2, 6-3, 6-18, 10-19
HIGHLIGHT phrase. See HIGH phrase
locating of, 2-3, 3-10
Home. See SCREEN-HOME value
object, 6-2, 6-3, 7-1, 10-19
HOME environment variable, file locations, 2-3
source, 6-2, 6-3, 10-19
FILL character, 3-27
FLAGGING keyword, COMPILER-OPTIONS
I
configuration record, 10-12 I Runtime Command Option, 7-3, 11-1
FORCE-CLOSED keyword, RUN-INDEX- Indexed File Conversion utilities (rmifca and
FILES configuration record, 8-51, 10-31 rmifcb), G-4
FORCE-DATA keyword, RUN-INDEX-FILES Indexed file performance, 8-59
configuration record, 8-52, 10-32 altering size of indexed file blocks, 8-62
FORCE-DISK keyword, RUN-INDEX-FILES controlling length of record keys, 8-62
configuration record, 8-52, 10-32 correct data recovery strategy, 8-63
FORCE-INDEX keyword, RUN-INDEX-FILES in-memory buffering, 8-60
configuration record, 8-52, 10-32 using key and data compression, 8-63
FORCE-USER-MODE keyword, RUN-FILES- using RM/COBOL facilities, 8-64
ATTR configuration record, 3-45, 10-28 with Btrieve, 4-1, 4-4, 4-8
FORM-FEED-AVAILABLE keyword, Indexed File Recovery utility (recover1), xlii,
PRINT-ATTR configuration record, 10-21 xlvi, 2-5, 3-4, 3-12, 3-16, 3-18, 8-51, 8-64,
FROM phrase, SEND statement, 8-69 8-65, 10-31, A-13, A-31, G-23
FROM/UPON CONSOLE phrase, ACCEPT and recover2, xlii, G-35
DISPLAY statements, 2-22–2-25 recovery, xlii
Function key mapping, 2-9 Indexed File Unload utility (recover2). See
Indexed File Recovery utility (recover1)
G Indexed files, 8-40, 8-50. See also File types and
structure
G Compile Command Option, 6-6, 10-1, A-38
and Btrieve, 4-1, 4-4, 4-8
Generic exception keys, 10-48
block sizes, xlvii, 8-56
Generic key name, field termination codes, 8-5
Index-name, user-defined word type, 6-26
GRAPHICS keyword, CONTROL phrase,
ini2reg utility, xliii, 3-4, 3-16, G-40
ACCEPT and DISPLAY statements, 2-21,
INITIAL clause, PROGRAM-ID paragraph, 8-34
3-41, 8-13, 8-17
Initial contents of a screen field, 8-1
GUI keyword, TERM-INTERFACE
Initial entry flag, D-14
X-14 Index
Initialization File to Windows Registry Internal data formats
Conversion utility (ini2reg), xliii, 3-4, nonnumeric data items, C-2
3-16, G-40 numeric computational data items, C-5
Input sequence specification, 10-44 signed numeric COMPUTATIONAL, C-13
Input/output control signed numeric COMPUTATIONAL-1, C-14
redirection of, 2-22, 8-1, 10-25 signed numeric COMPUTATIONAL-3, C-16
standard error device, 2-25, 6-7, 10-25 signed numeric COMPUTATIONAL-4, C-21
standard input device, 2-22, 10-25 unsigned numeric COMPUTATIONAL, C-11
standard output device, 2-24–2-25, 6-11, 6-18, unsigned numeric COMPUTATIONAL-3,
6-33, 6-41, 10-13, 10-25, 10-39 C-15
Insert Character key, 8-4 unsigned numeric COMPUTATIONAL-4,
INSERT-CHARACTER value, ACTION C-18
keyword, 10-41, 10-46 unsigned numeric COMPUTATIONAL-6,
Insertion mode C-24
ANSI, 10-45 numeric DISPLAY data items, C-5
RM, 10-45 signed numeric DISPLAY (LEADING
single-character, 10-45 SEPARATE), C-8
Installation signed numeric DISPLAY (LEADING), C-10
UNIX, 2-1–2-3 signed numeric DISPLAY (TRAILING
system considerations, 2-3–2-25. See also SEPARATE), C-7
Configuration records signed numeric DISPLAY (TRAILING), C-9
system requirements, 2-1 unsigned numeric DISPLAY (NSU), C-6
system verification, 5-1 Internal subprogram library, F-1
Windows, 3-1–3-7
registering the runtime, 3-5 K
system considerations, xliv, 3-7–3-45.
K Compile Command Option, 6-7, 6-18, 10-13
See also Configuration records
K keyword, RUN-OPTION configuration
system removal, 3-7
record, 10-33
system requirements, 3-1
K Runtime Command Option, 7-3, 10-33,
system verification, 5-3
A-41–A-42
Installing the utility programs, G-3
KEEP-FLOPPY-OPEN keyword, RUN-FILES-
Instrumentation
ATTR configuration record, 10-28
data analysis, 11-4
Key compression, 8-63, 10-32
ANALYSIS program, 11-4
KEY phrase
listing files processed by, 11-5
DISABLE statement, 8-69
suppression of, 11-7
ENABLE statement, 8-69
data collected, 11-2
KEY-COMPRESSION keyword, RUN-INDEX-
method of, 11-3
FILES configuration record, 10-32
sample data structure, 11-2
Keys
invocation of, 11-1
cursor types, 2-9, 3-43
Interactive Debugger. See Debug
defined, 8-2
INTERMEDIATE-FILES keyword, RUN-SORT
edit, 8-3
generate field termination codes, 8-5

L
Listing, 6-18
L (Line Display) Command, Debug option, 9-28
allocation map, 6-22, 10-12
L Compile Command Option, 6-9, 6-18, 6-33,
alphabet-names, symbolic-characters,
10-13, 10-14, 11-1
mnemonic-names and
L Runtime Command Option, 7-2, 7-6, 8-34,
class-names, 6-22
A-40, G-11
as used by Debug, 9-10
Language elements
constant-names, 6-27
extensions, I-2
data-names, condition-names, file-names
obsolete, I-8
and cd-names, 6-24
subset, I-9
index-names, 6-26
LANs. See Local area networks
split-key-names, 6-23
LARGE-FILE-LOCK-LIMIT keyword,
called program summary, 6-27
RUN-FILES-ATTR configuration record,
configuration, 10-12
xlii, 10-28, G-16
copy level indicator, 6-20
Left Arrow key, 8-3
cross reference listing, 6-28, 10-13
LEFT-ARROW value, ACTION
error marker and diagnostics, 6-31
keyword, 10-41, 10-46
error recovery, 6-32
Libraries, 6-3, 7-2
error threading, 6-33
internal subprogram, F-1
program listing, 6-19
Library files, 6-3, 7-2
listing header, 6-19
Table of Contents (TOC)
listing subheader, 6-19
rmmappgm utility, 3-4, G-12
summary listing, 6-29
rmpgmcom utility, 3-4, 6-3, G-9
summary of sections, 6-18
Library initialization, G-9
Listing file, 6-2, 6-3, 6-18
Limits and ranges
RM/COBOL, B-1
default extension, 10-19
RM/COBOL indexed files and Btrieve
LISTING keyword, EXTENSION-NAMES
MicroKernel Database Engine, 4-19
LINAGE clause, 8-43
Listing options, Compile Command, 6-8
LINAGE-COUNTER special-register, 10-8
LISTING-ATTRIBUTES keyword,
LINAGE-INITIAL-FORM-POSITION
keyword, PRINT-ATTR configuration
record, 6-22, 6-28, 10-12
record, 8-43, 10-21
LISTING-DATE-FORMAT keyword,
LINAGE-PAGES-PER-PHYSICAL-PAGE
keyword, PRINT-ATTR configuration
record, 10-13
record, 8-43, 10-22
LISTING-DATE-SEPARATOR keyword,
Line draw characters, 2-20, 3-41, 8-13, 8-28
LINE phrase, DISPLAY statement, 8-25
record, 10-14
Line sequential files
LISTING-FILE value, LISTING-ATTRIBUTES
configuring, 10-15, 10-35
keyword, 10-13
record delimiting technique, 6-8, 8-41
LISTING-PATHNAME keyword, COMPILER-
LINES keyword, PRINT-ATTR configuration
OPTIONS configuration record, 10-14
record, 10-22
X-16 Index
LISTING-TIME-SEPARATOR keyword, MCS. See Message Control System
COMPILER-OPTIONS configuration Memory available for a run unit, 2-7, 3-41
record, 10-14 MEMORY-SIZE keyword, RUN-SORT
Local area networks (LANs), 4-1, 4-4, 4-9, D-2 configuration record, 10-36
Locating RM/COBOL files Message Control System (MCS), 8-65, D-5
directory search sequences Message file processing errors, A-39
under UNIX, 2-4 Message files, 3-12
under Windows, 3-11 Messages. See also Runtime messages
file access names compiler
under UNIX, 2-5 banner, Compile Command, 6-33
under Windows, 3-13, 3-29 configuration errors, 6-35, 6-42
file locations within operating system error marker and diagnostic format, 6-31
pathnames error recovery, 6-32
under UNIX, 2-3, 10-27 error threading facility, 6-33
under Windows, 3-10, 10-27 exit codes, 6-44
NetWare search paths, 3-13 initialization errors, 6-43
Windows systems print jobs, 3-15 input/output errors, 6-35
LOG-PATH keyword, RUN-OPTION status, 6-34
configuration record, 10-33 syntax errors, 6-31
LOW keyword, CONTROL phrase, DISPLAY debug errors, 9-13
statement, 8-24 program exit codes, 7-8, 8-33
LOW phrase recover1, G-26, G-34
ACCEPT and DISPLAY statements, redirection of input and output, 2-22
8-17, 8-19 runtime errors, 7-7, A-1
DISPLAY statement, 8-25 Microsoft Windows
Low-intensity attribute, 2-20, 8-12, 8-25 32-bit implementation, xliii
LOWLIGHT. See LOW phrase CALL "SYSTEM", 3-45, 6-44, 7-8,
D-20, F-41
M configuration
creating a shortcut, 3-7
M (Modify) Command, Debug option, 9-28
filename extension associations, 3-9
M Compile Command Option, 2-23, 6-11, 10-6
prompting for a filename, 3-9
M keyword, RUN-OPTION configuration
Control menu, 3-43
record, 10-34
Copy option, 3-44
M Runtime Command Option, 2-25, 7-4, 10-34
Copy table option, 3-44
Makefile. See Customizing RM/COBOL for
icon, 3-42
UNIX
Paste option, 3-24, 3-44
Map Indexed File utility (rmmapinx), xlvi, 3-4,
Properties option, 3-44
8-61, G-14
default configuration example, 10-57
Map Program File utility (rmmappgm), 3-4, G-12
file sharing, 8-38
MASK keyword, CONTROL phrase,
ini2reg utility, xliii, 3-4, 3-16, G-40
ACCEPT and DISPLAY statements, xlii,
initialization files, 3-16
8-2, 8-3, 8-14
Masked input processing, xlii, 8-2, 8-14, 8-16

Microsoft Windows (Cont.) Microsoft Windows
installation and system requirements, xliv, properties, setting
3-1–3-7 Miscellaneous (Cont.)
registering the runtime, 3-5 Printer Dialog Never, 3-25
line draw characters, portable, 3-41 Printer Enable Escape Sequences, 3-26
locating RM/COBOL files Printer Enable Raw Mode, 3-26
directory search sequences, 3-11 Remove Trailing Blanks, 3-26
file access names, 3-13, 3-29 Scroll Buffer Size, 3-26
file locations within operating system Show Return Code Dialog, 3-27, 3-44
pathnames, 3-10, 10-27 Show Through Borders, 3-27
NetWare search paths, 3-13 Sizing Priority, 3-27
Windows system print jobs, 3-15 Status Bar, 3-27, F-38
memory available for a COBOL run unit, 3-41 Status Bar Text, 3-27, F-25
NetWare, 3-10, 4-4 SYSTEM Window Type, xliv,
performance, 3-45 3-28, F-42
printing, xxvi, 3-15, 3-25, 3-26, 10-18, E-1 Title Text, 3-28, 3-43, F-39, F-40
properties, setting, 3-17, 3-44 Toolbar, 3-21, 3-28
Color, 3-31 Update Timeout, 3-28
Menu Bar, 3-26, 3-34, 3-42, F-17 Use Windows Colors, 3-29, 8-12
Miscellaneous, 3-19 Pop-up Menu, xliv, 3-36, 3-43, F-22
Auto Paste, 3-20, 3-24, F-16 Properties dialog box, illustrated, 3-17
Auto Scale, 3-20, 3-27, F-16 selecting a file to configure, 3-17
Command Line Options, 3-20 Synonyms, 3-29
Enable Close, 3-20, F-16 Toolbar, 3-26, 3-32, 3-43, F-37
Enable Properties Dialog, 3-21, F-16 recover1.ini file, 3-16
Font, 3-21 registry file, xliii, 3-16, 3-22, 3-30, F-16
Full OEM To ANSI Conversions, rmcobol.ini file, 3-16
3-21, F-16 rmconfig utility, xliii, 3-4, 3-16, G-41
Icon File, 3-21, 3-32, F-33–F-39 runcobol.ini file, 3-16
Load Registry On CALL, 3-22, 3-30 runtime system screen
Load Registry On RETURN, 3-22, 3-30 cursor types, 3-43
Logo Bitmap, 3-22 described, 3-42
Logo Bitmap File, 3-23 system considerations, 3-7–3-45
Main Window Type, 3-23 SYSTEM subprogram, 3-45
Mark Alphanumeric, 3-23, 3-44, F-16 Toolbar editor, 3-21, 3-37, F-39
Offset X, 3-23 use with pop-up windows, 8-21
Offset Y, 3-24 Mnemonic-name, user-defined word type, 6-22
Panels Controls 3D, 3-24 MOVE-ATTR keyword, TERM-UNIT
Panels Static Controls Border configuration record, 10-50
property, 3-24 MULTIPLE phrase, LOCK MODE clause, file
Paste Termination, 3-24, F-16 control entry, 2-8, H-9
Persistent, 3-24, F-16, G-23 Multiple record locks, 2-8, H-9
Printer Dialog Always, 3-15, 3-25
X-18 Index
N OFF phrase, ACCEPT statement, 8-17, 8-20
ON EXCEPTION phrase
N Compile Command Option, 6-11
ACCEPT statement, 2-22–2-24, 8-5, 8-21
NAME keyword, EXTERNAL-ACCESS-
CALL statement, 8-35
METHOD configuration record, 10-20
ON OVERFLOW phrase, CALL statement, 8-35
Named pipe support, 8-47
Online services, xxxix
NetWare, 3-10, 4-4
OPEN OUTPUT
search paths, 3-13
block sizes in indexed files, xlvii, 8-56
system requirements, 3-1–3-2
sequential files in a shared environment, 8-38
Network file access, 2-8
OPEN statement
NO BEEP keyword
REVERSED phrase (sequential I-O), 8-44
WITH LOCK phrase, 8-38
OPTIONS keyword, EXTERNAL-ACCESS-
NO BLINK keyword
METHOD configuration record, 10-20
Organization of this guide, xxxiv
Overlay file, compiler, 2-5, 3-12
NO ERASE keyword, CONTROL phrase,
NO REVERSE keyword
P
CONTROL phrase, DISPLAY statement, 8-24 P Compile Command Option, 6-10, 6-18, 6-33,
RUN-ATTR configuration record, 10-25 6-41, 10-13
Nonnumeric data items, C-2 P$ChangeDeviceModes subprogram, E-37, E-44
NO-TERMINAL-DISPLAY value, LISTING- P$ClearDialog subprogram, E-15
ATTRIBUTES keyword, 10-13 P$ClearFont subprogram, E-24, E-29
Number of files a run unit can open, 2-8 P$DisplayDialog subprogram, 3-15, E-16
Number of region locks, 2-8 P$DrawBitmap subprogram, E-7, E-19
Numeric computational data items, C-5 P$DrawBox subprogram, E-20, E-22, E-23
Numeric DISPLAY data items, C-5 P$DrawLine subprogram, E-20, E-23
P$EnableDialog subprogram, 3-15, 3-25, E-16
O P$EnableEscapeSequences subprogram, E-38
P$GetDeviceCapabilities subprogram,
O Compile Command Option, 6-12, 10-14
E-39, E-44
Object file, 6-2, 6-3, 7-1
P$GetDialog subprogram, E-17, E-44
default extension, 10-19
P$GetHandle subprogram, E-41
OBJECT keyword, EXTENSION-NAMES
P$GetPosition subprogram, E-21, E-28
P$GetPrinterInfo subprogram, E-41, E-44
Object program options, Compile
P$GetTextExtent subprogram, E-25
Command, 6-11
P$GetTextMetrics subprogram, E-25, E-29, E-44
Object versions, G-13, H-1–H-10
P$GetTextPosition subprogram, E-28
OBJECT-PATHNAME keyword, COMPILER-
P$LineTo subprogram, E-21, E-23
P$MoveTo subprogram, E-22
Objects, external, 8-36
P$SetBoxShade subprogram, E-22, E-34
OBJECT-VERSION keyword, COMPILER-
P$SetDefaultAlignment subprogram, E-28
P$SetDefaultMode subprogram, E-7, E-8, E-35

P$SetDefaultUnits subprogram, E-8, E-36 Pop-up windows, 8-22
P$SetDialog subprogram, E-18, E-44 color terminal support, 8-24
P$SetFont subprogram, E-6, E-24, E-29, E-44 control block, 8-24, 8-27
P$SetHandle subprogram, E-41, E-43 binary allocation, 10-8
P$SetLeftMargin subprogram, E-36 defining the border, 8-28
P$SetLineExtendMode subprogram, E-31 defining the location, 8-28
P$SetPen subprogram, E-23 defining the location of the title, 8-29
P$SetPitch subprogram, E-31 defining the size, 8-28
P$SetPosition subprogram, E-23, E-33 defining the title, 8-30
P$SetRawMode subprogram, E-43 identifying, 8-28
P$SetTabStops subprogram, E-32 initializing, 8-29
P$SetTextColor subprogram, E-32 creating, 8-22
P$SetTextPosition subprogram, E-33 BEEP phrase, DISPLAY statement, 8-23
P$SetTopMargin subprogram, E-37 BLINK phrase, DISPLAY statement, 8-23
P$TextOut subprogram, E-32, E-34 CONTROL phrase, DISPLAY
PADDING CHARACTER clause, 8-37 statement, 8-24
PARITY keyword, TERM-UNIT configuration ERASE phrase, DISPLAY statement, 8-24
record, 10-50 HIGH phrase, DISPLAY statement, 8-25
PASS-THRU keyword, CONTROL phrase, LINE phrase, DISPLAY statement, 8-25
DISPLAY statement, 8-17 LOW phrase, DISPLAY statement, 8-25
PASS-THRU-ESCAPE keyword, TERM-ATTR POSITION phrase, DISPLAY
configuration record, 8-17, 10-39 statement, 8-25
PATH environment variable, 2-5, 3-12, 6-35, REVERSE phrase, DISPLAY
6-41, 8-36, G-26 statement, 8-25
PATH keyword UNIT phrase, DISPLAY statement, 8-26
DEFINE-DEVICE configuration record, customiz utility, under UNIX, D-3
10-17 installing with the customiz utility, xlvii
TERM-UNIT configuration record, 10-50 operation status, 8-30
Pathname, 2-3, 3-10 removing, 8-26
Performance, improved, 3-45 CONTROL phrase, DISPLAY
PICTURE character-string, window control statement, 8-26
block, 8-27 UNIT phrase, DISPLAY statement, 8-26
PIF. See Program information file sample program, 7-6
PIPE keyword, DEFINE-DEVICE configuration system verification, 5-2, 5-3
record, 10-17 use with the Windows operating system,
Piping, 2-22, 8-1 8-21, D-3
named pipe support, 8-47 POSITION phrase, DISPLAY statement, 8-25
Pop-Up Window Manager. See Pop-up windows PRECEDENCE keyword, TERM-INPUT
X-20 Index
PRINT-ATTR configuration record, 10-20 Printing, from Windows
AUTO-LINE-FEED keyword, 10-21 examples, code fragments (Cont.)
COLUMNS keyword, 10-21 print multiple copies, E-13, E-75
FORM-FEED-AVAILABLE keyword, 10-21 print multiple text outputs on the
LINAGE-INITIAL-FORM-POSITION same line, E-78
keyword, 8-43, 10-21 print text at the corners of a page, E-82
LINAGE-PAGES-PER-PHYSICAL-PAGE print text at the top of a page, E-81
keyword, 8-43, 10-22 set alignment of text, E-84
LINES keyword, 10-22 set text position, E-84
TOP-OF-FORM-AT-CLOSE keyword, 10-23 set the point size for a specific font, E-83
WRAP-COLUMN keyword, 10-23 set the printer device, display the Windows
WRAP-MODE keyword, 10-23 Print dialog box, and check the return
Printer code value, E-76
DEFINE-DEVICE configuration P$ subprogram functions, E-1–E-9
record, 10-17 bypass printer drivers and enable printing
file access names, 2-7 with escape sequences, E-85
support on sequential files, 8-46 change the current printer, E-43
PRINTER? printer device, 10-19, 3-15, E-4, change the orientation of the paper, E-37
E-16, E-41, E-43 change the paper source, E-37
Printing, from Windows, xxvi, 3-15, 3-25, 3-26, clear all font description values and return
10-18, E-1 them to their default (unset) state, E-24
copy files, E-44 clear values of the Windows Print dialog
escape sequences, RM/COBOL-specific, box to their default (unset) state, E-15
E-43, E-85 compute the printable area of the page to be
raw mode-byte I/O, E-43, E-85 printed, E-39
examples, code fragments concatenate lines while printing, E-31
change a font while printing, E-77 display Windows Print dialog box
change the orientation of the page, E-75 automatically when predefined
change the orientation of the paper, E-79 printer device (PRINTER?) is next
change the pitch of a font, E-79 opened, E-16
change the print resolution, E-75 draw a line starting at the current position,
draw a box around text, E-73 E-21
draw a box using relative positioning, E-73 draw boxes, E-20
draw a ruler, E-74 draw boxes around text, E-25
draw a shaded box with colors, E-73 draw lines, E-20
list of, E-71 enable a set of RM/COBOL-specific escape
open and write to separate printers, E-80 sequences, E-38
print a watermark, E-73 enable printing with RM/COBOL-specific
print a word in boldface type, E-78 escape sequences and bypass printer
print a word in italics, E-78 drivers, E-43
print a word underlined, E-78 font, returning to normal, E-6
print bitmap files, E-77 generate columns of text, E-36

Printing, from Windows Printing, from Windows
P$ subprogram functions(Cont.) P$ subprogram functions(Cont.)
invoke standard Windows Print set default mode used in positioning
dialog box, E-16 and sizing parameters, E-35
list of, E-2–E-4 set default unit of measurement
omitting P$ subprogram arguments, in positioning and sizing
OMITTED keyword, CALL parameters, E-36
statement, E-9 set new values in DEVMODE
print a bitmap file, E-19 structure, E-37
print multiple copies, E-13, E-75 set normal, compressed, or expanded
print partial reports, E-14 font pitch, E-31
reposition the line-draw pen without set output text on the printer while
drawing a line, E-22 bypassing COBOL WRITE
reset the printer, E-37 statement, E-34
retrieve characteristics of the set raw mode output when the next printer
current font, E-25 is opened, E-43
retrieve device capabilities of printer, E-39 set style, width, and color of pen tool for
retrieve ending position of the last print a box or line, E-23
operation, E-21 set tab stop increments, E-32
retrieve ending position the last print set top margin for subsequent pages, E-37
operation adjusted to the top or specify detailed printer information, E-41
bottom of the current font, E-28 using, E-6
retrieve handle to the current printer, E-41 common arguments, E-7
retrieve values from Windows Print overview, E-4
dialog box, E-17 Printer Dialog Always property, 3-25
set (change) fonts while printing to a Printer Dialog Never property, 3-25
Windows printer, E-29 Printer Enable Escape Sequences
set (initialize) values in Windows Print property, 3-26
dialog box, E-18 Printer Enable Raw Mode property, 3-26
set a left margin (offset from left side of Windows system print jobs, 3-15
paper) for the subsequent COBOL PRINT-LISTING value, LISTING-
WRITE statement, E-36 ATTRIBUTES keyword, 10-13
set a new position for the next print Program exit codes, 7-8
operation adjusted from the top or Program information file, 3-45
bottom of the current font, E-33 Program listing, 6-19
set a position for the next print Program names, resolution of, xlvii, 8-34
operation, E-23 Program, internal, F-1
set color and density of the color used in Prompt character, xlvii
P$DrawBox, E-22 PROMPT keyword, CONTROL phrase,
ACCEPT statement, xlvii, 8-18
set color for text output, E-32
PROMPT phrase, ACCEPT statement, 8-1, 8-3,
set default alignment used in text
8-17
positioning, E-28
Properties, setting. See Microsoft Windows
PURGE statement, 8-65
X-22 Index
Q
Registry file, xliii, 3-16
Q (Quit) Command, Debug option, 9-33
C$GUICFG subprogram, F-16
Q Compile Command Option, 6-13, 9-1, 11-3,
Initialization File to Windows Registry
A-2, F-11, F-40
Conversion utility (ini2reg), xliii, 3-4,
3-16, G-40
R Load Registry On CALL property, 3-22, 3-30
R (Resume) Command, Debug option, 9-34, A-2 Load Registry On RETURN property,
R Compile Command Option, 6-10, 10-15 3-22, 3-30
RAW keyword, DEFINE-DEVICE configuration RM/COBOL Configuration utility (rmconfig),
record, 3-26, 10-17, E-43 xliii, 3-4, 3-16, G-41
READ statement Relative File Conversion utility
WITH NO LOCK phrase (indexed I-O), 8-55 rmcrl1, G-6
WITH NO LOCK phrase (relative I-O), 8-49 rmcrl2, G-7
WITH NO LOCK phrase Relative files, 8-40, 8-47. See also File types
(sequential I-O), 8-44 and structure
RECEIVE statement, 8-65 Relativity, 1-3
RECORD clause, 8-42, 8-48, 8-52 Removing pop-up windows, 8-26
Record delimiting techniques Renaming executables, 1-4
binary sequential, 6-8, 8-42 REPAINT-SCREEN keyword, CONTROL
configuring, 10-15, 10-34 phrase, ACCEPT and DISPLAY
line sequential, 6-8, 8-41 statements, 8-18, D-23
RECORD KEY clause, file control entry, REPAINT-SCREEN value, ACTION
DUPLICATES phrase, H-8 keyword, 10-41, 10-46
Record locking, 2-8, H-9 REPLACING LINE phrase, SEND
time-out settings, 10-27, 10-30 statement, 8-69
Redirection of input and output control, 2-22, RESEQUENCE-LINE-NUMBERS keyword,
6-18, 8-1, 10-25 COMPILER-OPTIONS configuration
REDRAW-ON-CALL-SYSTEM keyword, record, 10-14
TERM-ATTR configuration record, 10-39, RESERVE clause, 8-44, 8-49, 8-54
D-20 Reserved words, dereserve, 6-16, 10-12
REEL phrase, CLOSE statement RESET-ANSI-INSERTION value, ACTION
(sequential I-O), 8-45 keyword, 10-41, 10-46
Region lock facility, H-9 Resolution of program names, xlvii, 8-34
under UNIX, 2-8 RESOLVE-LEADING-NAME keyword,
Registering the runtime, 3-5 RUN-FILES-ATTR configuration
Registration, xxxix record, 2-6, 3-15, 10-29
RESOLVE-SUBSEQUENT-NAMES
keyword, RUN-FILES-ATTR
configuration record, 2-6, 3-15, 10-30
RETURN-CODE special register, 7-8, 8-33
Reverse attribute, 2-20

REVERSE keyword RM/COBOL (Cont.)
CONTROL phrase, DISPLAY statement, 8-24 file naming conventions, 1-4
RUN-ATTR configuration record, 10-25 for UNIX
REVERSE phrase customizing, 10-2, D-1
ACCEPT and DISPLAY installation and system
statements, 8-20, 10-25 requirements, 2-1–2-3
DISPLAY statement, 8-25 system considerations, 2-3–2-25
REVERSED phrase, OPEN statement for Windows
(sequential I-O), 8-44 installation and system
REVERSE-VIDEO phrase. See REVERSE requirements, xliv, 3-1–3-7
phrase registering the runtime, 3-5
Right Arrow key, 8-3 system considerations, 3-7–3-45
RIGHT-ARROW value, ACTION instrumentation, 11-1
keyword, 10-41, 10-47 internal data formats, C-1
RM insertion mode internal libraries and utility programs, 1-2
field editing, 10-45 limits and ranges, 4-19, B-1
SET-RM-INSERTION value, 10-47 local area networks (LANs), 4-1, 4-4, 4-9
RM/COBOL NetWare, 3-1–3-2, 3-10, 3-13, 4-4
add-on packages, 1-3 object versions, H-1
Btrieve, 3-2, 4-1 P$ subprograms, xxvi, E-1
CodeBridge, xxvi, 1-2, F-4 printing from Windows, xxvi, E-1
code-set translation tables, J-1 renaming executables, 1-4
CodeWatch, xxvi, 1-2, 3-4, 6-13 runtime messages, A-1
compiler, 1-1, 6-1 runtime system, 1-1, 7-1
configuration, 10-1 software, 1-1
debugging, 9-1 subprogram library, F-1
extension, obsolete, and subset language system verification, 5-1
elements, I-1 RM/COBOL and ANSI COBOL, 6-7
features, xxv, xli–xlvii, 8-1–8-22 RM/COBOL Configuration utility (rmconfig),
ACCEPT and DISPLAY statements, xliii, 3-4, 3-16, G-41
operating-system specific information, RM/COBOL indexed files and Btrieve
8-1–8-21 MicroKernel Database Engine
CALL statement, 8-33 limitations, 4-19
file buffering, 8-40, 8-49, 8-54 automatic creation of variable-length record
file sharing, 8-38 files, 4-23
file types and structure, 8-40 current record position limitations, 4-19
indexed file performance, 8-59 effect on input/output errors, 4-24
message control system (MCS), 8-65 effect on RM/COBOL applications, 4-22
pop-up windows, 8-21 file position indicator limitations, 4-20
STOP RUN numeric statement and key placement, 4-23
RETURN-CODE special register, 8-33 Permission Error detection limitations, 4-21
temporary files, 8-59, 10-19
X-24 Index
RM/COBOL indexed files and Btrieve RM/Panels, 1-3
MicroKernel Database Engine Load Registry On CALL property, 3-22
limitations (Cont.) Load Registry On RETURN property, 3-22
support for Btrieve internal data formats, 4-24 pop-up menus, 3-36
support for RM/COBOL internal data formats, three-dimensional controls, 3-24
4-23 RM/plusDB, 10-20, D-3
using existing Btrieve files with RM/COBOL, rmattach utility, xlv, 10-2, G-39
4-21 rmbtrv32 program. See RM/COBOL-to-Btrieve
variable-length records, 4-7, 4-15, 4-23 Adapter (rmbtrv32) program; Btrieve
verification of maximum record and block rmcobol (Compile Command), 6-1, 6-3
length, 4-23 RMCOBOL-2 keyword, COMPILER-OPTIONS
RM/COBOL Open File Manager, 10-20, D-2 configuration record, 10-15
RM/COBOL-to-Btrieve Adapter (rmbtrv32) rmconfig utility, xliii, 3-4, 3-16, G-41
program. See also Btrieve rmdefinx utility, 3-4, 8-50, 8-56, 8-64, 8-65,
Btrieve MicroKernel Database Engine A-31, G-19
(MKDE), 4-4, 4-5 rmmapinx utility, xlvi, 3-4, 8-61, G-14
Btrieve software requirements, 3-2 rmmappgm utility, 3-4, G-12
COBOL application programs, 4-5 RMPATH environment variable, 2-4, 3-11–3-13,
concepts, 4-1 3-30, 8-32
configuration options, 4-9, 10-20 rmpgmcom utility, 3-4, 6-3, 6-13, 10-11,
EXTERNAL-ACCESS-METHOD record 10-16, G-9
B rmbtrv32 MKDE page size, 4-10 ROWS keyword, TERM-ATTR configuration
C create, 4-10 record, 3-26, 10-39
D duplicates, 4-11 RUN-ATTR configuration record, 10-23
I initial display, 4-12 ACCEPT-FIELD-FROM-SCREEN keyword,
L lock, 4-13 8-1, 10-23
M mode, 4-14 ACCEPT-INTENSITY keyword, 10-23
O owner, 4-15 ACCEPT-PROMPT-CHAR keyword, 10-24
P rmbtrv32 page size, 4-8, 4-15, 4-23 BEEP keyword, 10-24
T diagnostic trace filename, 4-15 BLINK keyword, 10-24
RUN-INDEX-FILES record DISPLAY-INTENSITY keyword, 10-24
BLOCK-SIZE, 4-16 EDIT-COMMA keyword, 10-24
DATA-COMPRESSION, 4-16 EDIT-CURRENCY-SYMBOL
dynamic link libraries, 4-5, 4-18 keyword, 10-24
enhancements, xliv EDIT-DECIMAL keyword, 10-25
file management system, RM/COBOL, 4-6 EDIT-DOLLAR keyword, 10-25
indexed files, 4-1, 4-5 ERROR-MESSAGE-DESTINATION
RUNPATH environment variable, 4-10 keyword, 2-25
starting, 4-18 REVERSE keyword, 10-25
system considerations for Btrieve files, 4-7 SCROLL-SCREEN-AT-TERMINATION
RM/InfoExpress, xlvii, 1-3, 10-20, D-2 keyword, 10-25
TAB keyword, 10-26
UNDERLINE keyword, 10-26

runcobol (Runtime Command), 7-1 RUN-OPTION configuration record, 10-33
RUN-FILES-ATTR configuration B keyword, 10-33
record, xlii, 10-26 ENABLE-LOGGING keyword, 10-33
ALLOW-EXTENDED-CHARS-IN- K keyword, 10-33
FILENAMES keyword, 10-26 LOG-PATH keyword, 10-33
BLOCK-SIZE keyword, 10-26 M keyword, 10-34
BUFFER-POOL-SIZE keyword, 6-43, 8-40, RUNPATH environment variable, 2-4,
8-60, 10-26, A-7, A-28, G-34 3-11–3-13, 3-30, 4-10, 8-35
DISABLE-COMMIT-FILE keyword, 10-27 RUN-REL-FILES configuration record,
ENABLE-OLD-DOS-FILENAME- xlii, 10-34
HANDLING keyword, 10-27 BLOCK-SIZE keyword, 10-34
EXPANDED-PATH-SEARCH keyword, 2-3, USE-LARGE-FILE-LOCK-LIMIT
3-10, 10-27 keyword, xlii, 10-34
FATAL-RECORD-LOCK-TIMEOUT RUN-SEQ-FILES configuration record,
keyword, 10-27 xlii, 10-34
FILE-HANDLE-LIMIT keyword, 10-27 BLOCK-SIZE keyword, 10-34
FILE-LOCK-LIMIT keyword, 10-28 DEFAULT-TYPE keyword, 10-35
FILE-PROCESS-COUNT keyword, 10-28 DEVICE-SLEWING-RESERVE
FORCE-USER-MODE keyword, 3-45, 10-28 keyword, 10-35
KEEP-FLOPPY-OPEN keyword, 10-28 TAB-STOPS keyword, 10-35
LARGE-FILE-LOCK-LIMIT keyword, xlii, USE-LARGE-FILE-LOCK-LIMIT
10-28, G-16 keyword, xlii, 10-35
RESOLVE-LEADING-NAME keyword, 2-6, RUN-SORT configuration record, 10-36
3-15, 10-29 INTERMEDIATE-FILES keyword, 10-36
RESOLVE-SUBSEQUENT-NAMES MEMORY-SIZE keyword, 10-36
keyword, 2-6, 3-15, 10-30 Runtime Command, 7-1
USE-PROCEDURE-RECORD-LOCK- input/output control redirection,
TIMEOUT keyword, 10-30 under UNIX, 2-22
RUN-INDEX-FILES configuration invoking, 7-1
record, 4-16, 10-31 messages
ALLOCATION-INCREMENT diagnostic, 7-7
keyword, 10-31 execution, 7-7
ATOMIC-TRANSFER-SIZE keyword, 10-31 program exit codes, 7-8
BLOCK-SIZE keyword, 10-31 options, 7-2
DATA-COMPRESSION keyword, 10-31 banner and STOP RUN message
DEFAULT-FILE-VERSION-NUMBER suppression (K), 7-3, 10-33,
keyword, 10-31 A-41–A-42
FORCE-CLOSED keyword, 8-51, 10-31 configuration file (C), 7-3, 10-1, A-38
FORCE-DATA keyword, 8-52, 10-32 instrumentation (I), 7-3, 11-1
FORCE-DISK keyword, 8-52, 10-32 invoke Interactive Debugger (D), 7-3, 9-1
FORCE-INDEX keyword, 8-52, 10-32 level 2 semantics for Format 1 ACCEPT
KEY-COMPRESSION keyword, 10-32 and DISPLAY statements (M),
2-25, 7-4, 10-34
X-26 Index
Runtime Command S
options (Cont.)
S (Step) Command, Debug option, 9-35
maximum size for ACCEPT and DISPLAY
S Compile Command Option, 6-7, 6-16, 10-15,
buffers (B), 7-4, 8-20, 10-33
C-7, C-9
memory to be used for a sort
S Runtime Command Option, 7-4, 11-7
operation (T), 7-4, A-7, A-36
Scan suppression, 6-32
object or non-COBOL program libraries
Screen field, initial contents, 8-1
(L), 7-2, 7-6, 8-34, A-40, G-11
Screen width, 8-18
pass an argument to the main
SCREEN-COLUMNS keyword, CONTROL
program (A), 7-5
phrase, ACCEPT and DISPLAY
supplemental runtime configuration
statements, 8-18
file (X), 7-3, 10-1, A-38
SCREEN-CONTENT-OPTIMIZE keyword,
switch set and reset (S), 7-4, 11-7
samples of valid and invalid, 7-6
SCREEN-ESCAPE value, ACTION
types of options
keyword, 10-41, 10-47
configuration, 7-3
SCREEN-HOME value, ACTION
debug and test, 7-3
keyword, 10-41, 10-47
environment, 7-4
SCREEN-PREVIOUS-FIELD value, ACTION
program, 7-5
keyword, 10-41, 10-47
Runtime messages
SCREEN-TERMINATE value, ACTION
error message format, A-1
keyword, 10-41, 10-47
error message types, 7-7, A-1
SCROLL-SCREEN-AT-TERMINATION
COBOL normal termination, A-1, A-42
keyword, RUN-ATTR configuration
configuration, A-1, A-37
record, 10-25
data reference, A-1, A-3
SECURE phrase, ACCEPT statement, 8-17,
input/output, A-1, A-11
8-20. See also OFF phrase
internal error, A-1, A-36
Segmentation, 6-1
message control, A-1, A-37
SELECT clause, use of, 3-14
operator-requested termination, A-1, A-3
SEND statement, 8-65, 8-69
procedure, A-1, A-6
Separate sign
runcobol initialization messages, A-1, A-39
compiler option, 6-7
initialization errors, A-39
main program loading errors, A-40
leading, C-8
message file processing errors, A-39
trailing, C-7
option processing errors, A-40
SEPARATE-SIGN keyword, COMPILER-
registration error messages, A-41
runcobol banner message, A-41
Sequential File Conversion utility (rmcseq), G-8
runcobol usage message, A-41
Sequential files, 8-40, 8-41. See also File types
sort-merge, A-1, A-36
and structures
traceback, A-1, A-3
SEQUENTIAL-FILE-TYPE keyword,
record, 10-15

SET-ANSI-INSERTION value, ACTION Split keys, 4-7, 6-23
keyword, 10-41, 10-47 Split-key-name, user-defined word type, 6-23
SET-RM-INSERTION value, ACTION Standard error device, 2-25, 6-7, 10-25
keyword, 10-41, 10-47 Standard input device, 2-22, 10-25
Shared environments, 8-38 Standard output device, 2-24–2-25, 6-11, 6-18,
Sign, operational 6-33, 6-41, 10-13, 10-25, 10-39
compiler option, 6-7 STOP literal statement, 2-25, 7-7
configuration, 10-15 STOP RUN numeric statement, 8-33
leading combined, C-10 STOP-BITS keyword, TERM-UNIT
leading separate, C-8 configuration record, 10-51
trailing combined, C-9 STRIP option (rmpgmcom utility), 6-13, 10-11,
trailing separate, C-7 10-16, G-9
Signed COMPUTATIONAL, C-13 Subprogram libraries, xxvii, F-1
Signed COMPUTATIONAL-1, C-14 Subprogram loading, 8-34, D-13
Signed numeric COMPUTATIONAL-3, C-16 resolution of program names, xlvii
Signed numeric COMPUTATIONAL-4, C-21 Summary listing, 6-29
Signed numeric DISPLAY (LEADING Support services, technical, xxxix
SEPARATE), C-8 SUPPRESS-COPY-FILES value, LISTING-
Signed numeric DISPLAY (LEADING), C-10 ATTRIBUTES keyword, 10-13
Signed numeric DISPLAY (TRAILING SUPPRESS-NULLS keyword, TERM-ATTR
SEPARATE), C-7 configuration record, 10-40
Signed numeric DISPLAY (TRAILING), C-9 SUPPRESS-NUMERIC-OPTIMIZATION
SIZE phrase keyword, COMPILER-OPTIONS
ACCEPT and DISPLAY statements, 2-23, configuration record, 10-15
2-25, 8-17, 8-20 Switches, 7-4
START statement (relative and Symbolic-character, user-defined word type, 6-22
indexed I-O), H-7 Symbols and conventions, xxxvii
Sort files, temporary, 8-59 SYMBOL-TABLE-OUTPUT keyword,
SORT statement COMPILER-OPTIONS configuration
configuring, 10-36 record, 10-16
errors, A-36 Synonyms
memory, 7-4, 10-36 entries in file access names, 2-5, 3-13
Sort-merge facility, temporary files, 8-59 in directory search sequences, use of, 3-11
Source file, 6-2, 6-3 properties, setting, 3-11, 3-29
default extension, 10-19 Syntax errors, 6-31
SOURCE keyword, EXTENSION-NAMES System files. See Files
configuration record, 10-19 SYSTEM subprogram, 3-45, 6-44, 7-8,
Source listing, 6-19 D-20, F-41
Source program options, Compile System verification
Command, 6-15 under UNIX, 5-1
Special-registers under Windows, 5-3
LINAGE-COUNTER, 10-8
RETURN-CODE, 7-8, 8-33
X-28 Index
T
Termcap, 8-2
T (Trap) Command, Debug option, 9-36
database, 2-10–2-22
T Compile Command Option, 6-11, 6-18, 6-33,
default configuration, 10-51
6-41, 10-13
changing, D-2
T Runtime Command Option, 7-4, A-7, A-36
terminal input and output, 2-9
TAB keyword
TERMCAP environment variable, 2-10
CONTROL phrase, ACCEPT statement, 8-17
TERMCAP keyword, TERM-INTERFACE
TAB phrase, ACCEPT statement, 8-17
Terminal attributes, 2-9
Tab stops
configuring, 10-36
configuring, 10-35
Terminal input and output
source files (BDS), 6-2
cursor types, 2-9
Table of Contents (TOC)
rmmappgm utility, G-12
rmpgmcom utility, G-9
Terminal interfaces, 2-9, D-2
TAB-STOPS keyword, RUN-SEQ-FILES
TERMINAL-LISTING value, LISTING-
ATTRIBUTES keyword, 10-13
Tape
Terminate. See SCREEN-TERMINATE value
DEFINE-DEVICE configuration
Terminfo, 8-2
record, 10-17
database, 2-10–2-22
file access names, 2-7
default configuration, 10-54
support on sequential files, 8-47
changing, D-2
Technical support services, xxxix
terminal input and output, 2-9
TEMP, locating temporary files, 8-59
TERMINFO environment variable, 2-11
Temporary files, locating, 8-59
TERMINFO keyword, TERM-INTERFACE
TERM environment variable, 2-11, 8-18
TERM-INPUT configuration record, 10-41
BCOLOR keyword, 10-36
ACTION keyword, 10-41
field editing actions
8-21, 10-36
BACKSPACE value, 10-45
COLUMNS keyword, 10-37
CONTROL-BREAK value, 10-45
DATA-CHARACTERS keyword, 10-37
DELETE-CHARACTER value, 10-45
DBCS-CHARACTERS keyword, xlii, 10-37
ERASE-ENTIRE value, 10-46
FCOLOR keyword, 10-39
ERASE-REMAINDER value, 10-46
PASS-THRU-ESCAPE keyword, 8-17, 10-39
ESCAPE-TO-COMMAND value, 10-46
REDRAW-ON-CALL-SYSTEM
ESCAPE-TO-OS value, 10-46
keyword, 10-39, D-20
FIELD-HOME value, 10-46
ROWS keyword, 3-26, 10-39
INSERT-CHARACTER value, 10-46
SCREEN-CONTENT-OPTIMIZE
LEFT-ARROW value, 10-46
keyword, 10-39
REPAINT-SCREEN value, 10-46
SUPPRESS-NULLS keyword, 10-40
RESET-ANSI-INSERTION value, 10-46
USE-COLOR keyword, 10-40
RIGHT-ARROW value, 10-47

TERM-INPUT configuration record Time-out, BEFORE TIME phrase, ACCEPT
ACTION keyword statement, 8-21, 10-36
field editing actions (Cont.) TMP, locating temporary files, 8-59
SCREEN-ESCAPE value, 10-47 TOGGLE-ANSI-INSERTION value, ACTION
SCREEN-HOME value, 10-47 keyword, 10-41, 10-48
SCREEN-PREVIOUS-FIELD TOP-OF-FORM-AT-CLOSE keyword,
value, 10-47 PRINT-ATTR configuration record, 10-23
SCREEN-TERMINATE value, 10-47 TYPE keyword, TERM-UNIT configuration
SET-ANSI-INSERTION value, 10-47 record, 10-51
SET-RM-INSERTION value, 10-47
TOGGLE-ANSI-INSERTION U
value, 10-48
U (Untrap) Command, Debug option, 9-40
character sequence specifications, 10-42
U Compile Command Option, 6-7, 10-10
CODE keyword, 10-41
UNC. See Universal naming convention
DATA keyword, 10-42
Underline attribute, 2-20
EXCEPTION keyword, 10-42
UNDERLINE keyword, RUN-ATTR
field editing actions, 10-45
input sequence specification, 10-44
UNIT keyword, TERM-UNIT configuration
PRECEDENCE keyword, 10-42
record, 10-51
TERM-INTERFACE configuration record, 10-49
UNIT phrase
GUI keyword, 10-49
CLOSE statement (sequential I-O files), 8-45
TERMCAP keyword, 10-49
TERMINFO keyword, 10-49
Universal naming convention (UNC), 3-10
WINDOWS keyword, 10-49
UNIX
TERM-UNIT configuration record, 10-49
customizing RM/COBOL, D-1
BPS keyword, 10-49
input/output control redirection, 2-22
CHARACTER-WIDTH keyword, 10-50
installation and system requirements, 2-1–2-3
DEFINE-CONTROL-CHARACTERS
locating RM/COBOL files
keyword, 10-50
directory search sequences, 2-4
MOVE-ATTR keyword, 10-50
file access names, 2-5
PARITY keyword, 10-50
file locations within operating system
PATH keyword, 10-50
pathnames, 2-3
STOP-BITS keyword, 10-51
memory available for a COBOL run unit, 2-7
TYPE keyword, 10-51
network file access, 2-8
UNIT keyword, 10-51
number of files, 2-8
Tilde (~)
number of region locks, 2-8
file locations, 2-3, 10-27
pathnames, 2-3
negation character, Compile
system considerations, 2-3–2-25
Command line, 6-4
terminal input and output
setting menu bar properties, 3-35
cursor types, 2-9
setting pop-up menu properties, 3-36
Time, listing separator configuration, 10-14
Unsigned numeric COMPUTATIONAL, C-11
X-30 Index
Unsigned numeric COMPUTATIONAL-3, C-15 Utilities (Cont.)
Unsigned numeric COMPUTATIONAL-4, C-18 Relative File Conversion
Unsigned numeric COMPUTATIONAL-6, C-24 rmcrl1, G-6
Unsigned numeric DISPLAY (NSU), C-6 rmcrl2, G-7
UPDATE phrase, ACCEPT statement, 8-1 RM/COBOL Configuration (rmconfig),
UPON/FROM CONSOLE phrase, ACCEPT and xliii, 3-4, 3-16, G-41
DISPLAY statements, 2-22–2-25 Sequential File Conversion (rmcseq), G-8
USAGE clause, 10-10, C-5
data description entry, 10-8 V
USE-COLOR keyword, TERM-ATTR
V Compile Command Option, 6-8, 6-16, 10-15
VanGui Interface Builder, 1-3, D-5
USE-LARGE-FILE-LOCK-LIMIT keyword
Variable-length records, 4-7, 4-15, 4-23
RUN-REL-FILES configuration
Verification procedures
record, xlii, 10-34
for UNIX, 5-1
USE-LARGE-FILE-LOCK-LIMIT keyword,
for Windows, 5-3
RUN-SEQ-FILES configuration
Version number, file, xlii, 8-56, 8-64, 10-31,
record, xlii, 10-35
G-16, G-22
USE-PROCEDURE-RECORD-LOCK-
Video display attributes, 2-9
TIMEOUT keyword, RUN-FILES-ATTR
User-defined words, 6-22
W
Utilities W Compile Command Option, 6-7, 10-16
Attach Configuration (rmattach), xlv, WANs. See Wide Area Networks (WANs)
10-2, G-39 WCB-BORDER-CHAR parameter, 8-28
Combine Program (rmpgmcom), 3-4, 6-3, WCB-BORDER-SWITCH parameter, 8-28
6-13, 10-11, 10-16, G-9 WCB-BORDER-TYPE parameter, 8-28
Define Indexed File (rmdefinx), 3-4, 8-50, WCB-FILL-SWITCH parameter, 8-29
8-56, 8-64, 8-65, A-31, G-19 WCB-HANDLE parameter, 8-28
delivered media, G-2 WCB-LOCATION-REFERENCE
Indexed File Conversion (rmifca parameter, 8-28
and rmifcb), G-4 WCB-NUM-COLS parameter, 8-28
Indexed File Recovery (recover1), xlii, xlvi, WCB-NUM-ROWS parameter, 8-28
2-5, 3-4, 3-12, 3-16, 3-18, 8-51, 8-64, WCB-TITLE parameter, 8-29
8-65, 10-31, A-13, A-31, G-23 WCB-TITLE-JUSTIFICATION parameter, 8-29
recover2, xlii, G-35 WCB-TITLE-LENGTH parameter, 8-29
recovery, xlii WCB-TITLE-LOCATION parameter, 8-29
Initialization File to Windows Registry Web site, xxxix
Conversion (ini2reg), xliii, 3-4, Wide area networks (WANs), D-2
3-16, G-40 WINDOW-CREATE keyword, pop-up windows
installation, 2-2, G-3 CONTROL phrase, 8-22
Map Indexed File (rmmapinx), xlvi, 3-4, WINDOW-REMOVE keyword, pop-up windows
8-61, G-14 CONTROL phrase, 8-26
Map Program File (rmmappgm), 3-4, G-12

Windows. See Microsoft Windows; Pop-up
windows; Printing, from Windows
WINDOWS keyword, TERM-INTERFACE
WITH DUPLICATES phrase, RECORD KEY
clause, H-8
WITH LOCK phrase, OPEN statement (relative
and indexed I-O), 8-38, 8-64
WITH NO LOCK phrase, READ statement,
8-44, 8-49, 8-55
WITH NO REWIND phrase, CLOSE statement
(sequential I-O), 8-44
WITH phrase, SEND statement, 8-69
WORKSPACE-SIZE keyword, COMPILER-
WRAP-COLUMN keyword, PRINT-ATTR
WRAP-MODE keyword, PRINT-ATTR
WRITE statement
ADVANCING mnemonic-name phrase
ADVANCING ZERO LINES phrase
X
X Compile Command Option, 6-11, 6-28, 10-13
X Runtime Command Option, 7-3, 10-1, A-38
Y
Y Compile Command Option, xxxiii, 6-13, 9-1,
9-5, 9-6, 10-11, 10-16, G-9, H-10
Year 2000 subprogram, xlvi, F-7
Z
Z Compile Command Option, 6-14, H-2
Zoned sign
leading, C-10
trailing, C-9
X-32 Index
Liant Software Corporation
License Agreement
THIS LICENSE AGREEMENT SETS FORTH THE TERMS AND CONDITIONS OF THE LICENSE AND THE
LIMITED WARRANTY FOR THE SOFTWARE ON THE ENCLOSED MAGNETIC AND/OR CD-ROM MEDIA.
CAREFULLY READ THE FOLLOWING LICENSE AGREEMENT BEFORE BREAKING THE SEAL ON ANY
OF THE MEDIA. BY BREAKING THE SEAL YOU ACCEPT THE TERMS OF THIS AGREEMENT. IF YOU
DO NOT ACCEPT THE TERMS OF THIS AGREEMENT, DO NOT OPEN ANY OF THE MEDIA; PROMPTLY
RETURN THE ENTIRE PACKAGE TO YOUR DEALER FOR A FULL REFUND.
DEFINITIONS
The following definitions apply to the terms as they appear in this agreement.
• Liant means Liant Software Corporation, a Delaware corporation.
• You and Your refer to any person or entity that acquires or uses this Package.
• Package means the Software, user's manual(s), and other items accompanying this
agreement.
• Software refers to the computer program contained in this Package, together with all codes,
techniques, software tools, formats, designs, concepts, methods, and ideas associated with
that computer program. The term also includes all copies of any part of the Software, as well
as the user manual(s), other printed materials, and any "online" or electronic documentation,
contained in this Package.
• Media means magnetic disks, tape, and/or CD-ROM containing the Software.
• LAN means a local area network of computers interconnected to each other or to a hub or
concentrator by metallic or fiber-optic circuits. Computers or networks connected over public
common carrier circuits or over a public switched-circuit network, are not considered to be a
single LAN.
• Usage Level means the number of simultaneous uses of the Software on a single computer
or LAN, permitted under this agreement as indicated on the Media.
PERMITTED USES
Liant grants You a non-exclusive license to use the Software in this Package according to the
terms set forth below.
You may:
• Install the Software on one computer at a time.
• Make one backup copy of the Software, which automatically becomes the property of Liant
and is subject to this agreement.
• Operate the Software on one computer or LAN at a time.
• In the case of LAN installations, operate the Software on as many computers on a single LAN
as is permitted by the Software's Usage Level.
• In the case of a multiuser computer, operate the Software to service up to the number of
concurrent program executions permitted by the Software's Usage Level.
PROHIBITED USES
You may not:
• Allow the Software to become available to any person or entity other than Your employees.
You may, however, after written notification to Liant, transfer all (but no lesser portion) of the
Software to another person or entity who is not otherwise prohibited by this agreement to use
the Software, provided such person or entity agrees in writing to be subject to all terms of this
agreement.
• Modify the Software or merge it with another program, except for Your personal use on a
single computer. The program resulting from any modification or merger of the Software is
subject to this agreement.
• Reverse engineer, disassemble, decompile, or make any attempt to discover the source code
to the Software.
• Translate or create derivative works based on the Software.
• Remove, obscure, or alter any notice of the patent, copyright, or other proprietary rights
related to the Software.
• Sub-license, sell, lend, rent, or lease any portion of the Software, directly or indirectly.
• Copy any portion of the Software, except to make a backup copy, as described above under
Permitted Uses.
• Transfer the Software or any direct, modified or merged product thereof to any person or
entity in violation of the United States Export Administration Act.
• Operate the Software on more than one computer or LAN at a time, except as described
above under Permitted Uses.
The Software involves valuable proprietary rights of Liant and others. There is no transfer to
You of any title to or ownership of the Software or any patent, copyright, trade secret, trade name,
trademark, and other proprietary rights related to the Software, regardless of the form that original
or other copies exist in. You may not violate these rights, and You must take all appropriate steps
to protect Liant's rights. Liant may at any time replace, modify, alter, improve, enhance, or change
the Software without prior notice.
Both the license and Your right to use the Software terminate automatically if You violate any
part of this agreement. In the event of termination, You must immediately destroy all copies of the
Software or return them to Liant.
LIMITED WARRANTY
For a period of ninety (90) days from the date You received the Software, Liant warrants that, upon
delivery by Liant and acceptance by You, the media on which the Software is distributed will be
materially free from defects in materials and workmanship and that the Software will substantially
conform to the specifications established by Liant. This warranty gives You specific legal rights,
and You may also have other rights that vary from state to state.
If any of the Software fails to comply with the warranties set forth above, Liant will replace the
Media or, at Liant's option, make a reasonable effort to correct the program errors. You must,
however, return all copies of the Software, along with a copy of Your paid invoice, to an authorized
Liant dealer within ninety (90) days of the date You received the Software. If Liant is unable to
correct defective Media or program errors, Liant will refund all or a fair portion of the price You paid
for this Package, at Liant's option. The refund will fully satisfy Your claims for Software or Media
failure. Any replacement software will be warranted for the rest of the original 90-day warranty
period or for thirty (30) days from the date You received the replacement, whichever is longer.
Liant WILL NOT BE LIABLE FOR ANY:
• BUG, ERROR, OMISSION, DEFECT, DEFICIENCY, OR NONCONFORMITY IN ANY SOFTWARE.
• IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
• IMPLIED WARRANTY RELATING TO COURSE OF PERFORMANCE, COURSE OF DEALING, OR
USAGE OF TRADE OR ANY OTHER IMPLIED WARRANTY OF ANY TYPE WHATSOEVER.
• CLAIM OF INFRINGEMENT.
• CLAIM IN TORT, WHETHER OR NOT ARISING IN WHOLE OR IN PART FROM Liant's FAULT,
NEGLIGENCE, STRICT LIABILITY, OR PRODUCT LIABILITY.
• CLAIM FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES,
COVER, OR LOSS OF DATA, REVENUE, CUSTOMERS, GOODWILL OR USE.
Any written or oral information or advice given by Liant dealers, distributors, agents, or employees
will in no way increase or modify the scope of this warranty. Nor may You rely on any such written
or oral communication.
GENERAL
Under this agreement, Liant is not responsible for maintaining or helping You to use the Software.
This agreement constitutes the entire agreement and supersedes any prior agreement
between Liant and You concerning this Package. Liant is not bound by any provision of any
purchase order, receipt, acceptance, confirmation, correspondence, or otherwise. This agreement
cannot be amended, modified, or waived, unless the change is written, specifically identified as an
amendment and signed by an authorized Liant representative and You.
U.S. GOVERNMENT RESTRICTED RIGHTS
The Software and accompanying documentation are provided with RESTRICTED RIGHTS. Use,
duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph
(c)(1)(ii) of the Rights in Technical Data and Computer Software clause at 48 DFARS 252.227-
7013, or in subparagraph (c)(1) and (2) of the Commercial Computer Software–Restricted Rights
clause at 48 CFR 52.27-19, as applicable. The contractor/manufacturer is Liant Software
Corporation, 8911 Capital of Texas Highway North, Suite 4300, Austin, Texas 78759-7267.
Part No. 301563

Printed in USA 0192 Rev 0499

RM COBOL Win 70 Manual

Uploaded by

Copyright:

Available Formats

RM COBOL Win 70 Manual

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

RM COBOL Win 70 Manual

Uploaded by

Copyright:

Available Formats

RM/COBOL®

The information contained herein applies to systems running under Microsoft

No part of this publication may be reproduced, stored in a retrieval system, or transmitted,

Copyright © 1985, 1986-1999 by Liant Software Corporation. All rights reserved.

RM, RM/COBOL, RM/COBOL-85, Relativity, Enterprise CodeBench, RM/InfoExpress, RM/Panels,

Welcome to RM/COBOL Version 7.0

Note For information on the significant enhancements in previous releases of

RM/COBOL User's Guide for 32-Bit Windows xxv

CodeBridge Cross-Language Call System Introduced

Refer to the CodeBridge manual, included in the RM/COBOL development system

Enhanced Windows Printing

Additions to the RM/COBOL Subprogram Library

• C$ClearDevelopmentMode disables expanded error information reporting (known

• C$GetEnv and C$SetEnv retrieve and set, respectively, environment variables.

• C$GetLastFileName retrieves the last file-name and pathname used in a COBOL

• C$GetLastFileOp retrieves information about the last COBOL I/O file

• C$GetRMInfo retrieves information about the RM/COBOL runtime system.

• C$GetSysInfo retrieves information about the operating system on which the

• C$MemoryAllocate allocates dynamic memory.

• C$MemoryDeallocate deallocates (frees) dynamically allocated memory.

• C$PlaySound plays Windows predefined sound events or sound files.

RM/COBOL User's Guide for 32-Bit Windows xxvii

• C$ShowArgs displays a list of the arguments used to call a subprogram.

Ability to Use Btrieve Interface

Runtime New Features

• Enhanced Runtime Performance. The RM/COBOL version 7.0 for Windows

• Termination Log Added. On Windows, a log of termination error messages,

• New Runtime Behavior. When the RM/COBOL runtime loads a non-COBOL

• LINAGE Configuration Options. The PRINT-ATTR configuration record now

The new LINAGE-INITIAL-FORM-POSITION keyword defines where the form is

The new LINAGE-PAGES-PER-PHYSICAL-PAGE keyword in the PRINT-ATTR

RM/COBOL User's Guide for 32-Bit Windows xxix

• Increased Compiler Capacity. RM/COBOL version 7.0 for Windows compiler

• ACCEPT Statement Enhancements. A number of changes have been made

• Constant-Names. Compile-time constants can now be defined with constant-names

• Binary Allocation Configuration. New configuration options allow binary numeric

• Binary Allocation Override. In addition to binary allocation configuration, the

• COUNT, COUNT-MAX, and COUNT-MIN Special Registers. The compiler

RM/COBOL User's Guide for 32-Bit Windows xxxi

• PROGRAM-ID Special Register. The compiler now supports a new special

• GIVING/RETURNING Phrase. The compiler now supports the

• Formal Arguments (USING/GIVING). The compiler now handles as a special

Enhanced File Recovery Performance

New Rmpgmcom Utility Option

Who Should Use This Book

RM/COBOL User's Guide for 32-Bit Windows xxxiii

Chapter 1—Introduction describes the general concepts of the RM/COBOL compiler

Chapter 2—Installation and System Considerations for UNIX explains the

Chapter 3—Installation and System Considerations for Microsoft Windows explains

Chapter 4—System Considerations for Btrieve presents information about the

Chapter 5—System Verification describes the suite of verification programs provided

Chapter 6—Compiling describes RM/COBOL files, details the RM/COBOL Compile

Chapter 8—RM/COBOL Features presents information about the implementation of

Chapter 10—Configuration details the methods available for modifying the

Appendix B—Limits and Ranges describes RM/COBOL limits and ranges.

Appendix C—Internal Data Formats describes and illustrates the internal

Appendix D—Customizing RM/COBOL for UNIX provides information on how to

Appendix E—Windows Printing describes the subprograms supplied with the

Appendix F—Subprogram Library describes a set of supplied subprograms that can be

Appendix I—Extension, Obsolete, and Subset Language Elements lists the