Order Number: AA-Q6PGC-TE

This manual explains how to develop Oracle DBMS database programs with Compaq COBOL on either the OpenVMS Alpha or the OpenVMS VAX operating system.

Revision/Update Information: This manual supersedes the DIGITAL COBOL DBMS Database Programming Manual and includes the DBMS information from the VAX COBOL User Manual, Version 5.4.

Operating System and Version:
OpenVMS Alpha Version 6.2 or higher;
OpenVMS VAX Version 6.2 or higher

Software Version:
Compaq COBOL for OpenVMS Alpha Version 2.8; Compaq COBOL for OpenVMS VAX Version 5.7

Compaq Computer Corporation
Houston, Texas

© 2002 Compaq Information Technologies Group, L.P.

COMPAQ, the Compaq logo, AlphaServer, OpenVMS, POLYCENTER, Tru64, VAX, VMS, and the DIGITAL logo are trademarks of Compaq Information Technologies Group, L.P. in the U.S. and/or other countries.

All other product names mentioned herein may be trademarks of their respective companies.

Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

None of Compaq, Hewlett-Packard Company ("HP") or any other direct or indirect subsidiary of HP shall be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq or HP products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK6393

Contents

Index

This manual describes how to develop Oracle CODASYL DBMS database programs with Compaq COBOL on the OpenVMS Alpha or OpenVMS VAX operating system. It also contains information about Compaq COBOL language features specific to OpenVMS.

The Compaq COBOL DBMS Database Programming Manual is a separately orderable component of the Compaq COBOL documentation set. Complete information about Compaq COBOL can be found in the Compaq COBOL User Manual and Compaq COBOL Reference Manual.

Compaq COBOL is an implementation of COBOL (COmmon Business-Oriented Language), which is widely used throughout the world for business data processing. Compaq COBOL is a high-performance language for commercial application development that runs under the OpenVMS Alpha or OpenVMS VAX operating system. Compaq COBOL is based on the 1985 ANSI COBOL Standard X3.23--1985 and Federal Information Processing Standard Publication 21-3 (FIPS-PUB 21-3). The FIPS standard identifies the ANSI standard as the standard adopted by the U.S. federal government and as the criteria on which federal validation is based. Compaq COBOL also contains Compaq extensions to COBOL.

Oracle CODASYL DBMS, including DML (data manipulation language), is based on the 1979 CODASYL Standard for databases.

Intended Audience

This manual is designed for experienced applications programmers who have a basic understanding of the usage of the COBOL language and database programming. If you are a new COBOL user, you may need to read introductory COBOL textbooks or take COBOL courses. Some familiarity with your operating system is also recommended. This is not a tutorial manual.

Structure of This Document

This manual is organized as follows:

• Chapter 1, Program Organization and Structure, describes the structure and organization of a Compaq COBOL database program, and explains how you compile, link, and run your program.
• Chapter 2, Database Programming Elements of Compaq COBOL, describes elements of the Compaq COBOL language that support database programming.
• Chapter 3, Data Division, describes logical and physical concepts of the Data Division in relation to database programs.
• Chapter 4, Procedure Division, describes statements, names, rules, and conditions used in the Procedure Division of a Compaq COBOL database program.
• Chapter 5, Database Programming with Compaq COBOL, describes Compaq COBOL for OpenVMS database program development and Compaq COBOL database concepts.
• Chapter 6, DML Programming---Tips and Techniques, describes tips and techniques you can use to improve program performance and reduce development and debugging time.
• Chapter 7, Debugging and Testing Compaq COBOL DML Programs, describes commands and generic DML statements you use to debug and test your COBOL program's DML statements.
• Chapter 8, Database Programming Examples, provides examples of how you populate and manipulate a database.
• Appendix A, COBOL Database Programming Reserved Words, lists COBOL reserved words related to Compaq COBOL database programming, and those shared by database programs and other programs.
• Glossary of Oracle DBMS-Related Terms, provides a glossary of terms related to Compaq COBOL database programs.

Associated Documents

The following documents contain additional information directly related to various topics in this manual:

Compaq COBOL Reference Manual

Describes the concepts and rules of the Compaq COBOL programming language under the supported operating systems.

Compaq COBOL User Manual

Describes how to develop Compaq COBOL programs and how to use supported operating system features from the Compaq COBOL language.

Compaq COBOL for OpenVMS Alpha Systems Installation Guide

Provides information on how to install Compaq COBOL on the OpenVMS Alpha operating system.

Compaq COBOL for OpenVMS VAX Systems Installation Guide

Provides information on how to install Compaq COBOL on the OpenVMS VAX operating system.

Introduction to Oracle CODASYL DBMS

Introduces the features of Oracle CODASYL DBMS and provides a summary of product components. It also supplies a documentation directory, a glossary, and a master index for the entire documentation set.

Oracle CODASYL DBMS Database Administration Reference Manual

Describes the syntax and function of the data definition language (DDL) used to write schemas, storage schemas, subschemas, and security schemas. It explains the use of the DDL compiler to compile data definitions into the Oracle CDD/Repository data dictionary, the commands used in loading and unloading a database, conditional expressions, and the OpenVMS data types supported by Oracle CODASYL DBMS. Finally, the manual describes the syntax and function of each DBO command, and the DBALTER and DRU utilities.

In addition, there is a self-paced demonstration database, which is configured to show some of the features of Oracle CODASYL DBMS. It is designed to be used with the PARTS database, which is included in the Oracle CODASYL DBMS documentation set.

Oracle CODASYL DBMS Programming Guide

Describes how to program against an Oracle CODASYL DBMS database. The manual explains how to use the Database Query utility (DBQ) to test program logic, how to embed data manipulation language statements into programs and compile them with the DML precompiler, and how to use the callable system subroutines.

Oracle CODASYL DBMS Programming Reference Manual

Describes the syntax and functions of the Oracle CODASYL DBMS data manipulation language (DML), interactive use of the Database Query utility (DBQ), and use of the callable system subroutines. The manual also describes the syntax and functions of the FORTRAN DML (FDML) statements.

Using CDD/Repository on VMS Systems

A guide for repository users who store, maintain, and analyze repository information in Oracle CDD/Repository using the Common Dictionary Operator (CDO) utility.

The OpenVMS Alpha or VAX documentation set

The Oracle Corporation documentation on CDD/Repository

Related Documents

For additional information about OpenVMS products and services, access the following World Wide Web address:

http://www.compaq.com/

Conventions Used in the Compaq COBOL Documentation Set

The following table lists the conventions used in this doc set:

Conventions	Meaning
<>	A diamond, or angle brackets (<>) in the online HTML manual, signals the end of a section of system-specific information. The beginning of a system-specific section is identified in the text or header as Alpha or as VAX.
. . .	A vertical series of periods, or an ellipsis, means that not all the data is shown. Most program examples are shown in Compaq terminal format, rather than in ANSI standard format.
quotation mark	The quotation mark is used to refer to the double quotation mark character (").
apostrophe	The apostrophe is used to refer to the single quotation mark character (').
user input	In examples in hardcopy versions of this document, user input (what you enter) is shown as monospaced text. In examples in online versions of this document, user input (what you enter) is shown as monospaced bold text.
report file	Bold type indicates a new term.
italic text	Italic type indicates important information, complete titles of manuals, or variables. Variables include generic terms (lowercase variable elements in syntax) when referred to in text; and information that varies in system output (error number) and in command lines (BASIC file-name) in text.
[TAB]	A boxed symbol indicates that you must press a key on the terminal; for example, [TAB] indicates that you press the TAB key on your terminal.
[CTRL/x]	The symbol [CTRL/x] indicates that you hold down the key labeled CTRL while you simultaneously press another key; for example, [CTRL/C], [CTRL/O].
$	The dollar sign ($) represents the OpenVMS system prompt.

Acknowledgment

COBOL is an industry language and is not the property of any company or group of companies, or of any organization or group of organizations.

No warranty, expressed or implied, is made by any contributor or by the CODASYL COBOL Committee as to the accuracy and functioning of the programming system and language. Moreover, no responsibility is assumed by any contributor, or by the committee, in connection therewith.

The authors and copyright holders of the copyrighted material used herein are as follows: FLOW-MATIC (trademark of Unisys Corporation), Programming for the UNIVAC (R) I and II, Data Automation Systems, copyrighted 1958, 1959, by Unisys Corporation; IBM Commercial Translator Form No. F28-8013, copyrighted 1959 by IBM; FACT, DSI 27A5260-2760, copyrighted 1960 by Minneapolis-Honeywell.

They have specifically authorized the use of this material, in whole or in part, in the COBOL specifications. Such authorization extends to the reproduction and use of COBOL specifications in programming manuals or similar publications.

References to Alpha and VAX

In this manual, every reference to Alpha or OpenVMS Alpha means the OpenVMS Alpha operating system and every use of VAX or OpenVMS VAX means the OpenVMS VAX operating system.

In this manual, every reference to Oracle CDD/Repository means the Oracle CDD/Repository product of Oracle Corporation.

How to Order Additional Documentation

Visit the following World Wide Web address for information about how to order additional documentation:

http://www.openvms.compaq.com/doc/

Reader's Comments

Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet	openvmsdoc@hp.com
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

Field Test Sites

We are indebted to our field test sites. The people at these sites provided us with invaluable information, which ultimately resulted in a higher quality product---a Compaq COBOL that does more of what programmers need to produce applications for today's data processing.

The fundamental elements of the COBOL language are described in the current ANSI standard and the Compaq COBOL basic documentation set. The elements specific to database programming have been collected and concentrated in this optional book for the convenience of programmers who write COBOL database programs.

1.1 Program Structure

Figure 1-1 shows the basic structure of a COBOL program, which is organized in divisions, sections, paragraphs, sentences, and entries.

Figure 1-1 Structure of a COBOL Program

IDENTIFICATION DIVISION. PROGRAM-ID. program-name. AUTHOR. INSTALLATION. DATE-WRITTEN. DATE-COMPILED. SECURITY. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. OBJECT-COMPUTER. SPECIAL-NAMES. INPUT-OUTPUT SECTION. FILE-CONTROL. I-O-CONTROL. DATA DIVISION. SUBSCHEMA SECTION. subschema entries and keeplist entries FILE SECTION. file and record description entries report file description entries sort-merge file and record description entries WORKING-STORAGE SECTION. record description entries LINKAGE SECTION. record description entries REPORT SECTION. report and report group description entries. SCREEN SECTION. (Alpha) screen description entries (Alpha) PROCEDURE DIVISION. DECLARATIVES. sections paragraphs sentences END DECLARATIVES. . . . sections paragraphs sentences . . . END PROGRAM header

The Data Division can contain a special SUB-SCHEMA SECTION section header for the Oracle CODASYL DBMS program, as shown in Figure 1-1.

A Data Division entry begins with a level indicator or level-number and is followed, in order, by:

1. A space
2. The name of a data item or file connector
3. A sequence of independent descriptive clauses
4. A separator period

The COBOL level indicators are as follows:

• DB (for subschema entries)
• LD (for keeplist entries)
• FD (for file description entries)
• SD (for sort-merge file description entries)
• RD (for report file description entries)

The first two level indicators in this list, DB and LD, are used in Oracle CODASYL DBMS database programs. FD, SD, and RD can be in database programs as well as in other programs.

Level indicators start in Area A.

Entries that begin with level-numbers are called data description entries. The level-number values are 01 to 49, 66, 77, and 88. Level-numbers 01 to 09 can be represented as one- or two-digit numbers.

Level 01 and 77 data description entries begin in Area A. All other data description entries can begin anywhere to the right of Margin A. Indentation has no effect on level-number magnitude; it merely enhances readability.

1.2 Compaq COBOL Data Manipulation Language (DML)

The Compaq COBOL data manipulation language (DML) is a programming language extension that provides a way for a COBOL application program to access a database. A Compaq COBOL database application program contains DML statements that tell the Database Control System (DBCS) what to do with specified data; the DBCS provides all database processing control at run time. The four classes of DML statements are data definition, control, retrieval, and update. An explanation of each class follows, together with important definitions of members of that class:

• Data definition---These entries define the specific part of the database to be accessed by the application program and any keeplists needed to navigate through it. The entries also result in the creation of a database user work area (UWA). Transfer of data between your program and the database takes place in the UWA. Your program delivers data for the DBCS to this area; it is here that the DBCS places data requested from the database for retrieval to your program.

  SUB-SCHEMA SECTION	Is the first section of the Data Division. It contains two paragraphs: the Subschema entry (DB) and the Keeplist Description entry (LD).
  DB	Names the target subschema, translates subschema record descriptions to compatible Compaq COBOL record descriptions, and creates a user work area (UWA).
  LD	Names a keeplist to help you navigate through the database.

  
  For more information on these entries see Chapter 3, Data Division.
• Control---The DML control functions tell the DBCS when and how to begin or end a database transaction.

  COMMIT	Terminates your transaction, makes permanent all changes made to the database since the last quiet point, and establishes a new quiet point for the run unit.
  READY	Prepares selected realms for use.
  ROLLBACK	Ends your transaction, cancels all changes made to the database since the start of your transaction, empties all keeplists, and nulls all currency indicators.

• Retrieval---The DML retrieval functions are used to find a record in the database and, if necessary, retain the record in the user work area (UWA) for later use.

  FIND	Locates a record in the database.
  FIND ALL	Locates all specified records in the database and puts them in a keeplist.
  FETCH	Locates a record in the database, retrieves its data item values, and places them in the user work area (UWA).
  FREE	Releases references to records.
  GET	Retrieves data item values of a previously located record and places them in the user work area (UWA).
  KEEP	Remembers a record so you can later refer to it.

  
  Records can be found in several ways in the database. By using a Record Selection Expression in a FIND or FETCH statement, a program has four formats to choose from: (1) database key identifier access, (2) set owner access, (3) record search access, or (4) DB-KEY access. Chapter 4, Procedure Division, explains these in detail.
  A COBOL program can sequentially search the database or individual realm. In all cases, once a record is found by the COBOL application program, the DBCS sets a currency indicator to hold the database key value of that record or the position of that record. The COBOL program can indirectly use this value in KEEP, FIND ALL, or FREE statements or use the RETAINING option as a placemarker to help the program navigate through the database.
• Update---These functions allow the creation, modification, and deletion of database records.

  CONNECT	Makes a record a member in one or more sets.
  DISCONNECT	Removes a record from one or more sets.
  ERASE	Deletes records from the database.
  MODIFY	Changes the contents of a record in the database.
  RECONNECT	Moves a record from one occurrence of a set type to another (possibly the same) occurrence.
  STORE	Adds a record to the database.

Chapter 4 discusses the effects of the schema data definition language (DDL) INSERTION and RETENTION options on each of the DML update verbs.

Once a record has been located by a COBOL program, it can be changed or even erased from the database. DML programming operations also change the fundamental relationships within sets, causing records to change as well. For example, each set is owned by a record or Oracle CODASYL DBMS itself. If the program erases a record that is the owner of the set, all member records may also be deleted.

Section 4.5 contains more information on DML statements, database conditional expressions, and the special registers DB-CONDITION, DB-CURRENT-RECORD-NAME, DB-CURRENT-RECORD-ID, DB-UWA, and DB-KEY.