Micro Focus^® Object COBOL^™

Programmer's Guide to Writing Programs

Micro Focus®

Issue 3c
September 2002

Micro Focus International Limited has made every effort to ensure that this book is correct and accurate, but reserves the right to make changes without notice at its sole discretion at any time. The software described in this document is supplied under a license and may be used or copied only in accordance with the terms of such license, and in particular any warranty of fitness of Micro Focus software products for any particular purpose is expressly excluded and in no event will Micro Focus be liable for any consequential loss.

Animator®, COBOL Workbench®, EnterpriseLink®, Mainframe Express®, Micro Focus®, Net Express®, REQL® and Revolve® are registered trademarks, and AAI™, Analyzer™, Application to Application Interface™, AddPack™, AppTrack™, AssetMiner™, CCI™, DataConnect™, Dialog System™, EuroSmart™, FixPack™, LEVEL II COBOL™, License Management Facility™, License Server™, Mainframe Access™, Mainframe Manager™, Micro Focus COBOL™, Object COBOL™, OpenESQL™, Personal COBOL™, Professional COBOL™, Server Express™, SmartFind™, SmartFind Plus™, SmartFix™, SourceConnect™, Toolbox™, VS COBOL™, WebSync™, and Xilerator™ are trademarks of Micro Focus International Limited. All other trademarks are the property of their respective owners.

No part of this publication, with the exception of the software product user documentation contained on a CD-ROM, may be copied, photocopied, reproduced, transmitted, transcribed, or reduced to any electronic medium or machine-readable form without prior written consent of Micro Focus International Limited.

Licensees may duplicate the software product user documentation contained on a CD-ROM, but only to the extent necessary to support the users authorized access to the software under the license agreement. Any reproduction of the documentation, regardless of whether the documentation is reproduced in whole or in part, must be accompanied by this copyright statement in its entirety, without modification.

U.S. GOVERNMENT RESTRICTED RIGHTS. It is acknowledged that the Software and the Documentation were developed at private expense, that no part is in the public domain, and that the Software and Documentation are Commercial Computer Software provided with RESTRICTED RIGHTS under Federal Acquisition Regulations and agency supplements to them. Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software clause at DFAR 252.227-7013 et. seq. or subparagraphs (c)(1) and (2) of the Commercial Computer Software Restricted Rights at FAR 52.227-19, as applicable. Contractor is Micro Focus International Limited, 9420 Key West Avenue, Rockville, Maryland 20850. Rights are reserved under copyright laws of the United States with respect to unpublished portions of the Software.

About this Book

The Micro Focus Object COBOL Programmer's Guides are complete guides to specific areas of the Micro Focus COBOL systems.

This guide contains general information about writing programs, not specifically covered by one of the other guides, that will help you write better applications. This includes information about making your applications portable, and interfacing with other languages.

Audience

You should be familiar with the COBOL language and with your operating system. You should read the Getting Started book for this COBOL system and be familiar with the COBOL development cycle described in the User's Guide before reading other books in the book set.

Environments

Micro Focus COBOL systems are available for DOS, Windows, Windows 95, Windows NT, and OS/2 V2.1 or later, and for many varieties of UNIX. Both 32-bit and 16-bit versions are available (16-bit is not available on UNIX.)

Some of the books supplied with this COBOL system are generic across all these environments. Other books are specific to your operating system, but might contain some generic chapters. The chapter Welcome! in your Getting Started book explains this in detail.

Conventions

In the books, unless otherwise stated:

References to Windows apply to Windows 3.1 or later (running the 16-bit COBOL system), and to Windows 95 and Windows NT (running the 16-bit and 32-bit COBOL systems).
References to OS/2 apply to all supported versions of OS/2 (running the 16-bit and 32-bit COBOL systems).
References to Windows NT apply to Windows 95 and Windows NT (running the 32-bit COBOL system).
References to DOS apply to both IBM Personal Computer DOS and MS-DOS.
References to UNIX apply to all operating systems that are compatible with UNIX System V, Release 3.0 or later, complying with the System V Interface Definition (SVID).

Side Headings

In a generic book or chapter, text that does not apply to all supported environments and COBOL systems is marked by a side heading in the left margin. A side heading applies to the paragraph it is next to, unless it is next to the first paragraph in a section, in which case it applies to that whole section.

The following examples of side headings show what they mean:

UNIX:
This text applies to the 32-bit COBOL system on UNIX.

DOS, Windows and OS/2:
This text applies to the 16-bit or 32-bit COBOL system on DOS, Windows, Windows 95, Windows NT, and OS/2 V2.1 or later.

16-bit:
This text applies to the 16-bit COBOL system on DOS, Windows, Windows 95, Windows NT, and OS/2 V2.1 or later.

32-bit:
This text applies to the 32-bit COBOL system on UNIX, Windows 95, Windows NT, and OS/2 V2.1 or later.

32-bit for Windows NT and OS/2:
This text applies to the 32-bit COBOL system on Windows 95, Windows NT, and OS/2 V2.1 or later.

Notation

The notation used in the books is as follows:

Enter refers to the carriage-return or Enter key. Where commands to be typed are shown, the Enter key is not shown. It is treated as implicit that the Enter key must be pressed at the end of the line.
Hexadecimal numbers are enclosed in quotation marks and preceded by a lower-case "x" or "h"; for example, x"9D", h"03FF". The "x" is used when the hexadecimal number represents a character string; the "h" when it represents a numerical value.
With COMP-X and COMP-5, PIC X is used rather than PIC 99. Unlike PIC 99, PIC X shows the length of the data item directly and so demonstrates more clearly the use of COMP-X, which is to define a binary item of the specified number of bytes.

Command Lines

The notation used to describe the format of command lines is as follows:

Words printed in italics are generic terms representing names to be devised by you.
Words printed in nonitalic characters are the actual words you must enter.
DOS, Windows and OS/2:
On DOS, Windows and OS/2 you can type them in upper, lower, or mixed case except where otherwise stated.

UNIX:
On UNIX you must type them in upper or lower case as shown.
Square brackets [ ] mean the material inside them is optional.
Braces { } mean you must choose from the options inside them. If there is only one option in the braces, they mean repetition.
An ellipsis (...) following { } or [ ] means you can repeat the material inside them. The number of repetitions allowed is unlimited unless otherwise stated. Square brackets [ ] with an ellipsis mean you can omit the material altogether.
If a command line does not fit across the page, it is continued on the next line; the continuation line is indented.
UNIX:
On UNIX, the books may refer you to the Release Notes for details specific to a particular UNIX platform.
UNIX:
On UNIX, all command line formats and examples are for the standard UNIX shell, the Bourne shell. If you are using another shell, see your UNIX documentation for the appropriate formats.
UNIX:
Where examples showing environment variables do not specifically show them being exported to the shell, it is treated as implicit that they are exported.
UNIX:
Some keystrokes using function keys or the Alt or Ctrl keys are not available on all UNIX platforms. The User's Guide contains a UNIX Key Usage Chart, listing how the keystrokes shown in the books map onto actual keystrokes.

Notes

F1=Help appears on every menu in character-mode Micro Focus software. It invokes a help screen describing the current menu. F1=Help is not described in the documentation.
What appears on your screen may differ in minor ways (for example, version numbers) from that illustrated in the books. This will not affect the operation of your software.

Key to COBOL System Library Routines

Descriptions for all of the call-by-name routines appear alphabetically. Each description contains the routine name and function and the following entries (as appropriate):

Syntax:	Shows the CALL statement you could use to call the routine. The optional RETURNING clause is also shown. Every routine returns a value showing the result of the operation. Unless otherwise indicated, zero indicates success, nonzero indicates failure. This value is left in the data item specified in the RETURNING clause, in this reference, status-code. If this clause is omitted, the value is left in the special register RETURN-CODE. (If call-convention bit two is set, RETURN-CODE is not changed.) status-code must be a numeric data item capable of holding positive values from 0 to 65535; for example, PIC X(2) COMP-5. The name of the routine must be coded in upper case.
Parameters:	Describes any parameters shown in the RETURNING and USING clause. A parameter enclosed in brackets, for example, [parameter1] is optional and might not be needed for all forms of the routine.
On Entry:	Indicates which of the parameters shown are passed on entry.
On Exit:	Indicates which of the parameters shown are returned on exit. Where bits of one or more bytes are referenced, bit 0 is the least significant (rightmost) bit.
Comments:	Provides any additional information necessary for the successful use of the routine.
Related Topics:	Lists other related topics.

Micro Focus® Object COBOL™

Programmer's Guide to Writing Programs

Micro Focus^® Object COBOL^™