Micro Focus Object COBOL™

Programmer's Guide to File Handling

MERANT™

Issue 3a
August 1999

MERANT has made every effort to ensure that this manual 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 MERANT products for any particular purpose is expressly excluded and in no event will MERANT be liable for any consequential loss.

Micro Focus® and Animator® are registered trademarks, and CCI™, Co-Writer™, Dialog System™, Fileshare™, Fileshare V2™, Forms™, IMS Option™, LEVEL II COBOL™, Micro Focus COBOL™, Object COBOL™, OSX™ and XM™ are trademarks of MERANT International Limited.

Btrieve® is a registered trademark of Pervasive Software, Inc

IBM®, AIX®, OS/2® and PC® are registered trademarks, and AIX/6000™, CICS™, CICS OS/2™, DB2™, DB2/2™ and MVS™ are trademarks of International Business Machines

Informix® is a registered trademark, and C-ISAM™ is a trademark of Informix Software, Inc

Microsoft® and MS® are registered trademarks, and Microsoft Access™, NT™, Windows™, Windows NT™ and SQL Server™ are trademarks of Microsoft Corporation

NetWare® and Novell® are registered trademarks of Novell, Inc

RM/COBOL® and Ryan-McFarland® are registered trademarks of Ryan-McFarland Corporation

UNIX® and X/Open® are registered trademarks of X/Open Company Limited

XENIX® is a registered trademark of Microsoft Corporation

Copyright© 1999 MERANT International Limited
All Rights Reserved

Preface

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

This guide contains everything you need to know to use data files with a Micro Focus COBOL system, from standard COBOL file formats to relational databases.

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

About This Book

This book is divided into several parts, as follows:

• Part I introduces you to file handling.

• Part II covers basic data file handling in COBOL. You should read this part to get started with file handling. The facilities explained include:
  • How to name physical files and how to assign the filenames used in your program to physical files.

  • The common COBOL file formats and how to process them.

  • Using file status to detect file I/O errors.

  • Sorting files.

  • Sharing data files in a multi-user environment.

  • Maintaining your data files.
    

• Part III looks at the more advanced file handling facilities provided. These include:
  • Handling directories.

  • Using the Callable File Handler and Callable Sort Module.

  • Handling non-COBOL files such as Btrieve and C-ISAM.

  • Handling files at the byte level.

  • Converting files from one format to another.
    

• Part IV is devoted to explaining Fileshare and the facilities it offers for accessing files across a network.

• Part V covers accessing relational databases from your COBOL program using SQL.

• Part VI contains reference material. This includes a full description of the format of COBOL data files, and a list of file status codes.

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