Re-engineered VS COBOL II Application Programming Language Reference

Important disclaimer: This is NOT "IBM's VS COBOL II Application Programming Language Reference" but the present document has been derived from IBM's document in the sense of "document re-engineering". This derivation has not been approved by IBM in any way. The derivation has been performed by Ralf Lämmel in a research effort on grammar engineering at the CWI and the Free University in Amsterdam. While this document is thought to be useful as a completed, corrected, and linked version of IBM's document, the document comes with ABSOLUTELY NO WARRANTY. To the extent possible, the document is COPYRIGHT Ralf Lämmel, CWI, Free University Amsterdam, say to the extent not covered by IBM's copyright.

The overall intention of this improved, say re-engineered version of IBM's document is to provide a useful Cobol grammar as part of the full, though modified IBM reference document. The original IBM document was retrieved from the IBM BookManager, and all necessary adaptations were traced in scripts; see the GRK distribution for details. These adaptations are concerned with completing the diagrams (i.e., adding syntax that was not in IBM's document previously), correcting the diagrams (i.e., rephrasing syntax which is in conflict with the intended one), and refactoring diagrams (to obtain a more concise definition of the Cobol syntax). All adaptations are described by comments before the corresponding diagrams. (All these comment lines start with @@.)

Useful links:


Ralf Lämmel
4 June 2003
Amsterdam
email: Ralf.Laemmel@cwi.nl


Print: IGYL1101 via IBM BookManager BookServer

IBM BookManager Print Preview

DOCNUM = GC26-4047-07 DATETIME = 03/12/93 09:30:06 BLDVERS = 1.2 TITLE = VS COBOL II Application Programming Language Reference AUTHOR = COPYR = Copyright IBM Corp. 1984, 1993

COVER Book Cover


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document. VS COBOL II

Application Programming Language Reference

Release 4

Document Number GC26-4047-07

Program Number 5668-958 5668-022 5668-023


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

ABSTRACT Abstract

   Presents the format of the VS COBOL II language and the rules for writing 
   source programs for the VS COBOL II compiler. 

Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| NOTICES Notices

| ___ Note! __________________________________________________________ | | | | Before using this information and the product it supports, be sure | | | to read the general information under "Notices" in topic FRONT_1. | | | |____________________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

EDITION Edition Notice

 | Eighth Edition (March 1993) 

| This edition replaces and makes obsolete the previous edition, | SC26-4047-06. Technical changes for this edition are summarized | under"Summary of Changes" in topic FRONT_3 and are indicated by a | vertical bar to the left of the change.

| This edition applies to Release 4 of VS COBOL II, Program Numbers | 5668-958 (Compiler and Library with Debug), 5688-023 (Compiler and | Library), and 5688-022 (Library only), and to any subsequent releases | until otherwise indicated in new editions or technical newsletters. | Make sure you are using the correct edition for the level of the | product.

Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the address below.

A form for readers' comments is provided at the back of this publication. If the form has been removed, address your comments to:

IBM Corporation, Department J58 P.O. Box 49023 San Jose, CA, 95161-9023 United States of America

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you.

Copyright International Business Machines Corporation 1984, 1993. All rights reserved. Note to U.S. Government Users -- Documentation related to restricted rights -- Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

CONTENTS Table of Contents

[Summarize]

COVER         Book Cover

ABSTRACT      Abstract

NOTICES       Notices

EDITION       Edition Notice

CONTENTS      Table of Contents

FIGURES       Figures

FRONT_1       Notices
FRONT_1.1     Programming Interface Information
FRONT_1.2     Trademarks

FRONT_2       About This Manual
FRONT_2.1     Who This Manual Is For
FRONT_2.2     How This Manual Is Organized
FRONT_2.3     IBM Extensions
FRONT_2.4     How to Read the Syntax Diagrams
FRONT_2.5     Obsolete Language Elements
FRONT_2.6     DBCS Notation
FRONT_2.7     Industry Standards Used
FRONT_2.8     Terminology for Industry Standards
FRONT_2.9     Acknowledgment
FRONT_2.10    VS COBOL II Publications

FRONT_3       Summary of Changes
FRONT_3.1     Release 4.0
FRONT_3.2     Release 3.2
FRONT_3.3     Release 3.1
FRONT_3.4     Release 3.0

1.0           Part 1.  COBOL Language Structure

1.1           Characters
1.1.1         Character-Strings
1.1.2         Separators

1.2           Sections and Paragraphs

1.3           Reference Format
1.3.1         Sequence Number Area
1.3.2         Indicator Area
1.3.3         Area A
1.3.4         Area B
1.3.5         Area A or Area B

1.4           Scope of Names
1.4.5         Resolution of Names

1.5           Methods of Data Reference
1.5.1         Uniqueness of Reference

1.6           Transfer of Control

2.0           Part 2.  COBOL Program Structure

2.1           COBOL Source Program

2.2           Identification Division
2.2.1         PROGRAM-ID Paragraph
2.2.2         Optional Paragraphs

2.3           Environment Division--Configuration Section
2.3.1         SOURCE-COMPUTER Paragraph
2.3.2         OBJECT-COMPUTER Paragraph
2.3.3         SPECIAL-NAMES Paragraph
2.3.4         ALPHABET Clause
2.3.5         SYMBOLIC CHARACTERS Clause
2.3.6         CLASS Clause
2.3.7         CURRENCY SIGN Clause

2.4           Environment Division--Input-Output Section
2.4.1         FILE-CONTROL Paragraph
2.4.2         SELECT Clause
2.4.3         ASSIGN Clause
2.4.4         RESERVE Clause
2.4.5         ORGANIZATION Clause
2.4.6         PADDING CHARACTER Clause
2.4.7         RECORD DELIMITER Clause
2.4.8         ACCESS MODE Clause
2.4.9         RECORD KEY Clause
2.4.10        ALTERNATE RECORD KEY Clause
2.4.11        RELATIVE KEY Clause
2.4.12        PASSWORD Clause
2.4.13        FILE STATUS Clause
2.4.14        I-O-CONTROL Paragraph
2.4.15        RERUN Clause
2.4.16        SAME AREA Clause
2.4.17        SAME RECORD AREA Clause
2.4.18        SAME SORT AREA Clause
2.4.19        SAME SORT-MERGE AREA Clause
2.4.20        MULTIPLE FILE TAPE Clause
2.4.21        APPLY WRITE-ONLY Clause

2.5           Data Division
2.5.1         Data Division Structure
2.5.2         Data Types
2.5.3         Data Relationships

2.6           Data Division--File Description Entries
2.6.1         File Section
2.6.2         EXTERNAL Clause
2.6.3         GLOBAL Clause
2.6.4         BLOCK CONTAINS Clause
2.6.5         RECORD Clause
2.6.6         LABEL RECORDS Clause
2.6.7         VALUE OF Clause
2.6.8         DATA RECORDS Clause
2.6.9         LINAGE Clause
2.6.10        RECORDING MODE Clause
2.6.11        CODE-SET Clause

2.7           Data Division--Data Description Entry
2.7.1         Level-Numbers
2.7.2         BLANK WHEN ZERO Clause
2.7.3         EXTERNAL Clause
2.7.4         GLOBAL Clause
2.7.5         JUSTIFIED Clause
2.7.6         OCCURS Clause
2.7.7         PICTURE Clause
2.7.8         REDEFINES Clause
2.7.9         RENAMES Clause
2.7.10        SIGN Clause
2.7.11        SYNCHRONIZED Clause
2.7.12        USAGE Clause
2.7.13        VALUE Clause

2.8           Procedure Division
2.8.1         The Procedure Division Header
2.8.2         Declaratives
2.8.3         Procedures
2.8.4         Arithmetic Expressions
2.8.5         Conditional Expressions
2.8.6         Statement Categories
2.8.7         Common Phrases for Arithmetic and Data Manipulation Statements
2.8.8         Arithmetic Statements
2.8.9         Input-Output Statements
2.8.10        Procedure Branching Statements

3.0           Part 3.  Procedure Division Statements
3.1           ACCEPT Statement
3.2           ADD Statement
3.3           ALTER Statement
3.4           CALL Statement
3.5           CANCEL Statement
3.6           CLOSE Statement
3.7           COMPUTE Statement
3.8           CONTINUE Statement
3.9           DELETE Statement
3.10          DISPLAY Statement
3.11          DIVIDE Statement
3.12          ENTRY Statement
3.13          EVALUATE Statement
3.14          EXIT Statement
3.15          EXIT PROGRAM Statement
3.16          GOBACK Statement
3.17          GO TO Statement
3.18          IF Statement
3.19          INITIALIZE Statement
3.20          INSPECT Statement
3.21          MERGE Statement
3.22          MOVE Statement
3.23          MULTIPLY Statement
3.24          OPEN Statement
3.25          PERFORM Statement
3.26          READ Statement
3.27          RELEASE Statement
3.28          RETURN Statement
3.29          REWRITE Statement
3.30          SEARCH Statement
3.31          SET Statement
3.32          SORT Statement
3.33          START Statement
3.34          STOP Statement
3.35          STRING Statement
3.36          SUBTRACT Statement
3.37          UNSTRING Statement
3.38          WRITE Statement

4.0           Part 4.  Compiler-Directing Statements
4.1           BASIS Statement
4.2           CBL (PROCESS) Statement
4.3           *CONTROL (*CBL) Statement
4.4           COPY Statement
4.5           DELETE Statement
4.6           EJECT Statement
4.7           ENTER Statement
4.8           INSERT Statement
4.9           READY or RESET TRACE Statement
4.10          REPLACE Statement
4.11          SERVICE LABEL Statement
4.12          SERVICE RELOAD Statement
4.13          SKIP1/2/3 Statements
4.14          TITLE Statement
4.15          USE Statement

APPENDIX1     Appendixes

APPENDIX1.1   Appendix A.  VS COBOL II Compiler Limits

APPENDIX1.2   Appendix B.  EBCDIC and ASCII Collating Sequences
APPENDIX1.2.1 EBCDIC Collating Sequence
APPENDIX1.2.2 ASCII Collating Sequence

APPENDIX1.3   Appendix C.  Source Language Debugging
APPENDIX1.3.1 Coding Debugging Lines and Debugging Sections
APPENDIX1.3.2 Activating the Compile-Time and Object-Time Switches

APPENDIX1.4   Appendix D.  VS COBOL II Reserved Words

APPENDIX1.5   Appendix E.  ASCII Considerations
APPENDIX1.5.1 Environment Division
APPENDIX1.5.2 Data Division
APPENDIX1.5.3 Procedure Division

BACK_1        Bibliography
BACK_1.1      VS COBOL II Publications
BACK_1.2      Other Publications You Might Need

BACK_2        Glossary

INDEX         Index

COMMENTS      Readers' Comments

Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FIGURES Figures

    1.  Reference Format for COBOL Source Line   1.3 
 |  2.  Nested program structure with directly and indirectly contained 
 |      programs   1.4.2 
    3.  Levels in a Record Description   2.5.3.2 
    4.  LINAGE Clause Phrases   2.6.9 
    5.  PICTURE Clause Symbol Sequence   2.7.7.1 
    6.  RENAMES Clause--Valid and Invalid Specifications   2.7.9 
 |  7.  Insertion of Slack Bytes within a Record   2.7.11.2 
 |  8.  Insertion of Slack Bytes within a Record   2.7.11.2 
    9.  Example of INSPECT Statement Execution Results   3.20.1 
   10.  Valid PERFORM Statement Execution Sequences   3.25.1 
   11.  Varying One Identifier--with TEST BEFORE   3.25.9 
   12.  Varying Two Identifiers--with TEST BEFORE   3.25.9 
   13.  Varying One Identifier--with TEST AFTER   3.25.9 
   14.  Varying Two Identifiers--with TEST AFTER   3.25.9 
 | 15.  READ Statement with Multiple Record Description   3.26.5 
   16.  Format 1 SEARCH with Two WHEN Phrases   3.30.6 
   17.  STRING Statement Execution Results   3.35.6 
   18.  Results of UNSTRING Statement Execution   3.37.7 

Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_1 Notices

   References in this publication to IBM products, programs, or services do 
   not imply that IBM intends to make these available in all countries in 
   which IBM operates.  Any reference to an IBM product, program, or service 
   is not intended to state or imply that only that IBM product, program, or 
   service can be used.  Any functionally equivalent product, program, or 
   service that does not infringe any of the intellectual property rights of 
   IBM can be used instead of the IBM product, program, or service.  The 
   evaluation and verification of operation in conjunction with other 
   products, except those expressly designated by IBM, are the responsibility 
   of the user. 

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Commercial Relations, IBM Corporation, Purchase, NY 10577, U.S.A.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_1.1 Programming Interface Information

This book is intended to help you write VS COBOL II source programs. This book documents General-use Programming Interface and Associated Guidance Information provided by VS COBOL II.

General-use programming interfaces allow the customer to write programs that obtain the services of VS COBOL II.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_1.2 Trademarks

The following terms, denoted by an asterisk (*) on their first occurrences in this publication, are trademarks of the IBM Corporation in the United States and/or other countries:

________________________________________________________________________ | | | | | BookManager | Operating System/2 | | | CICS | OS/2 | | | CICS/MVS | SAA | | | CICS/VM | Systems Application Architecture | | | CICS/VSE | System/370 | | | IBM | VM/XA | | | MVS/ESA | VSE/ESA | | | MVS/XA | | | | | |____________________________________|___________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_2 About This Manual

   This reference presents the syntax of VS COBOL II statements and the rules 
   for writing source programs that are to be compiled by the VS COBOL II 
   compiler.  It is meant to be used as a reference in conjunction with 
   VS COBOL II Application Programming Guide for MVS and CMS or VS COBOL II 
   Application Programming Guide for VSE. 

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_2.1 Who This Manual Is For

This language reference manual is designed for the experienced COBOL programmer whose primary discipline is data processing and whose task is the development of applications.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_2.2 How This Manual Is Organized

The VS COBOL II Application Programming Language Reference manual is organized for easy retrieval of language elements.

| About This Manual-- Describes the VS COBOL II library and related | publications, how to read the syntax diagrams, and the industry | standards supported by VS COBOL II.

| Part 1. VS COBOL II Language Structure-- Describes VS COBOL II | characters, standard COBOL format, scope of names, and methods of data | reference.

| Part 2. VS COBOL II Program Structure-- Describes language elements of | the Identification, Environment, and Data Divisions, plus an overview | of the Procedure Division. Because the structure of the first three | COBOL divisions is the same in most programs, the language element | descriptions are presented in the order most programmers follow.

| Part 3. Procedure Division Statements-- Describes the Procedure | Division statements. Because the arrangement of statements in the | Procedure Division varies from program to program, these statements | are presented in alphabetical order.

Part 4. Compiler Directing Statements-- Describes the statements that direct the compiler to take a specified action.

Part 5. Appendixes-- Provides the following supplemental information:

Appendix A. VS COBOL II Compiler Limits Appendix B. EBCDIC and ASCII Collating Sequences Appendix C. ASCII Considerations Appendix D. Source Language Debugging Appendix E. COBOL Reserved Word List

Glossary--Defines technical terms.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_2.3 IBM Extensions

IBM extensions generally add to or contradict language element rules or restrictions.

Extensions in text, tables, or figures are marked by x's in the left margin. Extensions in syntax diagrams are marked by x's in the left margin and are also enclosed in braces, to show exactly which language elements are extensions. For example:

x IBM extensions in text are shown this way.

IBM extensions in syntax diagrams are shown as follows:

___ Format _____________________________________________________________ | | | >>_______________________BINARY_____________________________________>< | | |_USAGE_________| |_COMP_________| | x | |_IS_| |_{__COMP-1__}_| | x | |_{__COMP-2__}_| | x | |_{__COMP-3__}_| | x | |_{__COMP-4__}_| | | | |________________________________________________________________________| Note: IBM extensions are marked in Parts 1 through 4 of this manual. They are not marked in the table of contents, appendixes, glossary, or index.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_2.4 How to Read the Syntax Diagrams

Throughout this book, syntax is described using the following structure:

o Read the syntax diagrams from left to right, from top to bottom, following the path of the line. The following table shows the meaning of symbols at the beginning and end of syntax diagram lines.

____________________________________________________________________ | Symbol | Indicates | |_____________|______________________________________________________| | >>- | the syntax diagram starts here | |_____________|______________________________________________________| | -> | the syntax diagram is continued on the next line | |_____________|______________________________________________________| | >- | the syntax diagram is continued from the previous | | | line | |_____________|______________________________________________________| | ->< | the syntax diagram ends here | |_____________|______________________________________________________|

o Required items appear on the horizontal line (the main path):

___ Format _________________________________________________________ | | | >>__STATEMENT__required item____________________________________>< | | | |____________________________________________________________________|

o Optional items appear below the main path:

___ Format _________________________________________________________ | | | >>__STATEMENT___________________________________________________>< | | |_optional item_| | | | |____________________________________________________________________| o When you can choose from two or more items, they appear vertically, in a stack. If you must choose one of the items, one item of the stack appears on the main path:

___ Format _________________________________________________________ | | | >>__STATEMENT____required choice 1______________________________>< | | |_required choice 2_| | | | |____________________________________________________________________|

If choosing one of the items is optional, the entire stack appears below the main path:

___ Format _________________________________________________________ | | | >>__STATEMENT___________________________________________________>< | | |_optional choice 1_| | | |_optional choice 2_| | | | |____________________________________________________________________| o An arrow returning to the left above the main line indicates an item that can be repeated:

___ Format _________________________________________________________ | | | <_________________ | | >>__STATEMENT____repeatable item_|______________________________>< | | | |____________________________________________________________________| A repeat arrow above a stack indicates that you can make more than one choice from the stacked items, or repeat a single choice.

| o A syntax fragment is delimited in the main syntax diagram by a set of | vertical lines. The meaning of the fragment is given below the main | diagram, with the name of the fragment followed by its syntax, which | starts and ends with a vertical line.

| ___ Format _________________________________________________________ | | | | | >>__STATEMENT__| fragment |_____________________________________>< | | | | | fragment: | | | |__syntax items__________________________________________________| | | | |____________________________________________________________________| | o Keywords appear in all uppercase letters (for example, ACCEPT). They | must be spelled exactly as shown.

o Variables appear in all lowercase italic letters (for example, identifier-1). They represent user-supplied names or values.

o If punctuation marks, parentheses, arithmetic operators, or such symbols are shown, they must be entered as part of the syntax.

The following example shows how the syntax is used.

___ Format _____________________________________________________________ | | | (1) (2) <___________________ | | >>__STATEMENT_______identifier-1___________________________|_________> | | |_literal-1_______| | (3)| | | |_| item 1 |____| | | | | <_______________________________ (4) | | | >____TO__identifier-3______________|_________________________________> | | |_ROUNDED_| | | | | (5) | | >____________________________________________________________________> | | | |_________SIZE ERROR__imperative-statement-1_| | | |_ON_| | | | | >___________________________________________________________________>< | | | (6)| | | |_END-STATEMENT____| | | | | item 1: | | |____identifier-2____________________________________________________| | | |_literal-2_________________________| | | | (7)| | x | |_{__arithmetic-expression-1__}_____| | | | | Notes: | | (1) The STATEMENT keyword must be specified and coded as shown. | | | | (2) This operand is required. Either identifier-1 or literal-1 must | | be coded. | | | | (3) The item 1 fragment is optional; it can be coded or not, as | | required by the application. If item 1 is coded, it can be | | repeated with each entry separated by one or more COBOL | | separators. Entry selections allowed for this fragment are | | described at the bottom of the diagram. | | | | | (4) The operand identifier-3 and associated TO keyword are required | | | and can be repeated with one or more COBOL separators separating | | | each entry. Each entry can be assigned the keyword ROUNDED. | | | | | (5) The ON SIZE ERROR phrase with associated imperative-statement-1 | | | are optional. If the ON SIZE ERROR phrase is coded, the keyword | | | ON is optional. | | | | (6) The END-STATEMENT keyword can be coded to end the statement. It | | is not a required delimiter. | | | x | (7) The "{" and "}" indicate that arithmetic-expression-1 is an IBM | x | extension. This operand is optional. | | | |________________________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_2.5 Obsolete Language Elements

Obsolete language elements are COBOL language elements in X3.23-1985, American National Standard for Information Systems-- Programming Language--COBOL that will be deleted from the next revision of this standard. Throughout this book each obsolete element will be identified.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_2.6 DBCS Notation

DBCS character strings in literals, comments, and user-defined words are delimited by shift-out and shift-in characters. In this manual, the shift-out delimiter is represented pictorially by the < character, and the shift-in character is represented pictorially by the > character. The EBCDIC codes for the shift-out and shift-in delimiters are X'0E' and X'0F', respectively.

The <> symbol denotes contiguous shift-out and shift-in characters. The >< symbol denotes contiguous shift-in and shift-out characters.

Double-byte characters are represented in this form: D1D2D3.

EBCDIC characters in double-byte form are represented in this form : .A.B.C. The dots separating the letters represent the hexadecimal value X'42'.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_2.7 Industry Standards Used

| VS COBOL II supports the following industry standards in the MVS, VM, and | VSE environments, as understood and interpreted by IBM as of September | 1989:

| 1. ISO 1989:1985, Programming Languages--COBOL.

| ISO 1989:1985 is identical to X3.23-1985, American National Standard | for Information Systems--Programming Language--COBOL.

| For supported modules, see 2 below.

| 2. X3.23-1985, American National Standard for Information | Systems--Programming Language--COBOL.

| Under MVS and VM, VS COBOL II supports all required modules at the | highest level defined by the standard.

| Under VSE, VS COBOL II supports all required modules at the | intermediate level. It also supports all required modules at the high | level with the exception of the following language features:

| o EXTEND phrase of the OPEN statement (However, OPEN EXTEND for VSAM | sequential files is supported.) | o REVERSED phrase of the OPEN statement | o OF/IN phrase of the COPY statement.

| In the following list, the shorthand notation describing module levels | is shown in parentheses. For example, to summarize module information | for sequential input/output, the shorthand notation is (2 SEQ 1,2). | The first digit indicates the level of language elements within the | module supported by VS COBOL II. Next is the three-character | abbreviation of the module name as used in the standard. Finally, the | two digits separated by a comma indicate the minimum and maximum | levels of the module. For example, (2 SEQ 1,2) means that VS COBOL II | supports the sequential I-O module at level 2, while the range of | levels in the module is from 1 (minimum) to 2 (maximum).

o Nucleus (2 NUC 1,2)

Provides internal processing of data within the four basic divisions of a program and the capability for defining and accessing tables.

o Sequential I-O (2 SEQ 1,2)

Provides access to records of a file in established sequence. The sequence is established as a result of writing the records to the file.

o Relative I-O (2 REL 0,2)

Provides access to records in either a random or sequential manner. Each record is uniquely identified by an integer specifying the record's logical position in a file.

o Indexed I-O (2 INX 0,2)

Provides access to records in either a random or sequential manner. Each record in an indexed file is uniquely identified by the value of a key within that record.

o Sort-Merge (1 SRT 0,1)

Orders one or more files of records, or combines two or more identically ordered files of records, according to a set of user-specified keys.

o Inter-Program Communication (2 IPC 1,2)

Allows a COBOL program to communicate with other programs through transfers of control and access to common data items.

o Source Text Manipulation (2 STM 0,2)

Allows the insertion of source program text as part of the compilation of the source program. COBOL libraries contain texts which are available to the compiler at compile time and which can be treated by the compiler as part of the source program.

| In addition, the following levels of optional modules are supported:

o Debug (1 DEB 0,2)

Monitors object program execution through declarative procedures, special debugging lines, and a special register, DEBUG-ITEM, which gives specific information about execution status.

o Segmentation (2 SEG 0,2)

Refreshes independent segments when required.

| The following optional modules of the standard are not supported:

| o Report Writer | o Communications | o Debug (2 DEB 0,2) | o Intrinsic Functions

| 3. FIPS Publication 21-3, Federal Information Processing Standard 21-3, | COBOL. VS COBOL II supports the FIPS intermediate subset, and the | FIPS high subset except for the Intrinsic Functions module.

4. International Reference Version of the ISO 7-bit code defined in International Standard 646, 7-Bit Coded Character Set for Information Processing Interchange.

5. The 7-bit coded character sets defined in American National Standard X3.4-1977, Code for Information Interchange.

The COBOL language is developed by the Conference On DAta SYstems Languages (CODASYL).


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_2.8 Terminology for Industry Standards

| The term "COBOL 85 Standard" is used in this book to refer to the | combination of the following standards:

| o ISO 1989:1985 Programming Languages--COBOL, as amended by ISO | 1989/Amendment 1, Programming Languages --COBOL--Amendment 1: | Intrinsic Function Module

| o X3.23-1985, American National Standard for Information | Systems--Programming Language--COBOL. as amended by X3.23a.1989, | American National Standard for Information Systems, Programming | Language-- Intrinsic Function Module for COBOL.

| The term "COBOL 74 Standard" is used in this book to refer to the | following obsolete standards:

| o X3.23-1974, American National Standard for Information | Systems--Programming Language--COBOL.

| o ISO 1989:1978, Programming Languages--COBOL.

| Note: The ISO standards are equivalent to the American National | standards.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_2.9 Acknowledgment

The following extract from Government Printing Office Form Number 1965-0795689 is presented for the information and guidance of the user:

Any organization interested in reproducing the COBOL report and specifications in whole or in part, using ideas taken from this report as the basis for an instruction manual or for any other purpose is free to do so. However, all such organizations are requested to reproduce this section as part of the introduction to the document. Those using a short passage, as in a book review, are requested to mention COBOL in acknowledgment of the source, but need not quote this entire section.

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

Procedures have been established for the maintenance of COBOL. Inquiries concerning the procedures for proposing changes should be directed to the Executive Committee of the Conference on Data Systems Languages.

The authors and copyright holders of copyrighted material:

| o FLOW-MATIC (Trademark of Sperry Rand Corporation), Programming | for the UNIVAC (R) I and II, Data Automation Systems | copyrighted 1958, 1959, by Sperry Rand Corporation

| o IBM(*) Commercial Translator, Form No. F28-8013, copyrighted | 1959 by IBM

| o FACT, DSI 27A5260-2760, copyrighted 1960 by | Minneapolis-Honeywell,

| ()

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


| () (*) IBM is a trademark of International Business Machines | Corporation.

Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_2.10 VS COBOL II Publications

   Table 1 lists the books in the VS COBOL II library and shows the 
   tasks--such as evaluating, installing, or application programming--with 
   which each book is designed to help you. 

________________________________________________________________________ | Table 1. VS COBOL II Publications | |________________________________________________________________________| | | | Order | | Task | Publication | Number | |______________|____________________________________________|____________| | Evaluation | General Information | GC26-4042 | | and | Migration Guide for MVS and CMS | GC26-3151 | | Planning | Migration Guide for VSE | GC26-3150 | | | Licensed Program Specifications | GC26-4044 | |______________|____________________________________________|____________| | Installation | Installation and Customization for MVS | SC26-4048 | | and | Installation and Customization for CMS | SC26-4213 | | Customization| Installation and Customization for VSE | SC26-4696 | |______________|____________________________________________|____________| | | Application Programming Guide for MVS and | | | Application | CMS | SC26-4045 | | Programming | Application Programming Guide for VSE | SC26-4697 | | | Application Programming Language Reference | GC26-4047 | | | Application Programming Reference Summary | SX26-3721 | | | Application Programming Debugging | SC26-4049 | |______________|____________________________________________|____________| | Diagnosis | Diagnosis Guide | LY27-9523 | | | Diagnosis Reference | LY27-9522 | |______________|____________________________________________|____________|

General Information Contains high-level information designed to help you evaluate the VS COBOL II product. This manual describes compiler and language features, as well as product support for industry standards.

Licensed Program Specifications Contains a product description and product warranty information for the VS COBOL II compiler and library.

Migration Guide for MVS and CMS Provides detailed migration information for current OS/VS COBOL users and general migration information for current VS COBOL II users who want to migrate their applications to the latest release of VS COBOL II. This manual also describes several migration aids and tools to help you plan a migration path for your installation.

Migration Guide for VSE Provides detailed migration information for current DOS/VS COBOL users and general migration information for current VS COBOL II users who want to migrate their applications to the latest release of VS COBOL II. This manual also describes several migration aids and tools to help you plan a migration path for your installation.

Installation and Customization for MVS Lists the steps to make VS COBOL II available for use on MVS. Information on creating reserved word tables and tailoring the run-time library is also included.

Installation and Customization for CMS Lists the steps to make VS COBOL II available for use under the CMS component of VM. Information on creating reserved word tables and tailoring the run-time library is also included.

Installation and Customization for VSE | Lists the steps to make VS COBOL II available for use under | VSE/ESA(*). () Information on creating reserved word tables and tailoring the run-time library is also included.

Application Programming Guide for MVS and CMS Contains guidance information to help you create application programs using VS COBOL II in an MVS or CMS environment. The purpose of this guide is to help programmers create, compile, link-edit, and run new VS COBOL II programs. Information on structured programming is included, as well as basic instructions on features that are new in VS COBOL II.

Application Programming Guide for VSE Contains guidance information to help you create application programs using VS COBOL II in a VSE environment. The purpose of this guide is to help programmers create, compile, link-edit, and run new VS COBOL II programs. Information on structured programming is included, as well as basic instructions on features that are new in VS COBOL II.

Application Programming Language Reference Presents syntax and semantic information about IBM's implementation of the COBOL language, including rules for writing source programs and descriptions of IBM language extensions. This manual is meant to be used in conjunction with the VS COBOL II Application Programming Guide for MVS and CMS or the VS COBOL II Application Programming Guide for VSE, which provide task-oriented programming information.

Application Programming Reference Summary Summarizes the VS COBOL II language format, reserved words, return codes, compiler options, and debugging language in a convenient booklet.

Application Programming Debugging Describes procedures for debugging run-time abends, as well as how to use tools provided with VS COBOL II to identify and correct problems in a VS COBOL II program.

Diagnosis Guide Describes how to diagnose failures in the VS COBOL II compiler and library that are not due to user error. This manual helps you determine if a correction for a product failure similar to yours has been previously documented. If not, there is a section that helps you prepare an Authorized Program Analysis Report (APAR).

Diagnosis Reference Provides general information about the VS COBOL II compiler and library structures. This manual contains primarily internal product information as guidance for diagnostic purposes and is used when the diagnostician has determined that the problem has not been previously reported.


| () (*) VSE/ESA is a trademark of International Business | Machines Corporation.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_2.10.1 Softcopy Information Available with VS COBOL II

| The VS COBOL II Release 4 publications are available in softcopy, via | BookManager(*)/Read files available on CD-ROM. () The VS COBOL II books | available on this CD-ROM include:

| o General Information | o Migration Guide for MVS and CMS | o Migration Guide for VSE | o Installation and Customization for MVS | o Installation and Customization for CMS | o Installation and Customization for VSE | o Application Programming Guide for MVS and CMS | o Application Programming Guide for VSE | o Application Programming Language Reference | o Application Programming Reference Summary | o Application Programming Debugging

| The VS COBOL II Diagnosis Guide and the VS COBOL II Diagnosis Reference | are also available in softcopy. Contact your IBM representative to obtain | these two licensed books.


| () (*) BookManager is a trademark of International Business | Machines Corporation.

Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_2.10.2 Other Publications You Might Need

| For a list of non-VS COBOL II publications that you might need, see | "Bibliography" in topic BACK_1.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3 Summary of Changes

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_3.1 Release 4.0

| Date of Publication: March 1993

| Form of Publication: Revision, SC26-4047-7

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_3.1.1 Programming Changes

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_3.1.1.1 31-bit Addressing under VSE/ESA

| When running under VSE/ESA V1R3 on an extended architecture processor, VS | COBOL II Release 4 can use 31-bit addressing, allowing you to take | advantage of storage above the 16-megabyte line. (VS COBOL II R3.0 (or | later) already uses the 31-bit addressing feature of the MVS and VM | operating systems.)


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_3.1.1.2 PTF-Level Indicator in Compiler and Library Modules

| A PTF-level "eyecatcher" is stored in most VS COBOL II compiler and | library modules. The "eyecatcher" shows the number of the latest PTF | (Program Temporary Fix) applied to the module, thus aiding in the | maintenance and debugging of the VS COBOL II product.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_3.1.1.3 Object Program Portability

| VS COBOL II Release 4 extends the object program portability provided by | VS COBOL II Release 3.2. Object programs compiled under VS COBOL II | Release 3.2 or Release 4 are portable between the MVS, VM, and VSE | operating environments, and between the CICS/MVS(*), CICS/VM(*), and | CICS/VSE(*) transaction processing environments, provided that the | functions and services used are available or supported in the target | operating systems and environments. ()


| () (*) CICS/MVS, CICS/VM, and CICS/VSE are trademarks of | International Business Machines Corporation.

Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_3.1.1.4 Enhanced COBOL 85 Standard Support under VSE

| Support of the intermediate subset of the COBOL 85 Standard under VSE/ESA, | and support of most of the high subset, with the exception of the | following language features:

| o EXTEND phrase of the OPEN statement (However, OPEN EXTEND for VSAM | sequential files is supported.) | o REVERSED phrase of the OPEN statement | o OF/IN phrase of the COPY statement


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_3.1.1.5 COBOL 85 Standard Interpretations

| Support for the following three COBOL 85 Standard interpretations:

| o Different treatment of blank lines and comment lines that appear in | pseudo-text-1 in the COPY REPLACING and REPLACE statements.

| o Changed precedence of USE procedures in contained programs, so that | USE procedure precedence goes from the current program to its | containing program, and so on to the outermost program.

| o Application of a maximum-length receiver rule to reference-modified | variable-length group items that contain their own OCCURS DEPENDING ON | object, so that when the group item is used as a receiving item, its | maximum length will be used regardless of any reference-modifier.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_3.1.2 Documentation Changes

| o Appendix F: Language Differences has been removed from this book and | placed in two separate books: VS COBOL II Migration Guide for MVS and | CMS and VS COBOL II Migration Guide for VSE.

| o The sections on "Scope of Names" and "Methods of Data Reference" have | been extensively revised.

| o Miscellaneous maintenance and editorial changes have been included.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.2 Release 3.2

Date of Publication: December 1990

Form of Publication: Revision, SC26-4047-6

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.2.1 Programming Changes

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_3.2.1.1 COBOL 85 Standard Support under VSE

| Support of the intermediate level of the COBOL 85 Standard under VSE/ESA.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_3.2.1.2 SAA COBOL Support for CICS/VSE

| Support of the SAA(*) (Systems Application Architecture(*)) COBOL Common | Programming Interface in the CICS/VSE operating environment, which will | provide application portability with CICS/MVS. ()


| () (*) SAA and Systems Application Architecture are trademarks | of International Business Machines Corporation.

Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_3.2.1.3 Run-Time Compatibility Library

| Object program coexistence, by means of a Run-Time Compatibility Library, | with DOS/VS COBOL Release 3.1.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_3.2.1.4 Enhanced Interfaces

| Enhanced interfaces to device and CICS(*) support modules. ()


| () (*) CICS is a trademark of International Business Machines | Corporation.

Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.2.2 Documentation Changes

Miscellaneous maintenance and editorial changes have been included.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.3 Release 3.1

Date of Publication: December 1989

Form of Publication: Revision, SC26-4047-5

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.3.1 Programming Changes

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_3.3.1.1 COBOL 85 Standard Support under VM/SP 6

| Full support for the high subset of the COBOL 85 Standard is available with VS COBOL II under the CMS subcomponent of VM/SP 6 with the appropriate SPE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.3.1.2 CICS SORT Interface

VS COBOL II has a run-time routine to interface with sort programs in the CICS environment.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.3.1.3 SORT/MERGE Support

VS COBOL II provides support for indexed and relative files with dynamic access.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.3.1.4 Compiler Listing Enhancements

Various compiler listing features allow improved usability.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.3.1.5 Generated Code Performance Improvements

Several run-time performance enhancements are applied to VS COBOL II


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.3.1.6 Diagnostic Message Improvements

Various compiler diagnostic messages are changed for clarity.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.3.2 Documentation Changes

Miscellaneous maintenance and editorial changes have been included.

Appendix F: Language Differences has been included in this manual to clarify different behaviors among language elements due to implementation of the COBOL 85 Standard.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.4 Release 3.0

Date of Publication: December 1988

Form of Publication: Revision, SC26-4047-4

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.4.1 Programming Changes

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| FRONT_3.4.1.1 COBOL 85 Standard Support Under MVS

| VS COBOL II incorporates all of the major and minor language enhancements | to the required modules for the high level of the COBOL 85 Standard when | run under MVS.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.4.1.2 SAA Support

The FLAGSAA option identifies elements that are not portable under SAA.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.4.1.3 VM/XA Support

| The compiler and the object program it produces can be run under CMS under | VM/XA(*), in either 24- or 31-bit addressing mode. ()


| () (*) VM/XA is a trademark of International Business Machines | Corporation.

Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.4.1.4 Hexadecimal Notation for Nonnumeric Literals

Allows the use of hexadecimal notation in nonnumeric literals.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.4.1.5 Release 2 to Release 3 compatibility and migration

The CMPR2 compiler option allows you continue to use your valid COBOL programs written for Release 2 by providing the same run-time results as when it is compiled on the Release 2 compiler. The NOCMPR2 compiler option allows you to take full advantage of the COBOL 85 Standard support for your new programs. The FLAGMIG compiler option can be used in combination with the CMPR2 compiler option to help identify language elements that exhibit different behavior between Release 2 and the COBOL 85 Standard features available under NOCMPR2.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.4.1.6 Nonnumeric literal with double-byte characters

Allows the use of both EBCDIC and double-byte characters in nonnumeric literals.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.4.1.7 National Language Support

VS COBOL II allows compiler diagnostics, runtime messages, and listing headings to be displayed in a language other than English. A separate language feature is required to implement the translated messages.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

FRONT_3.4.2 Documentation Changes

Miscellaneous maintenance and editorial changes have been included.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.0 Part 1. COBOL Language Structure

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1 Characters

   The most basic and indivisible unit of the COBOL language is the 
   character.  The VS COBOL II character set includes the letters of the 
   alphabet, digits, and special characters.  The complete set of characters 
   that form the VS COBOL II character set is shown in Table 2. 

The VS COBOL II language is restricted to the above character set, but the content of nonnumeric literals, comment lines, comment entries, and data can include any of the characters from the character set of the computer.

x Characters from the Double-Byte Character Set (DBCS) are valid characters x in certain COBOL character-strings. Double-byte characters, as the name x implies, occupy two adjacent bytes to represent 1 character. DBCS values x range from X'41' to X'FE' for both bytes, plus X'4040' for a blank. In x addition, DBCS data items and literals can include characters that range x in hexadecimal value from X'00' to X'FF' for both bytes.

Individual characters are joined to form character-strings, separators, | and text words.

A character-string is a character or a sequence of contiguous characters that forms a COBOL word, a literal, a PICTURE character-string, or a comment. A character-string is delimited by separators.

A separator is a string of one or more contiguous punctuation characters. Separators are described in detail under "Separators" in topic 1.1.2.

________________________________________________________________________ | Table 2. VS COBOL II Characters--Their Meanings and Uses | |________________________________________________________________________| | Character | Meaning | Use | |_____________|_____________________________|____________________________| | | Space | Punctuation character | |_____________|_____________________________|____________________________| | . | Decimal point or Period | Editing character | | | | Punctuation character | |_____________|_____________________________|____________________________| | < | Less than | Relation character | |_____________|_____________________________|____________________________| | ( | Left parenthesis | Punctuation character | |_____________|_____________________________|____________________________| | + | Plus sign | Arithmetic operator | | | | Editing character | |_____________|_____________________________|____________________________| | | $ | Currency sign | Editing character | |_____________|_____________________________|____________________________| | * | Asterisk | Arithmetic operator | | | | Editing character | | | | Comment character | |_____________|_____________________________|____________________________| | ) | Right parenthesis | Punctuation character | |_____________|_____________________________|____________________________| | ; | Semicolon | Punctuation character | |_____________|_____________________________|____________________________| | - | Minus sign or Hyphen | Arithmetic operator | | | | Editing character | | | | Continuation character | |_____________|_____________________________|____________________________| | | / | Slant, Solidus, Stroke, or | Arithmetic operator | | | | Slash | Editing character | | | | Line control character | |_____________|_____________________________|____________________________| | , | Comma | Punctuation character | | | | Editing character | |_____________|_____________________________|____________________________| | > | Greater than | Relation character | |_____________|_____________________________|____________________________| | : | Colon | Punctuation character | |_____________|_____________________________|____________________________| x | ' | Apostrophe | Nonnumeric literal | x | | | delimiter | |_____________|_____________________________|____________________________| | = | Equal sign | Relation character | | | | Punctuation character | |_____________|_____________________________|____________________________| | " | Quotation mark | Nonnumeric literal | | | | delimiter | |_____________|_____________________________|____________________________| | A-Z | Alphabet (uppercase) | Alphabetic characters | |_____________|_____________________________|____________________________| | a-z | Alphabet (lowercase) | Alphabetic characters | |_____________|_____________________________|____________________________| | 0-9 | Numeric characters | Numeric characters | |_____________|_____________________________|____________________________|

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1 Character-Strings

x You can use EBCDIC and/or DBCS character-strings to form:

o COBOL words o Literals o PICTURE character-strings (EBCDIC character-strings only) o Comments.

x DBCS character-strings are constructed using characters from the x Double-Byte Character Set of a system.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1.1 COBOL Words

| A COBOL word is a character-string of not more than 30 characters which | forms a user-defined word, a system-name, or a reserved word. Except for | arithmetic operators and relation characters, each character of a COBOL | word is selected from the set of letters, digits, and the hyphen; the | hyphen cannot appear as the first or last character in such words. Each | lowercase letter is considered to be equivalent to its corresponding | uppercase letter.

| Within a source program the following rules apply for all COBOL words:

| o A reserved word cannot be used as a user-defined word or as a | system-name.

| o The same COBOL word, however, can be used as both a user-defined word | and as a system-name. The classification of a specific occurrence of | a COBOL word is determined by the context of the clause or phrase in | which it occurs.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1.2 User-Defined Words

The types of user-defined words are listed below, with the rules that must be followed in forming them.

________________________________________________________________________ | Table 3. General Rules for VS COBOL II User-Defined Words | |________________________________________________________________________| | Types of User-Defined Words | General Rules | |____________________________________|___________________________________| | | | Each word must contain at least | | | alphabet-name | one alphabetic character. | | | class-name | | | | condition-name | | | | data-name | | | | file-name | | | | index-name | | | | mnemonic-name | | | | program-name (for | | | | contained program) | | | | record-name | | | | routine-name | | | | symbolic-character | | | | | |____________________________________|___________________________________| | | | See "PROGRAM-ID Paragraph" in | | | library-name | topic 2.2.1. | | | program-name | | | | text-name | | | | | |____________________________________|___________________________________| | | The word need not contain an | | | paragraph-name | alphabetic character. | | | section-name | | | | | |____________________________________|___________________________________| | | Each word must be a 1-digit or | | Level-numbers: 01-49,66,77,88 | 2-digit integer. | | Priority-numbers: 00-99 | | | | | |____________________________________|___________________________________|

The function of each user-defined word is described in the clause or statement in which it appears.

| User-defined words form sets equivalent to the types in the preceding | table, except that level-numbers are not a set. Within a given source program, but excluding any contained program, each user-defined word (except level-numbers and priority-numbers) can belong to only one of these sets. Each user-defined word within a set must be unique, except as specified in "Methods of Data Reference" in topic 1.5.

The following types of user-defined words can be referenced by statements and entries in that program in which the user-defined word is declared:

| o paragraph-name | o section-name.

The following types of user-defined words can be referenced by any COBOL program, provided that the compiling system supports the associated library or other system, and the entities referenced are known to that system:

| o library-name | o text-name.

The following types of names, when they are declared within a Configuration Section, can be referenced by statements and entries either in that program that contains a Configuration Section, or in any program contained within that program:

| o alphabet-name | o class-name | o condition-name | o mnemonic-name | o symbolic-character.

| An external-name is a character string that is one of the following:

| o assignment-name | o library-name | o outermost program-name | o text-name.

x User-defined words that can be formed from DBCS characters are listed x below, with the rules that must be followed in forming them.

x Types of DBCS User-Defined Words

| o alphabet-name | o class-name | o condition-name | o data-name/Identifier | o record-name | o file-name | o index-name | o mnemonic-name | o paragraph-name | o section-name | o symbolic-character.

x General Rules for DBCS User-Defined Words

x o DBCS user-defined words begin with a shift-out character, have 1 to 14 x DBCS characters, and end with a shift-in character. (For more x information on shift-out and shift-in characters, see topic 1.1.1.9.)

x o DBCS user-defined words can contain characters whose values range from x X'41' to X'FE' for both bytes.

x o A DBCS user-defined word must contain at least one double-byte x non-EBCDIC character. (Double-byte EBCDIC characters are represented x by X'42' in the first byte.)

x o DBCS user-defined words can contain both double-byte EBCDIC and x double-byte non-EBCDIC characters. The only double-byte EBCDIC x characters allowed are: "-", A - Z, a - z, and 0 - 9. The hyphen x cannot appear as the first or last character. (The rules that apply x to EBCDIC user-defined words also apply to DBCS user-defined words.)

x o DBCS user-defined words cannot be continued across lines.

| o In a DBCS user-defined word, lowercase double-byte letters are | equivalent to the corresponding uppercase double-byte letters.


@@ Diagram alphabet-name ADDED at the end of this section.
@@ Implemented in accordance with the above table.

    ___ alphabet-name ____________________
   |                                      |
   | >>__alphabetic-user-defined-word__>< |
   |                                      |
   |______________________________________|


@@ Diagram class-name ADDED at the end of this section.
@@ Implemented in accordance with the above table.

    ___ class-name _______________________
   |                                      |
   | >>__alphabetic-user-defined-word__>< |
   |                                      |
   |______________________________________|


@@ Diagram condition-name ADDED at the end of this section.
@@ Implemented in accordance with the above table.

    ___ condition-name ___________________
   |                                      |
   | >>__alphabetic-user-defined-word__>< |
   |                                      |
   |______________________________________|


@@ Diagram data-name ADDED at the end of this section.
@@ Implemented in accordance with the above table.

    ___ data-name ________________________
   |                                      |
   | >>__alphabetic-user-defined-word__>< |
   |                                      |
   |______________________________________|


@@ Diagram file-name ADDED at the end of this section.
@@ Implemented in accordance with the above table.

    ___ file-name ________________________
   |                                      |
   | >>__alphabetic-user-defined-word__>< |
   |                                      |
   |______________________________________|


@@ Diagram index-name ADDED at the end of this section.
@@ Implemented in accordance with the above table.

    ___ index-name _______________________
   |                                      |
   | >>__alphabetic-user-defined-word__>< |
   |                                      |
   |______________________________________|


@@ Diagram mnemonic-name ADDED at the end of this section.
@@ Implemented in accordance with the above table.

    ___ mnemonic-name ____________________
   |                                      |
   | >>__alphabetic-user-defined-word__>< |
   |                                      |
   |______________________________________|


@@ Diagram record-name ADDED at the end of this section.
@@ Error tables; record names can be qualified.

    ___ record-name _____________
   |                             |
   | >>__qualified-data-name__>< |
   |                             |
   |_____________________________|


@@ Diagram routine-name ADDED at the end of this section.
@@ Implemented in accordance with the above table.

    ___ routine-name _____________________
   |                                      |
   | >>__alphabetic-user-defined-word__>< |
   |                                      |
   |______________________________________|


@@ Diagram symbolic-character ADDED at the end of this section.
@@ Implemented in accordance with the above table.

    ___ symbolic-character _______________
   |                                      |
   | >>__alphabetic-user-defined-word__>< |
   |                                      |
   |______________________________________|


@@ Diagram library-name ADDED at the end of this section.
@@ Implemented in accordance with the above table.

    ___ library-name __________
   |                           |
   | >>__user-defined-word__>< |
   |                           |
   |___________________________|


@@ Diagram program-name ADDED at the end of this section.
@@ Implemented in accordance with the above table.

    ___ program-name __________
   |                           |
   | >>__user-defined-word__>< |
   |                           |
   |___________________________|


@@ Diagram text-name ADDED at the end of this section.
@@ Implemented in accordance with the above table.

    ___ text-name _____________
   |                           |
   | >>__user-defined-word__>< |
   |                           |
   |___________________________|


@@ Diagram paragraph-name ADDED at the end of this section.
@@ Implemented in accordance with the above table.

    ___ paragraph-name ________
   |                           |
   | >>__user-defined-word__>< |
   |                           |
   |___________________________|


@@ Diagram section-name ADDED at the end of this section.
@@ Implemented in accordance with the above table.

    ___ section-name __________
   |                           |
   | >>__user-defined-word__>< |
   |                           |
   |___________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1.3 System-Names

A system-name is a character string that is defined by IBM to have a specific meaning to the system. There are three types of system-names:

| o computer-name | o language-name | o implementor-name.

There are two types of implementor-names:

| o environment-name | o assignment-name.

The meaning of each system-name is described with the format in which it appears.

x The only system-name that can be specified in DBCS is "computer-name."


@@ Diagram computer-name ADDED at the end of this section.
@@ Implemented in accordance with the above description.

    ___ computer-name ___
   |                     |
   | >>__system-name__>< |
   |                     |
   |_____________________|


@@ Diagram language-name ADDED at the end of this section.
@@ Implemented in accordance with the above description.

    ___ language-name ___
   |                     |
   | >>__system-name__>< |
   |                     |
   |_____________________|


@@ Diagram implementor-name ADDED at the end of this section.
@@ Implemented in accordance with the above description.

    ___ implementor-name ___________
   |                                |
   | >>_____environment-name_____>< |
   |     |__assignment-name___|     |
   |                                |
   |________________________________|


@@ Diagram environment-name ADDED at the end of this section.
@@ Implemented in accordance with the above description.

    ___ environment-name ___
   |                        |
   | >>__system-name_____>< |
   |                        |
   |________________________|


@@ Diagram assignment-name ADDED at the end of this section.
@@ Implemented in accordance with the above description.

    ___ assignment-name ___
   |                       |
   | >>__system-name____>< |
   |                       |
   |_______________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1.4 Reserved Words

A reserved word is a character-string with a predefined meaning in a COBOL | source program. A reserved word must not be used as a user-defined word | or as a system-name. Reserved words can be used only as specified in the formats for a COBOL source program. COBOL reserved words are listed in Appendix D, "VS COBOL II Reserved Words" in topic APPENDIX1.4.

x Information on selecting an alternate reserved word table can be found in x VS COBOL II Application Programming Guide for MVS and CMS or VS COBOL II x Application Programming Guide for VSE.

There are five types of reserved words:

o Keywords o Optional words o Special characters o Figurative constants o Special registers.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1.5 Keywords

Keywords are reserved words that are required within a given clause, entry, or statement. Within each format, such words appear in uppercase on the main path.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1.6 Optional Words

Optional words are reserved words that can be included in the format of a clause, entry, or statement in order to improve readability. They have no effect on the execution of the program. Within each format, optional words are shown in uppercase below the main path on which the keywords appear.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1.7 Special Characters

There are two types of special character reserved words:

o Arithmetic operators: + - / * **

See "Arithmetic Expressions" in topic 2.8.4.

o Relational operators: < > = <= >=

See "Conditional Expressions" in topic 2.8.5.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1.8 Figurative Constants

Figurative constants are reserved words that name and refer to specific constant values. The reserved words for figurative constants and their meanings are:

ZERO/ZEROS/ZEROES Represents the numeric value zero (0), or one or more occurrences of the nonnumeric character zero (0), depending on context.

SPACE/SPACES Represents one or more blanks or spaces; treated as a nonnumeric literal.

HIGH-VALUE/HIGH-VALUES Represents one or more occurrences of the character that has the highest ordinal position in the collating sequence used. For the EBCDIC collating sequence, the character is X'FF'; for other collating sequences, the actual character used depends on the collating sequence. HIGH-VALUE is treated as a nonnumeric literal.

LOW-VALUE/LOW-VALUES Represents one or more occurrences of the character that has the lowest ordinal position in the collating sequence used. For the EBCDIC collating sequence, the character is X'00'; for other collating sequences, the actual character used depends on the collating sequence. LOW-VALUE is treated as a nonnumeric literal.

QUOTE/QUOTES Represents one or more occurrences of the quotation mark character. QUOTE or QUOTES cannot be used in place of a quotation mark to enclose a nonnumeric literal.

Represents one or more occurrences of a nonnumeric literal delimiter x depending on the QUOTE/APOST compiler option.

symbolic-character | Represents one or more of the characters specified as the value of the | symbolic-character in the SYMBOLIC CHARACTERS clause of the | SPECIAL-NAMES paragraph.

ALL literal Represents one or more occurrences of the string of characters composing the literal. The literal must be either a nonnumeric literal or a figurative constant other than the ALL literal. When a figurative constant other than ALL literal is used, the word ALL is redundant and is used for readability only. The figurative constant ALL literal must not be used with the INSPECT, STOP, or STRING statements.

Note: The figurative constant ALL literal, when associated with a numeric or numeric-edited item and when the length of the literal is | greater than one, is an obsolete element and will be deleted from the | next revision of the COBOL 85 Standard.

x NULL/NULLS x Represents a value used to indicate that data items defined with USAGE x IS POINTER or ADDRESS OF special registers do not contain a valid x address. NULL can be used only where explicitly allowed in the syntax x format. In VS COBOL II, NULL has the value of zero.

The singular and plural forms of a figurative constant other than symbolic-character are equivalent, and can be used interchangeably. For example, if DATA-NAME-1 is a 5-character data item, each of the following statements will fill DATA-NAME-1 with five spaces:

MOVE SPACE TO DATA-NAME-1 MOVE SPACES TO DATA-NAME-1 MOVE ALL SPACES TO DATA-NAME-1

A figurative constant can be used wherever "literal" appears in a syntax diagram, except where explicitly prohibited. When a numeric literal appears in a syntax diagram, only the figurative constant ZERO (ZEROS, ZEROES) can be used.

The length of a figurative constant depends on the context of the program. The following rules apply:

o When a figurative constant is specified in a VALUE clause or associated with a data item (for example, when it is moved to or compared with another item), the length of the figurative constant | character-string is equal to 1 or to the number of characters in the | associated data item, whichever is greater.

o When a figurative constant, other than ALL literal, is not associated with another data item (for example, in a STOP, STRING, or UNSTRING | statement), the length of the character-string is 1 character.


@@ Diagram figurative-constant ADDED at the end of this section.
@@ Implemented in accordance with the above enumeration.

    ___ figurative-constant ____
   |                            |
   | >>_____ZERO_____________>< |
   |     |__ZEROS_________|     |
   |     |__ZEROES________|     |
   |     |__SPACE_________|     |
   |     |__SPACES________|     |
   |     |__HIGH-VALUE____|     |
   |     |__HIGH-VALUES___|     |
   |     |__LOW-VALUE_____|     |
   |     |__LOW-VALUES____|     |
   |     |__QUOTE_________|     |
   |     |__QUOTES________|     |
   |     |__ALL__literal__|     |
   |     |__NULL__________|     |
   |     |__NULLS_________|     |
   |                            |
   |____________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1.9 Special Registers

Special registers are reserved words that name storage areas generated by | the compiler. Their primary use is to store information produced through | specific COBOL features. Each such storage area has a fixed name, and | need not be defined within the program.

| In the general formats of this specification, a special register can be | used wherever a data-name or identifier is specified, provided that the | special register is the same category as the data-name or identifier, and | the use of a special register is not explicitly prohibited. If | qualification is allowed, special registers can be qualified as necessary | to provide uniqueness. (For more information, see "Qualification" in | topic 1.5.1.1.)

For the first call to a program, the compiler initializes the special register fields to their initial values. The special registers will be reset to their initial values in subsequent calls to a program that had been canceled or that possesses the INITIAL attribute. Otherwise, the special registers will not be reset (they will be unchanged from the value contained on the previous call).

| The following individual special registers are described below.

| o ADDRESS OF | o DEBUG-ITEM | o LENGTH OF | o LINAGE-COUNTER | o RETURN-CODE | o SHIFT-OUT and SHIFT-IN | o SORT-CONTROL | o SORT-CORE-SIZE | o SORT-FILE-SIZE | o SORT-MESSAGE | o SORT-MODE-SIZE | o SORT-RETURN | o TALLY | o WHEN-COMPILED

x ADDRESS OF Special Register x The ADDRESS OF special register exists for each record (01 or 77) in x the Linkage Section, except for those records that redefine each x other. In such cases, the ADDRESS OF special register is similarly x redefined.

x The ADDRESS OF special register is implicitly defined USAGE IS x POINTER.

DEBUG-ITEM Special Register The DEBUG-ITEM special register provides information for a debugging declarative procedure about the conditions causing debugging section execution.

Note: The DEBUG-ITEM special register is an obsolete language element | and will be deleted from the next revision of the COBOL 85 Standard.

DEBUG-ITEM has the following implicit description:

01 DEBUG-ITEM. 02 DEBUG-LINE PICTURE X(6). 02 FILLER PICTURE X VALUE SPACE. 02 DEBUG-NAME PICTURE X(30). 02 FILLER PICTURE X VALUE SPACE. 02 DEBUG-SUB-1 PICTURE S9(4) SIGN IS LEADING SEPARATE CHARACTER. 02 FILLER PICTURE X VALUE SPACE. 02 DEBUG-SUB-2 PICTURE S9(4) SIGN IS LEADING SEPARATE CHARACTER. 02 FILLER PICTURE X VALUE SPACE. 02 DEBUG-SUB-3 PICTURE S9(4) SIGN IS LEADING SEPARATE CHARACTER. 02 FILLER PICTURE X VALUE SPACE. 02 DEBUG-CONTENTS PICTURE X(N).

Before each debugging section is executed, DEBUG-ITEM is filled with spaces. The contents of the DEBUG-ITEM subfields are updated according to the rules for the MOVE statement, with one exception: DEBUG-CONTENTS is updated as if the move were an alphanumeric-to-alphanumeric elementary move without conversion of data from one form of internal representation to another.

After updating, each field contains:

DEBUG-LINE The source-statement sequence number (or the compiler-generated sequence number, depending on the compiler option chosen) that caused execution of the debugging section.

DEBUG-NAME The first 30 characters of the name that caused execution of the debugging section. Any qualifiers are separated by the word "OF."

DEBUG-SUB-1, DEBUG-SUB-2, DEBUG-SUB-3 If the DEBUG-NAME is subscripted or indexed, the occurrence number of each level is entered in the respective DEBUG-SUB-n. If the item is not subscripted or indexed, these fields remain as spaces. You should not reference the DEBUG-ITEM special register if your program uses more than three levels of subscripting or indexing.

DEBUG-CONTENTS Data is moved into DEBUG-CONTENTS, as shown in Table 4.

__________________________________________________________________________ | Table 4. DEBUG-ITEM Subfield Contents | |__________________________________________________________________________| | Cause of | | | | | Debugging | Statement | Contents of | Contents of | | Section | Referred to | DEBUG-NAME | DEBUG-CONTENTS | | Execution | in DEBUG-LINE | | | |_________________|__________________|___________________|_________________| | procedure-name-1| ALTER statement | procedure-name-1 | procedure-name-n| | ALTER reference | | | in TO PROCEED | | | | | TO phrase | |_________________|__________________|___________________|_________________| | GO TO | GO TO statement | procedure-name-n | spaces | | procedure-name-n| | | | |_________________|__________________|___________________|_________________| | procedure-name-n| SORT/MERGE | procedure-name-n | | | in SORT/MERGE | statement | | "SORT INPUT" | | input/output | | | "SORT OUTPUT" | | procedure | | | "MERGE OUTPUT" | | | | | (as applicable) | | | | | | |_________________|__________________|___________________|_________________| | PERFORM | This PERFORM | procedure-name-n | "PERFORM LOOP" | | statement | statement | | | | transfer of | | | | | control | | | | |_________________|__________________|___________________|_________________| | procedure-name-n| Statement | procedure-name-n | "USE PROCEDURE" | | in a USE | causing USE | | | | procedure | procedure | | | | | execution | | | |_________________|__________________|___________________|_________________| | Implicit | Previous | procedure-name-n | "FALL THROUGH" | | transfer from | statement | | | | previous | executed in | | | | sequential | previous | | | | procedure | sequential | | | | | procedure * | | | |_________________|__________________|___________________|_________________| | First execution | Line number of | first | "START PROGRAM" | | of first | first | nondeclarative | | | nondeclarative | nondeclarative | procedure | | | procedure | procedure-name | | | |_________________|__________________|___________________|_________________| | Note: | | | | * If this procedure is preceded by a section header, and control is | | passed through the section header, the statement number refers to | | the section header. | |__________________________________________________________________________|

x LENGTH OF Special Register x The LENGTH OF special register contains the number of bytes used by an x identifier.

x LENGTH OF creates an implicit special register whose content is equal x to the current byte length of the data item referenced by the x identifier.

x Note: For DBCS data items, each character occupies 2 bytes of x storage.

x LENGTH OF can be used in the Procedure Division anywhere a numeric x data item having the same definition as the implied definition of the x LENGTH OF special register is used. The LENGTH OF special register x has the implicit definition:

x USAGE IS BINARY PICTURE 9(9)

x If the data item referenced by the identifier contains the GLOBAL x clause, the LENGTH OF special register is a global data item.

x The LENGTH OF special register can appear within either the starting x character position or the length expressions of a reference x modification specification. However, the LENGTH OF special register x cannot be applied to any operand that is reference modified.

x LENGTH OF can not be either of the following:

x o A receiving data item x o A subscript.

x When the LENGTH OF special register is used as a parameter in a CALL x statement, the parameter must be a BY CONTENT parameter.

x When a table element is specified, the LENGTH OF special register x contains the length, in bytes, of one occurrence. When referring to a x table element, it need not be subscripted.

x A value is returned for any identifier whose length can be determined, x even if the area referenced by the identifier is currently not x available to the program.

x A separate LENGTH OF special register exists for each identifier x referenced with the LENGTH OF phrase. For example:

x MOVE LENGTH OF A TO B x DISPLAY LENGTH OF A, A x ADD LENGTH OF A TO B x CALL "PROGX" USING BY REFERENCE A BY CONTENT LENGTH OF A

LINAGE-COUNTER Special Register A separate LINAGE-COUNTER special register is generated for each FD entry containing a LINAGE clause. When more than one is generated, you must qualify each LINAGE-COUNTER with its related file-name.

The implicit description of the LINAGE-COUNTER special register is one of the following:

| o If the LINAGE clause specifies a data-name, LINAGE-COUNTER has the same PICTURE and USAGE as that data-name.

o If the LINAGE clause specifies an integer, LINAGE-COUNTER is a binary item with the same number of digits as that integer.

For more information, see the description of the LINAGE Clause on topic 2.6.9.

The value in LINAGE-COUNTER at any given time is the line number at which the device is positioned within the current page. LINAGE-COUNTER can be referred to in Procedure Division statements; it must not be modified by them.

LINAGE-COUNTER is initialized to 1 when an OPEN statement for this file is executed.

LINAGE-COUNTER is automatically modified by any WRITE statement for this file. (See "WRITE Statement" in topic 3.38.)

If the file description entry for a sequential file contains the LINAGE clause and the EXTERNAL clause, the LINAGE-COUNTER data item is an external data item. If the file description entry for a sequential file contains the LINAGE clause and the GLOBAL clause, the LINAGE-COUNTER data item is a global data item.

x RETURN-CODE Special Register (1) x You can use the RETURN-CODE special register to pass return codes from x called programs to calling programs.

x For separately compiled programs, the RETURN-CODE special register is x used to pass return codes from a subprogram to a main program and from x a main program to the operating system.

x For nested programs, the RETURN-CODE special register is treated like x a numeric data item declared with the GLOBAL attribute in the x outermost program. Unlike separately compiled programs, when nested x programs are invoked, the RETURN-CODE special register is not x initialized to zero.

x The RETURN-CODE special register has the implicit definition:

x 01 RETURN-CODE GLOBAL PICTURE S9(4) USAGE BINARY VALUE ZERO.

x Here is an example of how to set the RETURN-CODE special register:

x MOVE 8 to RETURN-CODE

x SHIFT-OUT and SHIFT-IN Special Register (1) x The SHIFT-OUT and SHIFT-IN special registers are implicitly defined as x alphanumeric data items of the format:

x 01 SHIFT-OUT GLOBAL PICTURE X(1) USAGE DISPLAY VALUE X"0E". x 01 SHIFT-IN GLOBAL PICTURE X(1) USAGE DISPLAY VALUE X"0F".

x These special registers represent shift-out and shift-in control x characters without the use of unprintable characters.

x These special registers cannot be receiving items. SHIFT-OUT and x SHIFT-IN cannot be used in place of the keyboard control characters x when defining DBCS user-defined words and when specifying DBCS x literals.

x Following is an example of how SHIFT-OUT and SHIFT-IN might be used:

x DATA DIVISION. x WORKING-STORAGE SECTION. x 01 DBCSGRP. x 05 SO PICTURE X. x 05 DBCSITEM PICTURE G(3) USAGE DISPLAY-1. x 05 SI PICTURE X. x .......

x PROCEDURE DIVISION. x MOVE SHIFT-OUT TO SO x MOVE G"<D1D2D3>" TO DBCSITEM x MOVE SHIFT-IN TO SI x DISPLAY DBCSGRP

x SORT-CONTROL Special Register (1) x The SORT-CONTROL special register is the name of an alphanumeric data x item, which is implicitly defined as:

x 01 SORT-CONTROL GLOBAL PICTURE X(8) USAGE DISPLAY VALUE "IGZSRTCD".

x It contains the ddname of the data set that holds the control x statements used to improve the performance of a sorting or merging x operation.

x The SORT-CONTROL special register is not necessary for a successful x sorting or merging operation.

x Under MVS, you can provide a DD statement for the data set identified x by the SORT-CONTROL special register, and VS COBOL II will attempt to x open the data set at execution time. Any error will be diagnosed with x an informational message.

x Under VSE, you can specify the name of a VSE library member under the x SORT-CONTROL special register, and VS COBOL II will read the member at x execution time. Alternatively, you can specify that SYSIPT is to be x read at execution time.

x Note that the sort control file takes precedence over the SORT special x registers.

x For further information, see VS COBOL II Application Programming Guide x for MVS and CMS or VS COBOL II Application Programming Guide for VSE.

x SORT-CORE-SIZE Special Register (1) x The SORT-CORE-SIZE special register is the name of a binary data item x that you can use to specify the number of bytes of storage available x to the sort utility. It has the implicit definition:

x 01 SORT-CORE-SIZE GLOBAL PICTURE S9(8) USAGE BINARY VALUE ZERO.

x Under MVS and CMS, SORT-CORE-SIZE can be used in place of the MAINSIZE x or RESINV control statements in the sort control file.

x The 'MAINSIZE=' option control statement keyword is equivalent to x SORT-CORE-SIZE with a positive value.

x The 'RESINV=' option control statement keyword is equivalent to x SORT-CORE-SIZE with a negative value.

x The 'MAINSIZE=MAX' option control statement keyword is equivalent x to SORT-CORE-SIZE with a value of +999999 or +99999999.

x Under VSE, only a positive value can be specified, and it is x equivalent to the STORAGE = option control statement for Sort/Merge x II.

x SORT-FILE-SIZE Special Register (1) x The SORT-FILE-SIZE special register is the name of a binary data item x that you can use to specify the estimated number of records in the x sort input file, file-name-1. It has the implicit definition:

x 01 SORT-FILE-SIZE GLOBAL PICTURE S9(8) USAGE BINARY VALUE ZERO.

x Under MVS and CMS, SORT-FILE-SIZE is equivalent to the 'FILSZ=Ennn' x control statement in the sort control file. Under VSE, the special x register is equivalent to the SIZE= keyword in the SORT control x statement of Sort/Merge II. The SIZE= keyword is provided for x compatibility with previous releases of Sort/Merge II and is no longer x used.

x SORT-MESSAGE Special Register (1) x The SORT-MESSAGE special register is the name of an alphanumeric data x item that is available to both sort and merge programs. Under MVS and x CMS, it has the implicit definition:

x 01 SORT-MESSAGE GLOBAL PICTURE X(8) USAGE DISPLAY VALUE "SYSOUT".

x The SORT-MESSAGE special register allows you to specify the ddname of x a data set that the sort utility should use in place of the SYSOUT x data set. The ddname specified in SORT-MESSAGE is equivalent to the x name specified on the 'MSGDDN= ' control statement in the sort control x file. Under VSE, the SORT-MESSAGE special register is equivalent to x the 'ROUTE= ' option control statement keyword.

x SORT-MODE-SIZE Special Register (1) x The SORT-MODE-SIZE special register is the name of a binary data item x that you can use to specify the length of variable-length records that x occur most frequently. It has the implicit definition:

x 01 SORT-MODE-SIZE GLOBAL PICTURE S9(5) USAGE BINARY VALUE ZERO.

x SORT-MODE-SIZE is equivalent to the 'SMS= ' control statement in the x sort control file.

x SORT-RETURN Special Register (1) x The SORT-RETURN special register is the name of a binary data item and x is available to both sort and merge programs.

x The SORT-RETURN special register has the implicit definition:

x 01 SORT-RETURN GLOBAL PICTURE S9(4) USAGE BINARY VALUE ZERO.

x It contains a return code of 0 (successful) or 16 (unsuccessful) at x the completion of a sort/merge operation. If the sort/merge is x unsuccessful and there is no reference to this special register x anywhere in the program, a message is displayed on the console.

x You can set the SORT-RETURN special register to 16 in an error x declarative or input/output procedure to terminate a sort/merge x operation before all records are processed. The operation is x terminated on the next RETURN or RELEASE (generated by the compiler) x statement.

x TALLY Special Register (1) x The TALLY special register is the name of a binary data item with the x following definition:

x 01 TALLY GLOBAL PICTURE 9(5) USAGE BINARY VALUE ZERO.

x You can refer to or modify the contents of TALLY.

x WHEN-COMPILED Special Register (1) x The WHEN-COMPILED special register contains the date at the start of x the compilation. WHEN-COMPILED is an alphanumeric data item with the x implicit definition:

x 01 WHEN-COMPILED GLOBAL PICTURE X(16) USAGE DISPLAY.

x The WHEN-COMPILED special register has the format:

x MM/DD/YYhh.mm.ss (MONTH/DAY/YEARhour.minute.second)

x For example, if compilation began at 2:04 PM on 15 May 1986, x WHEN-COMPILED would contain the value 05/15/8614.04.00.

x WHEN-COMPILED can only be used as the sending field in a MOVE x statement. WHEN-COMPILED special register data cannot be x reference-modified.


x (1) When used in nested programs, these special registers are x implicitly defined in the outermost program.

@@ Diagram special-register ADDED at the end of this section.
@@ Implemented in accordance with the above enumeration.

    ___ special-register _________________
   |                                      |
   | >>_____ADDRESS__OF__data-name_____>< |
   |     |__DEBUG-ITEM______________|     |
   |     |__LENGTH__OF__identifier__|     |
   |     |__RETURN-CODE_____________|     |
   |     |__SHIFT-OUT_______________|     |
   |     |__SHIFT-IN________________|     |
   |     |__SORT-CONTROL____________|     |
   |     |__SORT-CORE-SIZE__________|     |
   |     |__SORT-FILE-SIZE__________|     |
   |     |__SORT-MESSAGE____________|     |
   |     |__SORT-MODE-SIZE__________|     |
   |     |__SORT-RETURN_____________|     |
   |     |__TALLY___________________|     |
   |     |__WHEN-COMPILED___________|     |
   |                                      |
   |______________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1.10 Literals

A literal is a character-string whose value is specified either by the characters of which it is composed, or by the use of a figurative constant. (See "Figurative Constants" in topic 1.1.1.8.) There are three x types of literals: nonnumeric, numeric, and DBCS.


@@ Diagram literal ADDED at the end of this section.
@@ Implemented in accordance with the above text.

    ___ literal _______________________
   |                                   |
   | >>_____nonnumeric______________>< |
   |     |__numeric______________|     |
   |     |__dbcs_________________|     |
   |     |__figurative-constant__|     |
   |                                   |
   |___________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1.11 Nonnumeric Literals

A nonnumeric literal is a character-string enclosed in quotation marks ("), and can contain any allowable character from the character set of the computer. The maximum length of a nonnumeric literal is 160 characters.

The enclosing quotation marks are excluded from the literal when the program is compiled. An embedded quotation mark must be represented by a pair of quotation marks (""). For example, "THIS ISN""T WRONG"

x A nonnumeric literal can be enclosed in apostrophes ('). If the APOST x option is specified, these apostrophes are excluded from the literal when x the program is compiled. An embedded apostrophe must be represented by a x pair of apostrophes (''). For example, 'THIS ISN''T WRONG'

Any punctuation characters included within a nonnumeric literal are part of the value of the literal.

Every nonnumeric literal is in the alphanumeric data category. (Data categories are described in "Classes and Categories of Data" in topic 2.5.3.5.)

x Under the DBCS compiler option, the X'0E' and X'0F' in a nonnumeric x literal will be recognized as shift codes for DBCS characters. That is, x the characters between paired shift codes will be recognized as DBCS x characters. Unlike a nonnumeric literal compiled under the NODBCS option, x additional syntax rules apply to DBCS characters in a nonnumeric literal. x These nonnumeric literals with double-byte characters have the following x format:

x ___ Format for Nonnumeric Literals with Double-Byte Characters _________ | | x | "EBCDIC_data<D1D2>EBCDIC_data" | | | |________________________________________________________________________|

x " x The opening and closing delimiter (If the APOST compiler option is x specified, apostrophes (') can be used as delimiters.)

x < x Represents the shift-out control character (X'0E')

x > x Represents the shift-in control character (X'0F')

x Shift-out and shift-in control characters are part of the literal and must x be paired with zero or an even number of intervening bytes. Nested shift x codes are not allowed in the DBCS portion of the literal.

x The syntax rules for EBCDIC parts of the literal follow the rules for x nonnumeric literals. The syntax rules for DBCS parts of the literal x follow the rules for DBCS literals. The move and comparison rules for x nonnumeric literals with double-byte characters are the same as those for x any nonnumeric literal.

x The length of a nonnumeric literal with double-byte characters is its byte x length, including the shift control characters. The maximum length is x limited by the available space on one line in Area B. A nonnumeric x literal with double-byte characters cannot be continued. A nonnumeric x literal with double-byte characters is of the alphanumeric category.

x VS COBOL II statements process nonnumeric literals with double-byte x characters without sensitivity to the shift codes and character codes. x The use of statements that operate on a byte-to-byte basis (for example, x STRING and UNSTRING) may result in strings that are not valid mixtures of x EBCDIC and double-byte characters. It is the user's responsibility to be x certain that the statements are used correctly. See VS COBOL II x Application Programming Guide for MVS and CMS or VS COBOL II Application x Programming Guide for VSE for more information on using nonnumeric x literals and data items with double-byte characters in statements that x operate on a byte-by-byte basis.

x Nonnumeric literals with double-byte characters can be used wherever x nonnumeric literals are normally allowed, except:

x o As a literal in the following: x - ALPHABET clause x - ASSIGN clause x - CLASS clause x - CURRENCY SIGN clause x - CALL statement program-id x - CANCEL statement x - END PROGRAM statement x - ENTRY statement x - PADDING CHARACTER clause x - PROGRAM-ID paragraph x - RERUN clause x - STOP statement x o As the basis-name in a BASIS statement x o As the text-name in a COPY statement x o As the library-name in a COPY statement.

x Hexadecimal notation can be used for nonnumeric literals. This x hexadecimal notation has the following format:

x ___ Hexadecimal Notation Format for Nonnumeric Literals ________________ | | x | X"hexadecimal_digits" | | | |________________________________________________________________________|

x X" x The opening delimiter for hexadecimal notation of a nonnumeric literal x (If the compiler option APOST is specified, the opening delimiter is x X'.)

x " x The closing delimiter for the hexadecimal notation of a nonnumeric x literal. (If the compiler option APOST is specified, the closing x delimiter is '.)

x Hexadecimal digits can be characters in the range '0' to '9', 'a' to 'f', x and 'A' to 'F', inclusive. Two hexadecimal digits represent a single x EBCDIC character in the EBCDIC character set. An even number of x hexadecimal digits must be specified. The maximum length of a hexadecimal x literal is 320 hexadecimal digits.

x The continuation rules are the same as those for any nonnumeric literal. x The opening delimiter (X" or X') cannot be split across lines.

x The DBCS compiler option has no effect on the processing of hexadecimal x notation of nonnumeric literals.

x The compiler will convert the hexadecimal literal into a normal nonnumeric x literal. Hexadecimal notation for nonnumeric literals can be used x anywhere nonnumeric literals can appear.

x The padding character for hexadecimal notation of nonnumeric literals is x the blank (X'40').


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1.12 Numeric Literals

A numeric literal is a character-string whose characters are selected from the digits 0 through 9, a sign character (+ or -), and the decimal point. If the literal contains no decimal point, it is an integer. (In this manual, the word integer appearing in a format represents a numeric literal of nonzero value that contains no sign and no decimal point; any other restrictions are included with the description of the format.) The following rules apply:

o One through 18 digits are allowed.

o Only one sign character is allowed. If included, it must be the leftmost character of the literal. If the literal is unsigned, it is positive in value.

o Only one decimal point is allowed. If a decimal point is included, it is treated as an assumed decimal point (that is, as not taking up a character position in the literal). The decimal point can appear anywhere within the literal except as the rightmost character.

The value of a numeric literal is the algebraic quantity expressed by the characters in the literal. The size of a numeric literal in standard data format characters is equal to the number of digits specified by the user.

x Numeric literals can be either fixed-point or floating-point numbers.

x Rules for Floating-point Literal Values:

x o A floating-point literal is written in the form:

x ___ Format _________________________________________________________ x | | x | >>_________mantissa E_________exponent__>< | x | |_+_| |_+_| | x | |_-_| |_-_| | | | |____________________________________________________________________| x o The sign is optional before the mantissa and the exponent; if you x omit the sign, the compiler assumes a positive number.

x o The mantissa can contain between 1 and 16 digits. A decimal point x must be included in the mantissa.

x o The exponent is represented by an E followed by an optional sign and x one or two digits.

x o The magnitude of a floating-point literal value must fall between x 0.54E-78 and 0.72E+76. For values outside of this range, an E-level x diagnostic will be produced and the value will be replaced by either 0 x or 0.72E+76, respectively.

Every numeric literal is in the numeric data category. (Data categories are described under "Classes and Categories of Data" in topic 2.5.3.5.)


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1.13 DBCS Literals

x DBCS literals have the following format:

x ___ DBCS-Literal Format ________________________________________________ | | x | G"<D1D2D3>" | | | |________________________________________________________________________|

x G" x The opening delimiter for a DBCS literal. It must be followed x immediately by a shift-out control character. (If the compiler option x APOST is specified, the opening delimiter is G').

x < x represents the shift-out control character (X'0E')

x > x represents the shift-in control character (X'0F')

x " x The closing delimiter for a DBCS literal. The delimiter must appear x immediately after the shift-in control character. (If the compiler x option APOST is specified, the closing delimiter is '.)

x Note: Single-byte quotation marks or apostrophes can appear as part x of DBCS characters in a DBCS literal between the shift-out and x shift-in control characters.

x DBCS literals can contain double-byte characters that range from X'00' to x X'FF' for both bytes, except for X'0F7F' (or X'0F7D' if the APOST compiler x option is specified) at any position in the literal. In general, the x rules for forming a nonnumeric literal also apply to DBCS literals. The x maximum length of DBCS literals, however, is 28 double-byte characters, x and they cannot be continued across lines.

x DBCS literals can be specified in the Data Division:

x o In the VALUE clause of DBCS data description entries. If you specify x a DBCS literal in a VALUE clause for a data item, the length of the x literal must not exceed the size indicated by the data item's PICTURE x clause. Defining a DBCS data item as USAGE DISPLAY-1 specifies that x the data item is to be stored in character form, 1 character to each 2 x bytes.

x o In the VALUE OF clause of file description entries.

x DBCS literals can be specified in the Procedure Division:

x o As the sending item when a DBCS or group item is the receiving item.

x o In a relation condition when the comparand is a DBCS or group item.

x o As the figurative constants SPACE/SPACES, ALL SPACE/SPACES, or ALL x DBCS literal. These are the only figurative constants that can be x DBCS literals.

x DBCS literals can be specified wherever nonnumeric literals x are normally allowed, except:

x o As a literal in the following: x - ALPHABET clause x - ASSIGN clause x - CLASS clause x - CURRENCY SIGN clause x - CALL statement program-id x - CANCEL statement x - END PROGRAM statement x - ENTRY statement x - PADDING CHARACTER clause x - PROGRAM-ID paragraph x - RERUN clause x - STOP statement x o As the basis-name in a BASIS statement x o As the text-name in a COPY statement x o As the library-name in a COPY statement.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1.14 PICTURE Character-Strings

A PICTURE character-string is composed of the currency symbol and certain combinations of characters in the COBOL character set. PICTURE character-strings are delimited only by the separator space, separator comma, separator semicolon, or separator period.

Any punctuation character that appears as part of the specification of a PICTURE character-string is not considered as a punctuation character, but rather as a symbol used in the specification of that PICTURE character-string. (A chart of PICTURE clause symbols appears in Table 9 in topic 2.7.7.1.)


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.1.15 Comments

A comment is a character-string that can contain any combination of characters from the character set of the computer. It has no effect on the execution of the program. There are two forms of comments:

Comment entry (Identification Division)

This form is described under "Optional Paragraphs" in topic 2.2.2.

| Note: Comment entry is an obsolete element and will be deleted from | the next revision of the COBOL 85 Standard.

Comment line (Any division)

This form is described under "Comment Lines" in topic 1.3.5.2.

x Character-strings that form comments can contain either DBCS characters or x a combination of DBCS and EBCDIC characters. Multiple comment lines x containing DBCS strings are allowed. The embedding of DBCS characters in x a comment line must be done on a line-by-line basis. DBCS characters x cannot be continued to a following line. No syntax checking for valid x DBCS strings is provided in comment lines.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.2 Separators

A separator is a string of one or more punctuation characters. A separator comma is composed of a comma followed by a space; a separator period is composed of a period followed by a space; a separator semicolon is composed of a semicolon followed by a space. VS COBOL II separator characters are shown in Table 5.

| Note: The symbol indicates a space.

________________________________________________________________________ | Table 5. Separator Characters | |________________________________________________________________________| | Separator | Meaning | |_______________________|________________________________________________| | | Space | |_______________________|________________________________________________| | , | Comma | |_______________________|________________________________________________| | . | Period | |_______________________|________________________________________________| | ; | Semicolon | |_______________________|________________________________________________| | ( | Left parenthesis | |_______________________|________________________________________________| | ) | Right parenthesis | |_______________________|________________________________________________| | : | Colon | |_______________________|________________________________________________| | " | Quotation marks | |_______________________|________________________________________________| x | ' | Apostrophe | |_______________________|________________________________________________| | == | Pseudo-text delimiter | |_______________________|________________________________________________|

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.1.2.1 Rules for Separators

In the following description, brackets enclose each separator. Anywhere a space is used as a separator, or as part of a separator, more than one space can be used.

| Note: The symbol indicates a space.

| Space [] A space can immediately precede or follow any separator except:

o As specified in standard format rules (see "Reference Format" in topic 1.3).

o Within quotation marks. Spaces between quotation marks are considered part of the nonnumeric literal; they are not considered separators.

Period [.] Comma [,] Semicolon [;] The separator period must be used only to indicate the end of a sentence, or as shown in formats. The separator comma and separator semicolon can be used anywhere the separator space is used.

o In the Identification Division, separator commas and separator semicolons can be used in the comment-entries. Each paragraph must end with a separator period.

o In the Environment Division, separator commas or separator semicolons can separate clauses and operands within clauses. The SOURCE-COMPUTER, OBJECT-COMPUTER, SPECIAL-NAMES, and I-O-CONTROL paragraphs must each end with a separator period. In the FILE-CONTROL paragraph, each File-Control entry must end with a separator period.

o In the Data Division, separator commas or separator semicolons can separate clauses and operands within clauses. File (FD), Sort/Merge file (SD), and data description entries must each end with a separator period.

o In the Procedure Division, separator commas or separator semicolons can separate statements within a sentence, and operands within a statement. Each sentence and each procedure must end with a separator period.

Parentheses [ ( ] ... [ ) ] | Except in pseudo-text, parentheses can appear only in balanced pairs of left and right parentheses. They delimit subscripts, reference-modifiers, arithmetic expressions, or conditions.

Colon [ : ] The colon is a separator and is required when shown in general formats.

| Quotation marks ["] . . . ["] An opening quotation mark must be immediately preceded by a space or a left parenthesis. A closing quotation mark must be immediately followed by a separator (space, comma, semicolon, period, or right parenthesis). Quotation marks must appear as balanced pairs. They delimit nonnumeric literals, except when the literal is continued (see "Continuation Lines" in topic 1.3.4.2).

x Quotation marks are not treated as separators when the APOST compiler x option is chosen.

x Apostrophes ['] ... ['] x An opening apostrophe must be immediately preceded by a space or a x left parenthesis. A closing apostrophe must be immediately followed x by a separator (space, comma, semicolon, period, or right x parenthesis). Apostrophes must appear as balanced pairs. They x delimit nonnumeric literals, except when the literal is continued (see x "Continuation Lines" in topic 1.3.4.2).

x Apostrophes are not treated as separators when the QUOTE compiler x option is chosen.

Pseudo-text delimiters [==] . . . [==] An opening pseudo-text delimiter must be immediately preceded by a space. A closing pseudo-text delimiter must be immediately followed by a separator (space, comma, semicolon, or period). Pseudo-text delimiters must appear as balanced pairs. They delimit pseudo-text. (See "COPY Statement" in topic 4.4.)

Note: Any punctuation character included in a PICTURE character-string, a comment character-string, or a nonnumeric literal is not considered as a punctuation character, but rather as part of the character-string or literal.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.2 Sections and Paragraphs

   Sections and paragraphs define a program.  They are subdivided into 
   clauses and statements.  For more information on sections, paragraphs, and 
   statements, see "Procedures" in topic 2.8.3. 

Unless the associated rules explicitly state otherwise, each required clause or statement must be written in the sequence shown in its format. If optional clauses or statements are used, they must be written in the sequence shown in their formats. These rules are true even for clauses and statements treated as comments.

The grammatical hierarchy follows this form:

o Identification Division Paragraphs Entries Clauses

o Environment Division Sections Paragraphs Entries Clauses Phrases

o Data Division Sections Entries Clauses Phrases

o Procedure Division Sections Paragraphs Sentences Statements Phrases

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.2.1 Entries

An entry is a series of clauses ending with a separator period. Entries are constructed in the Identification, Environment, and Data Divisions.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.2.2 Clauses

A clause is an ordered set of consecutive COBOL character-strings that specifies an attribute of an entry. Clauses are constructed in the Identification, Environment, and Data Divisions.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.2.3 Sentences

A sentence is a sequence of one or more statements, ending with a separator period. Sentences are constructed in the Procedure Division.


@@ Diagram sentence ADDED at the end of this section.
@@ Implemented sentence.

    ___ sentence __________
   |                       |
   | >>__statements__.__>< |
   |                       |
   |_______________________|


@@ Diagram statements ADDED at the end of this section.
@@ Needed for sentences and IF-statements.

    ___ statements ____________________________________________
   |                                                           |
   | >>_____delimited-scope-statement_______________________>< |
   |     |                             |__statements__|  |     |
   |     |__conditional-statement________________________|     |
   |     |__unconditional-statement______________________|     |
   |                                 |__statements__|          |
   |                                                           |
   |___________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.2.4 Statements

A statement is a valid combination of a COBOL verb and its operands. It specifies an action to be taken by the object program. Statements are constructed in the Procedure Division. For descriptions of the different types of statements, see:

o "Imperative Statements" in topic 2.8.6.1 o "Conditional Statements" in topic 2.8.6.2 o "Delimited Scope Statements" in topic 2.8.6.3 o "Part 4. Compiler-Directing Statements" in topic 4.0.


@@ Diagram statement ADDED at the end of this section.
@@ Implemented statement according to given description; 2.8.6.4 omitted.

    ___ statement _______________________
   |                                     |
   | >>_____imperative-statement______>< |
   |     |__conditional-statement__|     |
   |                                     |
   |_____________________________________|


@@ Diagram imperative-statement ADDED at the end of this section.
@@ Implemented statement according to given description; 2.8.6.4 omitted.

    ___ imperative-statement ________________
   |                                         |
   | >>_____unconditional-statement_______>< |
   |     |__delimited-scope-statement__|     |
   |                                         |
   |_________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.2.5 Phrases

Each clause or statement in the program can be subdivided into smaller units called phrases.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3 Reference Format

COBOL programs must be written in the COBOL reference format. Figure 1 shows the reference format for a COBOL source line.

| | | | | | | | | | | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | ... | 71 | 72 | | | | | | | |__Sequence Number Area__| v |____Area A_______|_________Area B__________| Indicator Area

Figure 1. Reference Format for COBOL Source Line

The following areas are described below in terms of a 72-character line:

Sequence Number Area Columns 1 through 6

Indicator Area Column 7

Area A Columns 8 through 11

Area B Columns 12 through 72

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.1 Sequence Number Area

The sequence number area can be used to label a source statement line. The content of this area can consist of any character in the character set of the computer.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.2 Indicator Area

Use the indicator area to specify:

o The continuation of words or nonnumeric literals from the previous line onto the current line o The treatment of text as documentation o Debugging lines.

See "Continuation Lines" in topic 1.3.4.2, "Comment Lines" in topic 1.3.5.2, and "Debugging Lines" in topic 1.3.5.4.

| The indicator area can be used for source listing formatting. A slash | ("/") placed in the indicator column will cause the compiler to start a | new page for the source listing, and the corresponding source record to be | treated as a comment. The effect can be dependent on the LINECOUNT | compiler option. See the "LINECOUNT" compiler option in VS COBOL II | Application Programming Guide for MVS and CMS or VS COBOL II Application | Programming Guide for VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.3 Area A

The following items must begin in Area A:

o Division header o Section header o Paragraph header or paragraph name o Level indicator or level-number (01 and 77) o DECLARATIVES and END DECLARATIVES. o End program header.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.3.1 Division Header

A division header is a combination of words, followed by a separator period, that indicates the beginning of a division:

IDENTIFICATION DIVISION.

ENVIRONMENT DIVISION.

DATA DIVISION.

PROCEDURE DIVISION.

A division header (except when a USING phrase is specified with a Procedure Division header) must be immediately followed by a separator period. Except for the USING phrase, no text can appear on the same line.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.3.2 Section Header

In the Environment and Procedure Divisions, a section header indicates the beginning of a series of paragraphs; for example:

INPUT-OUTPUT SECTION.

In the Data Division, a section header indicates the beginning of an entry; for example:

FILE SECTION.

LINKAGE SECTION.

WORKING-STORAGE SECTION.

A section header must be immediately followed by a separator period.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.3.3 Paragraph Header or Paragraph Name

A paragraph header or paragraph name indicates the beginning of a paragraph.

In the Environment Division, a paragraph consists of a paragraph header followed by one or more entries. For example:

OBJECT-COMPUTER. computer-name

In the Procedure Division, a paragraph consists of a paragraph-name followed by one or more sentences.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.3.4 Level Indicator (FD and SD) or Level-Number (01 and 77)

A level indicator can be either FD or SD. It must begin in Area A and be | followed by a space. (See "File Section" in topic 2.6.1.) Level-numbers | 1, 01, and 77 must begin in Area A and must be followed by a space or | separator period.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.3.5 DECLARATIVES and END DECLARATIVES

DECLARATIVES and END DECLARATIVES are keywords that begin and end the declaratives part of the source program.

In the Procedure Division, each of the keywords DECLARATIVES and END DECLARATIVES must begin in Area A and be followed immediately by a separator period; no other text can appear on the same line. After the keywords END DECLARATIVES, no text can appear before the following section header. (See "Declaratives" in topic 2.8.2.)


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.3.6 End Program Header

The end program header is a combination of words, followed by a separator period, that indicates the end of a COBOL source program. For example:

END PROGRAM PROGRAM-NAME.

Program-name must be identical to the program-name of the corresponding PROGRAM-ID paragraph. Every COBOL program, except an outermost program that contains no nested programs and is not followed by another batch program, must end with an END PROGRAM header.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.4 Area B

The following items must begin in Area B:

o Entries, sentences, statements, clauses o Continuation lines.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.4.1 Entries, Sentences, Statements, Clauses

The first entry, sentence, statement, or clause begins on either the same line as the header or paragraph-name it follows, or in Area B of the next nonblank line that is not a comment line. Successive sentences or entries either begin in Area B of the same line as the preceding sentence or entry or in Area B of the next nonblank line that is not a comment line.

Within an entry or sentence, successive lines in Area B can have the same format, or can be indented to clarify program logic. The output listing is indented only if the input statements are indented. Indentation does not affect the meaning of the program. The programmer can choose the amount of indentation, subject only to the restrictions on the width of Area B. See also "Sections and Paragraphs" in topic 1.2.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.4.2 Continuation Lines

Any sentence, entry, clause, or phrase that requires more than one line can be continued in Area B of the next line that is neither a comment line nor a blank line. The line being continued is a continued line; the succeeding lines are continuation lines. Area A of a continuation line must be blank.

x DBCS literals cannot be continued.

x Both characters making up the opening delimiter for the hexadecimal x notation of a nonnumeric literal, X" or X' (if the compiler option APOST x is specified), must be on the same line.

If there is no hyphen (-) in the indicator area (column 7) of a line, the last character of the preceding line is assumed to be followed by a space.

If there is a hyphen in the indicator area of a line, the first nonblank character of this continuation line immediately follows the last nonblank character of the continued line without an intervening space.

If the continued line contains a nonnumeric literal without a closing quotation mark, all spaces at the end of the continued line (through column 72) are considered to be part of the literal. The continuation line must contain a hyphen in the indicator area, and the first nonblank character must be a quotation mark. The continuation of the literal begins with the character immediately following the quotation mark.

If the last character on the continued line of a nonnumeric literal is a single quotation mark in column 72, the continuation line must start with two consecutive quotation marks. This will result in a single quotation mark as part of the value of the nonnumeric literal.

x If the last character on the continued line of a nonnumeric literal is a x single quotation mark in Area B, the continuation line can start with a x single quotation mark. This will result in two consecutive nonnumeric x literals instead of one continued nonnumeric literal.

Both characters making up the pseudo-text delimiter separator "==" must be on the same line.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.5 Area A or Area B

The following items can begin in either Area A or Area B:

o Level-numbers o Comment lines o Compiler-directing statements o Debugging lines o Pseudo-text.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.5.1 Level-Numbers

| o Level-numbers 01 and 77 must begin in Area A | o Level-numbers 02-49, 66, and 88 can begin in Area A or B | o Level-numbers 01-09 can be written as a single digit.

| Level-numbers must be followed by a space or a separator period. For more | information, see "Level-Numbers" in topic 2.7.1.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.5.2 Comment Lines

A comment line is any line with an asterisk (*) or slash (/) in the indicator area (column 7) of the line. The comment can be written anywhere in Area A and Area B of that line, and can consist of any combination of characters from the character set of the computer. A comment line can be placed anywhere in the program following the Identification Division header.

x Comment lines are permitted to appear before the Identification Division, x but they must follow any control cards (for example, PROCESS or CBL).

x Note: Comments intermixed with control cards could nullify some of the x control cards and cause them to be diagnosed as errors.

Multiple comment lines are allowed. Each must begin with either an asterisk (*) or a slash (/) in the indicator area.

An asterisk (*) comment line is printed on the next available line in the | output listing. The effect may be dependent on the LINECOUNT compiler | option. See "LINECOUNT" compiler option in VS COBOL II Application | Programming Guide for MVS and CMS. A slash (/) comment line is printed on the first line of the next page, and the current page of the output listing is ejected.

The compiler treats a comment line as documentation, and does not check it syntactically.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.3.5.3 Compiler-Directing Statements:

| The compiler-directing statements COPY and REPLACE can start in either | Area A or Area B. USE must start in Area B.

x BASIS, *CBL (*CONTROL), CBL (PROCESS), DELETE, EJECT, ENTER, INSERT, READY x or RESET TRACE, SKIP1/2/3, and TITLE can also start in either Area A or x Area B.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.5.4 Debugging Lines

A debugging line is any line with a 'D' in the indicator area of the line. Debugging lines can be written in the Environment Division (after the OBJECT-COMPUTER paragraph), the Data Division, and the Procedure Division. If a debugging line contains only spaces in Area A and Area B, it is considered a blank line.

See "WITH DEBUGGING MODE" on topic 2.3.1.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.5.5 Pseudo-Text

The character-strings and separators comprising pseudo-text can start in either Area A or Area B. If, however, there is a hyphen in the indicator area (column 7) of a line which follows the opening pseudo-text delimiter, Area A of the line must be blank, and the rules for continuation lines apply to the formation of text words.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.3.5.6 Blank Lines

A blank line contains nothing but spaces from column 7 through column 72. A blank line can appear anywhere in a program.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.4 Scope of Names

| A COBOL object is any object in a COBOL program which is referenced via a | user-defined word.

| References to COBOL objects can be either explicit or implicit. This | section contains the rules for qualification and for explicit and implicit | object references.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.4.1 Types of Names

| data-name | A data-name names a data item.

| file-name | A file-name names a file connector.

| record-name | A record-name names a record.

| condition-name | A condition-name associates a value with a conditional variable.

| program-name | A program-name names a program, either external or internal (nested).

| See "Conventions for Program-Names" in topic 1.4.5.1.

| section-name | A section-name names a section in the Procedure Division.

| paragraph-name | A paragraph-name names a paragraph in the Procedure Division.

| library-name | A library-name names a COBOL library that is to be used by the | compiler for a given source program compilation.

| text-name | A text-name identifies library text.

| alphabet-name | An alphabet-name assigns a name to a specific character set and/or | collating sequence in the SPECIAL-NAMES paragraph of the Environment | Division.

| class-name | A class-name assigns a name to the proposition in the SPECIAL-NAMES | paragraph of the Environment Division for which a truth value can be | defined.

| mnemonic-name | A mnemonic-name assigns a user-defined word to an implementer-name.

| symbolic-character | A symbolic-character specifies a user-defined figurative constant.

| index-name | An index-name names an index associated with a specific table.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.4.2 Nested Programs

| A COBOL program may contain other COBOL programs. The contained (or | nested) programs may themselves contain yet other programs. A contained | program may be directly or indirectly contained within another program. | Figure 2 describes a nested program structure with directly and indirectly | contained programs.


| __________Id Division. | X is the outermost program | Program_Id. X. | and directly contains X1 and _________>| Procedure Division. | X2, and indirectly contains | Display "I'm in X" | X11 and X12 | Call "X1" | | Call "X2" | | Stop Run. | | ______Id Division. | X1 is directly contained | | Program_Id. X1. | in X and directly _________|_>| Procedure Division. | contains X11 and X12 | | Display "I'm in X1" | | | Call "X11" | | | Call "X12" | | | Exit Program. | | | ___Id Division. | X11 is directly | | | Program_Id. X11. | contained in X1 ________|__|_>| Procedure Division. | and indirectly | | | Display "I'm in X11" | contained in X | | | Exit Program. | | | |___End Program X11. | | | ___Id Division. | X12 is directly | | | Program_Id. X12. | contained in X1 ________|__|_>| Procedure Division. | and indirectly | | | Display "I'm in X12" | contained in X | | | Exit Program. | | | |___End Program X12. | | |______End Program X1. | | ______Id Division. | | | Program_Id. X2. | X2 is directly ___________________|_>| Procedure Division. | contained in X | | Display "I'm in X2" | | | Exit Program. | | |______End Program X2. | |_________End Program X.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document. | Figure 2. Nested program structure with directly and indirectly contained | programs

| For more information on nested programs, see "COBOL Source Program" in | topic 2.1, VS COBOL II Application Programming Guide for MVS and CMS, or | VS COBOL II Application Programming Guide for VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.4.3 Global and Local Names

| Names can have global or local attributes. Some names are always global; | other names are always local; and some other names are either local or | global depending upon specifications in the program in which the names are | declared.

| A program cannot reference any condition-name, data-name, file-name, or | record-name declared in any program it contains.

| A global name may be used to refer to the object with which it is | associated either from within the program in which the global name is | declared or from within any other program which is contained in the | program which declares the global name.

| A local name, however, may be used only to refer to the object with which | it is associated from within the program in which the local name is | declared.

| If a data-name, a file-name, record-name or a condition-name declared in a | data description entry is not global, the name is local.

| Note: Specific rules sometimes prohibit specification of the GLOBAL | clause for certain data description, file description, or record | description entries.

| data-name | A data-name is global if the GLOBAL clause is specified either in the | data description entry by which the data-name is declared or in | another entry to which that data description entry is subordinate.

| file-name | A file-name is global if the GLOBAL clause is specified in the file | description entry for that file-name.

| record-name | A record-name is global if the GLOBAL clause is specified in the | record description entry by which the record-name is declared or, in | the case of record description entries in the File Section, if the | GLOBAL clause is specified in the file description entry for the | file-name associated with the record description entry.

| condition-name | A condition-name, when declared in a data description entry, is global | if that entry is subordinate to another entry in which the GLOBAL | clause is specified.

| A condition-name, when declared within the Configuration Section, is | always global.

| program-name | A program-name is neither local nor global. See "Conventions for | Program-Names" in topic 1.4.5.1.

| section-name and paragraph-name | These names are always local.

| library-name and text-name | These names are external to the program and can be referenced by any | COBOL program, provided that the compiler system supports the | associated library and the entities referenced are known to that | system.

| alphabet-name | An alphabet-name is always global.

| class-name | A class-name is always global.

| mnemonic-name | A mnemonic-name is always global.

| symbolic-character | A symbolic-character is always global.

| index-name | If a data item possessing the global attribute includes a table | accessed with an index, that index also possesses the global | attribute. Therefore, the scope of an index-name is identical to that | of the data-name which names the table whose index is named by that | index-name and the scope of name rules for data-names apply. | Index-names cannot be qualified.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.4.4 External and Internal Objects

| Accessible data items usually require that certain representations of data | be stored. File connectors usually require that certain information | concerning files be stored. The storage associated with a data item or a | file connector may be external or internal to the program in which the | object is declared.

| A data item or file connector is external if the storage associated with | that object is associated with the run unit rather than with any | particular program within the run unit. An external object may be | referenced by any program in the run unit which describes the object. | References to an external object from different programs using separate | descriptions of the object are always to the same object. In a run unit, | there is only one representative of an external object.

| An object is internal if the storage associated with that object is | associated only with the program which describes the object.

| External and internal objects may have either global or local names.

| A data record described in the Working-Storage Section is given the | external attribute by the presence of the EXTERNAL clause in its data | description entry. Any data item described by a data description entry | subordinate to an entry describing an external record also attains the | external attribute. If a record or data item does not have the external | attribute, it is part of the internal data of the program in which it is | described.

| A file connector is given the external attribute by the presence of the | EXTERNAL clause in the associated file description entry. If the file | connector does not have the external attribute, it is internal to the | program in which the associated file-name is described.

| Two programs can reference the same file connector in the following | circumstances:

| 1. An external file connector can be referenced from any program that | describes that file connector.

| 2. If a program is contained within another program, both programs can | refer to a global file connector by referring to an associated global | file-name either in the containing program, or in any program that | directly or indirectly contains the containing program.

| Two programs in a run unit can reference common data in the following | circumstances:

| 1. The data content of an external data record can be referenced from any | program provided that program has described that data record.

| 2. If a program is contained within another program, both programs can | refer to data possessing the global attribute either in the containing | program, or in any program that directly or indirectly contains the | containing program.

| The data records described subordinate to a file description entry which | does not contain the EXTERNAL clause or a sort-merge file description | entry, as well as any data items described subordinate to the data | description entries for such records, are always internal to the program | describing the file-name. If the EXTERNAL clause is included in the file | description entry, the data records and the data items attain the external | attribute.

| Data records and subordinate data items described in the Linkage Section | of a program are always considered to be internal to the program | describing that data. Special considerations apply to data described in | the Linkage Section whereby an association is made between the data | records described and other data items accessible to other programs.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.4.5 Resolution of Names

| When a program, program B, is directly contained within another program, | program A, both programs may define a condition-name, a data-name, a | file-name, or a record-name using the same user-defined word. When such a | duplicated name is referenced in program B, the following rules are used | to determine the referenced object.

| o The referenced object is identified from the following set of names:

| - all names defined in program B | - all global names defined in program A | - all global names defined in any programs that directly or | indirectly contain program A.

| Using this set of names, the normal rules for qualification and any | other rules for uniqueness of reference are applied until one or more | objects is identified.

| o If only one object is identified, it is the referenced object.

| o If more than one object is identified, no more than one of them can | have a name local to program B. If zero or one of the objects has a | name local to program B, the following rules apply:

| - If the name is declared in program B, the object in program B is | the referenced object.

| - Otherwise, if program A is contained within another program, the | referenced object is:

| - The object in program A if the name is declared with the | GLOBAL attribute in program A.

| - The object in the containing program if the name is not | declared in program A and is declared with the GLOBAL | attribute in the program containing program A. This rule is | applied to further containing programs until a single valid | object has been found.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.4.5.1 Conventions for Program-Names

| The program-name of a program is specified in the PROGRAM-ID paragraph of | the program's Identification Division. A program-name can be referenced | only by the CALL statement, the CANCEL statement, or the END PROGRAM | header. Names of programs constituting a run unit are not necessarily | unique, but when two programs in a run unit are identically named, at | least one of those two programs must be directly or indirectly contained | within another separately compiled program which does not contain the | other of those two programs.

| A separately compiled program and all its contained programs must have | unique program-names.

| The following rules regulate the scope of a program-name.

| o If the program-name is that of a program which does not possess the | COMMON attribute and which is directly contained within another | program, that program-name can be referenced only by statements | included in that containing program.

| o If the program-name is that of a program which does possess the COMMON | attribute and which is directly contained within another program, that | program-name can be referenced only by statements included in that | containing program and any programs directly or indirectly contained | within that containing program, except that program possessing the | COMMON attribute and any programs contained within it.

| o If the program-name is that of a program which is separately compiled, | that program-name can be referenced by statements included in any | other program in the run unit, except programs it directly or | indirectly contains.

| The mechanism used to determine which program to call is as follows:

| - If one of the two programs having the same name as that specified | in the CALL statement is directly contained within the program | which includes the CALL statement, that program is called.

| - If one of the two programs having the same name as that specified | in the CALL statement possesses the COMMON attribute and is | directly contained within another program which directly or | indirectly contains the program which includes the CALL statement, | that common program is called unless the calling program is | contained within that common program.

| - Otherwise, the separately compiled program is called.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.4.5.1.1 Rules Regulating the Scope of Program-Names

| The following rules apply to referencing a program-name of a program that | is contained within another program. For this discussion, we will say | that Program-A contains Program-B and Program-C, Program-C contains | Program-D and Program-F, and Program-D contains Program-E.

| ________________________________________ | | Program-A | | | _________________________________ | | | | Program-B | | | | | | | | | | | | | | | | | | | |_________________________________| | | | | | | | | | _________________________________ | | | | Program-C | | | | | __________________________ | | | | | | Program-D | | | | | | | | | | | | | | _____________________ | | | | | | | | Program-E | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |_____________________| | | | | | | |__________________________| | | | | | __________________________ | | | | | | Program-F | | | | | | | | | | | | | |__________________________| | | | | |_________________________________| | | |________________________________________|

| If Program-D does not possess the COMMON attribute, then Program-D can | only be referenced by the program that directly contains Program-D, that | is, Program-C.

| If Program-D does possess the COMMON attribute, then Program-D can be | referenced by Program-C since it contains Program-D and by any programs | contained in Program-C except for programs contained in Program-D. In | other words, if Program-D possesses the COMMON attribute, Program-D can be | referenced in Program-C and Program-F but not by statements in Program-E, | Program-A or Program-B.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5 Methods of Data Reference

| References to data and procedures can be either explicit or implicit. | This section contains the rules for qualification and for explicit and | implicit data references.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5.1 Uniqueness of Reference

| Every user-defined name in a COBOL program is assigned, by the user, to | name a resource which is to be used in solving a data processing problem. | In order to use a resource, a statement in a COBOL program must contain a | reference which uniquely identifies that resource. In order to ensure | uniqueness of reference, a user-defined name can be qualified, | subscripted, or reference modified as described in the following | paragraphs.

| See "User-Defined Words" in topic 1.1.1.2.

| When the same name has been assigned in separate programs to two or more | occurrences of a resource, and when qualification by itself does not allow | the references in one of those programs to differentiate between the two | identically named resources, then certain conventions which limit the | scope of names apply. These conventions ensure that the resource | identified is that described in the program containing the reference. For | more information, see "Resolution of Names" in topic 1.4.5.

| Unless otherwise specified by the rules for a statement, any subscripting | and reference modification are evaluated only once as the first step in | executing that statement.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5.1.1 Qualification

| A name can be made unique if it exists within a hierarchy of names by | specifying one or more higher-level names in the hierarchy. The | higher-level names are called qualifiers, and the process of using such | names to make a unique reference is called qualification.

| Qualification is specified by placing one or more phrases after a | user-specified name, with each phrase made up of the word IN or OF | followed by a qualifier. (IN and OF are logically equivalent.)

| In any hierarchy, the data-name associated with the highest level must be | unique if it is referenced, and cannot be qualified.

| You must specify enough qualification to make the name unique; however, it | is not always necessary to specify all the levels of the hierarchy. For | example, if there is more than one file whose records contain the field | EMPLOYEE-NO, but only one of the files has a record named MASTER-RECORD, | then:

| o EMPLOYEE-NO OF MASTER-RECORD sufficiently qualifies EMPLOYEE-NO | o EMPLOYEE-NO OF MASTER-RECORD OF MASTER-FILE is valid but unnecessary.

| The rules for qualifying a name are:

| o A name can be qualified even though it does not need qualification, | except in a REDEFINES clause, in which case it must not be qualified.

| o Each qualifier must be of a higher level than the name it qualifies, | and must be within the same hierarchy.

| o If there is more than one combination of qualifiers that ensures | uniqueness, then any of these combinations can be used.

| If explicitly referenced, a condition-name must be unique or be made | unique through qualification and/or subscripting except when the scope of | names conventions by themselves ensure uniqueness of reference. See | "Scope of Names" in topic 1.4.

| If qualification is used to make a condition-name unique, the associated | conditional variable can be used as the first qualifier. If qualification | is used, the hierarchy of names associated with the conditional variable | itself must be used to make the condition-name unique.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5.1.1.1 References to COPY Libraries

___ reference-to-copy-library _______________________ | | | >>__text-name-1__________________________________>< | | |_____IN_____library-name-1__| | | |__OF__| | | | |_____________________________________________________| | If more than one COBOL library is available to the compiler during | compilation, text-name-1 must be qualified each time it is referenced.

| For rules on referencing COPY libraries, see "COPY Statement" in | topic 4.4.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5.1.1.2 References to Data Division Names

| Data Division names that are explicitly referenced must be either uniquely | defined or made unique through qualification. Unreferenced data items | need not be uniquely defined. The highest level in a data hierarchy must | be uniquely named, if referenced. This is a data item associated with a | level indicator (FD or SD in the File Section) or with a level-number 01. | Data items associated with level-numbers 02 through 49 are successively | lower levels of the hierarchy.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5.1.1.3 References to Procedure Division Names

___ reference-to-procedure-division-name-format-i ________ | | | >>__paragraph-name-1__________________________________>< | | |_____IN_____section-name-1__| | | |__OF__| | | | |__________________________________________________________| ___ reference-to-procedure-division-name-format-ii ___ | | | >>__section-name-1________________________________>< | | | |______________________________________________________| | A section-name, described on topic 2.8.3, is the highest and only | qualifier available for a paragraph-name and must be unique if referenced.

| If explicitly referenced, a paragraph-name must not be duplicated within a | section. When a paragraph-name is qualified by a section-name, the word | SECTION must not appear. A paragraph-name need not be qualified when | referred to within the section in which it appears. A paragraph-name or | section-name appearing in a program cannot be referenced from any other | program.


@@ Diagram procedure-name ADDED at the end of this section.
@@ Names as used in GO TOs and PERFORMS.

    ___ procedure-name ___________________________________________
   |                                                              |
   | >>_____reference-to-procedure-division-name-format-i______>< |
   |     |__reference-to-procedure-division-name-format-ii__|     |
   |                                                              |
   |______________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5.1.1.4 Simple Data Reference

| The most basic method of referencing data items in a COBOL program is | simple data reference, which is data-name-1 without qualification, | subscripting, or reference modification. Simple data reference is used to | reference a single elementary or group item.

___ simple-data-reference ___ | | | >>__data-name-1__________>< | | | |_____________________________| | data-name-1 | Can be any data description entry.

| Data-name-1 must be unique in a program.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5.1.2 Identifier

| In the syntax diagrams, the term identifier refers to a data-name that, if | not unique in a program, must be followed by a valid combination of | qualifiers, subscripts, or reference modifiers necessary for uniqueness of | reference. Rules for identifiers associated with a format can, however, | specifically prohibit qualification, subscripting, or | reference-modification.

| The term data-name refers to a name that must not be qualified, | subscripted, or reference modified, unless specifically permitted by the | rules for the format.

| o For a description of qualification, see "Qualification" in | topic 1.5.1.1. | o For a description of subscripting, see "Subscripting" in | topic 1.5.1.4. | o For a description of reference modification, see "Reference | Modification" in topic 1.5.1.5.

@@ Diagram identifier ADDED before diagram identifier-format-i. @@ Combined below formats and addendum in 1.1.1.9. ___ identifier _____________________ | | | >>_____identifier-format-i______>< | | |__identifier-format-ii__| | | |__special-register______| | | | |____________________________________| @@ Diagram identifier-format-i ADAPTED. @@ Moved iteration inside parentheses as in subscripting diagram. ___ identifier-format-i __________________________________________ | | | >>_____________________________________________________________> | | | | >___qualified-data-name________________________________________> | | | <____________ | | | |__(____subscript__|__)__| | | | | >_____________________________________________________________>< | | |__(__leftmost-character-position__:________________)__| | | |__length__| | | | |__________________________________________________________________| @@ Diagram qualified-data-name EXTRACTED from diagram identifier-format-i. @@ Made explicit qualified data names as part of identifiers. ___ qualified-data-name ____________________________________________________________ | | | >>__data-name-1_________________________________________________________________>< | | | <________________________ | |_____IN_____file-name-1__| | | |_______IN_____data-name-2__|__| |__OF__| | | |__OF__| | | | |____________________________________________________________________________________| | data-name-1, data-name-2 | Can be a record-name.

| file-name-1 | Must be identified by an FD or SD entry in the Data Division.

| File-name-1 must be unique within this program.

| The following rules apply:

| o Duplication of referenced data-names must not occur in those places | where the data-name cannot be made unique by qualification.

| In the same program, the data-name specified as the subject of the | entry whose level-number is 01 that includes the EXTERNAL clause must | not be the same data-name specified for any other data description | entry which includes the EXTERNAL clause.

| In the same Data Division, the data description entries for any two | data items for which the same data-name is specified must not include | the GLOBAL clause.

___ identifier-format-ii ____________________________ | | | >>__LINAGE-COUNTER_______________________________>< | | |_____IN_____file-name-2__| | | |__OF__| | | | |_____________________________________________________| | LINAGE-COUNTER | Must be qualified each time it is referenced if more than one file | description entry containing a LINAGE clause has been specified in the | source program.

| file-name-2 | Must be identified by an FD or SD entry in the Data Division.

| File-name-2 must be unique within this program.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5.1.3 condition-name

___ condition-name-in-data-division _____________________________ | | | >>__condition-name-1__________________________________________> | | | <________________________ | | | |_______IN_____data-name-1__|__| | | |__OF__| | | | | >____________________________________________________________>< | | |_____IN_____file-name-1__| | <__________________ | | | |__OF__| |____(__subscript__)__|__| | | | |_________________________________________________________________| ___ condition-name-in-special-names-paragraph __________________ | | | >>__condition-name-1________________________________________>< | | | <____________________________ | | | |_______IN_____mnemonic-name-1__|__| | | |__OF__| | | | |________________________________________________________________| | condition-name-1 | Can be referenced by statements and entries either in the program | containing the definition of condition-name-1, or in a program | contained within that program.

| If explicitly referenced, a condition-name must be unique or be made | unique through qualification and/or subscripting except when the scope | of names conventions by themselves ensure uniqueness of reference.

| If qualification is used to make a condition-name unique, the | associated conditional variable may be used as the first qualifier. | If qualification is used, the hierarchy of names associated with the | conditional variable itself must be used to make the condition-name | unique.

| If references to a conditional variable require subscripting, | reference to any of its condition-names also requires the same | combination of subscripting.

| In the general format of the chapters that follow, "condition-name" | refers to a condition-name qualified or subscripted, as necessary.

| data-name-1 | Can be a record-name.

| file-name-1 | Must be identified by an FD or SD entry in the Data Division.

| File-name-1 must be unique within this program.

| mnemonic-name-1 | For information on acceptable values for mnemonic-name-1, see topic | 2.3.3.


@@ Diagram condition-name-reference ADDED at the end of this section.
@@ Joined different formats for condition-name-references.

    ___ condition-name-reference ____________________________
   |                                                         |
   | >>_____condition-name-in-data-division_______________>< |
   |     |__condition-name-in-special-names-paragraph__|     |
   |                                                         |
   |_________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5.1.4 Subscripting

| Subscripting is a method of providing table references through the use of | subscripts. A subscript is a positive integer whose value specifies the | occurrence number of a table element.

___ subscripting _______________ | | | >>_____condition-name-1______> | | |__data-name-1_______| | | | | <____________ | | >___(____subscript__|__)____>< | | | |________________________________| @@ Diagram subscript EXTRACTED from diagram subscripting. @@ Identified phrase as referred to elsewhere. @@ Diagram subscript ADAPTED. @@ Enabled identifiers instead of plain data names. ___ subscript ________________________________________ | | | >>_____integer-1__________________________________>< | | |__identifier-2____________________________| | | | |_____+_____integer-2__| | | | | |__-__| | | | |__index-name-1____________________________| | | |_____+_____integer-3__| | | |__-__| | | | |______________________________________________________| | condition-name-1 | The conditional variable for condition-name-1 must contain an OCCURS | clause or must be subordinate to a data description entry which | contains an OCCURS clause.

| data-name-1 | Must contain an OCCURS clause or must be subordinate to a data | description entry which contains an OCCURS clause.

| integer-1 | Can be signed. If signed, it must be positive.

| data-name-2 | Must be a numeric elementary item representing an integer.

| Data-name-2 can be qualified.

| index-name-1 | Corresponds to a data description entry in the hierarchy of the table | being referenced which contains an INDEXED BY phrase specifying that | name.

| integer-2, integer-3 | Cannot be signed.

| The subscripts, enclosed in parentheses, are written immediately following | any qualification for the name of the table element. The number of | subscripts in such a reference must equal the number of dimensions in the | table whose element is being referenced. That is, there must be a | subscript for each OCCURS clause in the hierarchy containing the data-name | including the data-name itself.

| When more than one subscript is required, they are written in the order of | successively less inclusive dimensions of the data organization. If a | multi-dimensional table is thought of as a series of nested tables and the | most inclusive or outermost table in the nest is considered to be the | major table with the innermost or least inclusive table being the minor | table, the subscripts are written from left to right in the order major, | intermediate, and minor.

| For example, if TABLE-THREE is defined as:

| 01 TABLE-THREE. | 05 ELEMENT-ONE OCCURS 3 TIMES. | 10 ELEMENT-TWO OCCURS 3 TIMES. | 15 ELEMENT-THREE OCCURS 2 TIMES PIC X(8).

| a valid subscripted reference to TABLE-THREE is:

| ELEMENT-THREE (2 2 1)

| Subscripted references may also be reference modified. See the third | example on topic 1.5.1.5.2.

| A reference to an item must not be subscripted unless the item is a table | element or an item or condition-name associated with a table element.

| Each table element reference must be subscripted except when such | reference appears:

| o In a USE FOR DEBUGGING statement

| o As the subject of a SEARCH statement

| o In a REDEFINES clause

| o In the KEY is phrase of an OCCURS clause.

| The lowest permissible occurrence number represented by a subscript is 1. | The highest permissible occurrence number in any particular case is the | maximum number of occurrences of the item as specified in the OCCURS | clause.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5.1.4.1 Subscripting Using Data-Names

| When a data-name is used to represent a subscript, it can be used to | reference items within different tables. These tables need not have | elements of the same size. The same data-name can appear as the only | subscript with one item and as one of two or more subscripts with another | item. A data-name subscript can be qualified; it cannot be subscripted or | indexed. For example, valid subscripted references to TABLE-THREE -- | assuming that SUB1, SUB2, and SUB3 are all items subordinate to | SUBSCRIPT-ITEM -- include:

| ELEMENT-THREE (SUB1 SUB2 SUB3)

| ELEMENT-THREE IN TABLE-THREE (SUB1 OF SUBSCRIPT-ITEM, | SUB2 OF SUBSCRIPT-ITEM, SUB3 OF SUBSCRIPT-ITEM)


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5.1.4.2 Subscripting Using Index-Names (Indexing)

| Indexing allows such operations as table searching and manipulating | specific items. To use indexing you associate one or more index-names | with an item whose data description entry contains an OCCURS clause. An | index associated with an index-name acts as a subscript, and its value | corresponds to an occurrence number for the item to which the index-name | is associated.

| The INDEXED BY phrase, by which the index-name is identified and | associated with its table, is an optional part of the OCCURS clause. | There is no separate entry to describe the index associated with | index-name. At object time, the contents of the index corresponds to an | occurrence number for that specific dimension of the table with which the | index is associated.

| The initial value of an index at object time is undefined, and the index | must be initialized before it is used as a subscript. An initial value is | assigned to an index with one of the following:

| o the PERFORM statement with the VARYING phrase | o the SEARCH statement with the ALL phrase | o the SET statement.

| The use of an integer or data-name as a subscript referencing a table | element or an item within a table element does not cause the alteration of | any index associated with that table.

| An index-name can be used to reference only the table to which it is | associated by the INDEXED BY phrase.

| Data that is arranged in the form of a table is often searched. The | SEARCH statement provides facilities for producing serial and non-serial | searches. It is used to search for a table element that satisfies a | specific condition and to adjust the value of the associated index to | indicate that table element.

| To be valid during execution, an index value must correspond to a table | element occurrence of neither less than one, nor greater than the highest | permissible occurrence number.

| Further information on index-names is given in the description of the | INDEXED BY phrase of the OCCURS clause, on topic 2.7.6.1.2.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5.1.4.3 Relative Subscripting

| In relative subscripting, the name of a table element is followed by a | subscript of the form data-name or index-name followed by the operator + | or -, and an unsigned integer literal. The operator + and - must be | preceded and followed by a space. The value of the subscript used is the | same as if the index-name or data-name had been set up or down by the | value of the integer. The use of relative indexing does not cause the | object program to alter the value of the index.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5.1.5 Reference Modification

| Reference modification defines a data item by specifying a leftmost | character and optional length for the data item.

___ reference-modification ___________________________________________ | | | >>__data-name-1__(__leftmost-character-position__:_________________> | | |__length__| | | | | >___)_____________________________________________________________>< | | | |______________________________________________________________________| | data-name-1 | Must reference a data item whose usage is DISPLAY.

| Data-name-1 can be qualified or subscripted.

| leftmost-character-position | Must be an arithmetic expression. The evaluation of | leftmost-character-position must result in a positive nonzero integer | that is less than or equal to the number of characters in the data | item referenced by data-name-1.

| length | Must be an arithmetic expression.

| The sum of leftmost-character-position and length minus the value one | must be less than or equal to the number of characters in data-name-1. | If length is omitted, than the length used will be equal to the number | of characters in data-name-1 plus one minus | leftmost-character-position. The evaluation of length must result in | a positive nonzero integer.

| Unless otherwise specified, reference modification is allowed anywhere an | identifier referencing an alphanumeric data item is permitted.

| Each character of a data item referenced by data-name-1 is assigned an | ordinal number incrementing by one from the leftmost position to the | rightmost position. The leftmost position is assigned the ordinal number | one. If the data description entry for data-name-1 contains a SIGN IS | SEPARATE clause, the sign position is assigned an ordinal number within | that data item.

| If the data item referenced by data-name-1 is described as numeric, | numeric-edited, alphabetic, or alphanumeric-edited, it is operated upon | for purposes of reference modification as if it were redefined as an | alphanumeric data item of the same size as the data item referenced by | data-name-1.

| Reference modification creates a unique data item which is a subset of the | data item referenced by data-name-1. This unique data item is considered | an elementary data item without the JUSTIFIED clause.

| When data-name-1 is reference-modified, the unique data item has the same | class and category as that defined for the data item referenced by | data-name-1; however, if the category of data-name-1 is numeric, | numeric-edited, or alphanumeric-edited, the unique data item has the class | and category alphanumeric.

| If length is not specified, the unique data item created extends from and | includes the character identified by leftmost-character-position up to and | including the rightmost character of the data item referenced by | data-name-1.

Subtopics:


@@ Diagram leftmost-character-position ADDED at the end of this section.
@@ Implemented as required in the text.

    ___ leftmost-character-position ___
   |                                   |
   | >>__arithmetic-expression______>< |
   |                                   |
   |___________________________________|


@@ Diagram length ADDED at the end of this section.
@@ Implemented as required in the text.

    ___ length ____________________
   |                               |
   | >>__arithmetic-expression__>< |
   |                               |
   |_______________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5.1.5.1 Evaluation of Operands

| Reference modification for an operand is evaluated as follows:

| o If subscripting is specified for the operand, the reference | modification is evaluated immediately after evaluation of the | subscript.

| o If subscripting is not specified for the operand, the reference | modification is evaluated at the time subscripting would be evaluated | if subscripts had been specified.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 1.5.1.5.2 Reference Modification Examples

| The following statement transfers the first 10 characters of the data-item | referenced by WHOLE-NAME to the data-item referenced by FIRST-NAME.

| 77 WHOLE-NAME PIC X(25). | 77 FIRST-NAME PIC X(10). | .......

| MOVE WHOLE-NAME(1:10) TO FIRST-NAME.

| The following statement transfers the last 15 characters of the data-item | referenced by WHOLE-NAME to the data-item referenced by LAST-NAME.

| 77 WHOLE-NAME PIC X(25). | 77 LAST-NAME PIC X(15). | .......

| MOVE WHOLE-NAME(11:) TO LAST-NAME.

| The following statement transfers the 4th and 5th characters of the 3rd | occurrence of TAB to the variable SUFFIX.

| 01 TABLE-1. | 02 TAB OCCURS 10 TIMES PICTURE X(5). | 77 SUFFIX PICTURE X(2). | .......

| MOVE TAB OF TABLE-1 (3) (4:2) TO SUFFIX.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

1.6 Transfer of Control

In the Procedure Division, unless there is an explicit control transfer or there is no next executable statement, program flow transfers control from statement to statement in the order in which the statements are written. (See Note below.) This normal program flow is an implicit transfer of control.

In addition to the implicit transfers of control between consecutive statements, implicit transfer of control also occurs when the normal flow is altered without the execution of a procedure branching statement. The following examples show implicit transfers of control, overriding statement-to-statement transfer of control:

o After execution of the last statement of a procedure being executed under control of another COBOL statement, control implicitly transfers. (COBOL statements that control procedure execution are, for example: MERGE, PERFORM, SORT, and USE.) Further, if a paragraph is being executed under the control of a PERFORM statement which causes iterative execution, and that paragraph is the first paragraph in the range of that PERFORM statement, an implicit transfer of control occurs between the control mechanism associated with that PERFORM statement and the first statement in that paragraph for each iterative execution of the paragraph.

o During SORT or MERGE statement execution, control is implicitly transferred to an input or output procedure.

o During execution of any COBOL statement that causes execution of a declarative procedure, control is implicitly transferred to that procedure.

o At the end of execution of any declarative procedure, control is implicitly transferred back to the control mechanism associated with the statement that caused its execution.

COBOL also provides explicit control transfers through the execution of any procedure branching, program call, or conditional statement. (Lists of procedure branching and conditional statements are contained in "Procedure Division" in topic 2.8.)

Note: The term "next executable statement" refers to the next COBOL statement to which control is transferred, according to the rules given above. There is no next executable statement under these circumstances:

o When the program contains no Procedure Division

o Following the last statement in a declarative section when the paragraph in which it appears is not being executed under the control of some other COBOL statement

o Following the last statement in a program when the paragraph in which it appears is not being executed under the control of some other COBOL statement in that program

o Following the last statement in a declarative section when the statement is in the range of an active PERFORM statement executed in a different section and this last statement of the declarative section is not also the last statement of the procedure that is the exit of the active PERFORM statement

x o Following a STOP RUN statement, EXIT PROGRAM statement or GOBACK statement that transfers control outside the COBOL program

o The end program header.

When there is no next executable statement and control is not transferred outside the COBOL program, the program flow of control is undefined unless the program execution is in the nondeclarative procedures portion of a program under control of a CALL statement, in which case an implicit EXIT PROGRAM statement is executed.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.0 Part 2. COBOL Program Structure

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.1 COBOL Source Program

 | A COBOL source program is a valid set of COBOL statements. 

| Nested Programs: A nested program is a program that is contained in | another program. These contained programs can reference some of the | resources of the programs that contain them. If program B is contained in | program A, it is directly contained if there is no program contained in | program A that also contains program B. Program B is indirectly contained | in program A if there exists a program contained in program A that also | contains program B. For more information on nested programs, see "Nested | Programs" in topic 1.4.2, VS COBOL II Application Programming Guide for | MVS and CMS, or VS COBOL II Application Programming Guide for VSE.

| Object Program: A set or group of executable machine language | instructions and other material designed to interact with data to provide | problem solutions. An object program is generally the machine language | result of the operation of a COBOL compiler on a source program.

| Run Unit: One or more object programs which interact with one another and | which function at object time as an entity to provide problem solutions.

| Sibling Program: Programs that are directly contained by the same program | are called sibling programs.

With the exception of the COPY and REPLACE statements and the end program header, the statements, entries, paragraphs, and sections of a COBOL source program are grouped into the following four divisions:

o Identification Division o Environment Division o Data Division o Procedure Division.

The end of a COBOL source program is indicated by either the end program header, if specified, or by the absence of additional source program lines.

Following is the format for the entries and statements that constitute a separately-compiled COBOL source program.

@@ Diagram cobol-source-program ADAPTED. @@ Implemented footnote on optional periods. @@ Diagram cobol-source-program ADAPTED. @@ Enable Cobol subprograms ___ cobol-source-program _____________________________________________________________ | | | >>_____IDENTIFICATION_____DIVISION__.__PROGRAM-ID___________@1__program-name-1_____> | | |__{__ID__}________| |__.__| | | | | >____________________________________________________@1____________________________> | | |____________INITIAL_________________| |__.__| | | |__IS__| |__PROGRAM__| | | | | >__________________________________________________________________________________> | | |__identification-division-content__| | | | | >__________________________________________________________________________________> | | |__ENVIRONMENT__DIVISION__.__environment-division-content__| | | | | >__________________________________________________________________________________> | | |__DATA__DIVISION__.__data-division-content__| | | | | >__________________________________________________________________________________> | | |__PROCEDURE__DIVISION______________________.__procedure-division-content__| | | |__using-phrase__| | | | | >_________________________________________________________________________________>< | | |____________________________________END__PROGRAM__program-name-1__.__| | | | <________________________ | | | |____nested-source-program__|__| | | | |______________________________________________________________________________________| @@ Diagram nested-source-program ADAPTED. @@ Implemented footnote on optional periods. @@ Diagram nested-source-program ADAPTED. @@ Enable Cobol subprograms ___ nested-source-program ____________________________________________________________ | | | >>_____IDENTIFICATION_____DIVISION__.__PROGRAM-ID___________@1__program-name-2_____> | | |__{__ID__}________| |__.__| | | | | >________________________________________________________________________@1________> | | |_______________COMMON___________________________________| |__.__| | | |__IS__| | |__INITIAL__| | |__PROGRAM__| | | |__INITIAL________________| | | |__COMMON__| | | | | >__________________________________________________________________________________> | | |__identification-division-content__| | | | | >__________________________________________________________________________________> | | |__ENVIRONMENT__DIVISION__.__environment-division-content__| | | | | >__________________________________________________________________________________> | | |__DATA__DIVISION__.__data-division-content__| | | | | >__________________________________________________________________________________> | | |__PROCEDURE__DIVISION______________________.__procedure-division-content__| | | |__using-phrase__| | | | | >_____________________________________END__PROGRAM__program-name-2__._____________>< | | | <________________________ | | | |____nested-source-program__|__| | | | |______________________________________________________________________________________| ______________________________________________________________________________ | | | Note: | x | (1) This separator period is optional as an IBM extension. | | | |______________________________________________________________________________|

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.1.1 Sequence of COBOL Source Programs

A sequence of separate COBOL programs can also be input to the compiler. Following is the format for the entries and statements that constitute a sequence of source programs (batch compile).

___ sequence-of-cobol-source-programs ___ | | | <_______________________ | | >>____COBOL-source-program__|________>< | | | |_________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.1.2 END PROGRAM program-name

| An END PROGRAM header terminates a nested program or separates one program | from another in a sequence of programs. The program-name must conform to the rules for forming a user-defined word, and must be identical to the | program-name declared in the corresponding PROGRAM-ID paragraph. For more information on program-name, see "PROGRAM-ID Paragraph" in topic 2.2.1.

| Each program in a sequence must be terminated by an END PROGRAM header, | except the last program in the batch (for which the END PROGRAM header is | optional). An END PROGRAM header is optional for the last program in a sequence only if that program does not contain any nested source programs.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.2 Identification Division

The Identification Division must be the first division in every COBOL source program. It names the program and can include the date the program was written, the date of compilation, and other such documentary information about the program.

@@ Diagram identification-division ADAPTED. @@ Made "." optional for DATE-COMPILED as well. @@ Diagram identification-division ADAPTED. @@ Implemented footnote on optional periods. ___ identification-division ______________________________________________________ | | | >>_____IDENTIFICATION_____DIVISION__.__PROGRAM-ID___________@1__program-name___> | | |__{__ID__}________| |__.__| | | | | >________________________________________________________________________@1____> | | |_______________COMMON___________________________________| |__.__| | | |__IS__| | |__INITIAL__| | |__PROGRAM__| | | |__INITIAL________________| | | |__COMMON__| | | | | >___identification-division-content___________________________________________>< | | | |__________________________________________________________________________________| @@ Diagram identification-division-content EXTRACTED from diagram identification-division. @@ Identified content of the division as referred to elsewhere. @@ Diagram identification-division-content ADAPTED. @@ Added obsolete remarks paragraph. @@ Diagram identification-division-content ADAPTED. @@ Implemented note on optional paragraphs. ___ identification-division-content ________________________________ | | | ||______________________________________________________________|| | | |__AUTHOR___________@1____________________________| | | |__.__| | <________________ | | | |____comment-entry__|__| | | | | ||______________________________________________________________|| | | |__INSTALLATION___________@1____________________________| | | |__.__| | <________________ | | | |____comment-entry__|__| | | | | ||______________________________________________________________|| | | |__DATE-WRITTEN___________@1____________________________| | | |__.__| | <________________ | | | |____comment-entry__|__| | | | | ||______________________________________________________________|| | | |__DATE-COMPILED___________@1____________________________| | | |__.__| | <________________ | | | |____comment-entry__|__| | | | | ||______________________________________________________________|| | | |__SECURITY___________@1____________________________| | | |__.__| | <________________ | | | |____comment-entry__|__| | | | | ||______________________________________________________________|| | | |__REMARKS__.____________________________| | | | <________________ | | | |____comment-entry__|__| | | | |____________________________________________________________________| ________________________________________________________________________ | | | Note: | x | (1) This separator period is optional as an IBM extension. | | | |________________________________________________________________________|

The Identification Division must begin with the words IDENTIFICATION x DIVISION or ID DIVISION followed by a separator period.

The first paragraph of the Identification Division must be the PROGRAM-ID paragraph. The other paragraphs are optional, but, when written, must appear in the order shown in the format.

x The optional paragraphs can be in any order.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.2.1 PROGRAM-ID Paragraph

The PROGRAM-ID paragraph specifies the name by which the program is known and assigns selected program attributes to that program. It is required and must be the first paragraph in the Identification Division.

@@ Diagram program-id-paragraph ADAPTED. @@ Implemented footnote on optional periods. ___ program-id-paragraph _________________________________________________________ | | | >>_____IDENTIFICATION_____DIVISION__.__PROGRAM-ID___________@1__program-name___> | | |__{__ID__}________| |__.__| | | | | >________________________________________________________________________@1___>< | | |_______________COMMON___________________________________| |__.__| | | |__IS__| | |__INITIAL__| | |__PROGRAM__| | | |__INITIAL________________| | | |__COMMON__| | | | |__________________________________________________________________________________| ________________________________________________________________________ | | | Note: | x | (1) This separator period is optional as an IBM extension. | | | |________________________________________________________________________|

program-name A user-defined word that identifies your program. The system uses the first 8 characters of program-name of the outermost program as the identifying name of the program.

The first 8 characters of program-name of the outermost program should be unique within the system. The first character must be alphabetic. If the first character is not alphabetic, it is converted as follows:

o 1 through 9 are changed to A through I o Anything else is changed to J.

If a hyphen is used in characters 2 through 8 of the program-name of the outermost program, it is changed to zero (0).

For programs that are contained within another program, program-name can be any valid user-defined COBOL word, up to 30 characters long. | The first 8 characters need not be unique. Lowercase and uppercase | letters are both valid, but they will be considered equivalent in | resolving which program is called or referenced.

x The program-name can be a nonnumeric literal other than a figurative x constant. The content of the literal must follow the rules for x formation of program names. In the outermost program, the literal can x include the extension characters $, #, and @. Any lower case x characters in this literal will be folded to upper case.

COMMON | Specifies that the program named by program-name is contained within | another program, and can be called from siblings of the common program | and programs contained within them. The COMMON clause can be used | only if the program named by program-name is contained within another program. For more information on conventions for program names, see VS COBOL II Application Programming Guide for MVS and CMS or VS COBOL II Application Programming Guide for VSE.

INITIAL Specifies that when program-name is called, program-name and any programs contained within it are placed in their initial state.

A program is in the initial state:

o The first time the program is called in a run unit

o Every time the program is called, if it possesses the initial attribute

o The first time the program is called after the execution of a CANCEL statement referencing the program or a CANCEL statement referencing a program that directly or indirectly contains the program

o The first time the program is called after the execution of a CALL statement referencing a program that possesses the initial attribute, and that directly or indirectly contains the program.

When a program is in the initial state, the following occur:

o The program's internal data contained in the Working-Storage Section are initialized. If a VALUE clause is used in the description of the data item, the data item is initialized to the defined value. If a VALUE clause is not associated with a data item, the initial value of the data item is undefined.

o Files with internal file connectors associated with the program are not in the open mode.

o The control mechanisms for all PERFORM statements contained in the program are set to their initial states.

o An altered GO TO statement contained in the program is set to its initial state.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.2.1.1 Scope of Program-Names

The program-names allocated to programs constituting a run unit are not necessarily unique but, when two programs in a run unit are identically named, at least one of those two programs must be directly or indirectly contained within another separately compiled program that does not contain the other of those two programs.

The following rules regulate the scope of a program-name:

o If the program-name is that of a program that does not possess the COMMON attribute and that is directly contained within another program, that program-name can be referenced only by statements included in that containing program.

o If the program-name is that of a program that does possess the COMMON attribute and that is directly contained within another program, that program-name can be referenced only by statements included in that containing program and any programs directly or indirectly contained within that containing program, except that program possessing the COMMON attribute and any programs contained within it.

o If the program-name is that of a program that is separately compiled, that program-name can be referenced by statements included in any other program in the run unit, except programs it directly or indirectly contains.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.2.2 Optional Paragraphs

These optional paragraphs in the Identification Division can be omitted:

AUTHOR Name of the author of the program.

INSTALLATION Name of the company or location.

DATE-WRITTEN Date the program was written.

DATE-COMPILED Date the program was compiled.

SECURITY Level of confidentiality of the program.

| Note: These optional paragraphs are obsolete elements and will be deleted | from the next revision of the COBOL 85 Standard.

The comment-entry in any of the optional paragraphs can be any combination of characters from the character set of the computer. The comment-entry is written in Area B on one or more lines.

The paragraph name DATE-COMPILED and any comment-entry associated with it appear in the output program listing with the current date inserted:

DATE-COMPILED. 12/25/93.

Comment-entries serve only as documentation; they do not affect the meaning of the program. A hyphen in the indicator area (column 7) is not permitted in comment-entries.

x Comment-entries in the Identification Division can have DBCS strings. A x DBCS string must be preceded by a shift-out control character and followed x by a shift-in control character. For example:

x AUTHOR. <.A.U.T.H.O.R.-.N.A.M.E>, XYZ CORPORATION x DATE-WRITTEN. <.D.A.T.E>

x Multiple lines are allowed in a comment-entry containing DBCS strings; x however, shift-out and shift-in characters must be paired on a line.

x Note: DBCS strings are described under "Character-Strings" in x topic 1.1.1.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.3 Environment Division--Configuration Section

The Environment Division has two sections:

o The Configuration Section

o The Input-Output Section. (See "Environment Division--Input-Output Section" in topic 2.4.)

The Environment Division is optional in a COBOL source program.

___ environment-division _______________________________________ | | | >>__ENVIRONMENT__DIVISION__.__environment-division-content__>< | | | |________________________________________________________________| @@ Diagram environment-division-content EXTRACTED from diagram environment-division. @@ Identified content of the division as referred to elsewhere. ___ environment-division-content ________________________________ | | | >>___________________________________________________________>< | | |__configuration-section__| |__input-output-section__| | | | |_________________________________________________________________| ___ configuration-section _____________________________________________________________ | | | >>__CONFIGURATION__SECTION__.__computer-paragraphs_________________________________>< | | |__special-names-paragraph__| | | | |_______________________________________________________________________________________| @@ Diagram computer-paragraphs EXTRACTED from diagram configuration-section. @@ Identified body of permutation phrase. @@ Diagram computer-paragraphs ADAPTED. @@ No note on immaterial order, but code exercises different orders. ___ computer-paragraphs _________________ | | | ||___________________________________|| | | |__source-computer-paragraph__| | | | | ||___________________________________|| | | |__object-computer-paragraph__| | | | |_________________________________________| @@ Diagram input-output-section ADAPTED. @@ Implemented Note (2) from 2.4.1. ___ input-output-section _______________________________________ | | | >>__INPUT-OUTPUT__SECTION__._________________________________> | | |__file-control-paragraph__| | | | | >___________________________________________________________>< | | |__i-o-control-paragraph__| | | | |________________________________________________________________| The Configuration Section is optional. When specified, it can describe the computer on which the source program is compiled and the computer on which the object program is executed.

In addition, the Configuration Section can:

o Relate IBM-defined environment-names to user-defined mnemonic names o Specify the collating sequence o Specify a substitution for the currency sign o Exchange the functions of the comma and the period in PICTURE clauses and numeric literals o Relate alphabet-names to character sets or collating sequences o Specify symbolic-characters o Relate class names to sets of characters.

Each paragraph must contain one and only one separator period immediately after the last entry in the paragraph.

The Configuration Section must not be specified in a program that is contained within another program. The entries specified in the Configuration Section of a program apply to any program contained within that program.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.3.1 SOURCE-COMPUTER Paragraph

The SOURCE-COMPUTER paragraph describes the computer on which the source program is to be compiled.

___ source-computer-paragraph _____________________________________ | | | >>__SOURCE-COMPUTER__.__________________________________________> | | | | >______________________________________________________________>< | | |__computer-name_____________________________________.__| | | |______________DEBUGGING__MODE__| | | |__WITH__| | | | |___________________________________________________________________| computer-name A system-name. For example:

IBM-370.

WITH DEBUGGING MODE Activates a compile-time switch for debugging lines written in the source program.

A debugging line is a statement that is compiled only when the compile-time switch is activated. Debugging lines allow you, for example, to check the value of a data-name at certain points in a procedure.

To specify a debugging line in your program, code a 'D' in column 7 (indicator area). You can include successive debugging lines, but each must have a 'D' in column 7 and you cannot break character strings across lines.

All your debugging lines must be written so that the program is syntactically correct, whether the debugging lines are compiled or treated as comments.

The presence or absence of the DEBUGGING MODE clause is logically determined after all COPY and REPLACE statements have been processed.

You can code debugging lines in the Environment (after the OBJECT-COMPUTER paragraph), Data, or Procedure Divisions.

If a debugging line contains only spaces in Area A and in Area B, it is treated the same as a blank line.

| The computer-name is syntax-checked, but is treated as documentation.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.3.2 OBJECT-COMPUTER Paragraph

The OBJECT-COMPUTER paragraph specifies the system for which the object program is designated.

___ object-computer-paragraph __________________________________________________________________ | | | >>__OBJECT-COMPUTER__._______________________________________________________________________> | | | | >___________________________________________________________________________________________>< | | |__computer-name_______________________________________________________ocp-entry__.__| | | |__MEMORY______________integer_____WORDS__________| | | |__SIZE__| |__CHARACTERS__| | | |__MODULES_____| | | | |________________________________________________________________________________________________| ___ ocp-entry ___________________________________________________________________ | | | >>____________________________________________________________________________> | | |__________________________________SEQUENCE____________alphabet-name__| | | |__PROGRAM__| |__COLLATING__| |__IS__| | | | | >____________________________________________________________________________>< | | |__SEGMENT-LIMIT____________priority-number__| | | |__IS__| | | | |_________________________________________________________________________________| computer-name A system-name. For example:

IBM-370.

MEMORY SIZE The amount of main storage needed to run the object program. The | MEMORY SIZE clause is syntax-checked, but is treated as documentation.

| Note: MEMORY SIZE is an obsolete element, and will be deleted from | the next revision of the COBOL 85 Standard.

integer Expressed in words, characters, or modules.

PROGRAM COLLATING SEQUENCE IS The collating sequence used in this program is the collating sequence associated with the specified alphabet-name.

The collating sequence pertains to this program and any programs it may contain.

alphabet-name The collating sequence.

PROGRAM COLLATING SEQUENCE determines the truth value of the following nonnumeric comparisons:

o Those explicitly specified in relation conditions o Those explicitly specified in condition-name conditions.

The PROGRAM COLLATING SEQUENCE clause also applies to any nonnumeric merge or sort keys, unless the COLLATING SEQUENCE phrase is specified in the MERGE or SORT statement.

x The PROGRAM COLLATING SEQUENCE clause is not applied to the DBCS character x set.

When the PROGRAM COLLATING SEQUENCE clause is omitted, the EBCDIC collating sequence is used. (See Appendix B, "EBCDIC and ASCII Collating Sequences" in topic APPENDIX1.2.)

x Note: This element may exhibit different behavior when the CMPR2 compiler x option is in effect. For more information, see VS COBOL II Migration x Guide for MVS and CMS or VS COBOL II Migration Guide for VSE.

SEGMENT-LIMIT IS Certain permanent segments can be overlaid by independent segments while still retaining the logical properties of fixed portion segments. (Fixed portion segments are made up of fixed permanent and fixed overlayable segments.)

| Note: SEGMENT-LIMIT is an obsolete element, and will be deleted from | the next revision of the COBOL 85 Standard.

Priority-number An integer ranging from 1 through 49.

When SEGMENT-LIMIT is specified:

o A fixed permanent segment is one with a priority-number less than the priority-number specified.

o A fixed overlayable segment is one with a priority-number ranging from that specified through 49, inclusive.

For example, if SEGMENT-LIMIT IS 25 is specified:

o Sections with priority-numbers 0 through 24 are fixed permanent segments.

o Sections with priority-numbers 25 through 49 are fixed overlayable segments.

When SEGMENT-LIMIT is omitted, all sections with priority-numbers 0 through 49 are fixed permanent segments.

Except for the PROGRAM COLLATING SEQUENCE clause, the OBJECT-COMPUTER | paragraph is syntax-checked, but is treated as documentation.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.3.3 SPECIAL-NAMES Paragraph

The SPECIAL-NAMES paragraph:

o Relates IBM-specified environment-names to user-defined mnemonic-names o Relates alphabetic-names to character sets or collating sequences | o Specifies symbolic-characters o Relates class names to sets of characters o Specifies a substitute character for the currency sign o Specifies that the functions of the comma and decimal point are to be interchanged in PICTURE clauses and numeric literals.

___ special-names-paragraph __________________________________ | | | >>__SPECIAL-NAMES__.__special-names-clauses_______________>< | | |__.__@1__| | | | |______________________________________________________________| @@ Diagram environment-clause EXTRACTED from diagram special-names-paragraph. @@ Factored out clause for clarity. ___ environment-clause _____________________________________________________________ | | | >>_____environment-name-1____________mnemonic-name-1____________________________>< | | | |__IS__| | | | |__environment-name-2_______________mnemonic-name-2______________________| | | | |__IS__| |__snp-entry__| | | | |__snp-entry___________________________________| | | | |____________________________________________________________________________________| @@ Diagram alphabet-clause EXTRACTED from diagram special-names-paragraph. @@ Factored out clause for clarity. ___ alphabet-clause _______________________________________________________________________________ | | | >>__ALPHABET__alphabet-name-1_______________STANDARD-1_________________________________________>< | | |__IS__| |__STANDARD-2______________________________________| | | |__NATIVE__________________________________________| | | |__EBCDIC__________________________________________| | | | <____________________________________________ | | | |____literal-1__________________________________|__| | | |_____THROUGH_____literal-2__| | | | |__THRU_____| | | | | <__________________ | | | |____ALSO__literal-3__|______| | | | |___________________________________________________________________________________________________| @@ Diagram symbolic-clause EXTRACTED from diagram special-names-paragraph. @@ Factored out clause for clarity. @@ Diagram symbolic-clause ADAPTED. @@ Relaxed ARE | IS to be optional as exercised by actual code. ___ symbolic-clause ______________________________________________________________________________________________________ | | | <_______________________________________________________ | | <_______________________ <____________ | | | >>__SYMBOLIC________________________symbolic-character-1__|_______________integer-1__|__|_____________________________>< | | |__CHARACTERS__| |__ARE__| |__IN__alphabet-name-2__| | | |__IS___| | | | |__________________________________________________________________________________________________________________________| @@ Diagram class-clause EXTRACTED from diagram special-names-paragraph. @@ Factored out clause for clarity. ___ class-clause ______________________________________________________________________ | | | <____________________________________________ | | >>__CLASS__class-name-1______________literal-4__________________________________|__>< | | |__IS__| |_____THROUGH_____literal-5__| | | |__THRU_____| | | | |_______________________________________________________________________________________| @@ Diagram currency-clause EXTRACTED from diagram special-names-paragraph. @@ Factored out clause for clarity. ___ currency-clause ___________________________________________________________________________ | | | >>_________________________________________________________________________________________>< | | |__CURRENCY________________________literal-6__| |__DECIMAL-POINT____________COMMA__| | | |__SIGN__| |__IS__| |__IS__| | | | |_______________________________________________________________________________________________| @@ Diagram special-names-clauses EXTRACTED from diagram special-names-paragraph. @@ Identified body of permutation phrase. @@ Diagram special-names-clauses ADAPTED. @@ No note on immaterial order, but code exercises different orders. ___ special-names-clauses _____________ | | | ||_________________________________|| | | | <_____________________ | | | |____environment-clause__|__| | | | | ||_________________________________|| | | | <__________________ | | | |____alphabet-clause__|__| | | | | ||_________________________________|| | | | <__________________ | | | |____symbolic-clause__|__| | | | | ||_________________________________|| | | | <_______________ | | | |____class-clause__|__| | | | | ||__currency-clause________________|| | | | |_______________________________________| ___ snp-entry _________________________________________________________________________________________ | | | >>_____ON__________________________condition-1_____________________________________________________>< | | | |__STATUS__| |__IS__| |__OFF__________________________condition-2__| | | | | |__STATUS__| |__IS__| | | | |__OFF__________________________condition-2_________________________________________________| | | |__STATUS__| |__IS__| |__ON__________________________condition-1__| | | |__STATUS__| |__IS__| | | | |_______________________________________________________________________________________________________| ________________________________________________________________________________________________________________________________ | | | Note: | x | (1) This separator period must be used if any of the optional clauses are selected. | | | |________________________________________________________________________________________________________________________________|

environment-name-1 System devices or standard system actions taken by the compiler.

Valid specifications for environment-name-1 are:

________________________________________________________________________ | Table 6. Meanings of Environment Names | |________________________________________________________________________| | Environment- | | | | Name-1 | Meaning | Allowed In | |_______________|_______________________________|________________________| | SYSIN | System logical input unit | ACCEPT | | SYSIPT | | | |_______________|_______________________________|________________________| | SYSOUT | System logical output unit | DISPLAY | | SYSLIST | | | | SYSLST | | | |_______________|_______________________________|________________________| | SYSPUNCH | System punch device | DISPLAY | | SYSPCH | | | |_______________|_______________________________|________________________| | | CONSOLE | Console | ACCEPT and DISPLAY | |_______________|_______________________________|________________________| | C01 - C12 | Skip to channel 1 through 12, | WRITE ADVANCING | | | respectively | | |_______________|_______________________________|________________________| | CSP | Suppress spacing | WRITE ADVANCING | |_______________|_______________________________|________________________| | S01-S05 | Pocket select 1-5 on punch | WRITE ADVANCING | | | devices | | |_______________|_______________________________|________________________|

environment-name-2 A 1-byte User Programmable Status Indicator (UPSI) switch. Valid specifications for environment-name-2 are UPSI-0 through UPSI-7.

x Note: This element may exhibit different behavior when the CMPR2 x compiler option is in effect. For more information, see VS COBOL II x Migration Guide for MVS and CMS or VS COBOL II Migration Guide for x VSE.

mnemonic-name-1, mnemonic-name-2 Mnemonic-name-1 and mnemonic-name-2 follow the rules of formation for user-defined names. Mnemonic-name-1 can be used in ACCEPT, DISPLAY, and WRITE statements. Mnemonic-name-2 can be referenced only in the SET statement. Mnemonic-name-2 can qualify condition-1 or condition-2 names.

Mnemonic-names and environment-names need not be unique. If you choose a mnemonic-name that is also an environment-name, its definition as a mnemonic-name will take precedence over its definition as an environment-name.

ON STATUS IS, OFF STATUS IS UPSI switches process special conditions within a program, such as year-beginning or year-ending processing. For example, at the beginning of the Procedure Division, an UPSI switch can be tested; if it is ON, the special branch is taken. (See "Switch-Status Condition" in topic 2.8.5.7.)

| condition-1, condition-2 | Condition-names follow the rules for user-defined names. At least 1 | character must be alphabetic. A condition-name can be associated with | the on status and/or off status of each UPSI switch specified.

In the Procedure Division, the UPSI switch status is tested through the associated condition-name. Each condition-name is the equivalent of a level-88 item; the associated mnemonic-name, if specified, is considered the conditional variable and can be used for qualification.

Condition-names specified in a containing program's SPECIAL-NAMES paragraph can be referenced from any contained program.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.3.4 ALPHABET Clause

ALPHABET alphabet-name-1 IS Provides a means of relating an alphabet-name to a specified character code set or collating sequence.

x Note: This element may exhibit different behavior when the CMPR2 x compiler option is in effect. For more information, see VS COBOL II x Migration Guide for MVS and CMS or VS COBOL II Migration Guide for x VSE.

It specifies a collating sequence when used in either:

o The PROGRAM COLLATING SEQUENCE clause of the OBJECT-COMPUTER paragraph o The COLLATING SEQUENCE phrase of the SORT or MERGE statement.

It specifies a character code set when specified in either:

o The FD entry CODE-SET clause o The SYMBOLIC CHARACTERS clause.

STANDARD-1 Specifies the ASCII character set.

STANDARD-2 Specifies the International Reference Version of the ISO 7-bit code defined in International Standard 646, 7-bit Coded Character Set for Information Processing Interchange.

NATIVE Specifies the native character code set. If the alphabet-name clause is omitted, EBCDIC is assumed.

EBCDIC Specifies the EBCDIC character set.

literal-1, literal-2, literal-3 Specifies that the collating sequence is to be determined by the program, according to the following rules:

o The order in which literals appear specifies the ordinal number, in ascending sequence, of the character(s) in this collating sequence.

o Each numeric literal specified must be an unsigned integer and must have a value from 1 through 256. The value of each literal specifies the ordinal number (beginning with 1) of a character within the EBCDIC character set. For example:

The literal 92 represents the EBCDIC character $ (X'5B'). The literal 234 represents the EBCDIC character Z (X'E9').

Appendix B, "EBCDIC and ASCII Collating Sequences" in topic APPENDIX1.2, lists the ordinal number for characters in the EBCDIC and ASCII collating sequences.

o Each character in a nonnumeric literal represents that actual character in the EBCDIC character set. (If the nonnumeric literal contains more than 1 character, each character, starting with the leftmost, is assigned a successively ascending position within this collating sequence.)

o Any EBCDIC characters that are not explicitly specified assume positions in this collating sequence higher than any of the explicitly specified characters. The relative order within the set of these unspecified characters within the EBCDIC set remains unchanged.

o Within one alphabet-name clause, a given character must not be specified more than once.

o Each nonnumeric literal associated with a THROUGH or ALSO phrase must be 1 character in length.

o When the THROUGH phrase is specified, the contiguous characters in the native character set beginning with the character specified by literal-1 and ending with the character specified by literal-2 are assigned successively ascending positions in this collating sequence. This sequence can be either ascending or descending within the original native character set. That is, if "Z" THROUGH "A" is specified, the ascending values, left-to-right, for the uppercase letters are:

ZYXWVUTSRQPONMLKJIHGFEDCBA

o When the ALSO phrase is specified, the EBCDIC characters specified as literal-1, literal-3, etc., are assigned to the same position in this collating sequence. For example, if you specify:

"D" ALSO "N" ALSO "%"

the characters D, N, and % are all considered to be in the same position in the collating sequence.

o When the ALSO phrase is specified and alphabet-name-1 is referenced in a SYMBOLIC CHARACTERS clause, only literal-1 is used to represent the character in the EBCDIC set.

o The character having the highest ordinal position in this collating sequence is associated with the figurative constant HIGH-VALUE. If more than 1 character has the highest position, because of specification of the ALSO phrase, the | last character specified (or defaulted to when any EBCDIC | characters are not explicitly specified) is considered to be the HIGH-VALUE character for procedural statements such as | DISPLAY, or as the sending field in a MOVE statement. (If all | EBCDIC characters and the ALSO phrase example given above were | specified as the high-order characters of this collating | sequence, the HIGH-VALUE character would be %.)

o The character having the lowest ordinal position in this collating sequence is associated with the figurative constant LOW-VALUE. If more than 1 character has the lowest position, because of specification of the ALSO phrase, the first character specified is the LOW-VALUE character. (If the ALSO phrase example given above were specified as the low-order characters of the collating sequence, the LOW-VALUE character would be D.)

When literal-1, literal-2, or literal-3 is specified, the alphabet-name must not be referred to in a CODE-SET clause (see "CODE-SET Clause" in topic 2.6.11).

Literal-1, literal-2, and literal-3 must not specify a symbolic-character figurative constant.

x Floating-point literals cannot be used in a user-specified x collating sequence.

x DBCS literals cannot be used in a user-specified collating x sequence.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.3.5 SYMBOLIC CHARACTERS Clause

SYMBOLIC CHARACTERS symbolic-character-1 Provides a means of specifying one or more symbolic-characters. x Symbolic-character-1 is a user-defined word (it can be a DBCS x user-defined word) and must contain at least 1 alphabetic character. The same symbolic-character must appear only once in a SYMBOLIC CHARACTERS clause. The internal representation of symbolic-character-1 is the internal representation of the character that is represented in the specified character set. The following rules apply:

o The relationship between each symbolic-character-1 and the corresponding integer-1 is by their position in the SYMBOLIC CHARACTERS clause. The first symbolic-character-1 is paired with the first integer-1; the second symbolic-character-1 is paired with the second integer-1; and so forth.

o There must be a one-to-one correspondence between occurrences of symbolic-character-1 and occurrences of integer-1 in a SYMBOLIC CHARACTERS clause.

o If the IN phrase is specified, integer-1 specifies the ordinal position of the character that is represented in the character set named by alphabet-name-2. This ordinal position must exist.

o If the IN phrase is not specified, symbolic-character-1 represents the character whose ordinal position in the native character set is specified by integer-1.

| Note: Ordinal positions are numbered starting from 1.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.3.6 CLASS Clause

CLASS class-name-1 IS Provides a means for relating a name to the specified set of characters listed in that clause. Class-name can be referenced only in a class condition. The characters specified by the values of the literals in this clause define the exclusive set of characters of which this class-name consists.

x The class-name in a CLASS clause can be a DBCS user-defined word.

literal-4, literal-5 If numeric, must be unsigned integers and must have a value that is greater than or equal to 1 and less than or equal to the number of characters in the alphabet specified. Each number corresponds to the ordinal position of each character in the EBCDIC collating series.

x Literal-4 and Literal-5 cannot be specified as floating-point literals x or DBCS literals.

If nonnumeric, the literal is the actual EBCDIC character. Literal-4 and literal-5 must not specify a symbolic-character figurative constant. If the value of the nonnumeric literal contains multiple characters, each character in the literal is included in the set of characters identified by class-name.

If the nonnumeric literal is associated with a THROUGH phrase, it must be 1 character in length.

THROUGH, THRU THROUGH and THRU are equivalent. If THROUGH is specified, class-name includes those characters beginning with the value of literal-4 and ending with the value of literal-5. In addition, the characters specified by a THROUGH phrase can specify characters in either ascending or descending order.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.3.7 CURRENCY SIGN Clause

CURRENCY SIGN IS Currency symbol in the PICTURE clause.

literal-6 Must be a one-character, nonnumeric literal, and must not be any of the following:

o Digits zero (0) through nine (9)

o Uppercase alphabetic characters A B C D P R S V X Z

o Lowercase alphabetic characters a through z

o The space

| o Special characters * + - / , . ; ( ) = ' "

o A figurative constant

x o The uppercase alphabetic character G, for programs that use DBCS x data items.

x o The uppercase alphabetic character E, for programs that use x external floating-point data items.

x o The non-printable characters with hex values of X'20' and X'21'

When the CURRENCY SIGN clause is omitted, only the dollar sign ($) can be used as the PICTURE symbol for the currency sign.

DECIMAL-POINT IS COMMA Exchanges the functions of the period and the comma in PICTURE character strings and in numeric literals.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4 Environment Division--Input-Output Section

The Input-Output section of the Environment Division contains two paragraphs:

o FILE-CONTROL paragraph o I-O-CONTROL paragraph.

@@ Diagram input-output-section ADAPTED. @@ Implemented Note (2) from 2.4.1. ___ input-output-section _______________________________________ | | | >>__INPUT-OUTPUT__SECTION__._________________________________> | | |__file-control-paragraph__| | | | | >___________________________________________________________>< | | |__i-o-control-paragraph__| | | | |________________________________________________________________| FILE-CONTROL paragraph-name The keyword FILE-CONTROL can appear only once, at the beginning of the FILE-CONTROL paragraph. It must begin in Area A, and be followed by a separator period.

x The FILE-CONTROL paragraph is optional.

file-control-paragraph Names the files and associates them with the external data sets.

Must begin in Area B with a SELECT clause. It must end with a separator period. See "FILE-CONTROL Paragraph" in topic 2.4.1.

I-O-CONTROL paragraph-name Specifies information needed for efficient transmission of data between the external data set and the COBOL program.

input-output-control-paragraph The series of entries must end with a separator period. See "I-O-CONTROL Paragraph" in topic 2.4.14.

The exact contents of the Input-Output Section depend on the file organization and access methods used. See "ORGANIZATION Clause" in topic 2.4.5 and "ACCESS MODE Clause" in topic 2.4.8.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.1 FILE-CONTROL Paragraph

The FILE-CONTROL paragraph associates each file in the COBOL program with an external data set, and specifies file organization, access mode, and other information.

There are three formats for the FILE-CONTROL paragraph:

o QSAM, SAM, and VSAM sequential file entries o VSAM indexed file entries o VSAM relative file entries.

The FILE-CONTROL paragraph begins with the word "FILE-CONTROL", followed by a separator period. It must contain one and only one entry for each file described in an FD or SD entry in the Data Division. Within each | entry, the SELECT clause must appear first, followed by the ASSIGN clause. The other clauses can appear in any order.

x Note: There is one exception to the rule about order. For indexed files, x the PASSWORD clause, if specified, must immediately follow the RECORD KEY x or ALTERNATE RECORD KEY data-name with which it is associated. In the x ALTERNATE RECORD KEY clause, the keyword RECORD is optional.

@@ Diagram file-control-paragraph ADAPTED. @@ Redirected to a single format for entries. @@ Diagram file-control-paragraph ADAPTED. @@ Implemented Note (1) from 2.4.1. ___ file-control-paragraph ________________ | | | >>__FILE-CONTROL__.__@1_________________> | | | | >__________________________________@2__>< | | | <_____________________ | | | |____file-control-entry__|__| | | | |___________________________________________| @@ Diagram file-control-entry ADDED after diagram file-control-paragraph. @@ Start with SELECT/ASSIGN; leave other clauses for permutation phrase. ___ file-control-entry ________________________________________ | | | >>__select-clause__assign-clause__file-control-clauses__.__>< | | | |_______________________________________________________________| @@ Diagram select-clause ADDED after diagram file-control-paragraph. @@ Used elsewhere for folding. ___ select-clause ___________________________ | | | >>__SELECT__________________file-name-1__>< | | |__OPTIONAL__| | | | |_____________________________________________| @@ Diagram assign-clause ADDED after diagram file-control-paragraph. @@ Used elsewhere for folding. ___ assign-clause ______________________________________ | | | <__________________________ | | >>__ASSIGN_________________assignment-name-1_____|__>< | | |__TO__| |__literal-1__________| | | | |________________________________________________________| @@ Diagram file-control-clauses ADDED after diagram file-control-paragraph. @@ Permutation phrase for all possible file-control-clauses. ___ file-control-clauses _______________ | | | ||__________________________________|| | | |__reserve-clause__| | | | | ||__________________________________|| | | |__organisation-clause__| | | | | ||__________________________________|| | | |__padding-character-clause__| | | | | ||__________________________________|| | | |__record-delimiter-clause__| | | | | ||__________________________________|| | | |__access-mode-clause__| | | | | ||__________________________________|| | | |__key-clause__| | | | | ||__________________________________|| | | |__password-clause__| | | | | ||__________________________________|| | | |__status-clause__| | | | |________________________________________| @@ Diagram reserve-clause ADDED after diagram file-control-paragraph. @@ Used elsewhere for folding. ___ reserve-clause ____________________ | | | >>__RESERVE__integer_______________>< | | |__AREA___| | | |__AREAS__| | | | |_______________________________________| @@ Diagram organisation-clause ADDED after diagram file-control-paragraph. @@ Centralised different organisations. ___ organisation-clause ________________________________ | | | >>___________________________________SEQUENTIAL_____>< | | |__ORGANIZATION____________| |__INDEXED_____| | | |__IS__| |__RELATIVE____| | | | |________________________________________________________| @@ Diagram padding-character-clause ADDED after diagram file-control-paragraph. @@ Used elsewhere for folding. ___ padding-character-clause ____________________________________________ | | | >>__PADDING________________________________qualified-data-name-5_____>< | | |__CHARACTER__| |__IS__| |__literal-1______________| | | | |_________________________________________________________________________| @@ Diagram record-delimiter-clause ADDED after diagram file-control-paragraph. @@ Used elsewhere for folding. ___ record-delimiter-clause __________________________________ | | | >>__RECORD__DELIMITER_______________STANDARD-1____________>< | | |__IS__| |__assignment-name-2__| | | | |______________________________________________________________| @@ Diagram access-mode-clause ADDED after diagram file-control-paragraph. @@ Centralised and simplified different access modes ___ access-mode-clause _______________________________________ | | | >>_________________________________________SEQUENTIAL_____>< | | |__ACCESS________________________| |__RANDOM______| | | |__MODE__| |__IS__| |__DYNAMIC_____| | | | |______________________________________________________________| @@ Diagram key-clause ADDED after diagram file-control-paragraph. @@ Centralised and simplified different key clauses; ___ key-clause _____________ | | | >>_____record-key_______>< | | |__relative-key__| | | | |____________________________| @@ Diagram password-clause ADDED after diagram file-control-paragraph. @@ Used elsewhere for folding. ___ password-clause _____________________________________ | | | >>__{__PASSWORD____________qualified-data-name-6__}__>< | | |__IS__| | | | |_________________________________________________________| @@ Diagram status-clause ADDED after diagram file-control-paragraph. @@ Used elsewhere for folding. ___ status-clause ______________________________________________________________________________ | | | >>______________STATUS____________qualified-data-name-1_____________________________________>< | | |__FILE__| |__IS__| |__{__qualified-data-name-8__}__| | | | |________________________________________________________________________________________________| ________________________________________________________________________ | | | | Notes: | x | (1) If there are no files defined in the program and the INPUT-OUTPUT | x | SECTION is specified and no file-control-entry is specified, then | x | the FILE-CONTROL paragraph-name is optional as an IBM extension. | | | x | (2) If there are no files defined in the program and the FILE-CONTROL | x | paragraph-name is specified, then the file-control-entry is | x | optional as an IBM extension. | | | |________________________________________________________________________|

@@ Diagram qsam-sam-vsam-sequential-file-control-entries ADAPTED. @@ Enabled qualified instead of plain data names. @@ Diagram qsam-sam-vsam-sequential-file-control-entries FOLDED according to select-clause. @@ Factored out clause for clarity. @@ Diagram qsam-sam-vsam-sequential-file-control-entries FOLDED according to assign-clause. @@ Factored out clause for clarity. @@ Diagram qsam-sam-vsam-sequential-file-control-entries FOLDED according to reserve-clause. @@ Factored out clause for clarity. @@ Diagram qsam-sam-vsam-sequential-file-control-entries FOLDED according to padding-character-clause. @@ Factored out clause for clarity. @@ Diagram qsam-sam-vsam-sequential-file-control-entries FOLDED according to record-delimiter-clause. @@ Factored out clause for clarity. @@ Diagram qsam-sam-vsam-sequential-file-control-entries FOLDED according to password-clause. @@ Factored out clause for clarity. @@ Diagram qsam-sam-vsam-sequential-file-control-entries FOLDED according to status-clause. @@ Factored out clause for clarity. ___ qsam-sam-vsam-sequential-file-control-entries ______ | | | >>__select-clause____________________________________> | | | | >___assign-clause____________________________________> | | |__reserve-clause__| | | | | >____________________________________________________> | | |________________________________SEQUENTIAL__| | | |__ORGANIZATION____________| | | |__IS__| | | | | >____________________________________________________> | | |__padding-character-clause__| | | | | >____________________________________________________> | | |__record-delimiter-clause__| | | | | >____________________________________________________> | | |__ACCESS________________________SEQUENTIAL__| | | |__MODE__| |__IS__| | | | | >____________________________________________________> | | |__password-clause__| | | | | >________________________.__________________________>< | | |__status-clause__| | | | |________________________________________________________|

@@ Diagram vsam-indexed-file-control-entries ADAPTED. @@ Enabled qualified instead of plain data names. @@ Diagram vsam-indexed-file-control-entries FOLDED according to select-clause. @@ Factored out clause for clarity. @@ Diagram vsam-indexed-file-control-entries FOLDED according to assign-clause. @@ Factored out clause for clarity. @@ Diagram vsam-indexed-file-control-entries FOLDED according to reserve-clause. @@ Factored out clause for clarity. @@ Diagram vsam-indexed-file-control-entries FOLDED according to password-clause. @@ Factored out clause for clarity. @@ Diagram vsam-indexed-file-control-entries FOLDED according to status-clause. @@ Factored out clause for clarity. @@ Diagram vsam-indexed-file-control-entries ADAPTED. @@ Inserted a line break. ___ vsam-indexed-file-control-entries ________________________ | | | >>__select-clause__________________________________________> | | | | >___assign-clause__________________________________________> | | |__reserve-clause__| | | | | >_________________________________INDEXED__________________> | | |__ORGANIZATION____________| | | |__IS__| | | | | >__________________________________________________________> | | |__ACCESS___________________________SEQUENTIAL_____| | | |__MODE__| |__IS__| |__RANDOM______| | | |__DYNAMIC_____| | | | | >___record-key_____________________________________________> | | | | >________________________.________________________________>< | | |__status-clause__| | | | |______________________________________________________________| @@ Diagram record-key EXTRACTED from diagram vsam-indexed-file-control-entries. @@ Factored out key phrase for clarity. ___ record-key _________________________________________________ | | | >>__RECORD___________________________________________________> | | |__KEY__| | | | | >_____________qualified-data-name-2__________________________> | | |__IS__| |__password-clause__| | | | | >___________________________________________________________>< | | | <____________ | | | |____idx-entry__|__| | | | |________________________________________________________________| @@ Diagram idx-entry ADAPTED. @@ Enabled qualified instead of plain data names. @@ Diagram idx-entry ADAPTED. @@ Implemented Note (1) given below the diagram. ___ idx-entry _______________________________________________________________________________ | | | >>__ALTERNATE________________@1_______________________qualified-data-name-3_______________> | | |__RECORD__| |__KEY__| |__IS__| | | | | >________________________________________________________________________________________>< | | |__{__PASSWORD____________qualified-data-name-7__}__| |______________DUPLICATES__| | | |__IS__| |__WITH__| | | | |_____________________________________________________________________________________________| ______________________________________________________________________________ | | | Note: | x | (1) RECORD is optional as an IBM extension. | | | |______________________________________________________________________________|

@@ Diagram vsam-relative-file-control-entries ADAPTED. @@ Enabled qualified instead of plain data names. @@ Diagram vsam-relative-file-control-entries FOLDED according to select-clause. @@ Factored out clause for clarity. @@ Diagram vsam-relative-file-control-entries FOLDED according to assign-clause. @@ Factored out clause for clarity. @@ Diagram vsam-relative-file-control-entries FOLDED according to reserve-clause. @@ Factored out clause for clarity. @@ Diagram vsam-relative-file-control-entries FOLDED according to password-clause. @@ Factored out clause for clarity. @@ Diagram vsam-relative-file-control-entries FOLDED according to status-clause. @@ Factored out clause for clarity. ___ vsam-relative-file-control-entries ___________________________________________ | | | >>__select-clause__assign-clause_______________________________________________> | | | | >_______________________________________________________RELATIVE_______________> | | |__reserve-clause__| |__ORGANIZATION____________| | | |__IS__| | | | | >______________________________________________________________________________> | | |__ACCESS___________________________SEQUENTIAL_________________________| | | |__MODE__| |__IS__| | |__relative-key__| | | | |_____RANDOM______relative-key_____| | | |__DYNAMIC__| | | | | >_______________________________________________._____________________________>< | | |__password-clause__| |__status-clause__| | | | |__________________________________________________________________________________| @@ Diagram relative-key EXTRACTED from diagram vsam-relative-file-control-entries. @@ Factored out key phrase for clarity. ___ relative-key _____________________________________________ | | | >>__RELATIVE_______________________qualified-data-name-4__>< | | |__KEY__| |__IS__| | | | |______________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.2 SELECT Clause

The SELECT clause chooses a file.

SELECT OPTIONAL Can be specified only for files opened in the input, I-O, or extend mode. You must specify SELECT OPTIONAL for such input files that are not necessarily present each time the object program is executed. For more information, see VS COBOL II Application Programming Guide for MVS and CMS or VS COBOL II Application Programming Guide for VSE.

file-name Must be identified by an FD or SD entry in the Data Division. A file-name must conform to the rules for a COBOL user-defined name, must contain at least 1 alphabetic character, and must be unique within this program.

When file-name specifies a sort or a merge file, only the ASSIGN clause can follow the SELECT clause.

If the file connector referenced by file-name-1 is an external file connector, all file control entries in the run unit that reference this file connector must have the same specification for the OPTIONAL phrase.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.3 ASSIGN Clause

The ASSIGN clause associates the program's name for a file with the external name for the actual data set.

assignment-name-1 Can be specified as a user-defined word or a nonnumeric literal. Any assignment-name after the first is syntax-checked, but is treated as documentation.

Assignment-name-1 has the following formats:

___ Format--SAM File ___________________________________________________ | | | >>__________________________________name____________________________>< | | |_SYSnnn-____________| |_S-_| | | |_mfdc-_| | | | |________________________________________________________________________| ___ Format--QSAM File __________________________________________________ | | | >>______________________name________________________________________>< | | |_label-_| |_S-_| | | | |________________________________________________________________________| ___ Format--VSAM Sequential File _______________________________________ | | | >>______________AS-__name___________________________________________>< | | |_label-_| | | | |________________________________________________________________________| ___ Format--VSAM Indexed or Relative File ______________________________ | | | >>______________name________________________________________________>< | | |_label-_| | | | |________________________________________________________________________| SYSnnn- Defines the logical unit number assigned to the device on which the SAM file resides. The logical unit must be a programmer logical unit in the range SYS000 to SYS240. If specified, it must end with a hyphen.

mfdc- Defines the device characteristics of the 3505 card reader or 3525 multifunction card unit on which the SAM file resides. The format of the device characteristics for SAM files depends upon the device. If specified, it must end with a hyphen. For more information about device characteristics, see VSE/ESA(*) System Macros Reference or VS COBOL II Application Programming Guide for VSE.

label- Documents the device and device class to which a file is assigned. If specified, it must end with a hyphen.

S- For QSAM or SAM files, the S- (organization) field can be omitted.

AS- For VSAM sequential files, the AS- (organization) field must be specified.

For VSAM indexed and relative files, the organization field must be omitted.

name | Under MVS, name must be a required 1- to 8-character field that | specifies the external name for this file. It must be the name specified in the DD statement for this file.

Under VSE, name must be a 1- to 7-character field that specifies the system name of the file. It must be the same name specified in the DLBL or TLBL statement for the file.

| Name must conform to the rules for formation of a program-name. If | assignment-name-1 is specified as a nonnumeric literal, then name must | follow the rules for the formation of a program-name in the outermost | program. (For more information on program-name, see "PROGRAM-ID | Paragraph" in topic 2.2.1).

In a sort or merge file, name is treated as a comment. For more information, see VS COBOL II Application Programming Guide for VSE.

| literal-1 | Must be a nonnumeric literal that is not a figurative constant.

If the file connector referenced by file-name-1 in the SELECT clause is an external file connector, all file control entries in the run unit that reference this file connector must have a consistent specification for assignment-name-1 in the ASSIGN clause. For QSAM or SAM files and VSAM indexed and relative files, the name specified on the first assignment-name-1 must be identical. For VSAM sequential files, it must be specified as AS-name.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.4 RESERVE Clause

The reserve clause allows the user to specify the number of input/output buffers to be allocated at run-time for the files.

If the RESERVE clause is omitted, the number of buffers at run time is taken from the DD statement when running under MVS, or from the TLBL JCL statement when running under VSE. If none is specified, the system default is taken.

If the file connector referenced by file-name-1 in the SELECT clause is an external file connector, all file control entries in the run unit that reference this file connector must have the same value for the integer specified in the RESERVE clause.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.5 ORGANIZATION Clause

The ORGANIZATION clause identifies the logical structure of the file. The logical structure is established at the time the file is created and cannot subsequently be changed.

You can find a discussion of the different ways in which data can be organized and of the different access methods that you can use to retrieve the data under "Data Organization and Access Modes" in topic 2.4.8.1.

ORGANIZATION IS SEQUENTIAL (Format 1) A predecessor-successor relationship among the records in the file is established by the order in which records are placed in the file when it is created or extended.

ORGANIZATION IS INDEXED (Format 2) The position of each logical record in the file is determined by | indexes created with the file and maintained by the system. The | indexes are based on keys within the file's records.

ORGANIZATION IS RELATIVE (Format 3) The position of each logical record in the file is determined by its relative record number.

If you omit the ORGANIZATION clause, the compiler assumes ORGANIZATION IS SEQUENTIAL.

If the file connector referenced by file-name-1 in the SELECT clause is an external file connector, all file control entries in the run unit that reference this file connector must have the same organization.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.6 PADDING CHARACTER Clause

The PADDING CHARACTER clause specifies the character which is to be used for block padding on sequential files.

data-name-5 Must be defined in the Data Division as an alphanumeric 1-character data item, and must not be defined in the File Section. Data-name-5 can be qualified.

literal-1 Must be a 1-character nonnumeric literal.

For EXTERNAL files, if data-name-5 is specified, it must reference an external data item.

In VS COBOL II, the PADDING CHARACTER clause is syntax-checked, but no compile-time or run-time verification checking is done, and the clause is treated as documentation.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.7 RECORD DELIMITER Clause

The RECORD DELIMITER clause indicates the method of determining the length of a variable-length record on an external medium. It can be specified only for variable-length records.

STANDARD-1 If STANDARD-1 is specified, the external medium must be a magnetic tape file.

assignment-name-2 Can be any COBOL word.

In VS COBOL II, the RECORD DELIMITER clause is syntax-checked, but no compile-time or run-time verification checking is done, and the clause is treated as documentation.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.8 ACCESS MODE Clause

The ACCESS MODE clause defines the manner in which the records of the file are made available for processing. If the ACCESS MODE clause is not specified, sequential access is assumed.

x For sequentially accessed VSAM relative files, the ACCESS MODE clause does x not have to precede the RELATIVE KEY clause.

ACCESS MODE IS SEQUENTIAL Can be specified in all three formats.

Format 1--Sequential Records in the file are accessed in the sequence established when the file is created or extended. Format 1 supports only sequential access.

Format 2--Indexed Records in the file are accessed in the sequence of ascending record key values according to the collating sequence of the file.

Format 3--Relative Records in the file are accessed in the ascending sequence of relative record numbers of existing records in the file.

ACCESS MODE IS RANDOM Can be specified in Formats 2 and 3 only.

Format 2--Indexed The value placed in a record key data item specifies the record to be accessed.

Format 3--Relative The value placed in a relative key data item specifies the record to be accessed.

ACCESS MODE IS DYNAMIC Can be specified in Formats 2 and 3 only.

Format 2--Indexed Records in the file can be accessed sequentially or randomly, depending on the form of the specific input-output statement used.

Format 3--Relative Records in the file can be accessed sequentially or randomly, depending on the form of the specific input-output request.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.8.1 Data Organization and Access Modes

Data organization is the permanent logical structure of the file. You tell the computer how to retrieve records from the file by specifying the access mode. In COBOL you can specify any of three types of data organization, and three access modes.

_______________________________________________________ | Table 7. Data Organization and Access Modes | |_______________________________________________________| | Data Organizations | | | | QSAM, SAM, or VSAM Sequential | | | VSAM Indexed | | | VSAM Relative | | | | |______________________|________________________________| | Access Modes | Sequential | | | Random | | | Dynamic | |______________________|________________________________| | File Types | Sequential | | | VSAM Indexed | | | VSAM Relative | |______________________|________________________________|

Note: Sequentially organized data can only be accessed sequentially; however, data that has indexed or relative organization can be accessed with any of the three access methods.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.8.2 Data Organization

You establish the organization of the data when you create the file. Once the file has been created, you can expand the file, but you cannot change the organization.

QSAM, SAM, and VSAM Sequential Organization: The physical order in which the records are placed in the file determines the sequence of records. The relationships among records in the file do not change, except that the file can be extended. Records can be fixed-length or variable-length; there are no keys.

Each record in the file, except the first, has a unique predecessor record, and each record, except the last, also has a unique successor record.

| VSAM Indexed Organization: Each record in the file has one or more keys | (referred to as key data items); each key is associated with an index. An index provides a logical path to the data records, according to the contents of the associated embedded record key data items. Indexed files must be direct-access storage files. Records can be fixed-length or variable-length.

Each record in an indexed file must have an embedded prime key data item. When records are inserted, updated, or deleted, they are identified solely by the values of their prime keys. Thus, the value in each prime key data item must be unique and must not be changed when the record is updated. You tell COBOL the name of the prime key data item on the RECORD KEY clause of the FILE-CONTROL paragraph.

In addition, each record in an indexed file can contain one or more embedded alternate key data items. Each alternate key provides another means of identifying which record to retrieve. The programmer can specify with VSAM options that the values contained in an alternate key data item need not be unique. You tell COBOL the name of any alternate key data items on the ALTERNATE RECORD KEY clause of the FILE-CONTROL paragraph.

The key used for any specific input-output request is known as the key of reference.

VSAM Relative Organization: Think of the file as a string of record areas, each of which contains a single record. Each record area is identified by a relative record number; the access method stores and retrieves a record, based on its relative record number. For example, the first record area is addressed by relative record number 1, and the 10th is addressed by relative record number 10. The physical sequence in which the records were placed in the file has no bearing on the record area in which they are stored, and thus on each record's relative record number. Relative files must be direct-access files. Records can be fixed-length or variable-length.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.8.3 Access Modes

Sequential-Access Mode: Allows reading and writing records of a file in a serial manner; the order of reference is implicitly determined by the position of a record in the file.

Random-Access Mode: Allows reading and writing records in a programmer-specified manner; the control of successive references to the file is expressed by specifically defined keys supplied by the user.

Dynamic-Access Mode: Allows the specific input-output statement to determine the access mode. Therefore, records can be processed sequentially and/or randomly.

For EXTERNAL files, every file control entry in the run unit that is associated with that external file must specify the same access mode. In addition, for VSAM relative file entries, data-name-4 must reference an external data item and the RELATIVE KEY phrase in each associated file control entry must reference that same external data item in each case.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.8.4 Relationship Between Data Organizations and Access Modes

Sequential Files: Files with sequential organization can be accessed only sequentially. The sequence in which records are accessed is the order in which the records were originally written.

VSAM Indexed Files: All three access modes are allowed.

In the sequential access mode, the sequence in which records are accessed is the ascending order of the record key value. The order of retrieval within a set of records having duplicate alternate record key values is the order in which records were written into the set.

In the random access mode, you control the sequence in which records are | accessed. The desired record is accessed by placing the value of its | key(s) in the RECORD KEY data item (and the ALTERNATE RECORD KEY data | item). If a set of records has duplicate alternate record key values, only the first record written is available.

In the dynamic access mode, you can change, as necessary, from sequential access to random access, using appropriate forms of input-output statements.

VSAM Relative Files: All three access modes are allowed.

In the sequential access mode, the sequence in which records are accessed is the ascending order of the relative record numbers of all records that currently exist within the file.

In the random access mode, you control the sequence in which records are accessed. The desired record is accessed by placing its relative record number in the RELATIVE KEY data item; the RELATIVE KEY must not be defined within the record description entry for this file.

In the dynamic access mode, you can change, as necessary, from sequential access to random access, using the appropriate forms of input-output statements.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.9 RECORD KEY Clause

The RECORD KEY clause (Format 2) specifies the data item within the record that is the prime RECORD KEY for an indexed file. The values contained in the prime RECORD KEY data item must be unique among records in the file.

data-name-2 | Is the prime RECORD KEY data item. It must be described as a | fixed-length alphanumeric item within a record description entry associated with the file. It must not reference a group item that contains a variable occurrence data item. Data-name-2 can be qualified.

If the indexed file contains variable-length records, data-name-2 must be contained within the first "x" character positions of the record, where "x" equals the minimum record size specified for the file.

x Data-name-2 can be numeric, numeric-edited, alphanumeric-edited, x alphabetic, floating-point (both external and internal), or a DBCS x data item. The key is treated as an alphanumeric item for the input x and output statements for the file named in the SELECT clause. When x you specify data-name-2 as a DBCS data item, a key specified on the x READ statement must also be a DBCS data item.

The data description of data-name-2 and its relative location within the record must be the same as those used when the file was defined.

If the file has more than one record description entry, data-name-2 need only be described in one of these record description entries. The identical character positions referenced by data-name-2 in any one record description entry are implicitly referenced as keys for all other record description entries of that file.

For EXTERNAL files, all file description entries in the run unit that are associated with the EXTERNAL file must specify the same data description entry for data-name-2 with the same relative location within the associated record.

x The requirement for identical data description entries is not enforced, x but the key must have the same relative location in the records, as well x as the same length.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.10 ALTERNATE RECORD KEY Clause

The ALTERNATE RECORD KEY clause (Format 2) specifies a data item within the record that provides an alternative path to the data in an indexed file.

data-name-3 | Is an ALTERNATE RECORD KEY data item. It must be described as a | fixed-length alphanumeric item within a record description entry associated with the file. It must not reference a group item that contains a variable occurrence data item. Data-name-3 can be qualified.

If the indexed file contains variable-length records, data-name-3 must be contained within the first "x" character positions of the record, where "x" equals the minimum record size specified for the file.

x Data-name-3 can be a numeric, numeric-edited, alphanumeric-edited, x alphabetic, floating-point (both external and internal), or DBCS data x item. The key is treated as an alphanumeric item for the input and x output statements for the file named in the SELECT clause.

If the file has more than one record description entry, data-name-3 need be described in only one of these record description entries. The identical character positions referenced by data-name-3 in any one record description entry are implicitly referenced as keys for all other record description entries of that file.

The data description of data-name-3 and its relative location within the record must be the same as those used when the file was defined. The number of alternate record keys for the file must also be the same as that used when the file was created.

The leftmost character position of data-name-3 must not be the same as the leftmost character position of the RECORD KEY or of any other ALTERNATE RECORD KEY.

If the DUPLICATES phrase is not specified, the values contained in the ALTERNATE RECORD KEY data item must be unique among records in the file.

If the DUPLICATES phrase is specified, the values contained in the ALTERNATE RECORD KEY data item can be duplicated within any records in the file. In sequential access, the records with duplicate keys are retrieved in the order in which they were placed in the file. In random access, only the first record written of a series of records with duplicate keys can be retrieved.

For EXTERNAL files, all file description entries in the run unit that are associated with the EXTERNAL file must specify the same data description entry for data-name-3, the same relative location within the associated record, the same number of alternate record keys, and the same DUPLICATES phrase.

x The requirement for identical data description entries is not enforced, x but the key must have the same relative location in the records, as well x as the same length.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.11 RELATIVE KEY Clause

The RELATIVE KEY clause (Format 3) identifies a data-name that specifies the relative record number for a specific logical record within a relative file.

data-name-4 Must be defined as an unsigned integer data item whose description does not contain the PICTURE symbol P. Data-name-4 must not be defined in a record description entry associated with this relative file. That is, the RELATIVE KEY is not part of the record. Data-name-4 can be qualified.

Data-name-4 is required for ACCESS IS SEQUENTIAL only when the START statement is to be used. It is always required for ACCESS IS RANDOM and ACCESS IS DYNAMIC. When the START statement is issued, the system uses the contents of the RELATIVE KEY data item to determine the record at which sequential processing is to begin.

If a value is placed in data-name-4, and a START statement is not issued, the value is ignored and processing begins with the first record in the file.

If a relative file is to be referenced by a START statement, you must specify the RELATIVE KEY clause for that file.

For EXTERNAL files, data-name-4 must reference an external data item and the RELATIVE KEY phrase in each associated file control entry must reference that same external data item in each case.

The ACCESS MODE IS RANDOM clause must not be specified for file-names specified in the USING or GIVING phrase of a SORT or MERGE statement.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.12 PASSWORD Clause

x The PASSWORD clause controls access to files.

x data-name-6, data-name-7 x Password data items. Each must be defined in the Working-Storage x Section (of the Data Division) as an alphanumeric item. The first 8 x characters are used as the password; a shorter field is padded with x blanks to 8 characters. Each password data item must be equivalent to x one that is externally defined.

x When the PASSWORD clause is specified, at object time the PASSWORD data x item must contain the valid password for this file before the file can be x successfully opened.

x Format 1 Considerations:

x The PASSWORD clause is not valid for QSAM or SAM sequential files.

x Format 2 and 3 Considerations:

x When the PASSWORD clause is specified, it must immediately follow the x RECORD KEY or ALTERNATE RECORD KEY data-name with which it is associated.

x For indexed files, if the file has been completely predefined to VSAM, x only the PASSWORD data item for the RECORD KEY need contain the valid x password before the file can be successfully opened at file creation time.

x For any other type of file processing (including the processing of dynamic x calls at file creation time through a COBOL object-time subroutine), every x PASSWORD data item for this file must contain a valid password before the x file can be successfully opened, whether or not all paths to the data are x used in this object program.

x For EXTERNAL files, data-name-6 and data-name-7 must reference external x data items. The PASSWORD clauses in each associated file control entry x must reference the same external data items.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.13 FILE STATUS Clause

The FILE STATUS clause monitors the execution of each input-output operation for the file.

When the FILE STATUS clause is specified, the system moves a value into the status key data item after each input-output operation that explicitly or implicitly refers to this file. The value indicates the status of | execution of the statement. (See "Status Key" in topic 2.8.9.1.1.)

data-name-1 The status key data item can be defined in the Data Division as either of the following:

o A 2-character alphanumeric item x o A 2-character numeric data item, with explicit or implicit USAGE x IS DISPLAY. It is treated as an alphanumeric item.

x Note: Data-name-1 must not contain the PICTURE symbol 'P'.

Data-name-1 must not be defined in the File Section. Data-name-1 can be qualified.

x The status key data item must not be variably located; that is, the x data item cannot follow a data item containing an OCCURS DEPENDING ON x clause.

x data-name-8 x Must be defined as a group item of 6 bytes in the Working-Storage or x Linkage Section of the Data Division.

x o The first 2 bytes of data-name-8 contain the VSAM return code in x binary notation. The value for this code is defined (by VSAM) as x 0, 8, or 12. x o The next 2 bytes of data-name-8 contain the VSAM function code in x binary notation. The value for this code is defined (by VSAM) as x 0, 1, 2, 3, 4, or 5. x o The last 2 bytes of data-name-8 contain the VSAM feedback code in x binary notation. The code value is 0 through 255.

x Specify data-name-8 only if the file is a VSAM file (that is, ESDS, x KSDS, RRDS). If VSAM returns a nonzero return code, data-name-8 is x set.

x If FILE STATUS is returned without having called VSAM, data-name-8 is x zero.

x If data-name-1 is set to zero, the content of data-name-8 is x undefined. VSAM status return code information is available without x transformation in the currently defined COBOL FILE STATUS code. User x identification and handling of exception conditions are allowed at the x same level as that defined by VSAM.

x Definitions of values in the return code, function code, and feedback x code fields are defined by VSAM. There are no COBOL additions, x deletions, or modifications to the VSAM definitions. For more x information, see VSAM Administration: Macro Instruction Reference or x VSE/VSAM Messages and Codes.

x Function code and feedback code are set if and only if the return code x is set to nonzero. If they are referenced when the return code is set x to zero, the contents of the fields are not dependable. For more x information, see VSAM Administration: Macro Instruction Reference or x VSE/VSAM Commands and Macros.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.14 I-O-CONTROL Paragraph

The I-O-CONTROL paragraph of the INPUT-OUTPUT SECTION specifies when checkpoints are to be taken and the storage areas to be shared by different files. This paragraph is optional in a COBOL program.

The keyword I-O-CONTROL can appear only once, at the beginning of the paragraph. The word I-O-CONTROL must begin in Area A, and must be followed by a separator period.

Each clause within the paragraph can be separated from the next by a separator comma or a separator semicolon. The order in which I-O-CONTROL paragraph clauses are written is not significant. The I-O-CONTROL paragraph ends with a separator period.

___ i-o-control-paragraph ___________________________________________________ | | | >>__I-O-CONTROL__.________________________________________________________> | | | <________________________________________ | | | |_______qsam-or-sam-i-o-control-entries_____|__.__| | | |__vsam-i-o-control-entries_________| | | | | >________________________________________________________________________>< | | |__sort-merge-i-o-control-entries__.__| | | | |_____________________________________________________________________________| @@ Diagram qsam-or-sam-i-o-control-entries ADAPTED. @@ Implemented Note (1) given below the diagram. @@ Diagram qsam-or-sam-i-o-control-entries ADAPTED. @@ Implemented Note (2) given below the diagram. ___ qsam-or-sam-i-o-control-entries _____________________________________________________________________________________________ | | | >>_____RERUN____________@1_____assignment-name-1_____________________integer-1__RECORDS______________________file-name-1_____>< | | | |__ON__| |__file-name-1________| |__EVERY__| |__END_______________REEL_____| |__OF__| | | | | |__OF__| |__UNIT__| | | | |__SAME_______________________________________file-name-3_____________________________________________________________| | | | |__RECORD__| |__AREA__| |__FOR__| | <__________________ | | | | | |____file-name-4__@2__|__| | | | | <_________________________________________ | | | |__MULTIPLE__FILE________________________________file-name-5_____________________________|____________________________| | | | |__TAPE__| |__CONTAINS__| |__POSITION__integer-2__| | | | | <______________ | | | |__{__APPLY__WRITE-ONLY______________file-name-2__|__}________________________________________________________________| | | |__ON__| | | | |_________________________________________________________________________________________________________________________________| ______________________________________________________________________________________________________________________ | | | Notes: | x | (1) ON is optional as an IBM extension. | | | x | (2) File-name-4 is optional as an IBM extension. | | | |______________________________________________________________________________________________________________________|

@@ Diagram vsam-i-o-control-entries ADAPTED. @@ Implemented Note (1) given below the diagram. @@ Diagram vsam-i-o-control-entries ADAPTED. @@ Implemented Note (2) given below the diagram. ___ vsam-i-o-control-entries _______________________________________________________________________________________ | | | >>_____RERUN____________@1_____assignment-name-1__________________integer-1__RECORDS____________file-name-1_____>< | | | |__ON__| |__file-name-1________| |__EVERY__| |__OF__| | | | |__SAME_______________________________________file-name-3________________________________________________| | | |__RECORD__| |__AREA__| |__FOR__| | <__________________ | | | |____file-name-4__@2__|__| | | | |____________________________________________________________________________________________________________________| ______________________________________________________________________________________________________________________ | | | Notes: | x | (1) ON is optional as an IBM extension. | | | x | (2) File-name-4 is optional as an IBM extension. | | | |______________________________________________________________________________________________________________________|

@@ Diagram sort-merge-i-o-control-entries ADAPTED. @@ Implemented Note (1) given below the diagram. ___ sort-merge-i-o-control-entries __________________________________________________________________ | | | >>________________________________________________________________________________________________> | | |__{__RERUN__ON__assignment-name-1__}__| | | | | <_________________________________________________________________________________________ | | >_____SAME_____RECORD________________________________file-name-3______________________________|__>< | | |__SORT________| |__AREA__| |__FOR__| | <__________________ | | | |__SORT-MERGE__| |____file-name-4__@1__|__| | | | |_____________________________________________________________________________________________________| ______________________________________________________________________________________________________________________ | | | Note: | x | (1) File-name-4 is optional as an IBM extension. | | | |______________________________________________________________________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.15 RERUN Clause

The RERUN clause specifies that checkpoint records are to be taken. Subject to the restrictions given with each phrase, more than one RERUN clause can be specified.

For information regarding the checkpoint data set definition and the checkpoint method required for complete compliance to the COBOL 85 | Standard, see VS COBOL II Application Programming Guide for MVS and CMS or | VS COBOL II Application Programming Guide for VSE.

| Note: The RERUN clause is an obsolete element and will be deleted from | the next revision of the COBOL 85 Standard.

The RERUN clause cannot be used with files that have been defined with the EXTERNAL attribute.

file-name-1 Must be a sequentially organized file.

assignment-name-1 The external data set for the checkpoint file. It must not be the same assignment-name as that specified in any ASSIGN clause throughout the entire program, including contained and containing programs. For QSAM files, it has the format:

___ Format--QSAM File ______________________________________________ | | | >>______________________name____________________________________>< | | |_label-_| |_S-_| | | | |____________________________________________________________________| That is, it must be a QSAM file. It must reside on a tape or direct access device. See also Appendix E, "ASCII Considerations" in topic APPENDIX1.5.

Format 1 and 2 considerations:

The file named in the RERUN clause must be a file defined in the same program as the I-O-CONTROL paragraph, even if the file is defined as GLOBAL.

x Format 3 considerations:

x When the RERUN clause is specified in the I-O-CONTROL paragraph, x checkpoint records are written at logical intervals determined by the x sort/merge program during execution of each SORT or MERGE statement in x the program. When it is omitted, checkpoint records are not written.

x There can be only one Format 3 I-O-CONTROL paragraph in a program, and x it cannot be specified in contained programs. It will have a global x effect on all SORT and MERGE statements in the program unit.

x For SAM files, use job control statements and the RERUN EVERY x integer-1 RECORDS clause. You must associate each RERUN clause with a x particular COBOL file by using the ASSIGN clause. It has the x following format for SAM files:

x ___ Format--SAM File _______________________________________________ x | | x | >>_______________________name___________________________________>< | x | |_SYSnnn-_| |_S-_| | | | |____________________________________________________________________| x A detailed explanation of the ASSIGN clause for SAM files is provided x under "ASSIGN Clause" in topic 2.4.3. For more detailed information x about defining checkpoint files for processing SAM files, see x VS COBOL II Application Programming Guide for VSE.

EVERY integer-1 RECORDS A checkpoint record is to be written for every integer-1 record in file-name-1 that is processed.

When multiple integer-1 RECORDS phrases are specified, no two of them can specify the same file-name-1.

When the integer-1 RECORDS phrase is specified, assignment-name-1 must be given in the RERUN clause.

EVERY END OF REEL/UNIT A checkpoint record is to be written whenever end-of-volume for file-name-1 occurs. The terms REEL and UNIT are interchangeable.

Note: This clause is not supported under VSE; if you code this clause in your program, it will be treated as a comment.

When multiple END OF REEL/UNIT phrases are specified, no two of them can specify the same file-name-1.

The END OF REEL/UNIT phrase can only be used if file-name-1 is a sequentially organized file.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.16 SAME AREA Clause

The SAME AREA clause specifies that two or more files, that do not represent sort or merge files, are to use the same main storage area during processing.

The files named in a SAME AREA clause need not have the same organization or access.

file-name-3, file-name-4 Must be specified in the FILE-CONTROL paragraph of the same program. File-name-3 and file-name-4 cannot reference an external file connector.

o For QSAM or SAM files, the SAME clause is treated as documentation. o For VSAM files, the SAME clause is treated as if equivalent to the SAME RECORD AREA clause.

More than one SAME AREA clause can be included in a program. However:

o A specific file-name must not appear in more than one SAME AREA clause.

o If one or more file-names of a SAME AREA clause appear in a SAME RECORD AREA clause, all the file-names in that SAME AREA clause must appear in that SAME RECORD AREA clause. However, the SAME RECORD AREA clause can contain additional file-names that do not appear in the SAME AREA clause.

o The rule that in the SAME AREA clause only one file can be open at one time takes precedence over the SAME RECORD AREA rule that all the files can be open at the same time.

x Only one file is required in the SAME AREA clause.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.17 SAME RECORD AREA Clause

The SAME RECORD AREA clause specifies that two or more files are to use the same main storage area for processing the current logical record. All of the files can be open at the same time. A logical record in the shared storage area is considered to be both of the following:

o A logical record of each opened output file in the SAME RECORD AREA clause

o A logical record of the most recently read input file in the SAME RECORD AREA clause.

More than one SAME RECORD AREA clause can be included in a program. However:

o A specific file-name must not appear in more than one SAME RECORD AREA clause.

o If one or more file-names of a SAME AREA clause appear in a SAME RECORD AREA clause, all the file-names in that SAME AREA clause must appear in that SAME RECORD AREA clause. However, the SAME RECORD AREA clause can contain additional file-names that do not appear in the SAME AREA clause.

o The rule that in the SAME AREA clause only one file can be open at one time takes precedence over the SAME RECORD AREA rule that all the files can be open at the same time.

o If the SAME RECORD AREA clause is specified for several files, the record description entries or the file description entries for these files must not include the GLOBAL clause.

x o The SAME RECORD AREA clause must not be specified when the RECORD x CONTAINS 0 CHARACTERS clause is specified.

The files named in the SAME RECORD AREA clause need not have the same organization or access.

x Only one file is required in the SAME RECORD AREA clause.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.18 SAME SORT AREA Clause

The SAME SORT AREA clause is syntax-checked, but is treated as documentation.

file-name-3, file-name-4 Must be specified in the FILE-CONTROL paragraph of the same program. File-name-3 and file-name-4 cannot reference an external file connector.

When the SAME SORT AREA clause is specified, at least one file-name specified must name a sort file. Files that are not sort files can also be specified. The following rules apply:

o More than one SAME SORT AREA clause can be specified. However, a given sort file must not be named in more than one such clause.

o If a file that is not a sort file is named in both a SAME AREA clause and in one or more SAME SORT AREA clauses, all the files in the SAME AREA clause must also appear in that SAME SORT AREA clause.

o Files named in a SAME SORT AREA clause need not have the same organization or access.

o Files named in a SAME SORT AREA clause that are not sort files do not share storage with each other unless the user names them in a SAME AREA or SAME RECORD AREA clause.

During the execution of a SORT or MERGE statement that refers to a sort or merge file named in this clause, any nonsort or nonmerge files associated with file-names named in this clause must not be in the open mode.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.19 SAME SORT-MERGE AREA Clause

The SAME SORT-MERGE AREA clause is equivalent to the SAME SORT AREA clause.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.20 MULTIPLE FILE TAPE Clause

The MULTIPLE FILE TAPE clause (Format 1) specifies that two or more files share the same physical reel of tape.

| Note: The MULTIPLE FILE TAPE clause is an obsolete element and will be | deleted from the next revision of the COBOL 85 Standard.

| This clause is syntax-checked, but is treated as documentation. Under MVS, the function is performed by the system through the LABEL parameter of the DD statement. Under VSE, the function is performed by JCL statements that control file retrieval. For more information, see VS COBOL II Application Programming Guide for VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.4.21 APPLY WRITE-ONLY Clause

x The APPLY WRITE-ONLY clause optimizes buffer and device space allocation x for files that have standard sequential organization, have variable-length x records, and are blocked. If you specify this phrase, the buffer is x truncated only when the space available in the buffer is smaller than the x size of the next record. Otherwise, the buffer is truncated when the x space remaining in the buffer is smaller than the maximum record size for x the file.

x APPLY WRITE-ONLY is effective only for QSAM or SAM files.

x file-name-2 x Each file must have standard sequential organization and must be x opened for output.

x APPLY WRITE-ONLY clauses must agree among corresponding external file x description entries. For an alternate method of achieving the APPLY x WRITE-ONLY results, see the description of the AWO compiler option in x VS COBOL II Application Programming Guide for MVS and CMS or VS COBOL II x Application Programming Guide for VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5 Data Division

The Data Division of a COBOL source program describes, in a structured manner, all the data to be processed by the object program. The Data Division is optional in a COBOL source program.

This chapter outlines the structure of the Data Division and explains the types of data and how they are related in a COBOL program.

The following two sections describe how to code the entries that define the data:

o Data Division--File Description Entries o Data Division--Data Description Entry.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.1 Data Division Structure

The Data Division is divided into three sections:

File Section Defines the structure of data files (including sort-merge files).

Working-Storage Section Describes records and subordinate data items that are not part of data files but are developed and processed by the program.

Linkage Section Describes data made available by another program. It appears in the called program and describes data items that are referred to by the calling and the called programs.

Each section has a specific logical function within a COBOL source program, and each can be omitted from the source program when that logical function is not needed. If included, the sections must be written in the order shown.

___ data-division _____________ | | | >>__DATA__DIVISION__._______> | | | | >___data-division-content__>< | | | |_______________________________| @@ Diagram data-division-content EXTRACTED from diagram data-division. @@ Identified content of the division as referred to elsewhere. @@ Diagram data-division-content ADAPTED. @@ record-... and data-item-description-entry treated equally. ___ data-division-content ________________________________________________________________________ | | | >>_____________________________________________________________________________________________> | | |__FILE__SECTION__.____________________________________________________________________| | | | <________________________________________________________ | | | | <___________________________ | | | | |____file-description-entry____record-description-entry__|__|__| | | | | >______________________________________________________________________________________________> | | |__WORKING-STORAGE__SECTION__._____________________________________| | | | <_________________________ | | | |____data-description-entry__|__| | | | | >_____________________________________________________________________________________________>< | | |__LINKAGE__SECTION__._____________________________________| | | | <_________________________ | | | |____data-description-entry__|__| | | | |__________________________________________________________________________________________________| @@ Diagram record-description-entry ADDED after diagram data-division-content. @@ record-description-entry as a form of data-description-entry (see beginning of 2.7). ___ record-description-entry ___ | | | >>__data-description-entry__>< | | | |________________________________| @@ Diagram data-item-description-entry ADDED after diagram data-division-content. @@ data-item-description-entry as a form of data-description-entry (see beginning of 2.7). ___ data-item-description-entry ___ | | | >>__data-description-entry_____>< | | | |___________________________________|

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.1.1 File Section

The File Section defines the structure of data files. The File Section must begin with the header FILE SECTION, followed by a separator period.

file-description-entry Represents the highest level of organization in the File Section. It provides information about the physical structure and identification of a file, and gives the record-name(s) associated with that file. For the format and the clauses required in a file description entry, see "Data Division--File Description Entries" in topic 2.6.

record-description-entry A set of data description entries (described in "Data Division--Data Description Entry" in topic 2.7) that describe the particular record(s) contained within a particular file.

More than one record description entry can be specified; each is an alternative description of the same record storage area.

Data areas described in the File Section are not available for processing unless the file containing the data area is open.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.1.2 Working-Storage Section

   The Working-Storage Section describes data records that are not part of 
   data files but are developed and processed by the program.  It also 
 | describes data items whose values are assigned in the source program.  The 
   Working-Storage Section can also describe external data records which are 
   shared by programs throughout the run-unit. 

The Working-Storage Section contains record description entries and data description entries for independent data items, called data item description entries.

The Working-Storage Section must begin with the section header WORKING-STORAGE SECTION, followed by a separator period.

record-description-entry Data entries in the Working-Storage Section that bear a definite hierarchic relationship to one another must be grouped into records | structured by level number. For more information, see "Data | Division--Data Description Entry" in topic 2.7.

data-item-description-entry Independent items in the Working-Storage Section that bear no hierarchic relationship to one another need not be grouped into records, provided that they do not need to be further subdivided. Instead, they are classified and defined as independent elementary items. Each is defined in a separate data-item description entry that | begins with either the level number 77 or 01. For more information, | see "Data Division--Data Description Entry" in topic 2.7.

All clauses that are used in record descriptions in the File Section as well as the VALUE and EXTERNAL clauses (which cannot be specified in record description entries in the File section) can be used in record descriptions in the Working-Storage Section.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.1.3 Linkage Section

The Linkage Section describes data made available from another program.

record-description-entry See "Working-Storage Section" in topic 2.5.1.2 for description.

data-item-description-entry See "Working-Storage Section" in topic 2.5.1.2 for description.

Record description entries and data item description entries in the Linkage Section provide names and descriptions, but storage within the program is not reserved because the data area exists elsewhere.

Any data description clause can be used to describe items in the Linkage Section with the following exceptions:

| o The VALUE clause is treated as documentation in the Linkage Section | for other than condition-name entries.

o The EXTERNAL clause cannot be specified in the Linkage Section

o The GLOBAL clause cannot be specified in the Linkage Section


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.2 Data Types

Two types of data can be processed: file data and program data.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.2.1 File Data

File data is contained in files. (See "File Section" in topic 2.6.1.) A file is a collection of data records existing on some input-output device. A file can be considered as a group of physical records; it can also be considered as a group of logical records. The Data Division describes the relationship between physical and logical records.

A physical record is a unit of data that is treated as an entity when moved into or out of storage. The size of a physical record is determined by the particular input-output device on which it is stored. The size does not necessarily have a direct relationship to the size or content of the logical information contained in the file.

A logical record is a unit of data whose subdivisions have a logical relationship. A logical record may itself be a physical record (that is, be contained completely within one physical unit of data); several logical records may be contained within one physical record, or one logical record may extend across several physical records.

File description entries specify the physical aspects of the data (such as the size relationship between physical and logical records, the size and name(s) of the logical record(s), labeling information, and so forth).

Record description entries describe the logical records in the file, including the category and format of data within each field of the logical record, different values the data might be assigned, and so forth.

After the relationship between physical and logical records has been established, only logical records are made available to you. For this reason, a reference in this manual to "records" means logical records, unless the term "physical records" is used.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.2.2 Program Data

Program data is created by a program, instead of being read from a file.

The concept of logical records applies to program data as well as to file data. Program data can thus be grouped into logical records, and be defined by a series of record description entries. Items that need not be so grouped can be defined in independent data description entries (called data item description entries).


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.3 Data Relationships

The relationships among all data to be used in a program are defined in the Data Division, through a system of level indicators and level-numbers.

A level indicator, with its descriptive entry, identifies each file in a program. Level indicators represent the highest level of any data hierarchy with which they are associated; FD is the file description level indicator and SD is the sort-merge file description level indicator.

A level-number, with its descriptive entry, indicates the properties of specific data. Level-numbers can be used to describe a data hierarchy; they can indicate that this data has a special purpose, and while they can be associated with (and subordinate to) level indicators, they can also be used independently to describe internal data or data common to two or more programs. (See "Level-Numbers" in topic 2.7.1 for level-number rules.)

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.3.1 Levels of Data

   After a record has been defined, it can be subdivided to provide more 
   detailed data references. 

For example, in a customer file for a department store, one complete record could contain all data pertaining to one customer. Subdivisions within that record could be: customer name, customer address, account number, department number of sale, unit amount of sale, dollar amount of sale, previous balance, plus other pertinent information.

The basic subdivisions of a record (that is, those fields not further subdivided) are called elementary items. Thus, a record can be made up of a series of elementary items, or it can itself be an elementary item.

It may be necessary to refer to a set of elementary items; thus, elementary items can be combined into group items. Groups themselves can be combined into a more inclusive group that contains one or more subgroups. Thus, within one hierarchy of data items, an elementary item can belong to more than one group item.

A system of level-numbers specifies the organization of elementary and group items into records. Special level-numbers are also used; they identify data items used for special purposes.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.3.2 Levels of Data in a Record Description Entry

Each group and elementary item in a record requires a separate entry, and each must be assigned a level-number.

A level-number is a 1- or 2-digit integer between 01 and 49, or one of three special level-numbers: 66, 77, or 88. The following level-numbers are used to structure records:

01 This level-number specifies the record itself, and is the most inclusive level-number possible. A level-01 entry can be either a group item or an elementary item. It must begin in Area A.

02-49 These level-numbers specify group and elementary items within a record. They can begin in Area A or Area B. Less inclusive data items are assigned higher (not necessarily consecutive) level-numbers in this series.

A group item includes all group and elementary items following it, until a level-number less than or equal to the level-number of this group is encountered.

All elementary or group items immediately subordinate to one group item must be assigned identical level-numbers higher than the level-number of this group item.

Figure 3 illustrates the concept. Note that all groups immediately subordinate to the level-01 entry have the same level-number. Note also that elementary items from different subgroups do not necessarily have the same level numbers, and that elementary items can be specified at any level within the hierarchy.


The COBOL record-description entry written as follows is subdivided as indicated below:

01 RECORD-ENTRY. <______This entry includes_______ | 05 GROUP-1. <______This entry includes_____ | | | 10 SUBGROUP-1. <________This entry includes___ | | | | | 15 ELEM-1 PIC... . | | | 15 ELEM-2 PIC... . v | | | | 10 SUBGROUP-2. <________This entry includes___ | | | | | 15 ELEM-3 PIC... . | | | 15 ELEM-4 PIC... . v v | | 05 GROUP-2. <________This entry includes___ | | | 15 SUBGROUP-3. <_________This entry includes_____ | | | | | 25 ELEM-5 PIC... . | | | 25 ELEM-6 PIC... . v | | | | | 15 ELEM-7 PIC... . This entry includes itself. v | | | | 05 ELEM-8 PIC... . This entry includes itself. v

The storage arrangement of the record-description entry is illustrated below:

|<______________________________RECORD_ENTRY___________________________>| | | | | |<_____________GROUP_1_____________>|<________GROUP_2_________>| | | | | | |<__SUBGROUP_1___>|<__SUBGROUP_2___>|<___SUBGROUP_3__>| | |

_______________________________________________________________________ | | ELEM_1 | ELEM_2 | ELEM_3 | ELEM_4 | ELEM_5 | ELEM_6 | ELEM-7 | ELEM_8 | |________|________|________|________|________|________|________|________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document. Figure 3. Levels in a Record Description

x VS COBOL II accepts nonstandard level-numbers that are not identical to x others at the same level. For example, the following two record x description entries are equivalent:

01 EMPLOYEE-RECORD. 05 EMPLOYEE-NAME. 10 FIRST-NAME PICTURE X(10). 10 LAST-NAME PICTURE X(10). 05 EMPLOYEE-ADDRESS. 10 STREET PICTURE X(10). 10 CITY PICTURE X(10). 01 EMPLOYEE-RECORD. 05 EMPLOYEE-NAME. 10 FIRST-NAME PICTURE X(10). 10 LAST-NAME PICTURE X(10). 04 EMPLOYEE-ADDRESS. 08 STREET PICTURE X(10). 08 CITY PICTURE X(10).


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.3.3 Special Level-Numbers

Special level-numbers identify items that do not structure a record. The special level-numbers are:

66 Identifies items that must contain a RENAMES clause; such items regroup previously defined data items.

(For details, see "RENAMES Clause" in topic 2.7.9.)

77 Identifies data item description entries -- independent Working-Storage or Linkage Section items that are not subdivisions of other items, and are not subdivided themselves. Level-77 items must begin in Area A.

88 Identifies any condition-name entry that is associated with a particular value of a conditional variable. (For details, see "VALUE Clause" in topic 2.7.13.)

Note: Level-77 and level-01 entries in the Working-Storage and Linkage Sections that are referenced in the program must be given unique data-names, because neither can be qualified. Subordinate data-names that are referenced in the program must be either uniquely defined, or made unique through qualification. Unreferenced data-names need not be uniquely defined.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.3.4 Indentation

Successive data description entries can begin in the same column as preceding entries, or can be indented. Indentation is useful for documentation, but does not affect the action of the compiler. For indentation guidelines, see VS COBOL II Application Programming Guide for MVS and CMS or VS COBOL II Application Programming Guide for VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.3.5 Classes and Categories of Data

All data used in a COBOL program can be divided into classes and categories.

Every group item belongs to the alphanumeric class, even if the subordinate elementary items belong to another class.

Every elementary item in a program belongs to one of the classes as well as to one of the categories. Table 8 shows the relationship among data classes and categories.

_____________________________________________________________ | Table 8. Classes and Categories of Data | |_____________________________________________________________| | Level of Item | Class | Category | |________________|________________|___________________________| | Elementary | Alphabetic | Alphabetic | | |________________|___________________________| | | Numeric | Numeric | | | |___________________________| x | | | Internal Floating-point | | | |___________________________| x | | | External Floating-point | | |________________|___________________________| | | Alphanumeric | Numeric-Edited | | | |___________________________| | | | Alphanumeric-Edited | | | |___________________________| | | | Alphanumeric | | | |___________________________| x | | | DBCS | |________________|________________|___________________________| | Group | Alphanumeric | Alphabetic | | | |___________________________| | | | Numeric | | | |___________________________| x | | | Internal Floating-point | | | |___________________________| x | | | External Floating-point | | | |___________________________| | | | Numeric-Edited | | | |___________________________| | | | Alphanumeric-Edited | | | |___________________________| | | | Alphanumeric | | | |___________________________| x | | | DBCS | |________________|________________|___________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.3.6 Alignment Rules

The standard alignment rules for positioning data in an elementary item depend on the category of a receiving item (that is, an item into which the data is moved; see "Elementary Moves" in topic 3.22.1).

Numeric: For such receiving items, the following rules apply:

1. The data is aligned on the assumed decimal point and, if necessary, truncated or padded with zeros. (An assumed decimal point is one that has logical meaning but that does not exist as an actual character in the data.)

2. If an assumed decimal point is not explicitly specified, the receiving item is treated as though an assumed decimal point is specified immediately to the right of the field. The data is then treated according to the preceding rule.

Numeric-edited: The data is aligned on the decimal point, and (if necessary) truncated or padded with zeros at either end, except when editing causes replacement of leading zeros.

x Internal Floating-point: A decimal point is assumed immediately to the x left of the field. The data is aligned then on the leftmost digit x position following the decimal point, with the exponent adjusted x accordingly.

x External Floating-point: The data is aligned on the leftmost digit x position; the exponent is adjusted accordingly.

x Alphanumeric, Alphanumeric-Edited, Alphabetic, DBCS: For these receiving items, the following rules apply:

1. The data is aligned at the leftmost character position, and (if necessary) truncated or padded with spaces at the right.

2. If the JUSTIFIED clause is specified for this receiving item, the above rule is modified, as described in "JUSTIFIED Clause" in topic 2.7.5.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.3.7 Standard Data Format

COBOL makes data description as machine independent as possible. For this reason, the properties of the data are described in relation to a standard data format rather than a machine-oriented format.

The standard data format uses the decimal system to represent numbers, no matter what base is used by the system, and uses all the characters of the character set of the computer to represent nonnumeric data.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.3.8 Character-String and Item Size

In your program, the size of an elementary item is determined through the number of character positions specified in its PICTURE character-string. In storage, however, the size is determined by the actual number of bytes the item occupies, as determined by the combination of its PICTURE character-string and its USAGE clause.

x For internal floating-point items, the size of the item in storage is x determined by its USAGE clause. USAGE COMPUTATIONAL-1 reserves 4 bytes of x storage for the item; USAGE COMPUTATIONAL-2 reserves 8 bytes of storage.

Normally, when an arithmetic item is moved from a longer field into a shorter one, the compiler truncates the data to the number of characters represented in the shorter item's PICTURE character-string.

For example, if a sending field with PICTURE S99999, and containing the value +12345, is moved to a BINARY receiving field with PICTURE S99, the data is truncated to +45. For additional information see "USAGE Clause" in topic 2.7.12.

x The TRUNC compiler option may affect the value of a binary numeric item. x For information on TRUNC, see VS COBOL II Application Programming Guide x for MVS and CMS or VS COBOL II Application Programming Guide for VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.3.9 Signed Data

There are two categories of algebraic signs used in VS COBOL II: operational signs and editing signs.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.3.10 Operational Signs

Operational signs are associated with signed numeric items, and indicate their algebraic properties. The internal representation of an algebraic sign depends on the item's USAGE clause, its SIGN clause (if present), and on the operating environment involved. (For further details about the internal representation see "USAGE Clause" in topic 2.7.12.) Zero is considered a unique value, regardless of the operational sign. An unsigned field is always assumed to be either positive or zero.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.5.3.11 Editing Signs

Editing signs are associated with numeric-edited items; editing signs are PICTURE symbols that identify the sign of the item in edited output.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.6 Data Division--File Description Entries

In a COBOL program, the File Description (FD) Entry (or Sort File Description (SD) Entry for sort/merge files) represents the highest level of organization in the File Section. The order in which the optional clauses follow the FD or SD entry is not important.

@@ Diagram fd-entry-sequential-files ADAPTED. @@ Enabled qualified instead of plain data names. @@ Diagram fd-entry-sequential-files FOLDED according to external-clause. @@ Factored out clause for conciseness. @@ Diagram fd-entry-sequential-files FOLDED according to global-clause. @@ Factored out clause for conciseness. @@ Diagram fd-entry-sequential-files FOLDED according to block-contains-clause. @@ Factored out clause for conciseness. @@ Diagram fd-entry-sequential-files FOLDED according to record-clause. @@ Factored out clause for conciseness. @@ Diagram fd-entry-sequential-files FOLDED according to label-records-clause. @@ Factored out clause for conciseness. @@ Diagram fd-entry-sequential-files FOLDED according to value-of-clause. @@ Factored out clause for conciseness. @@ Diagram fd-entry-sequential-files FOLDED according to data-records-clause. @@ Factored out clause for conciseness. @@ Diagram fd-entry-sequential-files FOLDED according to linage-clause. @@ Factored out clause for conciseness. @@ Diagram fd-entry-sequential-files FOLDED according to recording-mode-clause. @@ Factored out clause for conciseness. @@ Diagram fd-entry-sequential-files FOLDED according to code-set-clause. @@ Factored out clause for conciseness. ___ fd-entry-sequential-files ____________________________________________________________________ | | | >>__FD__file-name-1____________________________________________________________________________> | | |__external-clause__| |__global-clause__| |__block-contains-clause__| | | | | >______________________________________________________________________________________________> | | |__record-clause__| |__label-records-clause__| | | | | >______________________________________________________________________________________________> | | |__value-of-clause__| |__data-records-clause__| | | | | >______________________________________________________________________________________________> | | |__linage-clause__| |__recording-mode-clause__| | | | | >__________________________.__________________________________________________________________>< | | |__code-set-clause__| | | | |__________________________________________________________________________________________________| @@ Diagram seq-clause-a DELETED. @@ Not needed anymore as a result of refactoring. @@ Diagram seq-clause-a FOLDED according to record-varying-clause. @@ Factored out clause for conciseness. @@ Diagram seq-clause-b DELETED. @@ Not needed anymore as a result of refactoring. @@ Diagram seq-clause-b FOLDED according to linage-area-clause. @@ Factored out clause for conciseness.

@@ Diagram fd-entry-relative-indexed-files ADAPTED. @@ Enabled qualified instead of plain data names. @@ Diagram fd-entry-relative-indexed-files FOLDED according to external-clause. @@ Factored out clause for conciseness. @@ Diagram fd-entry-relative-indexed-files FOLDED according to global-clause. @@ Factored out clause for conciseness. @@ Diagram fd-entry-relative-indexed-files FOLDED according to block-contains-clause. @@ Factored out clause for conciseness. @@ Diagram fd-entry-relative-indexed-files UNFOLDED according to ri-clause. @@ Inline clause for conciseness. @@ Diagram fd-entry-relative-indexed-files FOLDED according to record-clause. @@ Factored out clause for conciseness. @@ Diagram fd-entry-relative-indexed-files FOLDED according to value-of-clause. @@ Factored out clause for conciseness. @@ Diagram fd-entry-relative-indexed-files FOLDED according to data-records-clause. @@ Factored out clause for conciseness. ___ fd-entry-relative-indexed-files _________________________________ | | | >>__FD__file-name-1_______________________________________________> | | |__external-clause__| |__global-clause__| | | | | >_________________________________________________________________> | | |__block-contains-clause__| | | | | >_________________________________________________________________> | | |__record-clause__| | | | | >_________________________________________________________________> | | |__LABEL_____RECORD____________________STANDARD_____| | | | |__IS__| | |__OMITTED___| | | |__RECORDS_____________| | | |__ARE__| | | | | >_________________________________________________________________> | | |__value-of-clause__| | | | | >______________________________._________________________________>< | | |__data-records-clause__| | | | |_____________________________________________________________________| @@ Diagram ri-clause DELETED. @@ Not needed anymore as a result of refactoring. @@ Diagram ri-clause FOLDED according to record-varying-clause. @@ Factored out clause for conciseness.

@@ Diagram sd-entry-sort-merge-files ADAPTED. @@ Enabled qualified instead of plain data names. @@ Diagram sd-entry-sort-merge-files FOLDED according to block-contains-clause. @@ Factored out clause for conciseness. @@ Diagram sd-entry-sort-merge-files UNFOLDED according to sd-clause-a. @@ Inline clause for conciseness. @@ Diagram sd-entry-sort-merge-files FOLDED according to record-clause. @@ Factored out clause for conciseness. @@ Diagram sd-entry-sort-merge-files FOLDED according to value-of-clause. @@ Factored out clause for conciseness. @@ Diagram sd-entry-sort-merge-files FOLDED according to data-records-clause. @@ Factored out clause for conciseness. @@ Diagram sd-entry-sort-merge-files UNFOLDED according to sd-clause-b. @@ Inline clause for conciseness. @@ Diagram sd-entry-sort-merge-files FOLDED according to linage-clause. @@ Factored out clause for conciseness. @@ Diagram sd-entry-sort-merge-files FOLDED according to code-set-clause. @@ Factored out clause for conciseness. ___ sd-entry-sort-merge-files ___________________________________________________ | | | >>__SD__file-name-1___________________________________________________________> | | | | >_____________________________________________________________________________> | | |__record-clause__| | | | | >______________________________{______________________________________________> | | |__data-records-clause__| | | | | >_____________________________________________________________________________> | | |__block-contains-clause__| | | | | >_____________________________________________________________________________> | | |__LABEL_____RECORD____________________STANDARD_______________________| | | | |__IS__| | |__OMITTED_____________________| | | |__RECORDS_____________| | <________________________ | | | |__ARE__| |____qualified-data-name-2__|__| | | | | >_____________________________________________________________________________> | | |__value-of-clause__| | | | | >_____________________________________________________________________________> | | |__linage-clause__| | | | | >__________________________}__.______________________________________________>< | | |__code-set-clause__| | | | |_________________________________________________________________________________| @@ Diagram sd-clause-a DELETED. @@ Not needed anymore as a result of refactoring. @@ Diagram sd-clause-a FOLDED according to record-varying-clause. @@ Factored out clause for conciseness. @@ Diagram sd-clause-b DELETED. @@ Not needed anymore as a result of refactoring. @@ Diagram sd-clause-b FOLDED according to linage-area-clause. @@ Factored out clause for conciseness.

Subtopics:


@@ Diagram file-description-entry ADDED at the end of this section.
@@ Unified format for file (and sort) description entries.

    ___ file-description-entry _____________________
   |                                                |
   | >>_____FD_____file-name-1__file-clauses__.__>< |
   |     |__SD__|                                   |
   |                                                |
   |________________________________________________|


@@ Diagram file-clauses ADDED after diagram file-description-entry.
@@ Capture the above subtopics as permutation phrase.

    ___ file-clauses ____________________
   |                                     |
   | ||_______________________________|| |
   |     |__external-clause__|           |
   |                                     |
   | ||_______________________________|| |
   |     |__global-clause__|             |
   |                                     |
   | ||_______________________________|| |
   |     |__block-contains-clause__|     |
   |                                     |
   | ||_______________________________|| |
   |     |__record-clause__|             |
   |                                     |
   | ||_______________________________|| |
   |     |__label-records-clause__|      |
   |                                     |
   | ||_______________________________|| |
   |     |__value-of-clause__|           |
   |                                     |
   | ||_______________________________|| |
   |     |__data-records-clause__|       |
   |                                     |
   | ||_______________________________|| |
   |     |__linage-clause__|             |
   |                                     |
   | ||_______________________________|| |
   |     |__recording-mode-clause__|     |
   |                                     |
   | ||_______________________________|| |
   |     |__code-set-clause__|           |
   |                                     |
   |_____________________________________|


@@ Diagram external-clause ADDED after diagram file-clauses.
@@ Used elsewhere for folding.

    ___ external-clause ________
   |                            |
   | >>____________EXTERNAL__>< |
   |     |__IS__|               |
   |                            |
   |____________________________|


@@ Diagram global-clause ADDED after diagram file-clauses.
@@ Used elsewhere for folding.

    ___ global-clause ________
   |                          |
   | >>____________GLOBAL__>< |
   |     |__IS__|             |
   |                          |
   |__________________________|


@@ Diagram block-contains-clause ADDED after diagram file-clauses.
@@ Used elsewhere for folding.

@@ Diagram block-contains-clause ADAPTED.
@@ Made ( "CHARACTERS" | "RECORDS" ) option to allow for default as of 2.6.4

@@ Diagram block-contains-clause ADAPTED.
@@ Added RECORD as option for RECORDS as found in VS Cobol II code.

    ___ block-contains-clause _______________________________________________________
   |                                                                                 |
   | >>__BLOCK_______________________________________integer-2____________________>< |
   |            |__CONTAINS__|  |__integer-1__TO__|             |__CHARACTERS__|     |
   |                                                            |__RECORDS_____|     |
   |                                                            |__RECORD______|     |
   |                                                                                 |
   |_________________________________________________________________________________|


@@ Diagram record-clause ADDED after diagram file-clauses.
@@ Used elsewhere for folding.

@@ Diagram record-clause UNFOLDED according to seq-clause-a.
@@ Inline clause for conciseness.

    ___ record-clause _____________________________________________________________________________
   |                                                                                               |
   | >>__RECORD_____________________integer-3___________________________________________________>< |
   |             |  |__CONTAINS__|             |__CHARACTERS__|                              |     |
   |             |__________________integer-4__TO__integer-5_________________________________|     |
   |             |  |__CONTAINS__|                            |__CHARACTERS__|               |     |
   |             |__record-varying-clause____________________________________________________|     |
   |                                       |__DEPENDING____________qualified-data-name-1__|        |
   |                                                     |__ON__|                                  |
   |                                                                                               |
   |_______________________________________________________________________________________________|


@@ Diagram record-varying-clause ADDED after diagram file-clauses.
@@ Used elsewhere for folding.

    ___ record-varying-clause __________________________________________________
   |                                                                            |
   | >>____________VARYING____________________________________________________> |
   |     |__IS__|           |__IN__|  |__SIZE__|                                |
   |                                                                            |
   | >_______________________________________________________________________>< |
   |     |______________integer-6__|  |__TO__integer-7__|  |__CHARACTERS__|     |
   |        |__FROM__|                                                          |
   |                                                                            |
   |____________________________________________________________________________|


@@ Diagram label-records-clause ADDED after diagram file-clauses.
@@ Captured most general format that is used in the above diagrams.

    ___ label-records-clause ________________________________________________________
   |                                                                                 |
   | >>__LABEL_____RECORD____________________STANDARD_____________________________>< |
   |            |          |__IS__|    |  |__OMITTED___________________________|     |
   |            |__RECORDS_____________|  |     <________________________      |     |
   |                        |__ARE__|     |__{____qualified-data-name-2__|__}__|     |
   |                                                                                 |
   |_________________________________________________________________________________|


@@ Diagram value-of-clause ADDED after diagram file-clauses.
@@ Used elsewhere for folding.

    ___ value-of-clause __________________________________________________________
   |                                                                              |
   |                <_______________________________________________________      |
   | >>__VALUE__OF____system-name-1_______________qualified-data-name-3_____|__>< |
   |                                 |__IS__|  |__literal-1______________|        |
   |                                                                              |
   |______________________________________________________________________________|


@@ Diagram data-records-clause ADDED after diagram file-clauses.
@@ Used elsewhere for folding.

    ___ data-records-clause ____________________________________________
   |                                                                    |
   |                                     <________________________      |
   | >>__DATA_____RECORD___________________qualified-data-name-4__|__>< |
   |           |          |__IS__|    |                                 |
   |           |__RECORDS_____________|                                 |
   |                       |__ARE__|                                    |
   |                                                                    |
   |____________________________________________________________________|


@@ Diagram linage-clause ADDED after diagram file-clauses.
@@ Used elsewhere for folding.

@@ Diagram linage-clause UNFOLDED according to seq-clause-b.
@@ Inline clause for conciseness.

    ___ linage-clause ______________________________________________________________________
   |                                                                                        |
   | >>__LINAGE_______________qualified-data-name-5__________________linage-area-clause__>< |
   |             |__IS__|  |__integer-8______________|  |__LINES__|                         |
   |                                                                                        |
   |________________________________________________________________________________________|


@@ Diagram linage-area-clause ADDED after diagram file-clauses.
@@ Used elsewhere for folding.

    ___ linage-area-clause _________________________________________
   |                                                                |
   | >>___________________________________________________________> |
   |     |______________FOOTING_______________data-name-6_____|     |
   |        |__WITH__|           |__AT__|  |__integer-9____|        |
   |                                                                |
   | >____________________________________________________________> |
   |     |_________________________TOP_____data-name-7_____|        |
   |        |__LINES__|  |__AT__|       |__integer-10___|           |
   |                                                                |
   | >___________________________________________________________>< |
   |     |_________________________BOTTOM_____data-name-8_____|     |
   |        |__LINES__|  |__AT__|          |__integer-11___|        |
   |                                                                |
   |________________________________________________________________|


@@ Diagram recording-mode-clause ADDED after diagram file-clauses.
@@ Used elsewhere for folding.

    ___ recording-mode-clause ___________________________
   |                                                     |
   | >>__{__RECORDING________________________mode__}__>< |
   |                   |__MODE__|  |__IS__|              |
   |                                                     |
   |_____________________________________________________|


@@ Diagram code-set-clause ADDED after diagram file-clauses.
@@ Used elsewhere for folding.

    ___ code-set-clause _______________________
   |                                           |
   | >>__CODE-SET____________alphabet-name__>< |
   |               |__IS__|                    |
   |                                           |
   |___________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.6.1 File Section

The File Section must contain a level indicator for each input and output file:

o For all files except sort/merge, the File Section must contain an FD entry. o For each sort or merge file, the File Section must contain an SD entry.

file-name Must follow the level indicator (FD or SD), and must be the same as that specified in the associated SELECT clause. The file-name must adhere to the rules of formation for a user-defined word; at least 1 character must be alphabetic. The file-name must be unique within this program.

One or more record description entries must follow the file-name. When more than one record description entry is specified, each entry implies a redefinition of the same storage area.

The clauses that follow file-name are optional; they can appear in any order.

FD (Formats 1 and 2) The last clause in the FD entry must be immediately followed by a separator period.

SD (Format 3) An SD entry must be written for each sort or merge file in the program. The last clause in the SD entry must be immediately followed by a separator period.

The following example illustrates the File Section entries needed for a sort or merge file:

SD SORT-FILE. 01 SORT-RECORD PICTURE X(80).


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.6.2 EXTERNAL Clause

The EXTERNAL clause specifies that a file connector is external, and permits communication between two programs by the sharing of files. A file connector is external if the storage associated with that file is associated with the run unit rather than with any particular program within the run unit. An external file can be referenced by any program in the run unit that describes the file. References to an external file from different programs using separate descriptions of the file are always to the same file. In a run unit, there is only one representative of an external file.

In the File Section, the EXTERNAL clause can be specified only in file description entries.

The records appearing in the file description entry need not have the same name in corresponding external file description entries. In addition, the number of such records need not be the same in corresponding file description entries.

Use of the EXTERNAL clause does not imply that the associated file-name is a global name. For specific information on the use of the EXTERNAL clause, see VS COBOL II Application Programming Guide for MVS and CMS or VS COBOL II Application Programming Guide for VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.6.3 GLOBAL Clause

The GLOBAL clause specifies that the file connector named by a file-name is a global name. A global file-name is available to the program that declares it and to every program that is contained directly or indirectly in that program.

A file-name is global if the GLOBAL clause is specified in the file description entry for that file-name. A record-name is global if the GLOBAL clause is specified in the record description entry by which the record-name is declared or, in the case of record description entries in the File Section, if the GLOBAL clause is specified in the file description entry for the file-name associated with the record description entry. For specific information on the use of the GLOBAL clause, see VS COBOL II Application Programming Guide for MVS and CMS or VS COBOL II Application Programming Guide for VSE.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.6.3.1 Sharing Files in the EXTERNAL and GLOBAL Clauses

Two programs in a run unit can reference global file connectors in the following circumstances:

1. An external file connector can be referenced from any program that describes that file connector.

2. If a program is contained within another program, both programs can refer to a global file connector by referring to an associated global file-name either in the containing program or in any program that directly or indirectly contains the containing program.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.6.4 BLOCK CONTAINS Clause

The BLOCK CONTAINS clause specifies the size of the physical records.

If the records in the file are not blocked, the BLOCK CONTAINS clause can be omitted.

When it is omitted, the compiler assumes that records are not blocked. Even if each physical record contains only one complete logical record, coding BLOCK CONTAINS 1 RECORD would result in fixed blocked records.

The BLOCK CONTAINS clause can be omitted when the associated File Control entry specifies a VSAM file; the concept of blocking has no meaning for | VSAM files; the clause is syntax-checked but is treated as documentation.

For EXTERNAL files, the value of all BLOCK CONTAINS clauses of | corresponding EXTERNAL files must match within the run unit. This | conformance is in terms of character positions and does not depend upon | whether the value was specified as CHARACTERS or as RECORDS.

integer-1, integer-2 Must be nonzero unsigned integers. They specify the number of:

CHARACTERS Specifies the number of character positions required to store the physical record, no matter what USAGE the characters have within the data record.

If only integer-2 is specified, it specifies the exact character size of the physical record. When integer-1 and integer-2 are both specified, they represent, respectively, the minimum and maximum character sizes of the physical record.

Integer-1 and integer-2 must include any control bytes and padding contained in the physical record. (Logical records do not include padding.)

The CHARACTERS phrase is the default. CHARACTERS must be specified when:

o The physical record contains padding.

o Logical records are grouped so that an inaccurate physical record size could be implied. For example, suppose you describe a variable-length record of 100 characters, yet each time you write a block of 4, one 50-character record is written followed by three 100-character records. If the RECORDS phrase were specified, the compiler would calculate the block size as 420 characters instead of the actual size, 370 characters. (This calculation includes block and record descriptors.)

RECORDS Specifies the number of logical records contained in each physical record.

The compiler assumes that the block size must provide for integer-2 records of maximum size, and provides any additional space needed for control bytes.

x The BLOCK CONTAINS clause cannot be used with the RECORDING MODE U clause.

x The BLOCK CONTAINS clause is treated as a comment under an SD.

x Under MVS, BLOCK CONTAINS 0 can be specified for QSAM files; the block x size is determined at object time from the DD parameters or the data set x label. If the RECORD CONTAINS 0 CHARACTERS clause is specified, and the x BLOCK CONTAINS 0 CHARACTERS clause is specified (or omitted), the block x size is determined at object time from the DD parameters or the data set x label of the file.

x Under MVS, the BLOCK CONTAINS clause can be omitted for SYSIN/SYSOUT x files. The blocking is determined by the operating system.

Under VSE, the BLOCK CONTAINS 0 clause can also be specified for SAM files. You must set the block size at object time by using the DLBL statement with the BLKSIZE parameter. If files are defined using VSE/VSAM Space Management for SAM feature, the block size is determined from the VSAM catalog at object time. For more information about the BLOCK CONTAINS clause under VSE, see VS COBOL II Application Programming Guide for VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.6.5 RECORD Clause

x Note: This element may exhibit different behavior when the CMPR2 compiler x option is in effect. For more information, see VS COBOL II Migration x Guide for MVS and CMS or VS COBOL II Migration Guide for VSE.

Format 1 specifies the number of character positions for fixed-length records.

___ record-clause-format-i __________________________________ | | | >>__RECORD__________________integer-3____________________>< | | |__CONTAINS__| |__CHARACTERS__| | | | |_____________________________________________________________| integer-3 Must be an unsigned integer that specifies the number of character positions contained in each record in the file.

x Under MVS, the RECORD CONTAINS 0 clause can be specified for input x QSAM files containing fixed-length records; the record size is x determined at object time from the DD statement parameters or the data x set label. If, at object time, the actual record is larger than the x 01 record description, only the 01 record length is available. If the x actual record is shorter, only the actual record length can be x referred to. Otherwise, uninitialized data or an addressing exception x may be produced.

x Under VSE, the RECORD CONTAINS clause can also be specified for input x files defined using the VSE/VSAM Space Management for SAM feature, x provided that the record size matches the record size in the VSAM x catalog. Alternatively, RECORD CONTAINS 0 can be used for such files. x For more information about the RECORD CONTAINS clause under VSE, see x VS COBOL II Application Programming Guide for VSE.

x Note: If the RECORD CONTAINS 0 clause is specified, then the SAME x AREA, SAME RECORD AREA, or APPLY WRITE-ONLY clause cannot be x specified.

Format 2 specifies the number of character positions for either | fixed-length or variable-length records. Fixed-length records are | obtained when all 01 record description entry lengths are the same. The Format 2 RECORD CONTAINS clause is never required, because the minimum and maximum record lengths are determined from the record description entries.

___ record-clause-format-ii ________________________________________________ | | | >>__RECORD__________________integer-4__TO__integer-5____________________>< | | |__CONTAINS__| |__CHARACTERS__| | | | |____________________________________________________________________________| integer-4, integer-5 Must be unsigned integers. Integer-4 specifies the size of the smallest data record, and integer-5 specifies the size of the largest data record.

Format 3 is used to specify variable-length records.

___ record-clause-format-iii _______________________________________________ | | | >>__RECORD____________VARYING____________________________________________> | | |__IS__| |__IN__| |__SIZE__| | | | | >________________________________________________________________________> | | |______________integer-6__| |__TO__integer-7__| |__CHARACTERS__| | | |__FROM__| | | | | >_______________________________________________________________________>< | | |__DEPENDING____________data-name-1__| | | |__ON__| | | | |____________________________________________________________________________| integer-6 Specifies the minimum number of character positions to be contained in any record of the file. If integer-6 is not specified, the minimum number of character positions to be contained in any record of the file is equal to the least number of character positions described for a record in that file.

integer-7 Specifies the maximum number of character positions in any record of the file. If integer-7 is not specified, the maximum number of character positions to be contained in any record of the file is equal to the greatest number of character positions described for a record in that file.

The number of character positions associated with a record description is determined by the sum of the number of character positions in all elementary data items (excluding redefinitions and renamings), plus any implicit FILLER due to synchronization. If a table is specified:

o The minimum number of table elements described in the record is used in the summation above to determine the minimum number of character positions associated with the record description.

o The maximum number of table elements described in the record is used in the summation above to determine the maximum number of character positions associated with the record description.

If data-name-1 is specified:

o Data-name-1 must be an elementary unsigned integer.

o The number of character positions in the record must be placed into the data item referenced by data-name-1 before any RELEASE, REWRITE, or WRITE statement is executed for the file.

o The execution of a DELETE, RELEASE, REWRITE, START, or WRITE statement or the unsuccessful execution of a READ or RETURN statement does not alter the content of the data item referenced by data-name-1.

o After the successful execution of a READ or RETURN statement for the file, the contents of the data item referenced by data-name-1 indicate the number of character positions in the record just read.

During the execution of a RELEASE, REWRITE, or WRITE statement, the number of character positions in the record is determined by the following conditions:

o If data-name-1 is specified, by the content of the data item referenced by data-name-1.

o If data-name-1 is not specified and the record does not contain a variable occurrence data item, by the number of character positions in the record.

o If data-name-1 is not specified and the record contains a variable occurrence data item, by the sum of the fixed position and that portion of the table described by the number of occurrences at the time of execution of the output statement.

During the execution of a READ ... INTO or RETURN ... INTO statement, the number of character positions in the current record that participate as the sending data items in the implicit MOVE statement is determined by the following conditions:

o If data-name-1 is specified, by the content of the data item referenced by data-name-1.

o If data-name-1 is not specified, by the value that would have been moved into the data item referenced by data-name-1 had data-name-1 been specified.

For information on using RECORD IS VARYING with relative organization files under MVS, see VS COBOL II Application Programming Guide for MVS and CMS.

For all 3 Formats: When the RECORD clause is used, the record size must be specified as the number of character positions needed to store the record internally. That is, it must specify the number of bytes occupied internally by the characters of the record (not the number of characters used to represent the item within the record). The size of a record is determined according to the rules for obtaining the size of a group item. (See "USAGE Clause" in topic 2.7.12 and "SYNCHRONIZED Clause" in topic 2.7.11.)

When the RECORD clause is omitted, the compiler determines the record lengths from the record descriptions. When one of the entries within a record description contains an OCCURS DEPENDING ON clause, the compiler uses the maximum value of the variable-length item to calculate the number of character positions needed to store the record internally.

If the associated file connector is an external file connector, all file description entries in the run unit that are associated with that file connector must specify the same maximum number of character positions.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.6.6 LABEL RECORDS Clause

The LABEL RECORDS clause indicates the presence or absence of labels. If it is not specified for a file, label records for that file must conform to the system label specifications.

| For VSAM files, the LABEL RECORDS clause is syntax-checked, but is treated | as documentation. COBOL label processing, therefore, is not performed.

| Note: The LABEL RECORDS clause is an obsolete element and will be deleted | from the next revision of the COBOL 85 Standard.

STANDARD Labels conforming to system specifications exist for this file.

STANDARD is permitted for mass storage devices and tape devices.

OMITTED No labels exist for this file.

OMITTED is permitted for tape devices.

x data-name-2 x User labels are present in addition to standard labels. Data-name-2 x specifies the name of a user label record. Data-name-2 must appear as x the subject of a record description entry associated with the file, x and it must not appear as an operand of the DATA RECORDS clause for x the file.

x The LABEL RECORDS clause is treated as a comment under an SD.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.6.7 VALUE OF Clause

The VALUE OF clause describes an item in the label records associated with | this file. The clause is syntax-checked, but is treated as documentation.

| Note: The VALUE OF clause in the file description entry is an obsolete | element and will be deleted from the next revision of the COBOL 85 | Standard.

data-name-3 Should be qualified when necessary, but cannot be subscripted. It must be described in the Working-Storage Section. It cannot be described with the USAGE IS INDEX clause.

literal-1 Can be numeric or nonnumeric, or a figurative constant of category numeric or nonnumeric.

Cannot be a floating-point literal.

x The VALUE OF clause is treated as a comment under an SD.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.6.8 DATA RECORDS Clause

The DATA RECORDS clause is syntax-checked, but serves only as documentation for the names of data records associated with this file.

| Note: The DATA RECORDS clause is an obsolete element and will be deleted | from the next revision of the COBOL 85 Standard.

data-name-4 The names of record description entries associated with this file.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.6.9 LINAGE Clause

The LINAGE clause specifies the depth of a logical page in terms of number of lines. Optionally, it also specifies the line number at which the footing area begins, as well as the top and bottom margins of the logical page. (The logical page and the physical page may not be the same size.)

x The LINAGE clause is effective for QSAM or SAM files opened OUTPUT, or x QSAM files opened EXTEND.

All integers must be unsigned. All data-names must be described as unsigned integer data items.

data-name-5, integer-8 The number of lines that can be written and/or spaced on this logical page. The area of the page that these lines represent is called the page body. The value must be greater than zero.

WITH FOOTING AT Integer-9 or the value of the data item in data-name-6 specifies the first line number of the footing area within the page body. The footing line number must be greater than zero, and not greater than the last line of the page body. The footing area extends between those two lines.

LINES AT TOP Integer-10 or the value of the data item in data-name-7 specifies the number of lines in the top margin of the logical page. The value can be zero.

LINES AT BOTTOM Integer-11 or the value of the data item in data-name-8 specifies the number of lines in the bottom margin of the logical page. The value can be zero.

Figure 4 illustrates the use of each phrase of the LINAGE clause.

___________________________________________________________________ |) ^ ^ | |) LINES AT TOP integer-10 (top margin) | | |) v | | |___________________________________________________________|_______| | ^ | | | | | | | | logical | | page body page depth | | | | | | | | | | | | | | WITH FOOTING integer-9 ____________________|_____________|_______| | ^ | | | | footing area | | | | v v | | | LINAGE integer-8 ________________________________________|_______| |) ^ | | |) LINES AT BOTTOM integer-11 (bottom|margin) | | |) v v | |___________________________________________________________________|

Figure 4. LINAGE Clause Phrases

The logical page size specified in the LINAGE clause is the sum of all values specified in each phrase except the FOOTING phrase. If the LINES AT TOP and/or the LINES AT BOTTOM phrase is omitted, the assumed value for top and bottom margins is zero. Each logical page immediately follows the preceding logical page, with no additional spacing provided.

If the FOOTING phrase is omitted, its assumed value is equal to that of the page body (integer-8 or data-name-5).

At the time an OPEN OUTPUT statement is executed, the values of integer-8, integer-9, integer-10, and integer-11, if specified, are used to determine the page body, first footing line, top margin, and bottom margin of the logical page for this file. See Figure 4 above. These values are then used for all logical pages printed for this file during a given execution of the program.

At the time an OPEN statement with the OUTPUT phrase is executed for the file, data-name-5, data-name-6, data-name-7, and data-name-8 determine the page body, first footing line, top margin, and bottom margin for the first logical page only.

At the time a WRITE statement with the ADVANCING PAGE phrase is executed or a page overflow condition occurs, the values of data-name-5, data-name-6, data-name-7, and data-name-8 if specified, are used to determine the page body, first footing line, top margin, and bottom margin for the next logical page.

If an external file connector is associated with this file description entry, all file description entries in the run unit that are associated with this file connector must have:

o A LINAGE clause, if any file description entry has a LINAGE clause.

o The same corresponding values for integer-8, integer-9, integer-10, and integer-11, if specified.

o The same corresponding external data items referenced by data-name-5, data-name-6, data-name-7, and data-name-8.

See "ADVANCING Phrase" in topic 3.38.1.1 for the behavior of carriage control characters in EXTERNAL files.

x The LINAGE clause is treated as a comment under an SD.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.6.9.1 LINAGE-COUNTER Special Register

For information about the LINAGE-COUNTER Special Register, see topic 1.1.1.9.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.6.10 RECORDING MODE Clause

x The RECORDING MODE clause specifies the format of the physical records in x a QSAM or SAM file. The clause is ignored for a VSAM file.

x Permitted values for RECORDING MODE are:

x Recording Mode F (Fixed) x All the records in a file are the same length and each is wholly x contained within one block. Blocks may contain more than one record, x and there is usually a fixed number of records for each block. In x this mode, there are no record-length or block-descriptor fields.

x Recording Mode V (Variable) x The records can be either fixed-length or variable-length, and each x must be wholly contained within one block. Blocks can contain more x than one record. Each data record includes a record-length field and x each block includes a block-descriptor field. These fields are not x described in the Data Division. They are each 4 bytes long and x provision is automatically made for them. These fields are not x available to you.

x Recording Mode U (Fixed or Variable) x The records can be either fixed-length or variable-length. However, x there is only one record for each block. There are no record-length x or block-descriptor fields.

x When recording mode U is used, the BLOCK CONTAINS clause must not be x used.

x Recording Mode S (Spanned) x The records can be either fixed-length or variable-length, and can be x larger than a block. If a record is larger than the remaining space x in a block, a segment of the record is written to fill the block. The x remainder of the record is stored in the next block (or blocks, if x required). Only complete records are made available to you. Each x segment of a record in a block, even if it is the entire record, x includes a segment-descriptor field, and each block includes a x block-descriptor field. These fields are not described in the Data x Division; provision is automatically made for them. These fields are x not available to you.

x When recording mode S is used, the BLOCK CONTAINS CHARACTERS clause x must be used. Recording mode S is not allowed for ASCII files.

x If the RECORDING MODE clause is not specified for a QSAM or SAM file, the x VS COBOL II compiler determines the recording mode as follows:

x F The compiler determines the recording mode to be F if the largest x level-01 record associated with the file is not greater than the block x size specified in the BLOCK CONTAINS clause, and you do one of the x following:

x o Use the RECORD CONTAINS integer clause (for more information, see x VS COBOL II Migration Guide for MVS and CMS or VS COBOL II x Migration Guide for VSE).

x o Omit the RECORD clause and make sure all level-01 records x associated with the file are the same size and none contain an x OCCURS DEPENDING ON clause.

x V The compiler determines the recording mode to be V if the largest x level-01 record associated with the file is not greater than the block x size specified in the BLOCK CONTAINS clause, and you do one of the x following:

x o Use the RECORD IS VARYING clause

x o Omit the RECORD clause and make sure all level-01 records x associated with the file are not the same size or some contain an x OCCURS DEPENDING ON clause

x o Use the RECORD CONTAINS integer-1 TO integer-2 clause with x integer-1 the minimum length and integer-2 the maximum length of x the level-01 records associated with the file. The two integers x must be different, with values matching minimum and maximum length x of either different length records or record(s) with an OCCURS x DEPENDING ON clause.

x S The compiler determines the recording mode to be S if the maximum x block size is smaller than the largest record size.

x U Recording mode U is never obtained by default. The RECORDING MODE U x clause must be explicitly used.


@@ Diagram mode ADDED at the end of this section.
@@ Defined modes as described in text; note: modes are not reserved words.

    ___ mode ________
   |                 |
   | >>_____F_____>< |
   |     |__V__|     |
   |     |__U__|     |
   |     |__S__|     |
   |                 |
   |_________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.6.11 CODE-SET Clause

The CODE-SET clause specifies the character code used to represent data on a magnetic tape file. When the CODE-SET clause is specified, an alphabet-name identifies the character code convention used to represent data on the input-output device.

Alphabet-name must be defined in the SPECIAL-NAMES paragraph as STANDARD-1 (for ASCII-encoded files), as STANDARD-2 (for ISO 7-bit encoded files), as EBCDIC (for EBCDIC-encoded files), or as NATIVE. When NATIVE is | specified, the CODE-SET clause is syntax-checked, but is treated as | documentation.

The CODE-SET clause also specifies the algorithm for converting the character codes on the input-output medium from/to the internal EBCDIC character set.

When the CODE-SET clause is specified for a file, all data in this file must have USAGE DISPLAY, and, if signed numeric data is present, it must be described with the SIGN IS SEPARATE clause.

When the CODE-SET clause is omitted, the EBCDIC character set is assumed for this file.

If the associated file connector is an external file connector, all CODE-SET clauses in the run unit that are associated with that file connector must have the same character set.

The CODE-SET clause is valid only for magnetic tape files.

x The CODE-SET clause is treated as a comment under an SD.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7 Data Division--Data Description Entry

A data description entry specifies the characteristics of a data item.

This chapter describes the coding of data description entries and record description entries (which are sets of data description entries). The single term data description entry is used in this chapter to refer to data and record description entries.

Data description entries that define independent data items do not make up a record. These are known as data item description entries.

The data description entry has three general formats. All data description entries must end with a separator period.

Format 1 is used for data description entries in all Data Division sections.

@@ Diagram data-description-entry ADDED before diagram data-description-entry-format-i. @@ Different formats for data description entries. ___ data-description-entry ______________________ | | | >>_____data-description-entry-format-i_______>< | | |__data-description-entry-format-ii___| | | |__data-description-entry-format-iii__| | | | |_________________________________________________| @@ Diagram data-description-entry-format-i ADAPTED. @@ Inserted separator period as required at the beginning of 2.7. ___ data-description-entry-format-i _____________________________ | | | >>__level-number______________________________________________> | | |__data-name-1__| |__redefines-clause__| | | |__FILLER_______| | | | | >___data-clauses__.__________________________________________>< | | | |_________________________________________________________________| @@ Diagram data-clauses EXTRACTED from diagram data-description-entry-format-i. @@ Identified ingredients of a permutation phrase. @@ Diagram data-clauses ADAPTED. @@ Identified the kind of value clause needed here. @@ Diagram data-clauses ADAPTED. @@ Relaxed order as described in the below note. ___ data-clauses _____________________ | | | ||________________________________|| | | |__blank-when-zero-clause__| | | | | ||________________________________|| | | |__external-clause__| | | | | ||________________________________|| | | |__global-clause__| | | | | ||________________________________|| | | |__justified-clause__| | | | | ||________________________________|| | | |__occurs-clause__| | | | | ||________________________________|| | | |__picture-clause__| | | | | ||________________________________|| | | |__sign-clause__| | | | | ||________________________________|| | | |__synchronized-clause__| | | | | ||________________________________|| | | |__usage-clause__| | | | | ||________________________________|| | | |__value-clause-format-i__| | | | |______________________________________| Note: The clauses can be written in any order with two exceptions:

If data-name or FILLER is specified, it must immediately follow the level-number.

When the REDEFINES clause is specified, it must immediately follow data-name or FILLER, if either is specified. If data-name or FILLER is not specified, the REDEFINES clause must immediately follow the level-number.

Level-number in Format 1 can be any number from 01-49 or 77.

A space, a separator comma, or a separator semicolon must separate clauses.

Format 2 regroups previously defined items.

___ data-description-entry-format-ii _______ | | | >>__66__data-name-1__renames-clause__.__>< | | | |____________________________________________| A level-66 entry cannot rename another level-66 entry, nor can it rename a level-01, level-77, or level-88 entry.

All level-66 entries associated with one record must immediately follow the last data description entry in that record.

Details are contained in "RENAMES Clause" in topic 2.7.9.

Format 3 describes condition-names.

@@ Diagram data-description-entry-format-iii ADAPTED. @@ Identified the kind of value clause needed here. ___ data-description-entry-format-iii ___________________ | | | >>__88__condition-name-1__value-clause-format-ii__.__>< | | | |_________________________________________________________| condition-name A user-specified name that associates a value, a set of values, or a range of values with a conditional variable.

A conditional variable is a data item that can assume one or more values, that can, in turn, be associated with a condition-name.

Format 3 can be used to describe both elementary and group items. Further information on condition-name entries can be found under "VALUE Clause" in topic 2.7.13.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.1 Level-Numbers

The level-number specifies the hierarchy of data within a record, and identifies special-purpose data entries. A level-number begins a data description entry, a renamed or redefined item, or a condition-name entry. A level-number has a value taken from the set of integers between 1 and 49, or from one of the special level-numbers, 66, 77, or 88.

___ data-at-level _______________________ | | | >>__level-number_____________________>< | | |__data-name-1__| | | |__FILLER_______| | | | |_________________________________________| level-number | 01 and 77 must begin in Area A. Level number 01 must be followed | either by a separator period; or by a space, followed by its | associated data-name, FILLER, or appropriate data description clause. | Level number 77 must be followed by a space followed by its associated | data-name and appropriate data description clause.

Level numbers 02 through 49 can begin in Areas A or B and must be followed by a space or a separator period.

Level numbers 66 and 88 can begin in Areas A or B and must be followed by a space.

Single-digit level-numbers 1 through 9 can be substituted for level-numbers 01 through 09.

Successive data description entries can start in the same column as the first or they can be indented according to the level-number. Indentation does not affect the magnitude of a level-number.

When level-numbers are indented, each new level-number can begin any number of spaces to the right of Area A. The extent of indentation to the right is limited only by the width of Area B.

x VS COBOL II accepts nonstandard level-numbers that are not identical x to others at the same level.

| For more information on nonstandard level-numbers or level-numbers in | general, see "Levels of Data" in topic 2.5.3.1

data-name-1 Explicitly identifies the data being described.

| Data-name-1 identifies a data item used in the program. Data-name-1 | must be the first word following the level-number.

The data item can be changed during program execution.

| Data-name-1 must be specified for level-66 and level-88 items. It must also be specified for any entry containing the GLOBAL or EXTERNAL clause, and for record description entries associated with file description entries having the GLOBAL or EXTERNAL clauses.

FILLER Is a data item that is not explicitly referred to in a program. The keyword FILLER is optional. If specified, FILLER must be the first word following the level-number.

The keyword FILLER can be used with a conditional variable, if explicit reference is never made to the conditional variable but only to values it may assume. FILLER cannot be used with a condition-name.

In a MOVE CORRESPONDING statement, or in an ADD CORRESPONDING or SUBTRACT CORRESPONDING statement, FILLER items are ignored. In an INITIALIZE statement, elementary FILLER items are ignored.

If the data-name or FILLER clause is omitted, the data item being described is treated as though FILLER had been specified.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.2 BLANK WHEN ZERO Clause

The BLANK WHEN ZERO clause specifies that an item contains nothing but spaces when its value is zero.

___ blank-when-zero-clause ____________________ | | | >>__BLANK_________________ZERO_____________>< | | |__WHEN__| |__{__ZEROS__}___| | | |__{__ZEROES__}__| | | | |_______________________________________________| The BLANK WHEN ZERO clause can be specified only for elementary numeric or numeric-edited items. These items must be described, either implicitly or explicitly, as USAGE IS DISPLAY. When the BLANK WHEN ZERO clause is | specified for a numeric item, the item's category is numeric-edited.

The BLANK WHEN ZERO clause must not be specified for level-66 or level-88 items.

The BLANK WHEN ZERO clause must not be specified for the same entry as the PICTURE symbols S or *.

The BLANK WHEN ZERO clause is not allowed for:

o Items described as USAGE IS INDEX x o DBCS items x o Items described as USAGE IS POINTER x o External or internal floating-point items.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.3 EXTERNAL Clause

The EXTERNAL clause specifies that the storage associated with a data item is associated with the run unit rather than with any particular program within the run unit. An external data item can be referenced by any program in the run unit that describes the data item. References to an external data item from different programs using separate descriptions of the data item are always to the same data item. In a run unit, there is only one representative of an external data item.

The EXTERNAL clause can be specified only in data description entries in the Working-Storage Section whose level-number is 01. It cannot be specified in the Linkage Section or File Section. Any data item described by a data description entry subordinate to an entry describing an external record also attains the EXTERNAL attribute. Indexes in an external data record do not possess the external attribute.

The data contained in the record named by the data-name clause is external and can be accessed and processed by any program in the run unit that describes and, optionally, redefines it. This data is subject to the following rules:

o If two or more programs within a run unit describe the same external data record, each record-name of the associated record description entries must be the same and the records must define the same number of standard data format characters. However, a program that describes an external record can contain a data description entry including the REDEFINES clause that redefines the complete external record, and this complete redefinition need not occur identically in other programs in the run unit.

o Use of the EXTERNAL clause does not imply that the associated data-name is a global name.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.4 GLOBAL Clause

The GLOBAL clause specifies that a data-name is available to every program contained within the program that declares it, as long as the contained program does not itself have a declaration for that name. All data-names subordinate to or condition-names or indexes associated with a global name are global names.

A data-name is global if the GLOBAL clause is specified either in the data description entry by which the data-name is declared or in another entry | to which that data description entry is subordinate. The GLOBAL clause | can be specified in the Working-Storage and File Sections, but only in | data description entries whose level-number is 01. It cannot be specified | in the Linkage Section.

In the same Data Division, the data description entries for any two data items for which the same data-name is specified must not include the GLOBAL clause.

A statement in a program contained directly or indirectly within a program which describes a global name can reference that name without describing it again.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.4.1 Sharing Data

Two programs in a run unit can reference common data in the following circumstances:

1. The data content of an external data record can be referenced from any program provided that program has described that data record.

2. If a program is contained within another program, both programs can refer to data possessing the global attribute either in the containing program or in any program that directly or indirectly contains the containing program.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.5 JUSTIFIED Clause

The JUSTIFIED clause overrides standard positioning rules for a receiving item of the alphabetic or alphanumeric categories.

___ justified-clause _________________ | | | >>_____JUSTIFIED__________________>< | | |__JUST_______| |__RIGHT__| | | | |______________________________________| The JUSTIFIED clause can be specified only at the elementary level. JUST is an abbreviation for JUSTIFIED, and has the same meaning.

The JUSTIFIED clause cannot be specified for numeric, numeric-edited, or alphanumeric-edited items. Also, the JUSTIFIED clause cannot be specified in descriptions of items described with the USAGE IS INDEX clause.

The JUSTIFIED clause is not allowed for:

x o Items described as USAGE IS POINTER x o External or internal floating-point items.

When the JUSTIFIED clause is specified for a receiving item, the data is aligned at the rightmost character position in the receiving item. Also:

o If the sending item is larger than the receiving item, the leftmost characters are truncated.

o If the sending item is smaller than the receiving item, the unused character positions at the left are filled with spaces.

x The JUSTIFIED clause can be specified for a DBCS item. It is not x permitted for an edited DBCS item. When JUSTIFIED is specified for a x receiving item, the data is aligned on the rightmost character position. x If the sending item is larger than the receiving item, extra characters x are truncated on the left. If the sending item is smaller than the x receiving item, any unused positions on the left are filled with DBCS x blanks.

When the JUSTIFIED clause is omitted, the rules for standard alignment are followed (see "Alignment Rules" in topic 2.5.3.6).

The JUSTIFIED clause must not be specified with level-66 (RENAMES) and level-88 (condition-name) entries.

The JUSTIFIED clause does not affect initial values, as determined by the | VALUE clause, nor does it affect the value assigned to a conditional | variable when its associated condition-name is set to TRUE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.6 OCCURS Clause

The Data Division clauses used for table handling are the OCCURS clause and USAGE IS INDEX clause. For the USAGE IS INDEX description, see "USAGE Clause" in topic 2.7.12.

The OCCURS clause specifies tables whose elements can be referred to by indexing or subscripting. It also eliminates the need for separate entries for repeated data items.

x The OCCURS clause can be specified for a DBCS item.

x An item described as USAGE IS POINTER can contain an OCCURS clause, or be x subordinate to an item declared with an OCCURS clause.

x The OCCURS clause can be specified for external or internal floating-point x items.

Formats for the OCCURS clause are:

o Fixed-length tables o Variable-length tables.

| The subject of an OCCURS clause is the data-name of the data item | containing the OCCURS clause. Except for the OCCURS clause itself, data | description clauses used with the subject apply to each occurrence of the | item described.

| Whenever the subject of an OCCURS clause or any data-item subordinate to | it is referenced, it must be subscripted or indexed with the following | exceptions:

| o When the subject of the OCCURS clause is used as the subject of a | SEARCH statement.

| o When the subject or subordinate data item is the object of the | ASCENDING/DESCENDING KEY clause.

| o When the subordinate data item is the object of the REDEFINES clause.

| When subscripted or indexed, the subject refers to one occurrence within | the table.

| When not subscripted or indexed, the subject represents the entire table.

| The OCCURS clause cannot be specified in a data description entry that:

| o Has a level number of 01, 66, 77, or 88.

| o Describes a redefined data item. (However, a redefined item can be | subordinate to an item containing an OCCURS clause.) See "REDEFINES | Clause" in topic 2.7.8.

Subtopics:


@@ Diagram occurs-clause ADDED at the end of this section.
@@ Different formats of ADD statements.

    ___ occurs-clause _____________________
   |                                       |
   | >>_____occurs-clause-format-i______>< |
   |     |__occurs-clause-format-ii__|     |
   |                                       |
   |_______________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.6.1 Fixed-Length Tables

Fixed-length tables are specified using the OCCURS clause. Because seven subscripts or indexes are allowed, six nested levels and one outermost | level of the Format 1 OCCURS clause are allowed. In this way, a table of | up to seven dimensions can be specified. The Format 1 OCCURS clause can | be specified as subordinate to the OCCURS DEPENDING ON clause.

___ occurs-clause-format-i _________________________________________________ | | | >>__OCCURS__integer-2____________________________________________________> | | |__TIMES__| | | | | >________________________________________________________________________> | | | <__________________________________________________________ | | | | <______________ | | | | |_______ASCENDING_____________________________data-name-2__|__|__| | | |__DESCENDING__| |__KEY__| |__IS__| | | | | >_______________________________________________________________________>< | | | <_______________ | | | |__INDEXED______________index-name-1__|__| | | |__BY__| | | | |____________________________________________________________________________| integer-2 The exact number of occurrences. Integer-2 must be greater than zero.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.7.6.1.1 ASCENDING/DESCENDING KEY Phrase

| The ASCENDING/DESCENDING KEY phrase specifies the order in which the data | in the table will be arranged. Data is arranged in ascending or descending order (depending on the keyword specified) according to the values contained in data-name-2. The data-names are listed in their descending order of significance.

The order is determined by the rules for comparison of operands (see "Relation Condition" in topic 2.8.5.4). The ASCENDING and DESCENDING KEY | data items are used in OCCURS clauses and the SEARCH ALL statement for a | search of the table element.

data-name-2 Must be the name of the subject entry, or the name of an entry subordinate to the subject entry. It can be qualified.

If data-name-2 names the subject entry, that entire entry becomes the ASCENDING/DESCENDING KEY, and is the only key that can be specified for this table element.

If data-name-2 does not name the subject entry, then data-name-2:

o Must be subordinate to the subject of the table entry itself o Must not be subordinate to, or follow, any other entry that contains an OCCURS clause o Must not contain an OCCURS clause.

| Data-name-2 must not have subordinate items that contain OCCURS | DEPENDING ON clauses.

When the ASCENDING/DESCENDING KEY phrase is specified, the following rules apply:

o Keys must be listed in decreasing order of significance.

o The total number of keys for a given table element must not exceed 12.

| o You must ensure that the data actually present in the table is | arranged in ASCENDING or DESCENDING sequence according to the | collating sequence in use.

o A key can have DISPLAY, BINARY, PACKED-DECIMAL, or COMPUTATIONAL usage.

o The sum of the lengths of all the keys associated with one table element must not exceed 255.

x o A key can have COMPUTATIONAL-1, COMPUTATIONAL-2, COMPUTATIONAL-3, or x COMPUTATIONAL-4 usage.

x o The ASCENDING/DESCENDING KEY phrase (for a SEARCH ALL statement only) x can be specified in the OCCURS clause for a DBCS item.

x o If a key is specified without qualifiers and it is not a unique name, x the key will be implicitly qualified with the subject of the OCCURS x clause and all qualifiers of the OCCURS clause subject.

The following example illustrates the specification of ASCENDING KEY data item:

WORKING-STORAGE SECTION. 01 TABLE-RECORD. 05 EMPLOYEE-TABLE OCCURS 100 TIMES ASCENDING KEY IS WAGE-RATE EMPLOYEE-NO INDEXED BY A, B. 10 EMPLOYEE-NAME PIC X(20). 10 EMPLOYEE-NO PIC 9(6). 10 WAGE-RATE PIC 9999V99. 10 WEEK-RECORD OCCURS 52 TIMES ASCENDING KEY IS WEEK-NO INDEXED BY C. 15 WEEK-NO PIC 99. 15 AUTHORIZED-ABSENCES PIC 9. 15 UNAUTHORIZED-ABSENCES PIC 9. 15 LATE-ARRIVALS PIC 9.

The keys for EMPLOYEE-TABLE are subordinate to that entry, while the key for WEEK-RECORD is subordinate to that subordinate entry.

In the preceding example, records in EMPLOYEE-TABLE must be arranged in ascending order of WAGE-RATE, and in ascending order of EMPLOYEE-NO within WAGE-RATE. Records in WEEK-RECORD must be arranged in ascending order of WEEK-NO. If they are not, results of any SEARCH ALL statement will be unpredictable.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.7.6.1.2 INDEXED BY Phrase

The INDEXED BY phrase specifies the indexes that can be used with this table. The INDEXED BY phrase is required if indexing is used to refer to this table element. See "Subscripting Using Index-Names (Indexing)" in topic 1.5.1.4.2.

x A table without an INDEXED BY option can be referred to through indexing.

Note: Indexes specified in an External data record do not possess the external attribute.

index-name-1 Must follow the rules for formation of user-defined words. At least one character must be alphabetic.

Each index-name specifies an index to be created by the compiler for use by the program. These index-names are not data-names, and are not identified elsewhere in the COBOL program; instead, they can be regarded as private special registers for the use of this object program only. As such, they are not data, or part of any data hierarchy; as such, each must be unique.

In one table entry, up to 12 index-names can be specified.

If a data item possessing the GLOBAL attribute includes a table accessed with an index, that index also possesses the GLOBAL attribute. Therefore, the scope of an index-name is identical to that of the data-name which names the table whose index is named by that index-name and the scope of name rules for data-names apply.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.6.2 Variable-Length Tables

Variable-length tables are specified using the OCCURS DEPENDING ON clause.

@@ Diagram occurs-clause-format-ii ADAPTED. @@ Enabled qualified instead of plain data names triggered by actual code. @@ Diagram occurs-clause-format-ii ADAPTED. @@ Implemented note (1) below the diagram. ___ occurs-clause-format-ii ________________________________________________ | | | >>__OCCURS___________________________integer-2_______________DEPENDING___> | | |__integer-1__@1__TO__| |__TIMES__| | | | | >_____________qualified-data-name-1______________________________________> | | |__ON__| | | | | >________________________________________________________________________> | | | <__________________________________________________________ | | | | <______________ | | | | |_______ASCENDING_____________________________data-name-2__|__|__| | | |__DESCENDING__| |__KEY__| |__IS__| | | | | >_______________________________________________________________________>< | | | <_______________ | | | |__INDEXED______________index-name-1__|__| | | |__BY__| | | | |____________________________________________________________________________| ________________________________________________________________________ | | | Note: | x | (1) Integer-1 is optional as an IBM extension. If integer-1 is | x | omitted, a value of 1 is assumed and the keyword TO must also be | x | omitted. | | | |________________________________________________________________________|

integer-1 The minimum number of occurrences.

The value of integer-1 must be greater than or equal to zero; it must also be less than the value of integer-2.

integer-2 The maximum number of occurrences.

Integer-2 must be greater than integer-1.

The length of the subject item is fixed; it is only the number of repetitions of the subject item that is variable.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.7.6.2.1 OCCURS DEPENDING ON Clause

The OCCURS DEPENDING ON clause specifies variable-length tables.

data-name-1 Specifies the object of the OCCURS DEPENDING ON clause; that is, the data item whose current value represents the current number of occurrences of the subject item. The contents of items whose occurrence numbers exceed the value of the object are undefined.

| Must describe an integer item.

The object of the OCCURS DEPENDING ON clause must not occupy any storage position within the range of the table (that is, any storage position from the first character position in the table through the last character position in the table).

x The object of the OCCURS DEPENDING ON clause cannot be variably x located; the object cannot follow an item that contains an OCCURS x DEPENDING ON clause.

If the OCCURS clause is specified in a data description entry included in a record description entry containing the EXTERNAL clause, data-name-1, if specified, must reference a data item possessing the external attribute which is described in the same Data Division.

If the OCCURS clause is specified in a data description entry subordinate to one containing the GLOBAL clause, data-name-1, if specified, must be a global name and must reference a data item which is described in the same Data Division.

At the time that the group item, or any data item that contains a x subordinate OCCURS DEPENDING ON item or that follows but is not x subordinate to the OCCURS DEPENDING ON item, is referenced, the value of the object of the OCCURS DEPENDING ON clause must fall within the range integer-1 through integer-2.

x Note: This element may exhibit different behavior when the CMPR2 compiler x option is in effect. For more information, see VS COBOL II Migration x Guide for MVS and CMS or VS COBOL II Migration Guide for VSE.

When a group item containing a subordinate OCCURS DEPENDING ON item is referred to, the part of the table area used in the operation is determined as follows:

o If the object is outside the group, only that part of the table area that is specified by the object at the start of the operation will be used.

o If the object is included in the same group and the group data item is referenced as a sending item, only that part of the table area that is specified by the value of the object at the start of the operation will be used in the operation.

o If the object is included in the same group and the group data item is referenced as a receiving item, the maximum length of the group item will be used in the operation.

The following verbs are affected by the maximum length rule:

o ACCEPT identifier (Format 1 and 2) | o CALL ... USING BY REFERENCE o MOVE ... TO identifier o READ ... INTO identifier o RELEASE identifier FROM ... o RETURN ... INTO identifier o REWRITE identifier FROM ... o STRING ... INTO identifier o UNSTRING ... INTO identifier DELIMITER IN identifier o WRITE identifier FROM ... .

| The maximum length of variable-length groups is always used when they | appear as the identifier on the CALL ... USING BY REFERENCE identifier | statement. Therefore, the object of the OCCURS DEPENDING ON clause does | not need to be set.

In one record description entry, any entry that contains an OCCURS DEPENDING ON clause can be followed only by items subordinate to it.

The OCCURS DEPENDING ON clause cannot be specified as subordinate to another OCCURS clause.

x The following constitute complex OCCURS DEPENDING ON:

x o Subordinate items can contain OCCURS DEPENDING ON clauses.

x o Entries containing an OCCURS DEPENDING ON clause can be followed by x non-subordinate items. Non-subordinate items, however, cannot be the x object of an OCCURS DEPENDING ON clause.

x If the group item is followed by a non-subordinate item, the actual x length, rather than the maximum length, will be used. At the time the x subject of entry is referenced, or any data item subordinate or x superordinate to the subject of entry is referenced, the object of the x OCCURS DEPENDING ON clause must fall within the range integer-1 x through integer-2.

x o The location of any subordinate or non-subordinate item, following an x item containing an OCCURS DEPENDING ON clause, is affected by the x value of the OCCURS DEPENDING ON object.

x o Entries subordinate to the subject of an OCCURS DEPENDING ON clause x can contain OCCURS DEPENDING ON clauses.

x o When implicit redefinition is used in a File Description (FD) entry, x subordinate level items can contain OCCURS DEPENDING ON clauses.

x o The INDEXED BY phrase can be specified for a table that has a x subordinate item that contains an OCCURS DEPENDING ON clause.

x For more information on complex OCCURS DEPENDING ON, see VS COBOL II x Application Programming Guide for MVS and CMS or VS COBOL II Application x Programming Guide for VSE.

All data-names used in the OCCURS clause can be qualified; they cannot be subscripted or indexed.

The ASCENDING/DESCENDING KEY and INDEXED BY clauses are described under "Fixed-Length Tables" in topic 2.7.6.1.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.7 PICTURE Clause

The PICTURE clause specifies the general characteristics and editing requirements of an elementary item.

___ picture-clause ________________________________ | | | >>_____PICTURE_______________character-string__>< | | |__PIC______| |__IS__| | | | |___________________________________________________| The PICTURE clause must be specified for every elementary item except an index data item or the subject of the RENAMES clause. In these cases, use of this clause is prohibited.

The PICTURE clause can be specified only at the elementary level. PIC is an abbreviation for PICTURE and has the same meaning.

The PICTURE character-string is made up of certain COBOL characters used as symbols. The allowable combinations determine the category of the elementary data item.

The PICTURE character-string can contain a maximum of 30 characters.

DECIMAL-POINT IS COMMA, when specified in the SPECIAL-NAMES paragraph, exchanges the functions of the period and the comma in PICTURE character strings and in numeric literals.

The PICTURE clause is not allowed:

o In descriptions of items described with USAGE IS INDEX x o For USAGE IS POINTER data items x o For Internal floating-point data items.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.7.1 Symbols Used in the PICTURE Clause

The meaning of each PICTURE clause symbol is defined in Table 9 in topic 2.7.7.1. The sequence in which PICTURE clause symbols must be specified is shown in Figure 5 in topic 2.7.7.1. More detailed explanations of PICTURE clause symbols follow the figures.

Any punctuation character appearing within the PICTURE character-string is not considered a punctuation character, but rather a PICTURE character-string symbol.

The lowercase letters corresponding to the uppercase letters representing the PICTURE symbols A, B, P, S, V, X, Z, CR, and DB are equivalent to x their uppercase representations in a PICTURE character-string. The x lowercase letters corresponding to the uppercase letters representing the x PICTURE symbols E and G are equivalent to their uppercase representations x in a PICTURE character-string.

________________________________________________________________________ | Table 9. PICTURE Clause Symbol Meanings | |________________________________________________________________________| | Symbol | Meaning | |________|_______________________________________________________________| | A | A character position that can contain only a letter of the | | | alphabet or a space. | |________|_______________________________________________________________| | B | A character position into which the space character is | | | inserted. | | | | x | | A character position into which a DBCS space is inserted. | x | | For a DBCS item, each PICTURE symbol B occupies 2 bytes and | x | | represents a single DBCS character position containing a DBCS | x | | space. | |________|_______________________________________________________________| x | E | Marks the start of the exponent in an external floating-point | x | | item. It occupies 1 byte of storage. | |________|_______________________________________________________________| x | G | A Double Byte Character Set (DBCS) character position. Each | x | | PICTURE symbol G occupies 2 bytes of storage and represents a | x | | single DBCS character position. | |________|_______________________________________________________________| | P | An assumed decimal scaling position. It is used to specify | | | the location of an assumed decimal point when the point is | | | not within the number that appears in the data item. The | | | scaling position character P is not counted in the size of | | | the data item. Scaling position characters are counted in | | | determining the maximum number of digit positions (18) in | | | numeric-edited items or in items that appear as arithmetic | | | operands. | | | | | | The scaling position character P can appear only as a | | | continuous string of Ps in the leftmost or rightmost digit | | | positions within a PICTURE character-string. Because the | | | scaling position character P implies an assumed decimal point | | | (to the left of the Ps, if the Ps are leftmost PICTURE | | | characters; to the right of the Ps, if the Ps are rightmost | | | PICTURE characters), the assumed decimal point symbol, V, is | | | redundant as either the leftmost or rightmost character | | | within such a PICTURE description. | | | | | | In certain operations that reference a data item whose | | | PICTURE character-string contains the symbol P, the algebraic | | | value of the data item is used rather than the actual | | | character representation of the data item. This algebraic | | | value assumes the decimal point in the prescribed location | | | and zero in place of the digit position specified by the | | | symbol P. The size of the value is the number of digit | | | positions represented by the PICTURE character-string. These | | | operations are any of the following: | | | | | | o Any operation requiring a numeric sending operand. | | | o A MOVE statement where the sending operand is numeric and | | | its PICTURE character-string contains the symbol P. | | | o A MOVE statement where the sending operand is | | | numeric-edited and its PICTURE character-string contains | | | the symbol P and the receiving operand is numeric or | | | numeric-edited. | | | o A comparison operation where both operands are numeric. | | | | | | In all other operations the digit positions specified with | | | the symbol P are ignored and are not counted in the size of | | | the operand. | |________|_______________________________________________________________| | S | An indicator of the presence (but not the representation nor, | | | necessarily, the position) of an operational sign. It must | | | be written as the leftmost character in the PICTURE string. | | | An operational sign indicates whether the value of an item | | | involved in an operation is positive or negative. The symbol | | | S is not counted in determining the size of the elementary | | | item, unless an associated SIGN clause specifies the SEPARATE | | | CHARACTER phrase. | |________|_______________________________________________________________| | V | An indicator of the location of the assumed decimal point. | | | It can appear only once in a character-string. The V does | | | not represent a character position and, therefore, is not | | | counted in the size of the elementary item. When the assumed | | | decimal point is to the right of the rightmost symbol in the | | | string, the V is redundant. | |________|_______________________________________________________________| | X | A character position that can contain any allowable character | | | from the character set of the computer. | |________|_______________________________________________________________| | Z | A leading numeric character position; when that position | | | contains a zero, the zero is replaced by a space character. | | | Each Z is counted in the size of the item. | |________|_______________________________________________________________| | 9 | A character position that contains a numeral and is counted | | | in the size of the item. | |________|_______________________________________________________________| | 0 | A character position into which the numeral zero is inserted. | | | Each zero is counted in the size of the item. | |________|_______________________________________________________________| | / | A character position into which the slash character is | | | inserted. Each slash is counted in the size of the item. | |________|_______________________________________________________________| | , | A character position into which a comma is inserted. This | | | character is counted in the size of the item. If the comma | | | insertion character is the last symbol in the PICTURE | | | character-string, the PICTURE clause must be the last clause | | | of the data description entry and must be immediately | | | followed by the separator period. | | | | x | | A trailing comma insertion character can be immediately | x | | followed by the separator comma or separator semicolon; in | x | | this case, the PICTURE clause need not be the last clause of | x | | the data description entry. | |________|_______________________________________________________________| | . | An editing symbol that represents the decimal point for | | | alignment purposes. In addition, it represents a character | | | position into which a period is inserted. This character is | | | counted in the size of the item. If the period insertion | | | character is the last symbol in the PICTURE character-string, | | | the PICTURE clause must be the last clause of that data | | | description entry and must be immediately followed by the | | | separator period. | | | | x | | A trailing period insertion character can be immediately | x | | followed by the separator comma or separator semicolon; in | x | | this case, the PICTURE clause need not be the last clause of | x | | the data description entry. | | | | | | Note: For a given program, the functions of the period and | | | comma are exchanged if the clause DECIMAL-POINT IS COMMA is | | | specified in the SPECIAL-NAMES paragraph. In this exchange, | | | the rules for the period apply to the comma and the rules for | | | the comma apply to the period wherever they appear in a | | | PICTURE clause. | |________|_______________________________________________________________| | | Editing sign control symbols. Each represents the character | | + | position into which the editing sign control symbol is | | - | placed. The symbols are mutually exclusive in one | | CR | character-string. Each character used in the symbol is | | DB | counted in determining the size of the data item. | | | | | | | | | | |________|_______________________________________________________________| | * | A check protect symbol--a leading numeric character position | | | into which an asterisk is placed when that position contains | | | a zero. Each asterisk (*) is counted in the size of the | | | item. | |________|_______________________________________________________________| | $ | A character position into which a currency symbol is placed. | | | The currency symbol in a character-string is represented | | | either by the symbol $ or by the single character in the | | | CURRENCY SIGN clause in the SPECIAL-NAMES paragraph of the | | | Environment Division. The currency symbol is counted in the | | | size of the item. | |________|_______________________________________________________________|

Figure 5 shows the sequence in which PICTURE clause symbols must be specified. See the notes at the end of the figure.

PICTURE 1

Figure 5. PICTURE Clause Symbol Sequence

Notes to Figure 5:

1. A circle at an intersection in the table indicates that the symbol(s) at the top of the column can, in a given character-string, appear anywhere to the left of symbol(s) at the left of the row.

2. The $ character is the default value for the currency symbol.

3. At least one of the symbols A, X, Z, 9, or *, or at least two of the symbols +, -, or $ must be present in a PICTURE string.

x 4. The symbols E and G are IBM extensions. G can appear alone in a x PICTURE character-string.

5. Nonfloating insertion symbols + and -, floating insertion symbols Z, *, +, -, and $, and the symbol P appear twice in the above PICTURE character precedence table. The leftmost column and uppermost row for each symbol represents its use to the left of the decimal point position. The second appearance of the symbol in the table represents its use to the right of the decimal point position.

6. Braces ({ }) indicate items that are mutually exclusive.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.7.2 Character-String Representation

The following symbols can appear more than once in one PICTURE character-string:

A B P X Z 9 0 / , + - * $

x G

An unsigned nonzero integer enclosed in parentheses immediately following any of these symbols specifies the number of consecutive occurrences of that symbol.

For example, the following two PICTURE clause specifications are equivalent:

PICTURE IS $99999.99CR PICTURE IS $9(5).9(2)CR

The following symbols can appear only once in one PICTURE character-string:

S V . CR DB

x E

Each time any of the above symbols appears in the character-string, it represents an occurrence of that character or set of allowable characters in the data item.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.7.3 Data Categories and PICTURE Rules

The allowable combinations of PICTURE symbols determine the data category of the item.

o Alphabetic items o Numeric Items o Numeric-edited items o Alphanumeric items o Alphanumeric-edited items x o DBCS items x o External floating-point items.

Alphabetic Items:

o The PICTURE character-string can contain only the symbol A.

x Note: This element may exhibit different behavior when the CMPR2 x compiler option is in effect. For more information, see VS COBOL II x Migration Guide for MVS and CMS or VS COBOL II Migration Guide for x VSE.

o The contents of the item in standard data format must consist of any of the letters of the English alphabet and the space character.

o USAGE DISPLAY must be specified or implied.

o Any associated VALUE clause must specify a nonnumeric literal containing only alphabetic characters, SPACE, or a symbolic-character as the value of a figurative constant.

Numeric Items:

o Types of numeric items are:

- Binary - Packed decimal (internal decimal) - Zoned decimal (external decimal).

o The PICTURE character-string can contain only the symbols 9, P, S, and V.

o The number of digit positions must range from 1 through 18, inclusive.

| o If unsigned, the contents of the item in standard data format must be | one or more numeric characters. If signed, it can also contain a +, -, or other representation of the operational sign.

o The USAGE of the item can be DISPLAY, BINARY, COMPUTATIONAL, x PACKED-DECIMAL, COMPUTATIONAL-3, or COMPUTATIONAL-4.

o A VALUE clause can specify a figurative constant ZERO.

o A VALUE clause associated with an elementary numeric item must specify a numeric literal or the figurative constant ZERO. A VALUE clause associated with a group item consisting of elementary numeric items must specify a nonnumeric literal or a figurative constant, because the group is considered alphanumeric. In both cases, the literal is treated exactly as specified; no editing is performed.

| The following are examples of valid ranges for the PICTURE clause:

PICTURE Valid Range of Values

9999 0 through 9999 S99 -99 through +99 S999V9 -999.9 through +999.9 PPP999 0 through .000999 S999PPP -1000 through -999000 and +1000 through +999000 or zero

x The use of external decimal and internal decimal items which contain x non-preferred signs or negative zero values may be affected by the NUMPROC x compiler option.

x The value of a binary numeric item may be affected by the TRUNC compiler x option.

x For information on the NUMPROC and TRUNC compiler options, see VS COBOL II x Application Programming Guide for MVS and CMS or VS COBOL II Application x Programming Guide for VSE.

Numeric-edited Items:

o The PICTURE character-string can contain the following symbols:

B P V Z 9 0 / , . + - CR DB * $

The combinations of symbols allowed are determined from the PICTURE clause symbol order allowed (see Figure 5 in topic 2.7.7.1), and the editing rules (see "PICTURE Clause Editing" in topic 2.7.7.4). The following additional rules also apply:

- Either the BLANK WHEN ZERO clause must be specified for the item, or the string must contain at least one of the following symbols:

B / Z 0 , . * + - CR DB $

| - The number of digit positions represented by a PICTURE character-string must be in the range 1 through 18 inclusive.

| - The maximum number of character positions represented by a PICTURE | character-string is 249. The maximum number of symbols in one | PICTURE character-string is 30.

o The contents of those character positions representing digits in | standard data format must be one of the numeric characters, consistent | with the correct PICTURE symbol.

o USAGE DISPLAY must be specified or implied.

o Any associated VALUE clause must specify a nonnumeric literal or a figurative constant. The literal is treated exactly as specified; no editing is done.

Alphanumeric Items:

o The PICTURE character-string must consist of either of the following:

- The symbol X

- Combinations of the symbols A, X, and 9. (A character-string containing all As or all 9s does not define an alphanumeric item.)

o The item is treated as if the character-string contained only the symbol X.

- The contents of the item in standard data format can be any allowable characters from the character set of the computer.

- USAGE DISPLAY must be specified or implied.

- Any associated VALUE clause must specify a nonnumeric literal or a figurative constant.

Alphanumeric-edited Items:

o The PICTURE character-string can contain the following symbols:

A X 9 B 0 /

o The string must contain at least one A or X, and at least one B or 0 (zero) or /.

o The contents of the item in standard data format must be two or more characters from the character set of the computer.

o USAGE DISPLAY must be specified or implied.

o Any associated VALUE clause must specify a nonnumeric literal or a figurative constant. The literal is treated exactly as specified; no editing is done.

x DBCS Items:

x o The PICTURE character-string can contain the symbols G and/or B.

x o Each G or B represents a single DBCS character position (2 bytes).

x o USAGE DISPLAY-1 must be specified.

x o Any associated VALUE clause must specify a DBCS literal or the x figurative constant SPACE/SPACES.

x o The entire range of characters for a DBCS literal can be used.

x External Floating-point Items:

x o The PICTURE string must have the following form:

x ___ Format _________________________________________________________ x | | x | >>_________mantissa E_________exponent__>< | x | |_+_| |_+_| | x | |_-_| |_-_| | | | |____________________________________________________________________| x + or - x A sign character must immediately precede both the mantissa and x the exponent. x A + sign indicates that a positive sign will be used in the output x to represent positive values and that a negative sign will x represent negative values. x A - sign indicates that a blank will be used in the output to x represent positive values and that a negative sign will represent x negative values. Each sign position occupies one byte of storage.

x mantissa x The mantissa can contain the symbols:

x 9 . V

x An actual decimal point can be represented with a period (.) while x an assumed decimal point is represented by a V. Either an actual x or an assumed decimal point must be present in the mantissa; the x decimal point can be leading, embedded, or trailing. The mantissa x can contain from 1 to 16 numeric characters.

x E x Indicates the exponent.

x exponent x The exponent must consist of the symbol 99.

x o The OCCURS, REDEFINES, and RENAMES clauses can be associated with x external floating-point items.

x o The SIGN clause is accepted as documentation and has no effect on the x representation of the sign.

x o The SYNCHRONIZED clause is treated as documentation.

x o The following clauses are invalid with external floating-point items:

x - BLANK WHEN ZERO x - JUSTIFIED x - VALUE


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.7.4 PICTURE Clause Editing

There are two general methods of editing in a PICTURE clause:

o Insertion editing

- Simple insertion - Special insertion - Fixed insertion - Floating insertion.

o Suppression and replacement editing

- Zero suppression and replacement with asterisks - Zero suppression and replacement with spaces.

The type of editing allowed for an item depends on its data category. The type of editing that is valid for each category is shown below:

________________________________________________________________________ | Table 10. Data Categories | |________________________________________________________________________| | Data Category | Type of Editing | |____________________________________|___________________________________| | Alphabetic | None | |____________________________________|___________________________________| | Numeric | None | |____________________________________|___________________________________| | Numeric-edited | All | |____________________________________|___________________________________| | Alphanumeric | None | |____________________________________|___________________________________| | Alphanumeric-edited | Simple insertion | |____________________________________|___________________________________| x | DBCS | Simple insertion | |____________________________________|___________________________________| x | External floating-point | Special insertion | |____________________________________|___________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.7.5 Simple Insertion Editing

This type of editing is valid for alphanumeric-edited, numeric-edited, and x DBCS items.

The following insertion symbols are valid for each category:

________________________________________________________________________ | Table 11. Valid Insertion Symbols | |________________________________________________________________________| | Data Category | Insertion Symbol(s) | |____________________________________|___________________________________| | Numeric-edited | B 0 / , | |____________________________________|___________________________________| | Alphanumeric-edited | B 0 / | |____________________________________|___________________________________| x | DBCS | B | |____________________________________|___________________________________|

Each insertion symbol is counted in the size of the item, and represents the position within the item where the equivalent character is to be x inserted. For edited DBCS items, each insertion symbol (B) is counted in x the size of the item and represents the position within the item where the x DBCS space is to be inserted.

Examples of simple insertion editing:

PICTURE Value of Data Edited Result

X(10)/XX ALPHANUMER01 ALPHANUMER/01 X(5)BX(7) ALPHANUMERIC ALPHA NUMERIC 99,B999,B000 1234 01,234,000 99,999 12345 12,345 x GGBBGG D1D2D3D4 D1D2D3D4

| Note: The symbol indicates a space.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.7.6 Special Insertion Editing

x This type of editing is valid for either numeric-edited items or external x floating-point items.

The period (.) is the special insertion symbol; it also represents the actual decimal point for alignment purposes.

The period insertion symbol is counted in the size of the item, and represents the position within the item where the actual decimal point is inserted.

Either the actual decimal point or the symbol V as the assumed decimal point, but not both, must be specified in one PICTURE character-string.

Examples of special insertion editing:

PICTURE Value of Data Edited Results

999.99 1.234 001.23 999.99 12.34 012.34 999.99 123.45 123.45 999.99 1234.5 234.50 x +999.99E+99 12345 +123.45E+02


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.7.7 Fixed Insertion Editing

This type of editing is valid only for numeric-edited items. The following insertion symbols are used:

$ (currency symbol)

+ - CR DB (editing-sign control symbols)

In fixed insertion editing, only one currency symbol and one editing sign control symbol can be specified in one PICTURE character-string.

Unless it is preceded by a + or - symbol, the currency symbol must be the first character in the character-string.

When either + or - is used as a symbol, it must be the first or last character in the character-string.

When CR or DB is used as a symbol, it must occupy the rightmost two character positions in the character-string. If these two character positions contain the symbols CR or DB, the uppercase letters are the insertion characters.

Editing sign control symbols produce results that depend on the value of the data item, as shown below:

Editing Symbol Result: Result: in PICTURE Data Item Data Item Character-String Positive or Zero Negative

+ + - - space - CR 2 spaces CR DB 2 spaces DB

Examples of fixed insertion editing:

PICTURE Value of Data Edited Result

999.99+ +6555.556 555.55+ +9999.99 -6555.555 -6555.55 9999.99 +1234.56 1234.56 $999.99 -123.45 $123.45 -$999.99 -123.456 -$123.45 -$999.99 +123.456 $123.45 $9999.99CR +123.45 $0123.45 $9999.99DB -123.45 $0123.45DB


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.7.8 Floating Insertion Editing

This type of editing is valid only for numeric-edited items. The following symbols are used:

$ + -

Within one PICTURE character-string, these symbols are mutually exclusive as floating insertion characters.

Floating insertion editing is specified by using a string of at least two of the allowable floating insertion symbols to represent leftmost character positions into which these actual characters can be inserted.

The leftmost floating insertion symbol in the character-string represents the leftmost limit at which this actual character can appear in the data item. The rightmost floating insertion symbol represents the rightmost limit at which this actual character can appear.

The second leftmost floating insertion symbol in the character-string represents the leftmost limit at which numeric data can appear within the data item. Nonzero numeric data can replace all characters at or to the right of this limit.

| Any simple-insertion symbols (B 0 / ,) within or to the immediate right of | the string of floating insertion symbols are considered part of the | floating character-string.

In a PICTURE character-string, there are two ways to represent floating insertion editing and thus, two ways in which editing is performed:

1. Any or all leading numeric character positions to the left of the decimal point are represented by the floating insertion symbol. When editing is performed, a single floating insertion character is placed to the immediate left of the first nonzero digit in the data, or of the decimal point, whichever is farther to the left. The character positions to the left of the inserted character are filled with spaces.

| If all numeric character positions in the PICTURE character-string are | represented by the insertion character, then at least 1 of the | insertion characters must be to the left of the decimal point.

2. All the numeric character positions are represented by the floating insertion symbol. When editing is performed, then:

o If the value of the data is zero, the entire data item will contain spaces. o If the value of the data is nonzero, the result is the same as in rule 1.

To avoid truncation, the minimum size of the PICTURE character-string must be:

o The number of character positions in the sending item, plus o The number of nonfloating insertion symbols in the receiving item, plus o 1 character for the floating insertion symbol.

Examples of floating insertion editing:

PICTURE Value of Data Edited Result

$$$$.99 .123 $.12 $$$9.99 .12 $0.12 $,$$$,999.99 -1234.56 $1,234.56 +,+++,999.99 -123456.789 -123,456.78 $$,$$$,$$$.99CR -1234567 $1,234,567.00CR ++,+++,+++.+++ 0000.00


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.7.9 Zero Suppression and Replacement Editing

This type of editing is valid only for numeric-edited items. In zero suppression editing, the symbols Z and * are used. These symbols are mutually exclusive in one PICTURE character-string.

The following symbols are mutually exclusive as floating replacement symbols in one PICTURE character-string:

Z * + - $

Specify zero suppression and replacement editing with a string of one or more of the allowable symbols to represent leftmost character positions in which zero suppression and replacement editing can be performed.

| Any simple insertion symbols (B 0 / ,) within or to the immediate right of | the string of floating editing symbols are considered part of the string.

In a PICTURE character-string, there are two ways to represent zero suppression, and two ways in which editing is performed:

o Any or all of the leading numeric character positions to the left of the decimal point are represented by suppression symbols. When editing is performed, any leading zero in the data that appears in the same character position as a suppression symbol is replaced by the replacement character. Suppression stops at the leftmost character:

- That does not correspond to a suppression symbol - That contains nonzero data - That is the decimal point.

o All the numeric character positions in the PICTURE character-string are represented by the suppression symbols. When editing is performed, and the value of the data is nonzero, the result is the same as in the preceding rule. If the value of the data is zero, then:

- If Z has been specified, the entire data item will contain spaces.

- If * has been specified, the entire data item, except the actual decimal point, will contain asterisks.

Note: Do not specify both the asterisk (*) as a suppression symbol and the BLANK WHEN ZERO clause for the same entry.

Examples of zero suppression and replacement editing:

PICTURE Value of Data Edited Result

****.** 0000.00 ****.** ZZZZ.ZZ 0000.00 ZZZZ.99 0000.00 .00 ****.99 0000.00 ****.00 ZZ99.99 0000.00 00.00 Z,ZZZ.ZZ+ +123.456 123.45+ *,***.**+ -123.45 **123.45- **,***,***.**+ +12345678.9 12,345,678.90+ $Z,ZZZ,ZZZ.ZZCR +12345.67 $ 12,345.67 $B*,***,***.**BBDB -12345.67 $ ***12,345.67 DB


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.8 REDEFINES Clause

The REDEFINES clause allows you to use different data description entries to describe the same computer storage area.

@@ Diagram redefines-clause ADAPTED. @@ Implemented text below the diagram. ___ redefines-clause ___________ | | | >>__REDEFINES__data-name-2__>< | | | |________________________________| Note: Level-number, data-name-1, and FILLER are not part of the REDEFINES clause itself, and are included in the format only for clarity.

When specified, the REDEFINES clause must be the first entry following data-name-1 or FILLER. If data-name-1 or FILLER is not specified, the REDEFINES clause must be the first entry following the level-number.

The level-numbers of data-name-1 and data-name-2 must be identical, and must not be level 66 or level 88.

data-name-1, FILLER Identifies an alternate description for the same area, and is the redefining item or the REDEFINES subject.

x Data-name-1 can specify a DBCS, USAGE IS POINTER, or internal or x external floating-point data item.

data-name-2 Is the redefined item or the REDEFINES object.

x Data-name-2 can specify a DBCS, USAGE IS POINTER, or internal or x external floating-point data item.

When more that one level-01 entry is written subordinate to an FD entry, a condition known as implicit redefinition occurs. That is, the second level-01 entry implicitly redefines the storage allotted for the first entry. In such level-01 entries, the REDEFINES clause must not be specified.

Redefinition begins at data-name-1 and ends when a level-number less than or equal to that of data-name-1 is encountered. No entry having a level-number numerically lower than those of data-name-1 and data-name-2 can occur between these entries. For example:

05 A PICTURE X(6). 05 B REDEFINES A. 10 B-1 PICTURE X(2). 10 B-2 PICTURE 9(4). 05 C PICTURE 99V99.

In this example, A is the redefined item, and B is the redefining item. Redefinition begins with B and includes the two subordinate items B-1 and B-2. Redefinition ends when the level-05 item C is encountered.

x The data description entry for data-name-2, the redefined item, can x contain a REDEFINES clause.

The data description entry for the redefined item cannot contain an OCCURS clause with or without the DEPENDING ON option. However, the redefined item can be subordinate to an item whose data description entry contains an OCCURS clause. In this case, the reference to the redefined item in the REDEFINES clause must not be subscripted. Neither the original definition nor the redefinition can include a variable occurrence data item. Neither the redefined item nor the redefining item, or any items subordinate to them, can contain an OCCURS DEPENDING ON clause.

If the GLOBAL clause is used in the data description entry which contains the REDEFINES clause, it is only the subject of that REDEFINES clause that possesses the global attribute.

The EXTERNAL clause must not be specified on the same data description entry as a REDEFINES clause.

If the data item referenced by data-name-2 is either declared to be an external data record or is specified with a level-number other than 01, the number of character positions it contains must be greater than or equal to the number of character positions in the data item referenced by the subject of this entry. If the data-name referenced by data-name-2 is specified with a level-number of 01 and is not declared to be an external | data record, there is no such constraint; in this case, the storage | allocated is the length of the larger data-item, either data-name-1 or | data-name-2.

x When the data item implicitly redefines multiple 01-level records in a x file description (FD) entry, items subordinate to the redefining or x redefined item can contain an OCCURS DEPENDING ON clause.

One or more redefinitions of the same storage area are permitted. The entries giving the new descriptions of the storage area must immediately follow the description of the redefined area without intervening entries that define new character positions. Multiple redefinitions must all use the data-name of the original entry that defined this storage area. For example:

05 A PICTURE 9999. 05 B REDEFINES A PICTURE 9V999. 05 C REDEFINES A PICTURE 99V99.

The redefining entry (identified by data-name-1), and any subordinate entries, must not contain any VALUE clauses.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.8.1 REDEFINES Clause Considerations

Data items within an area can be redefined without changing their lengths. For example:

05 NAME-2. 10 SALARY PICTURE XXX. 10 SO-SEC-NO PICTURE X(9). 10 MONTH PICTURE XX. 05 NAME-1 REDEFINES NAME-2. 10 WAGE PICTURE XXX. 10 EMP-NO PICTURE X(9). 10 YEAR PICTURE XX.

Data item lengths and types can also be respecified within an area. For example:

05 NAME-2. 10 SALARY PICTURE XXX. 10 SO-SEC-NO PICTURE X(9). 10 MONTH PICTURE XX. 05 NAME-1 REDEFINES NAME-2. 10 WAGE PICTURE 999V999. 10 EMP-NO PICTURE X(6). 10 YEAR PICTURE XX.

When an area is redefined, all descriptions of the area are always in effect; that is, redefinition does not cause any data to be erased and never supersedes a previous description. Thus, if B REDEFINES C has been specified, either of the two procedural statements, MOVE X TO B and MOVE Y TO C, could be executed at any point in the program.

In the first case, the area described as B would assume the value and format of X. In the second case, the same physical area (described now as C) would assume the value and format of Y. Note that, if the second statement is executed immediately after the first, the value of Y replaces the value of X in the one storage area.

The usage of a redefining data item need not be the same as that of a redefined item. This does not, however, cause any change in existing data. For example:

05 B PICTURE 99 USAGE DISPLAY VALUE 8. 05 C REDEFINES B PICTURE S99 USAGE COMPUTATIONAL-4. 05 A PICTURE S99 USAGE COMPUTATIONAL-4.

The bit configuration of the DISPLAY VALUE 8 is:

1111 0000 1111 1000.

Redefining B does not change the bit configuration of the data in the storage area. Therefore, the following two statements produce different results:

ADD B TO A ADD C TO A

In the first case, the value 8 is added to A (because B has USAGE DISPLAY). In the second statement, the value -3848 is added to A (because C has USAGE COMPUTATIONAL-4), and the bit configuration of the storage area has the binary value -3848.

The above example demonstrates how the improper use of redefinition can give unexpected or incorrect results.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.8.2 REDEFINES Clause Examples

The REDEFINES clause can be specified for an item within the scope of an area being redefined (that is, an item subordinate to a redefined item). For example:

05 REGULAR-EMPLOYEE. 10 LOCATION PICTURE A(8). 10 GRADE PICTURE X(4). 10 SEMI-MONTHLY-PAY PICTURE 9999V99. 10 WEEKLY-PAY REDEFINES SEMI-MONTHLY-PAY PICTURE 999V999.

05 TEMPORARY-EMPLOYEE REDEFINES REGULAR-EMPLOYEE. 10 LOCATION PICTURE A(8). 10 FILLER PICTURE X(6). 10 HOURLY-PAY PICTURE 99V99.

The REDEFINES clause can also be specified for an item subordinate to a redefining item. For example:

05 REGULAR-EMPLOYEE. 10 LOCATION PICTURE A(8). 10 GRADE PICTURE X(4). 10 SEMI-MONTHLY-PAY PICTURE 999V999.

05 TEMPORARY-EMPLOYEE REDEFINES REGULAR-EMPLOYEE. 10 LOCATION PICTURE A(8). 10 FILLER PICTURE X(6). 10 HOURLY-PAY PICTURE 99V99. 10 CODE-H REDEFINES HOURLY-PAY PICTURE 9999.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.8.3 Undefined Results

Undefined results may occur when:

o A redefining item is moved to a redefined item (that is, if B REDEFINES C and the statement MOVE B TO C is executed)

o A redefined item is moved to a redefining item (that is, if B REDEFINES C and if the statement MOVE C TO B is executed).


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.9 RENAMES Clause

The RENAMES clause specifies alternative, possibly overlapping, groupings of elementary data items.

@@ Diagram renames-clause ADAPTED. @@ Enabled qualified instead of plain data names. @@ Diagram renames-clause ADAPTED. @@ Enabled qualified instead of plain data names. @@ Diagram renames-clause ADAPTED. @@ Implemented note that 66 and data-name-1 do not belong to clause. @@ Diagram renames-clause ADAPTED. @@ Neither does the "." belong to the clause. ___ renames-clause _________________________________ | | | >>__RENAMES__qualified-data-name-2_______________> | | | | >_______________________________________________>< | | |_____THROUGH_____qualified-data-name-3__| | | |__THRU_____| | | | |____________________________________________________| The special level-number 66 must be specified for data description entries that contain the RENAMES clause. Level-number 66 and data-name-1 are not part of the RENAMES clause itself, and are included in the format only for clarity.

One or more RENAMES entries can be written for a logical record. All RENAMES entries associated with one logical record must immediately follow that record's last data description entry.

data-name-1 Identifies an alternative grouping of data items.

A level-66 entry cannot rename a level-01, level-77, level-88, or another level-66 entry.

Data-name-1 cannot be used as a qualifier; it can be qualified only by the names of level indicator entries or level-01 entries.

x Can specify a DBCS data item if data-name-2 specifies a DBCS data item x and the THROUGH phrase is not specified.

data-name-2, data-name-3 Identify the original grouping of elementary data items; that is, they must name elementary or group items within the associated level-01 entry, and must not be the same data-name. Both data-names can be qualified.

The OCCURS clause must not be specified in the data entries for data-name-2 and data-name-3, or for any group entry to which they are subordinate. In addition, the OCCURS DEPENDING ON clause must not be specified for any item defined between data-name-2 and data-name-3.

When data-name-3 is specified, data-name-1 is treated as a group item that includes all elementary items:

o Starting with data-name-2 (if it is an elementary item) or the first elementary item within data-name-2 (if it is a group item)

o Ending with data-name-3 (if it is an elementary item) or the last elementary item within data-name-3 (if it is a group item).

The keywords THROUGH and THRU are equivalent.

The leftmost character in data-name-3 must not precede the leftmost character in data-name-2; the rightmost character in data-name-3 must not precede the rightmost character in data-name-2. This means that data-name-3 cannot be totally subordinate to data-name-2.

When data-name-3 is not specified, all of the data attributes of data-name-2 become the data attributes for data-name-1. That is:

o When data-name-2 is a group item, data-name-1 is treated as a group item.

o When data-name-2 is an elementary item, data-name-1 is treated as an elementary item.

Figure 6 illustrates valid and invalid RENAMES clause specifications.


COBOL Specifications Storage Layouts

Example 1 (Valid) 01 RECORD_I. 05 DN_1... . |<_______________RECORD_I_______________>| 05 DN_2... . ________________________________________ 05 DN_3... . | DN_1 | DN_2 | DN_3 | DN_4 | 05 DN_4... . |______|__________|___________|__________| 66 DN_6 RENAMES DN_1 THROUGH DN_3. |<___________DN_6____________>|

Example 2 (Valid) 01 RECORD_II. |<_______________RECORD_II______________>| 05 DN_1. |<___________DN_1_____________>| | 10 DN_2... . ________________________________________ 10 DN_2A... . | DN_2 | DN_2A | DN_5 | 05 DN_1A REDEFINES DN_1. |__________|___________________|_________| 10 DN_3A... . |<___________DN_1A____________>| 10 DN_3... . ______________________________ 10 DN_3B... . | DN_3A | DN_3 | DN_3B | 05 DN_5... . |_______|________|_____________| 66 DN_6 RENAMES DN_2 THROUGH DN_3. |<_____DN_6_____>|

Example 3 (Invalid) 01 RECORD_III. |<______________RECORD_III______________>| 05 DN_2. |<________DN_2_________>| | 10 DN_3... . ________________________________________ 10 DN_4... . | DN_3 | DN_4 | DN_5 | 05 DN_5... . |__________|____________|________________| 66 DN_6 RENAMES DN_2 THROUGH DN_3. DN_6 is indeterminate

Example 4 (Invalid) 01 RECORD_IV. |<______________RECORD_IV_______________>| 05 DN_1. |<_________DN_1___________>| | 10 DN_2A... . ________________________________________ 10 DN_2B... . | DN_2A | DN_2B | DN_3 | 10 DN_2C REDEFINES DN_2B. |__________|_______________|_____________| 15 DN_2... . _______________ 15 DN_2D... . | DN_2 | DN_2D | 05 DN_3... . |_______|_______| 66 DN_4 RENAMES DN_1 THROUGH DN_2. DN_4 is indeterminate


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document. Figure 6. RENAMES Clause--Valid and Invalid Specifications

Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.10 SIGN Clause

The SIGN clause specifies the position and mode of representation of the operational sign for a numeric entry.

___ sign-clause _______________________________________________________________ | | | >>___________________________LEADING_______________________________________>< | | |__SIGN____________| |__TRAILING__| |__SEPARATE___________________| | | |__IS__| |__CHARACTER__| | | | |_______________________________________________________________________________| The SIGN clause can be specified only for a signed numeric data description entry (that is, one whose PICTURE character-string contains an S), or for a group item that contains at least one such elementary entry. USAGE IS DISPLAY must be specified, explicitly or implicitly.

If a SIGN clause is specified in either an elementary or group entry subordinate to a group item for which a SIGN clause is specified, the SIGN clause for the subordinate entry takes precedence for the subordinate entry.

If you specify the CODE-SET clause in an FD entry, any signed numeric data description entries associated with that file description entry must be described with the SIGN IS SEPARATE clause.

The SIGN clause is required only when an explicit description of the properties and/or position of the operational sign is necessary.

When specified, the SIGN clause defines the position and mode of representation of the operational sign for the numeric data description entry to which it applies, or for each signed numeric data description entry subordinate to the group to which it applies.

If the SEPARATE CHARACTER phrase is not specified, then:

o The operational sign is presumed to be associated with the LEADING or TRAILING digit position, whichever is specified, of the elementary numeric data item. (In this instance, specification of SIGN IS TRAILING is the equivalent of the standard action of the compiler.)

o The character S in the PICTURE character string is not counted in determining the size of the item (in terms of standard data format characters).

If the SEPARATE CHARACTER phrase is specified, then:

o The operational sign is presumed to be the LEADING or TRAILING character position, whichever is specified, of the elementary numeric data item. This character position is not a digit position.

o The character S in the PICTURE character string is counted in determining the size of the data item (in terms of standard data format characters).

o + is the character used for the positive operational sign.

o - is the character used for the negative operational sign.

Every numeric data description entry whose PICTURE contains the symbol S is a signed numeric data description entry. If the SIGN clause is also specified for such an entry, and conversion is necessary for computations or comparisons, the conversion takes place automatically.

x The SIGN clause is treated as documentation for external floating-point x items. For internal floating-point items, the SIGN clause is invalid and x will result in an S-level diagnostic message.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.11 SYNCHRONIZED Clause

The SYNCHRONIZED clause specifies the alignment of an elementary item on a natural boundary in storage.

___ synchronized-clause _________________ | | | >>_____SYNCHRONIZED__________________>< | | |__SYNC__________| |__LEFT___| | | |__RIGHT__| | | | |_________________________________________| SYNC is an abbreviation for SYNCHRONIZED and has the same meaning.

The SYNCHRONIZED clause is never required, but may improve performance on some systems for binary items used in arithmetic.

The SYNCHRONIZED clause be specified only at the elementary level.

x The SYNCHRONIZED clause be specified for level-01 group items, in which x case every elementary item within the level-01 group item is synchronized.

LEFT Specifies that the elementary item is to be positioned so that it will begin at the left character position of the natural boundary in which the elementary item is placed.

RIGHT Specifies that the elementary item is to be positioned such that it will terminate on the right character position of the natural boundary in which it has been placed.

| When specified, the LEFT and the RIGHT phrases are syntax-checked, but are | treated as documentation.

The length of an elementary item is not affected by the SYNCHRONIZED clause.

When the SYNCHRONIZED clause is specified for an item within the scope of an OCCURS clause, each occurrence of the item is synchronized.

| The SYNCHRONIZED clause for a DISPLAY or PACKED-DECIMAL item is | syntax-checked, but is treated as documentation.

When the SYNCHRONIZED clause is specified for a BINARY or COMPUTATIONAL item that is the first elementary item subordinate to an item that contains a REDEFINES clause, the item must not require the addition of unused character positions.

| When the synchronized clause is specified for a subordinate data item (one with a level number of 02 through 49):

o The item is aligned at a displacement that is a multiple of 2 relative to the beginning of the record, if its USAGE is BINARY and its PICTURE is in the range of S9 through S9(4).

o The item is aligned at a displacement that is a multiple of 4 relative to the beginning of the record, if its USAGE is BINARY and its PICTURE x is in the range of S9(5) through S9(18), or its USAGE is INDEX.

When SYNCHRONIZED is not specified for binary items, no space is reserved for slack bytes.

x The SYNCHRONIZED clause for a USAGE IS POINTER data item aligns the data x on a fullword boundary.

x The SYNCHRONIZED clause for a COMPUTATIONAL-1 data item aligns the data on x a fullword boundary.

x The SYNCHRONIZED clause for a COMPUTATIONAL-2 data item aligns the data on x a doubleword boundary.

x The SYNCHRONIZED clause for a COMPUTATIONAL-3 data item is treated the x same as the SYNCHRONIZED clause for a PACKED-DECIMAL item.

x The SYNCHRONIZED clause for a COMPUTATIONAL-4 item is treated the same as x the SYNCHRONIZED clause for a COMPUTATIONAL item.

x The SYNCHRONIZED clause is ignored for a DBCS item and floating-point data x items.

When the SYNCHRONIZED clause is specified for an item that also contains a REDEFINES clause, the data item that is redefined must have the proper boundary alignment for the data item that redefines it. For example, if you write the following, be sure that data item A begins on a fullword boundary:

02 A PICTURE X(4). 02 B REDEFINES A PICTURE S9(9) BINARY SYNC.

In the File Section, the compiler assumes that all level-01 records containing SYNCHRONIZED items are aligned on doubleword boundaries in the buffer. You must provide the necessary slack bytes between records to ensure alignment when there are multiple records in a block.

In the Working-Storage Section, the compiler aligns all level-01 entries on a doubleword boundary.

For the purposes of aligning binary items in the Linkage Section, all level-01 items are assumed to begin on doubleword boundaries. Therefore, if you issue a CALL statement, such operands of any USING phrase within it must be aligned correspondingly.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.11.1 Slack Bytes

There are two types of slack bytes:

Slack bytes within records Unused character positions preceding each synchronized item in the record.

Slack bytes between records Unused character positions added between blocked logical records.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.11.2 Slack Bytes within Records

For an output file, or in the Working-Storage Section, the compiler inserts slack bytes within a record to ensure that all SYNCHRONIZED items are on their proper boundaries. For an input file, or in the Linkage Section, performance is improved if binary items are properly aligned.

Because it is important that you know the length of the records in a file, you need to determine whether slack bytes are required and, if necessary, how many to add. The algorithm the compiler uses to calculate this is as follows:

o The total number of bytes occupied by all elementary data items preceding the binary item are added together, including any slack bytes previously added.

o This sum is divided by m, where:

m = 2 for binary items of 4-digit length or less

m = 4 for binary items of 5-digit length or more and for USAGE IS INDEX data items

x m = 4 for USAGE IS POINTER and COMPUTATIONAL-1 data items

x m = 8 for COMPUTATIONAL-2 data items.

o If the remainder (r) of this division is equal to zero, no slack bytes are required. If the remainder is not equal to zero, the number of slack bytes that must be added is equal to m - r.

These slack bytes are added to each record immediately following the elementary data item preceding the binary item. They are defined as if they constituted an item with a level number equal to that of the elementary item that immediately precedes the SYNCHRONIZED binary item, and are included in the size of the group that contains them.

For example:

01 FIELD-A. 05 FIELD-B PICTURE X(5). 05 FIELD-C. 10 FIELD-D PICTURE XX. [10 SLACK-BYTES PICTURE X. INSERTED BY COMPILER] 10 FIELD-E COMPUTATIONAL PICTURE S9(6) SYNC.

01 FIELD-L. 05 FIELD-M PICTURE X(5). 05 FIELD-N PICTURE XX. [05 SLACK-BYTES PICTURE X. INSERTED BY COMPILER] 05 FIELD-O. 10 FIELD-P COMPUTATIONAL PICTURE S9(6) SYNC.

Slack bytes may also be added by the compiler when a group item is defined with an OCCURS clause and contains within it a SYNCHRONIZED binary data item. To determine whether slack bytes are to be added, the following action is taken:

o The compiler calculates the size of the group, including all the necessary slack bytes within a record.

o This sum is divided by the largest m required by any elementary item within the group.

o If r is equal to zero, no slack bytes are required. If r is not equal to zero, m - r slack bytes must be added.

| The slack bytes are inserted before the SYNCHRONIZED items within each occurrence of the group item containing the OCCURS clause. For example, a record defined as follows will appear in storage as shown in Figure 7:

01 WORK-RECORD. 05 WORK-CODE PICTURE X. 05 COMP-TABLE OCCURS 10 TIMES. 10 COMP-TYPE PICTURE X. [10 SLACK-BYTES PIC XX. INSERTED BY COMPILER] 10 COMP-PAY PICTURE S9(4)V99 COMP SYNC. 10 COMP-HRS PICTURE S9(3) COMP SYNC. 10 COMP-NAME PICTURE X(5).

The storage layout for the first occurrence of COMP-TABLE will now appear as shown in Figure 7.

| PICTURE 2

| Figure 7. Insertion of Slack Bytes within a Record

In order to align COMP-PAY and COMP-HRS upon their proper boundaries, the compiler has added two slack bytes within the record.

In the previous example, without further adjustment, the second occurrence of COMP-TABLE would begin one byte before a doubleword boundary, and the alignment of COMP-PAY and COMP-HRS would not be valid for any occurrence of the table after the first. Therefore, the compiler must add slack | bytes at the end of each occurrence of the group item containing the | OCCURS clause, as though the record had been written as follows:

01 WORK-RECORD. 05 WORK-CODE PICTURE X. 05 COMP-TABLE OCCURS 10 TIMES. 10 COMP-TYPE PICTURE X. [10 SLACK-BYTES PIC XX. INSERTED BY COMPILER ] 10 COMP-PAY PICTURE S9(4)V99 COMP SYNC. 10 COMP-HRS PICTURE S9(3) COMP SYNC. 10 COMP-NAME PICTURE X(5). [10 SLACK-BYTES PIC XX. INSERTED BY COMPILER]

In this example, the second (and each succeeding) occurrence of COMP-TABLE | begins 1 byte beyond a doubleword boundary. The storage layout for the | first two occurrences of COMP-TABLE will now appear as shown in Figure 8.

| PICTURE 3

| Figure 8. Insertion of Slack Bytes within a Record

Each succeeding occurrence within the table will now begin at the same relative position as the first.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.11.3 Slack Bytes between Records

If the file contains blocked logical records that are to be processed in a buffer, and any of the records contain binary entries for which the SYNCHRONIZED clause is specified, you can improve performance by adding any needed slack bytes between records for proper alignment.

The lengths of all the elementary data items in the record, including all slack bytes, are added. (For variable-length records, it is necessary to add an additional 4 bytes for the count field.) The total is then divided by the highest value of m for any one of the elementary items in the record.

If r (the remainder) is equal to zero, no slack bytes are required. If r is not equal to zero, m - r slack bytes are required. These slack bytes can be specified by writing a level-02 FILLER at the end of the record.

To show the method of calculating slack bytes both within and between records, consider the following record description:

01 COMP-RECORD. 05 A-1 PICTURE X(5). 05 A-2 PICTURE X(3). 05 A-3 PICTURE X(3). 05 B-1 PICTURE S9999 USAGE COMP SYNCHRONIZED. 05 B-2 PICTURE S99999 USAGE COMP SYNCHRONIZED. 05 B-3 PICTURE S9999 USAGE COMP SYNCHRONIZED.

The number of bytes in A-1, A-2, and A-3 totals 11. B-1 is a 4-digit COMPUTATIONAL item and 1 slack byte must therefore be added before B-1. With this byte added, the number of bytes preceding B-2 totals 14. Because B-2 is a COMPUTATIONAL item of 5 digits in length, two slack bytes must be added before it. No slack bytes are needed before B-3.

The revised record description entry now appears as:

01 COMP-RECORD. 05 A-1 PICTURE X(5). 05 A-2 PICTURE X(3). 05 A-3 PICTURE X(3). [05 SLACK-BYTE-1 PICTURE X. INSERTED BY COMPILER] 05 B-1 PICTURE S9999 USAGE COMP SYNCHRONIZED. [05 SLACK-BYTE-2 PICTURE XX. INSERTED BY COMPILER] 05 B-2 PICTURE S99999 USAGE COMP SYNCHRONIZED. 05 B-3 PICTURE S9999 USAGE COMP SYNCHRONIZED.

There is a total of 22 bytes in COMP-RECORD, but, from the rules given in the preceding discussion, it appears that m = 4 and r = 2. Therefore, to attain proper alignment for blocked records, you must add 2 slack bytes at the end of the record.

The final record description entry appears as:

01 COMP-RECORD. 05 A-1 PICTURE X(5). 05 A-2 PICTURE X(3). 05 A-3 PICTURE X(3). [05 SLACK-BYTE-1 PICTURE X. INSERTED BY COMPILER] 05 B-1 PICTURE S9999 USAGE COMP SYNCHRONIZED. [05 SLACK-BYTE-2 PICTURE XX. INSERTED BY COMPILER] 05 B-2 PICTURE S99999 USAGE COMP SYNCHRONIZED. 05 B-3 PICTURE S9999 USAGE COMP SYNCHRONIZED. 05 FILLER PICTURE XX. [SLACK BYTES YOU ADD]


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.12 USAGE Clause

The USAGE clause specifies the format of a data item in computer storage.

___ usage-clause ___________________________________________ | | | >>____________________________BINARY____________________>< | | |__USAGE____________| |__COMP___________________| | | |__IS__| |__{__COMP-1__}___________| | | |__{__COMP-2__}___________| | | |__{__COMP-3__}___________| | | |__{__COMP-4__}___________| | | |__COMPUTATIONAL__________| | | |__{__COMPUTATIONAL-1__}__| | | |__{__COMPUTATIONAL-2__}__| | | |__{__COMPUTATIONAL-3__}__| | | |__{__COMPUTATIONAL-4__}__| | | |__DISPLAY________________| | | |__{__DISPLAY-1__}________| | | |__INDEX__________________| | | |__PACKED-DECIMAL_________| | | |__{__POINTER__}__________| | | | |____________________________________________________________| The USAGE clause can be specified for a data description entry with a level-number other than 66 or 88. However, if it is specified at the group level, it applies to each elementary item in the group. The usage of an elementary item must not contradict the usage of a group to which the elementary item belongs.

The USAGE clause specifies the format in which data is represented in storage. The format may be restricted if certain Procedure Division statements are used.

When the USAGE clause is not specified at either the group or elementary level, it is assumed that the usage is DISPLAY.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.12.1 Computational Items

| A computational item is a value that can be used in arithmetic operations. It must be numeric. If the USAGE of a group item is described with any of these items, the elementary items within the group have this usage.

The maximum length of a computational item is 18 decimal digits.

The PICTURE of a computational item can contain only:

9 one or more numeric character positions S One operational sign V One implied decimal point P One or more decimal scaling positions.

x COMPUTATIONAL-1 and COMPUTATIONAL-2 items (internal floating-point) cannot x have PICTURE strings.

BINARY Specified for binary data items. Such items have a decimal equivalent consisting of the decimal digits 0 through 9, plus a sign. Negative numbers are represented as the two's complement of the positive number with the same absolute value.

The amount of storage occupied by a binary item depends on the number of decimal digits defined in its PICTURE clause:

____________________________________________________________________ | Digits in PICTURE Clause | Storage Occupied | |__________________________________|_________________________________| | 1 through 4 | 2 bytes (halfword) | |__________________________________|_________________________________| | 5 through 9 | 4 bytes (fullword) | |__________________________________|_________________________________| | 10 through 18 | 8 bytes (doubleword) | |__________________________________|_________________________________|

The leftmost bit of the storage area is the operational sign.

PACKED-DECIMAL Specified for internal decimal items. Such an item appears in storage in packed decimal format. There are 2 digits for each character position, except for the trailing character position, which is occupied by the low-order digit and the sign. Such an item can contain any of the digits 0 through 9, plus a sign, representing a value not exceeding 18 decimal digits.

The sign representation uses the same bit configuration as the 4-bit sign representation in zoned decimal fields (see Table 12 in topic 2.7.12.2 and Table 13 in topic 2.7.12.2).

COMPUTATIONAL or COMP Representation of the COMPUTATIONAL phrase is system-dependent and is normally assigned to representations that yield the greatest efficiency when arithmetic operations are performed on that system. For the VS COBOL II compiler, the COMPUTATIONAL phrase is synonymous with BINARY.

x COMPUTATIONAL-1 or COMP-1 x Specified for internal floating-point items (single precision). x COMP-1 items are 4 bytes long. The sign is contained in the first bit x of the leftmost byte and the exponent is contained in the remaining 7 x bits. The last 3 bytes contain the mantissa.

x COMPUTATIONAL-2 or COMP-2 x Specified for internal floating-point items (double precision). x COMP-2 items are 8 bytes long. The sign is contained in the first bit x of the leftmost byte and the remaining 7 bits contain the exponent. x The remaining 7 bytes contain the mantissa.

x COMPUTATIONAL-3 or COMP-3 (internal decimal) x For VS COBOL II, this is the equivalent of PACKED-DECIMAL.

x COMPUTATIONAL-4 or COMP-4 (binary) x For VS COBOL II this is the equivalent of BINARY.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.12.2 DISPLAY Phrase

The data item is stored in character form, 1 character for each 8-bit byte. This corresponds to the format used for printed output. DISPLAY can be explicit or implicit.

USAGE IS DISPLAY is valid for the following types of items:

o Alphabetic o Alphanumeric o Alphanumeric-edited o Numeric-edited x o External floating-point o External decimal (numeric).

Alphabetic, alphanumeric, alphanumeric-edited, and numeric-edited items are discussed in "Data Categories and PICTURE Rules" in topic 2.7.7.3.

External Decimal Items are sometimes referred to as zoned decimal items. Each digit of a number is represented by a single byte. The 4 high-order bits of each byte are zone bits; the 4 high-order bits of the low-order byte represent the sign of the item. The 4 low-order bits of each byte contain the value of the digit.

The maximum length of an external decimal item is 18 digits.

The PICTURE character-string of an external decimal item can contain only 9s; the operational-sign, S; the assumed decimal point, V; and one or more Ps.

______________________________________________________________________________________________________________________ | Table 12. Internal Representation of Numeric Items | |______________________________________________________________________________________________________________________| | Numeric Type | PICTURE and USAGE and Optional SIGN Clause | Value. | Internal Representation* | |_________________|____________________________________________|__________________|____________________________________| | External | PIC S9999 DISPLAY | + 1234 | | | | | | | | | | Decimal | | - 1234 | | F1 | F2 | F3 | C4| | | | | | | 1234 | | F1 | F2 | F3 | D4| | | | | | | | | F1 | F2 | F3 | C4| | | | | | PIC 9999 DISPLAY | + 1234 | | | | | | | | | | | | - 1234 | | F1 | F2 | F3 | F4| | | | | | | 1234 | | F1 | F2 | F3 | F4| | | | | | | | | F1 | F2 | F3 | F4| | | | | | PIC S9999 DISPLAY | + 1234 | | | | | | | | | | | SIGN LEADING | - 1234 | | C1 | F2 | F3 | F4| | | | | | | | | D1 | F2 | F3 | F4| | | | | | PIC S9999 DISPLAY | + 1234 | | | | | | | | | | | SIGN LEADING SEPARATE | - 1234 | 4E| F1 | F2 | F3 | F4| | | | | | | | 60| F1 | F2 | F3 | F4| | | | | | PIC S9999 DISPLAY | + 1234 | | | | | | | | | | | SIGN TRAILING SEPARATE | - 1234 | | F1 | F2 | F3 | F4| 4E | | | | | | | | F1 | F2 | F3 | F4| 60 | | | | | | | | | | | | | | | |_________________|____________________________________________|__________________|___|____|____|____|___|____|____|___| | Binary | PIC S9999 BINARY | + 1234 | | | | | | | | | | | COMP | - 1234 | | 04 | D2 | | | | | | x | | COMP-4 | | | FB | 2E | | | | | | | | | | | | | | | | | | | | PIC 9999 BINARY | + 1234 | | | | | | | | | | | COMP | - 1234 | | 04 | D2 | | | | | | x | | COMP-4 | | | 04 | D2 | | | | | | | | | | | | | | | | | | |_________________|____________________________________________|__________________|___|____|____|____|___|____|____|___| | Internal | PIC S9999 PACKED-DECIMAL | + 1234 | | | | | | | | | x | Decimal | COMP-3 | - 1234 | | 01 | 23 | 4C | | | | | | | | | | 01 | 23 | 4D | | | | | | | PIC 9999 PACKED-DECIMAL | + 1234 | | | | | | | | | x | | COMP-3 | - 1234 | | 01 | 23 | 4F | | | | | | | | | | 01 | 23 | 4F | | | | | | | | | | | | | | | | | |_________________|____________________________________________|__________________|___|____|____|____|___|____|____|___| x | Internal | COMP-1 | + 1234 | | | | | | | | | x | Floating | | - 1234 | 43| 4D | 20 | 00 | | | | | x | Point | | | C3| 4D | 20 | 00 | | | | | | | | | | | | | | | | | |_________________|____________________________________________|__________________|___|____|____|____|___|____|____|___| x | Internal | COMP-2 | + 1234 | | | | | | | | | x | Floating | | - 1234 | 43| 4D | 20 | 00 | 00| 00 | 00 | 00| x | Point | | | C3| 4D | 20 | 00 | 00| 00 | 00 | 00| | | | | | | | | | | | | |_________________|____________________________________________|__________________|___|____|____|____|___|____|____|___| x | External | PIC +9(2).9(2)E+99 DISPLAY | + 1234 | | | | | | | | | x | Floating | | | 4E| F1 | F2 | 4B | F3| | | | x | Point | | - 1234 | | F4 | C5 | 4E | F0| F2 | | | x | | | | 60| F1 | F2 | 4B | F3| | | | x | | | | | F4 | C5 | 4E | F0| F2 | | | | | | | | | | | | | | | |_________________|____________________________________________|__________________|___|____|____|____|___|____|____|___|

______________________________________________________________________________ | Table 13. Bit Configuration and Sign Convention | |______________________________________________________________________________| | Hex. Digit| Bit Configuration | | Hex. Digit| Bit Configuration | |___________|_______________________|_______|___________|______________________| | 0 | 0000 | | 8 | 1000 | |___________|_______________________|_______|___________|______________________| | 1 | 0001 | | 9 | 1001 | |___________|_______________________|_______|___________|______________________| | 2 | 0010 | | A | 1010 | |___________|_______________________|_______|___________|______________________| | 3 | 0011 | | B | 1011 | |___________|_______________________|_______|___________|______________________| | 4 | 0100 | | C | 1100 | |___________|_______________________|_______|___________|______________________| | 5 | 0101 | | D | 1101 | |___________|_______________________|_______|___________|______________________| | 6 | 0110 | | E | 1110 | |___________|_______________________|_______|___________|______________________| | 7 | 0111 | | F | 1111 | |___________|_______________________|_______|___________|______________________| | Note: | | | | 1. The internal representation of each byte is shown as two hexadecimal | | digits. The bit configuration for each digit is shown above. | | 2. The leftmost bit of a binary number represents the sign: 0 is positive, | | 1 is negative. Negative numbers are shown in twos complement form. | | 3. Hexadecimal 4E and 60 represent the EBCDIC + and - signs, respectively. | | 4. For decimal sign conventions, see VS COBOL II Application Programming | | Guide for MVS and CMS. | x | 5. For internal floating-point sign conventions, see IBM System/370(*) | x | Principles of Operation (or comparable XA or ESA manual). | |______________________________________________________________________________|

x ()


x () (*) System/370 is a trademark of International Business x Machines Corporation.

Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

x 2.7.12.3 DISPLAY-1 Phrase

x The DISPLAY-1 phrase defines an item as DBCS.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.12.4 INDEX Phrase

A data item defined with the INDEX phrase is an index data item.

An index data item is a 4-byte elementary item (not necessarily connected with any table) that can be used to save index-name values for future reference. Through a SET statement, an index data item can be assigned an index-name value; such a value corresponds to the occurrence number in a table.

Direct references to an index data item can be made only in a SEARCH statement, a SET statement, a relation condition, the USING phrase of the Procedure Division header, or the USING phrase of the CALL statement.

x An index data item can be referred to directly in the USING phrase of an x ENTRY statement.

An index data item can be part of a group item referred to in a MOVE statement or an input/output statement.

An index data item saves values that represent table occurrences, yet is not necessarily defined as part of any table. Thus, when it is referred to directly in a SEARCH or SET statement, or indirectly in a MOVE or input/output statement, there is no conversion of values when the statement is executed.

The USAGE IS INDEX clause can be written at any level. If a group item is described with the USAGE IS INDEX clause, the elementary items within the group are index data items; the group itself is not an index data item, and the group name cannot be used in SEARCH and SET statements or in relation conditions. The USAGE clause of an elementary item cannot contradict the USAGE clause of a group to which the item belongs.

An index data item cannot be a conditional variable.

The JUSTIFIED, PICTURE, BLANK WHEN ZERO, SYNCHRONIZED, or VALUE clauses cannot be used to describe group or elementary items described with the USAGE IS INDEX clause.

x SYNCHRONIZED can be used with USAGE IS INDEX to obtain efficient use of x the index data item.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.12.5 POINTER Phrase

x A data item defined with the USAGE IS POINTER clause is a pointer data x item.

x A pointer data item is a 4-byte elementary item that can be used to x accomplish limited base addressing. Pointer data items can be compared x for equality or moved to other pointer items.

x A pointer data item can only be used:

x o In a SET statement (Format 5 only)

x o In a relation condition

x o In the USING phrase of a CALL statement, an ENTRY statement, or the x Procedure Division header.

x The USAGE IS POINTER clause can be written at any level except level 88. x If a group item is described with the USAGE IS POINTER clause, the x elementary items within the group are pointer data items; the group itself x is not a pointer data item and cannot be used in the syntax where a x pointer data item is allowed. The USAGE clause of an elementary item x cannot contradict the USAGE clause of a group to which the item belongs.

x Pointer data items can be part of a group that is referred to in a MOVE x statement or an input/output statement. However, if a pointer data item x is part of a group, there is no conversion of values when the statement is x executed.

x A pointer data item can be the subject or object of a REDEFINES clause.

x SYNCHRONIZED can be used with USAGE IS POINTER to obtain efficient use of x the pointer data item.

x A VALUE clause for a pointer data item can contain only NULL or NULLS.

x A pointer data item cannot be a conditional variable.

x A pointer data item does not belong to any class or category.

x The JUSTIFIED, PICTURE, and BLANK WHEN ZERO clauses cannot be used to x describe group or elementary items defined with the USAGE IS POINTER x clause.

x Pointer data items are ignored in CORRESPONDING operations.

x A pointer data item can be written to a data set, but, upon subsequent x reading of the record containing the pointer, the address contained may no x longer represent a valid pointer.

x Note: USAGE IS POINTER is implicitly specified for the ADDRESS OF special x register. For more information, see VS COBOL II Application Programming x Guide for MVS and CMS or VS COBOL II Application Programming Guide for x VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.7.13 VALUE Clause

The VALUE clause specifies the initial contents of a data item or the value(s) associated with a condition-name.

The use of the VALUE clause differs depending on the Data Division section in which it is specified.

In the File and Linkage Sections, the VALUE clause must be used only in condition-name entries.

x In the File and Linkage Sections, if the VALUE clause is used in entries x other than condition-name entries, the VALUE clause is treated as a x comment.

In the Working-Storage Section, the VALUE clause can be used in condition-name entries, or in specifying the initial value of any data item. The data item assumes the specified value at the beginning of program execution. If the initial value is not explicitly specified, it is unpredictable.

___ value-clause-format-i ________ | | | >>__VALUE____________literal__>< | | |__IS__| | | | |__________________________________| Format 1 specifies the initial value of a data item. Initialization is independent of any BLANK WHEN ZERO or JUSTIFIED clause specified.

A format 1 VALUE clause specified in a data description entry that contains or is subordinate to an OCCURS clause causes every occurrence of the associated data item to be assigned the specified value. Each structure that contains the DEPENDING ON phrase of the OCCURS clause is assumed to contain the maximum number of occurrences for the purposes of VALUE initialization.

x Note: This element may exhibit different behavior when the CMPR2 compiler x option is in effect. For more information, see VS COBOL II Application x Programming Guide for MVS and CMS or VS COBOL II Application Programming x Guide for VSE.

The VALUE clause must not be specified for a data description entry that contains, or is subordinate to, an entry containing either an EXTERNAL or a REDEFINES clause. This rule does not apply to condition-name entries.

If the VALUE clause is specified at the group level, the literal must be a nonnumeric literal or a figurative constant. The group area is initialized without consideration for the subordinate entries within this group. In addition, the VALUE clause must not be specified for subordinate entries within this group.

For group entries, the VALUE clause must not be specified if the entry also contains any of the following clauses: JUSTIFIED, SYNCHRONIZED, or USAGE (other than USAGE DISPLAY).

The VALUE clause must not conflict with other clauses in the data description entry, or in the data description of this entry's hierarchy.

x Any VALUE clause associated with COMPUTATIONAL-1 or COMPUTATIONAL-2 x (internal floating-point) items must specify a floating-point literal. x The condition-name VALUE phrase must also specify a floating-point x literal. In addition, the figurative constant ZERO and both integer and x decimal forms of the zero literal can be specified in a floating-point x VALUE clause or condition-name VALUE phrase.

x For information on floating-point literal values, see "Rules for x Floating-point Literal Values:" in topic 1.1.1.12.

x A VALUE clause cannot be specified for external floating-point items.

x A VALUE clause associated with a DBCS item must contain a DBCS literal or x the figurative constant SPACE.

x A data item cannot contain a VALUE clause if the prior data item contains x a OCCURS clause with the DEPENDING ON phrase.

Rules for Literal Values:

o Wherever a literal is specified, a figurative constant can be substituted.

o If the item is numeric, all VALUE clause literals must be numeric. If the literal defines the value of a Working-Storage item, the literal is aligned according to the rules for numeric moves, with one additional restriction: The literal must not have a value that requires truncation of nonzero digits. If the literal is signed, the associated PICTURE character-string must contain a sign symbol (S).

o All numeric literals in a VALUE clause of an item must have a value that is within the range of values indicated by the PICTURE clause for that item. For example, for PICTURE 99PPP, the literal must be within the range 1000 through 99000, or zero. For PICTURE PPP99, the literal must be within the range 0.00000 through 0.00099.

o If the item is an elementary or group alphabetic, alphanumeric, alphanumeric-edited, or numeric-edited item, all VALUE clause literals must be nonnumeric literals. The literal is aligned according to the alphanumeric alignment rules, with one additional restriction: The number of characters in the literal must not exceed the size of the item.

o The functions of the editing characters in a PICTURE clause are ignored in determining the initial appearance of the item described. However, editing characters are included in determining the size of the item. Therefore, any editing characters must be included in the literal. For example, if the item is defined as PICTURE +999.99 and the value is to be +12.34, then the VALUE clause should be specified as VALUE "+012.34".

@@ Diagram value-clause-format-ii ADAPTED. @@ Implemented note that 88 and condition-name-1 do not belong to clause. @@ Diagram value-clause-format-ii ADAPTED. @@ Neither does the "." belong to the clause. ___ value-clause-format-ii _____________________________ | | | >>_____VALUE_________________________________________> | | | |__IS__| | | | |__VALUES_____________| | | |__ARE__| | | | | <____________________________________________ | | >_____literal-1__________________________________|__>< | | |_____THROUGH_____literal-2__| | | |__THRU_____| | | | |________________________________________________________|

This format associates a value, values, and/or range(s) of values with a condition-name. Each such condition-name requires a separate level-88 entry. Level-number 88 and condition-name are not part of the Format 2 VALUE clause itself. They are included in the format only for clarity.

| condition-name-1 Is a user-specified name that associates a value with a conditional variable. If the associated conditional variable requires subscripts or indexes, each procedural reference to the condition-name must be subscripted or indexed as required for the conditional variable.

| Condition-name-1 is tested procedurally in condition-name conditions (see "Conditional Expressions" in topic 2.8.5).

literal-1 When literal-1 is specified alone, the condition-name is associated with a single value.

literal-1 THROUGH literal-2 The condition-name is associated with at least one range of values. Whenever the THROUGH phrase is used, literal-1 must be less than literal-2.

| In the VALUE clause of a data description entry (Format 2), all the | literals specified in the VALUE clause must be DBCS literals if the x associated conditional variable is a DBCS data item. The figurative x constants SPACE and SPACES can be used as DBCS literals.

x The range of DBCS literals specified for the THROUGH phrase is based on x the binary collating sequence of the hexadecimal values of the DBCS x characters.

Rules for Condition-Name Values:

o The VALUE clause is required in a condition-name entry, and must be the only clause in the entry. Each condition-name entry is associated with a preceding conditional variable. Thus, every level-88 entry must always be preceded either by the entry for the conditional variable, or by another level-88 entry when several condition-names apply to one conditional variable. Each such level-88 entry implicitly has the PICTURE characteristics of the conditional variable.

o The keywords THROUGH and THRU are equivalent.

The condition-name entries associated with a particular conditional variable must immediately follow the conditional variable entry. The conditional variable can be any elementary data description entry except another condition-name, a RENAMES clause (level-66 item), or an item with USAGE IS INDEX.

x The conditional variable cannot be an item described as USAGE IS x POINTER.

A condition-name can be associated with a group item data description entry. In this case:

- The condition-name value must be specified as a nonnumeric literal or figurative constant.

- The size of the condition-name value must not exceed the sum of the sizes of all the elementary items within the group.

- No element within the group can contain a JUSTIFIED or SYNCHRONIZED clause.

- No USAGE other than DISPLAY can be specified within the group.

x USAGE other than USAGE IS DISPLAY can be specified within the x group.

Condition-names can be specified both at the group level and at subordinate levels within the group.

The relation test implied by the definition of a condition-name at the group level is performed in accordance with the rules for comparison of nonnumeric operands, regardless of the nature of elementary items within the group.

x The VALUE clause is allowed for internal floating-point data items.

x The VALUE clause is allowed for DBCS data items. Relation tests for x DBCS data items are performed according to the rules for comparison of x DBCS items. These rules can be found in "Comparing DBCS Operands" in x topic 2.8.5.5.5.

A space, a separator comma, or a separator semicolon, must separate successive operands.

Each entry must end with a separator period.

o The type of literal in a condition-name entry must be consistent with the data type of its conditional variable. In the following example:

- CITY-COUNTY-INFO, COUNTY-NO, and CITY are conditional variables.

The PICTURE associated with COUNTY-NO limits the condition-name value to a 2-digit numeric literal.

The PICTURE associated with CITY limits the condition-name value to a 3-character nonnumeric literal.

- The associated condition-names are level-88 entries.

Any values for the condition-names associated with CITY-COUNTY-INFO cannot exceed 5 characters.

Because this is a group item, the literal must be nonnumeric.

05 CITY-COUNTY-INFO. 88 BRONX VALUE "03NYC". 88 BROOKLYN VALUE "24NYC". 88 MANHATTAN VALUE "31NYC". 88 QUEENS VALUE "41NYC". 88 STATEN-ISLAND VALUE "43NYC". 10 COUNTY-NO PICTURE 99. 88 DUTCHESS VALUE 14. 88 KINGS VALUE 24. 88 NEW-YORK VALUE 31. 88 RICHMOND VALUE 43. 10 CITY PICTURE X(3). 88 BUFFALO VALUE "BUF". 88 NEW-YORK-CITY VALUE "NYC". 88 POUGHKEEPSIE VALUE "POK". 05 POPULATION...

___ value-clause-format-iii ________________ | | | >>__{__VALUE_______________NULL______}__>< | | |__IS__| |__NULLS__| | | | |____________________________________________|

x This format assigns an invalid address as the initial value of an item x described as USAGE IS POINTER.

x VALUE IS NULL can only be specified for elementary items described x implicitly or explicitly as USAGE IS POINTER.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8 Procedure Division

The Procedure Division is optional in a COBOL source program. The Procedure Division consists of optional declaratives, and procedures that contain sections and/or paragraphs, sentences, and statements.

The structure of the Procedure Division is as follows:

___ procedure-division-format-i ____________________ | | | >>__PROCEDURE__DIVISION______________________.___> | | |__using-phrase__| | | | | >___procedure-division-content__________________>< | | | |____________________________________________________| @@ Diagram using-phrase EXTRACTED from diagram procedure-division-format-i. @@ Identified USING phrases as referred to elsewhere. ___ using-phrase ________________ | | | <______________ | | >>__USING____data-name-1__|__>< | | | |_________________________________| @@ Diagram section EXTRACTED from diagram procedure-division-format-i. @@ Identified section structure for clarity. ___ section _______________________________________________________ | | | >>__section-name__@1__SECTION_________________________.__para__>< | | |__priority-number__| | | | |___________________________________________________________________| @@ Diagram procedure-division-content EXTRACTED from diagram procedure-division-format-i. @@ Identified relevant part for procedure-division-content @@ Diagram procedure-division-content ADAPTED. @@ Enforced separation of directives vs. statements @@ Diagram procedure-division-content ADAPTED. @@ Stretched below note (1): entire section header is optional. ___ procedure-division-content ____________________________________________________________ | | | >>______________________________________________________________________________________> | | | <__________________________________ | | | |__DECLARATIVES__.____sect__.__use-directive__.__para__|__END__DECLARATIVES__.__| | | | | >______________________________________________________________________________________>< | | |__para__| | <__________ | | | |____section__|__| | | | |___________________________________________________________________________________________| ___ sect _____________________________________________ | | | >>__section-name__SECTION_________________________>< | | |__priority-number__| | | | |______________________________________________________| @@ Diagram para ADAPTED. @@ Applied Note (1) for 2nd format to 1st format as well. ___ para _____________________________________________________________________________ | | | >>________________________________________________________________________________>< | | |__________________________________________________________________________| | | | <___________ | | <_________________________________________ | | | |____sentence__|__| |____paragraph-name__._______________________|__| | | | <___________ | | | |____sentence__|__| | | | |______________________________________________________________________________________| _____________________________________________________________________________________________ | | | Note: | x | (1) This section-name is optional as an IBM extension. | | | |_____________________________________________________________________________________________|

@@ Diagram procedure-division-format-ii FOLDED according to using-phrase. @@ Fold USING phrase as referred to elsewhere. ___ procedure-division-format-ii ________________________ | | | >>__PROCEDURE__DIVISION______________________.________> | | |__using-phrase__| | | | | <_____________________________________________ | | >_____paragraph-name__.__@1_______________________|__>< | | | <___________ | | | |____sentence__|__| | | | |_________________________________________________________| ________________________________________________________________________ | | | Note: | x | (1) Paragraph-name is optional as an IBM extension. | | | |________________________________________________________________________|

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.1 The Procedure Division Header

The Procedure Division, if specified, is identified by the following header.

___ procedure-division-header _________________________________ | | | >>__PROCEDURE__DIVISION_________________________________.__>< | | | <______________ | | | |__USING____data-name-1__|__| | | | |_______________________________________________________________| The USING phrase is required only if the object program is to be invoked by a CALL statement and that statement includes a USING phrase.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.1.1 The USING Phrase

The USING phrase makes data items defined in a calling program available to a called subprogram.

The USING phrase is specified in the Procedure Division header if, and only if, this program is a subprogram invoked by a CALL statement that itself contains a USING phrase. That is, for each CALL USING statement in a calling program, there must be a corresponding USING phrase specified in a called subprogram.

The USING phrase is valid in the Procedure Division header of a called subprogram entered at the beginning of the nondeclaratives portion; each USING identifier must be defined as a level-01 or level-77 item in the Linkage Section of the called subprogram; it must not contain a REDEFINES clause.

x A data item in the USING phrase of the Procedure Division header can have x a REDEFINES clause in its data description entry.

x In a called subprogram entered at the first executable statement following x an ENTRY statement, the USING option is valid in the ENTRY statement; each x USING identifier must be defined as a level-01 or level-77 item in the x Linkage Section of the called subprogram.

In a calling program, the USING phrase is valid for the CALL statement; each USING identifier must be defined as a level-01, level-77, or an elementary item in the Data Division.

x Each USING identifier in a calling program can be a data item of any level x in the Data Division.

It is possible to call from non-COBOL programs or pass user parameters from a system EXEC to a COBOL main program.

The order of appearance of USING identifiers in both calling and called subprograms determines the correspondence of single sets of data available to both programs. The correspondence is positional and not by name. Corresponding identifiers must contain the same number of characters, although their data descriptions need not be the same. For index-names, no correspondence is established; index-names in calling and called programs always refer to separate indexes.

The identifiers specified in a CALL USING statement name data items available to the calling program that can be referred to in the called program; a given identifier can appear more than once. These items are defined in any Data Division section. An identifier can appear only once in a Procedure Division USING phrase.

x An identifier can appear more than once in a Procedure Division USING x phrase. The last value passed to it by a CALL USING statement is used.

Data items defined in the Linkage Section of the called program can be referenced within the Procedure Division of that program if, and only if, they satisfy one of the following conditions:

o They are operands of the USING phrase of the Procedure Division header x or the ENTRY statement

x o They are operands of SET ADDRESS OF or CALL...BY REFERENCE ADDRESS OF

o They are defined with a REDEFINES or RENAMES clause, the object of which satisfies the above conditions

o They are items subordinate to any item that satisfies the condition in the rules above

o They are condition-names or index-names associated with data items that satisfy any of the above conditions.

If the reference to the corresponding data item in the CALL statement declares the parameter to be passed BY REFERENCE (explicit or implicit), the object program executes as if each reference to a USING identifier in the called subprogram Procedure Division is replaced by a reference to the corresponding USING identifier in the calling program.

If the reference to the corresponding data item in the CALL statement declares the parameter to be passed BY CONTENT, the value of the item is moved when the CALL statement is executed and placed into a system-defined | storage item possessing the attributes declared for data-name-1 in the | calling program. The data description of each parameter in the BY CONTENT phrase of the CALL statement must be the same, meaning no conversion or extension or truncation, as the data description of the corresponding parameter in the USING phrase of the Procedure Division header.

Examples illustrating these concepts can be found in VS COBOL II Application Programming Guide for MVS and CMS or VS COBOL II Application Programming Guide for VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.2 Declaratives

Declaratives provide one or more special-purpose sections that are executed when an exceptional condition occurs.

When Declarative Sections are specified, they must be grouped at the beginning of the Procedure Division, and the entire Procedure Division must be divided into sections.

Each Declarative Section starts with a USE statement that identifies the section's function; the series of procedures that follow specify what actions are to be taken when the exceptional condition occurs. Each Declarative Section ends with another section-name followed by a USE statement, or with the keywords END DECLARATIVES. For more information on the USE statement, see "USE Statement" in topic 4.15.

| The entire group of Declarative Sections is preceded by the keyword | DECLARATIVES written on the line after the Procedure Division header; the group is followed by the keywords END DECLARATIVES. The keywords DECLARATIVES and END DECLARATIVES must each begin in Area A and be followed by a separator period. No other text can appear on the same line.

In the declaratives part of the Procedure Division, each section header must be followed by a separator period, and must be followed by a USE statement, followed by a separator period. No other text can appear on the same line.

The USE statement itself is never executed; instead, the USE statement defines the conditions that execute the succeeding procedural paragraphs, which specify the actions to be taken. After the procedure is executed, control is returned to the routine that activated it.

Within a declarative procedure, except for the USE statement itself, there must be no reference to any nondeclarative procedure.

Within a declarative procedure, no statement should be included that would cause the execution of a USE procedure that had been previously invoked and had not yet returned control to the invoking routine.

x You can include a statement that executes a previously invoked USE x procedure that is still in control. However, to avoid an infinite loop, x you must be sure there is an eventual exit at the bottom.

The declarative procedure is exited when the last statement in the procedure is executed.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.3 Procedures

Within the Procedure Division, a procedure consists of:

o A section or a group of sections o A paragraph or group of paragraphs.

A procedure-name is a user-defined name that identifies a section or a paragraph.

Section A section-header optionally followed by one or more paragraphs.

Section-header A section-name followed by the keyword SECTION, optionally followed, by a priority-number, followed by a separator period.

x If there are no declaratives (Procedure Division Format-2), a x section-header is not required in the Procedure Division.

Section-name A user-defined word that identifies a section. A referenced section-name, because it cannot be qualified, must be unique within the program in which it is defined.

| Priority-number | An integer ranging in value from 0 through 99.

x Priority-number can also be a positive signed fixed-point x numeric literal ranging in value from 0 through 99.

Sections in the declaratives portion must contain priority | numbers in the range of 0 through 49.

A section ends immediately before the next section header, or at the end of the Procedure Division, or, in the declaratives portion, at the keywords END DECLARATIVES.

Paragraph A paragraph-name followed by a separator period, optionally followed by one or more sentences.

| Note: Paragraphs must be preceded by a period because paragraphs | always follow either the ID Division Header, a Section, or another | paragraph, all of which must end with a period.

Paragraph-name | A user-defined word that identifies a paragraph. If referenced, a | paragraph-name must either be unique within the section in which | it is referenced or made unique through qualification with a | section-name.

x If there are no declaratives (Procedure Division Format-2), a x paragraph-name is not required in the Procedure Division.

A paragraph ends immediately before the next paragraph-name or section header, or at the end of the Procedure Division, or, in the declaratives portion, at the keywords END DECLARATIVES.

If one paragraph in a program is contained within a section, all paragraphs must be contained in sections.

x All paragraphs do not need to be contained within sections, even if x one or more paragraphs are so contained.

Sentence One or more statements terminated by a separator period.

Statement A syntactically valid combination of identifiers and symbols (literals, relational-operators, and so forth) beginning with a COBOL verb.

identifier The word or words necessary to make unique reference to a data item, optionally including qualification, subscripting, indexing, and reference-modification. In any Procedure Division reference (except the class test), the contents of an identifier must be compatible with the class specified through its PICTURE clause, or results are unpredictable.

Execution begins with the first statement in the Procedure Division, excluding declaratives. Statements are executed in the order in which they are presented for compilation, unless the statement rules dictate some other order of execution.

The end of the Procedure Division is indicated by one of the following:

o An Identification Division header which indicates the start of a nested source program

o The END PROGRAM header

o The physical end of the program; that is, the physical position in a source program after which no further source program lines occur.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.4 Arithmetic Expressions

Arithmetic expressions are used as operands of certain conditional and arithmetic statements.

An arithmetic expression can consist of any of the following:

| 1. An identifier described as a numeric elementary item

| 2. A numeric literal (including the figurative constant ZERO)

| 3. Identifiers and literals, separated by arithmetic operators

| 4. An arithmetic expression, enclosed in parentheses

| 5. Two arithmetic expressions, separated by an arithmetic operator.

Any arithmetic expression can be preceded by a unary operator.

Identifiers and literals appearing in arithmetic expressions must represent either numeric elementary items or numeric literals on which arithmetic can be performed.

| If an exponential expression can be evaluated as both a positive and | negative number, the result will always be the positive number. For | example, the square root of 4, (expressed as 4 ** 0.5) can be evaluated as | +2 or -2. VS COBOL II always returns +2.

| The evaluation of an arithmetic expression can result in a size error, for | example when it involves division by zero or zero raised to a negative | power (0 ** (-1)). For more information, see "SIZE ERROR Phrases" in | topic 2.8.7.4.

Subtopics:


@@ Diagram arithmetic-expression ADDED at the end of this section.
@@ Top layer of arithmetic expressions.

    ___ arithmetic-expression ________________________
   |                                                  |
   | >>__times-div_________________________________>< |
   |                |  <_____________________   |     |
   |                |_______+_____times-div__|__|     |
   |                     |__-__|                      |
   |                                                  |
   |__________________________________________________|


@@ Diagram times-div ADDED at the end of this section.
@@ 2nd layer of arithmetic expressions.

    ___ times-div ____________________________
   |                                          |
   | >>__power_____________________________>< |
   |            |  <_________________   |     |
   |            |_______*_____power__|__|     |
   |                 |__/__|                  |
   |                                          |
   |__________________________________________|


@@ Diagram power ADDED at the end of this section.
@@ 3rd layer of arithmetic expressions.

    ___ power ____________________________________
   |                                              |
   | >>___________basis________________________>< |
   |     |__+__|         |  <____________   |     |
   |     |__-__|         |____**__basis__|__|     |
   |                                              |
   |______________________________________________|


@@ Diagram basis ADDED at the end of this section.
@@ Bottom layer of arithmetic expressions.

    ___ basis _________________________________
   |                                           |
   | >>_____identifier______________________>< |
   |     |__literal______________________|     |
   |     |__(__arithmetic-expression__)__|     |
   |                                           |
   |___________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.4.1 Arithmetic Operators

Five binary arithmetic operators and two unary arithmetic operators | (Table 14) can be used in arithmetic expressions. Binary and unary | operators must be preceded and followed by a space.

________________________________________________________________________ | Table 14. Binary and Unary Operators | |________________________________________________________________________| | Binary | | Unary | | | Operator | Meaning | Operator | Meaning | |__________|_________________________|__________|________________________| | + | Addition | + | Multiplication by +1 | |__________|_________________________|__________|________________________| | - | Subtraction | - | Multiplication by -1 | |__________|_________________________|__________|________________________| | * | Multiplication | | | |__________|_________________________|__________|________________________| | / | Division | | | |__________|_________________________|__________|________________________| | ** | Exponentiation | | | |__________|_________________________|__________|________________________|

Note: Exponents in fixed-point exponential expressions cannot contain more than 9 digits. The compiler will truncate any exponent with more than 9 digits. In this case, the compiler will issue a diagnostic message if the exponent is a literal or constant; if the exponent is a variable or data-name, a diagnostic is issued at run-time.

Parentheses can be used in arithmetic expressions to specify the order in | which elements are to be evaluated. They can also be used to improve | readability in cases where they do not affect the order of evaluation.

Expressions within parentheses are evaluated first. When expressions are contained within a nest of parentheses, evaluation proceeds from the | innermost (least inclusive) to the outermost (most inclusive) set.

When parentheses are not used, or parenthesized expressions are at the same level of inclusiveness, the following hierarchic order is implied:

1. Unary operator 2. Exponentiation 3. Multiplication and division 4. Addition and subtraction.

When the order of consecutive operations at the same hierarchic level is not completely specified by parentheses, the order is from left to right.

| Following are some examples of how the use of parentheses affects the | order of evaluation in arithmetic expressions:

| 8 - 3 - 2 = 3 | (8 - 3) - 2 = 3 | 8 - (3 - 2) = 7 | 24 / 4 / 2 = 3 | 24 / (4 / 2) = 12 | 4 + 5 * 6 = 34 | (4 + 5) * 6 = 54 | -2 ** 2 = 4 | -(2 ** 2) = -4

An arithmetic expression can begin only with a left parenthesis, a unary operator, or an operand (that is, an identifier or a literal). It can end only with a right parenthesis or an operand. An arithmetic expression must contain at least one reference to an identifier or a literal.

There must be a one-to-one correspondence between left and right parentheses in an arithmetic expression, with each left parenthesis placed to the left of its corresponding right parenthesis.

Table 15 shows permissible arithmetic symbol pairs. An arithmetic symbol pair is the combination of two such symbols in sequence. In the figure:

Yes indicates a permissible pairing. No indicates that the pairing is not permitted.

________________________________________________________________________ | Table 15. Valid Arithmetic Symbol Pairs | |________________________________________________________________________| | | Second Symbol | |____________________|___________________________________________________| | | Identifier | | Unary + | | | | First Symbol | or Literal | * / ** | or Unary | ( | ) | | | | + - | - | | | |____________________|_____________|_________|__________|_________|______| | Identifier or | No | Yes | No | No | Yes | | Literal | | | | | | |____________________|_____________|_________|__________|_________|______| | * / ** + - | Yes | No | Yes | Yes | No | |____________________|_____________|_________|__________|_________|______| | Unary + or Unary - | Yes | No | No | Yes | No | |____________________|_____________|_________|__________|_________|______| | ( | Yes | No | Yes | Yes | No | |____________________|_____________|_________|__________|_________|______| | ) | No | Yes | No | No | Yes | |____________________|_____________|_________|__________|_________|______|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.5 Conditional Expressions

A conditional expression causes the object program to select alternative paths of control, depending on the truth value of a test. Conditional expressions are specified in EVALUATE, IF, PERFORM, and SEARCH statements.

A conditional expression can be specified in either simple conditions or complex conditions. Both simple and complex conditions can be enclosed within any number of paired parentheses; the parentheses do not change whether the condition is simple or complex.

Subtopics:


@@ Diagram condition ADDED at the end of this section.
@@ Implemented definition as given in the text.

    ___ condition ______________________
   |                                    |
   | >>_____combinable-condition_____>< |
   |     |__combined-condition____|     |
   |                                    |
   |____________________________________|


@@ Diagram combinable-condition ADDED at the end of this section.
@@ Implemented definition as given in the text.

    ___ combinable-condition ______________________________
   |                                                       |
   | >>_____simple-condition____________________________>< |
   |     |__negated-simple-condition_________________|     |
   |     |__abbreviated-combined-relation-condition__|     |
   |                                                       |
   |_______________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.5.1 Simple Conditions

There are five simple conditions:

o Class condition o Condition-name condition o Relation condition o Sign condition o Switch-status condition.

A simple condition has a truth value of either true or false.


@@ Diagram simple-condition ADDED at the end of this section.
@@ Implemented definition as given in the text.

    ___ simple-condition ___________________
   |                                        |
   | >>_____class-condition______________>< |
   |     |__condition-name-condition__|     |
   |     |__relation-condition________|     |
   |     |__sign-condition____________|     |
   |     |__switch-status-condition___|     |
   |     |__(__condition__)___________|     |
   |                                        |
   |________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.5.2 Class Condition

The class condition determines whether the content of a data item is alphabetic, alphabetic-lower, alphabetic-upper, numeric, or contains only the characters in the set of characters specified by the CLASS clause as defined in the SPECIAL-NAMES paragraph of the Environment Division.

x The class condition determines whether the contents of a data item are x DBCS or KANJI.

| When identifier-1 is a zero-length group item, the result of the class | test is always true when it includes the word NOT, and always false when | it does not include the word NOT.

___ class-condition _______________________________________________ | | | >>__identifier-1__________________________NUMERIC______________>< | | |__IS__| |__NOT__| |__ALPHABETIC________| | | |__ALPHABETIC-LOWER__| | | |__ALPHABETIC-UPPER__| | | |__class-name-1______| | | |__{__DBCS__}________| | | |__{__KANJI__}_______| | | | |___________________________________________________________________| identifier-1 Must reference a data item whose usage is explicitly or implicitly DISPLAY.

x Can reference a data item whose usage is DISPLAY-1 or PACKED-DECIMAL.

NOT When used, NOT and the next keyword define the class test to be executed for truth value. For example, NOT NUMERIC is a truth test for determining that an identifier is nonnumeric.

NUMERIC | Identifier-1 consists entirely of the characters 0 through 9, with or without an operational sign.

If its PICTURE does not contain an operational sign, the identifier being tested is determined to be numeric only if the contents are numeric and an operational sign is not present.

If its PICTURE does contain an operational sign, the identifier being tested is determined to be numeric only if the item is an elementary item, the contents are numeric, and a valid operational sign is present.

The NUMERIC test cannot be used with an identifier described as alphabetic or as a group item that contains one or more signed elementary items.

For numeric data items, the identifier being tested must be described implicitly or explicitly as USAGE DISPLAY.

x For numeric data items, the identifier being tested can be described x as USAGE COMPUTATIONAL-3 or USAGE PACKED-DECIMAL.

ALPHABETIC | Identifier-1 consists entirely of any combination of the lowercase or uppercase alphabetic characters A through Z and the space.

The ALPHABETIC test cannot be used with an identifier described as numeric.

x Note: This element may exhibit different behavior when the CMPR2 x compiler option is in effect. For more information, see VS COBOL II x Migration Guide for MVS and CMS or VS COBOL II Migration Guide for x VSE.

ALPHABETIC-LOWER | Identifier-1 consists entirely of any combination of the lowercase alphabetic characters a through z and the space.

The ALPHABETIC-LOWER test cannot be used with an identifier described as numeric.

ALPHABETIC-UPPER | Identifier-1 consists entirely of any combination of the uppercase alphabetic characters A through Z and the space.

The ALPHABETIC-UPPER test cannot be used with an identifier described as numeric.

class-name | Identifier-1 consists entirely of the characters listed in the definition of class-name in the SPECIAL-NAMES paragraph.

The class-name test must not be used with an identifier described as numeric.

x DBCS x Identifier-1 consists entirely of double-byte characters.

x The following rules apply:

x o The DBCS identifier being tested must be explicitly described as x USAGE DISPLAY-1. Each byte of the identifier being tested can x contain characters that range in value from X'00' through X'FF'.

x o A range check is performed on the data portion of the item for x valid DBCS character representation. The valid range is X'41' x through X'FE' for both bytes of each DBCS character and X'4040' x for the DBCS blank.

x KANJI x Identifier-1 consists entirely of double-byte characters.

x The following rules apply:

x o The identifier being tested must be explicitly described as USAGE x DISPLAY-1. Each byte of the identifier being tested can contain x characters that range in value from X'00' through X'FF'.

x o A range check is performed on the data portion of the item for x valid KANJI character representation. The valid range is from x X'41' through X'7F' for the first byte, from X'41' through X'FE' x for the second byte, and X'4040' for the DBCS blank.

The class test is not valid for items defined as USAGE IS INDEX, as these items do not belong to any class or category.

x The class test is not valid for items defined as USAGE IS POINTER, as x these items do not belong to any class or category.

x The class condition cannot be used for external floating-point (USAGE x DISPLAY) or internal floating-point (USAGE COMP-1 and USAGE COMP-2) items.

Table 16 shows valid forms of the class test.

________________________________________________________________________ | Table 16. Valid Forms of the Class Test | |________________________________________________________________________| | Type of Identifier | Valid Forms of the Class Test | |______________________|_________________________________________________| | | | | | Alphabetic | ALPHABETIC | NOT ALPHABETIC | | | ALPHABETIC-LOWER | NOT ALPHABETIC-LOWER | | | ALPHABETIC-UPPER | NOT ALPHABETIC-UPPER | | | class-name | NOT class-name | | | | | |______________________|__________________|______________________________| | | | | | Alphanumeric, | ALPHABETIC | NOT ALPHABETIC | | Alphanumeric-edited, | ALPHABETIC-LOWER | NOT ALPHABETIC-LOWER | | or Numeric-edited | ALPHABETIC-UPPER | NOT ALPHABETIC-UPPER | | | NUMERIC | NOT NUMERIC | | | class-name | NOT class-name | | | | | |______________________|__________________|______________________________| | Numeric (USAGE | | | | DISPLAY | NUMERIC | NOT NUMERIC | x | or PACKED-DECIMAL) | | | |______________________|__________________|______________________________| | | | | x | DBCS | DBCS | NOT DBCS | x | | KANJI | NOT KANJI | | | | | |______________________|__________________|______________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.5.3 Condition-Name Condition

A condition-name condition tests a conditional variable to determine whether its value is equal to any value(s) associated with the condition-name.

@@ Diagram condition-name-condition ADAPTED. @@ Allowed for proper condition-name reference not just names. ___ condition-name-condition _____ | | | >>__condition-name-reference__>< | | | |__________________________________| A condition-name is used in conditions as an abbreviation for the relation condition. The rules for comparing a conditional variable with a condition-name value are the same as those specified for relation conditions.

If the condition-name has been associated with a range of values (or with several ranges of values), the conditional variable is tested to determine whether or not its value falls within the range(s), including the end values. The result of the test is true if one of the values corresponding to the condition-name equals the value of its associated conditional variable.

x Condition-names with DBCS and floating-point are allowed.

The following example illustrates the use of conditional variables and condition-names:

01 AGE-GROUP PIC 99. 88 INFANT VALUE 0. 88 BABY VALUE 1, 2. 88 CHILD VALUE 3 THRU 12. 88 TEEN-AGER VALUE 13 THRU 19.

AGE-GROUP is the conditional variable; INFANT, BABY, CHILD, and TEEN-AGER are condition-names. For individual records in the file, only one of the values specified in the condition-name entries can be present.

The following IF statements can be added to the above example to determine the age group of a specific record:

IF INFANT... (Tests for value 0) IF BABY... (Tests for values 1, 2) IF CHILD... (Tests for values 3 through 12) IF TEEN-AGER... (Tests for values 13 through 19)

Depending on the evaluation of the condition-name condition, alternative paths of execution are taken by the object program.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.5.4 Relation Condition

A relation condition compares two operands, either of which can be an identifier, literal, arithmetic expression, or index-name.

x A nonnumeric literal can be enclosed in parentheses within a relation x condition.

___ relation-condition _________________ | | | >>__operand-1__relational-operator___> | | | | >___operand-2_______________________>< | | | |________________________________________| @@ Diagram operand ADDED after diagram relation-condition. @@ Implemented in accordance with the below text. ___ operand ___________________ | | | >>__arithmetic-expression__>< | | | |_______________________________| @@ Diagram relational-operator EXTRACTED from diagram relation-condition. @@ Enabled reuse for elsewhere. ___ relational-operator __________________________________________ | | | >>_____________________________GREATER________________________>< | | |__IS__| | |__NOT__| | |__THAN__| | | | | | |__>____________________| | | | | |__LESS_________________| | | | | | |__THAN__| | | | | | |__<____________________| | | | | |__EQUAL________________| | | | | | |__TO__| | | | | | |__=____________________| | | | |__GREATER______________OR__EQUAL____________| | | | |__THAN__| |__TO__| | | | |__>=________________________________________| | | |__LESS______________OR__EQUAL_______________| | | | |__THAN__| |__TO__| | | | |__<=________________________________________| | | | |__________________________________________________________________| operand-1 | The subject of the relation condition. Operand-1 can be an | identifier, literal, arithmetic expression, or index-name.

x Operand-1 can be a DBCS, POINTER, or floating-point item.

operand-2 | The object of the relation condition. Operand-2 can be an identifier, | literal, arithmetic expression, or index-name.

x Operand-2 can be a DBCS, POINTER, or floating-point item.

The relation condition must contain at least one reference to an identifier.

The relational operator specifies the type of comparison to be made. Table 17 shows relational operators and their meanings. Each relational | operator must be preceded and followed by a space. The relational | operators >= and <= must not have a space within them.

________________________________________________________________________ | Table 17. Relational Operators and Their Meanings | |________________________________________________________________________| | Relational Operator | Can Be Written | Meaning | |________________________|_________________|_____________________________| | IS GREATER THAN | IS > | Greater than | |________________________|_________________|_____________________________| | IS NOT GREATER THAN | IS NOT > | Not greater than | |________________________|_________________|_____________________________| | IS LESS THAN | IS < | Less than | |________________________|_________________|_____________________________| | IS NOT LESS THAN | IS NOT < | Not less than | |________________________|_________________|_____________________________| | IS EQUAL TO | IS = | Equal to | |________________________|_________________|_____________________________| | IS NOT EQUAL TO | IS NOT = | Not equal to | |________________________|_________________|_____________________________| | IS GREATER THAN OR | IS >= | Is greater than or equal to | | EQUAL TO | | | |________________________|_________________|_____________________________| | IS LESS THAN OR EQUAL | IS <= | Is less than or equal to | | TO | | | |________________________|_________________|_____________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.5.5 Comparison of Operands

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.5.5.1 Comparing Numeric Operands

| The algebraic values of numeric operands are compared, according to the | following rules:

o The length (number of digits) of the operands is not significant. o Unsigned numeric operands are considered positive. o Zero is considered to be a unique value, regardless of sign. o Comparison of numeric operands is permitted, regardless of the type of USAGE specified for each.

Table 18 summarizes permissible comparisons with numeric operands.

The symbols used in Table 18 and Table 19 are as follows:

NN = Comparison for nonnumeric operands NU = Comparison for numeric operands Blank = Comparison is not allowed.

______________________________________________________________________________________________________________________________________ | Table 18. Permissible Comparisons with Numeric Second Operands | |______________________________________________________________________________________________________________________________________| | | Second Operand | | First Operand |___________________________________________________________________________| x | | ZR | NL | ED | BI | AE | ID | IFP | EFP | FPL | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| | Nonnumeric Operand | |______________________________________________________________________________________________________________________________________| x | Group (GR) | NN | NN(1) | NN(1) | | | | | NN | | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| x | Alphabetic (AL) | NN | NN(1) | NN(1) | | | | | NN | | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| x | Alphanumeric (AN) | NN | NN(1) | NN(1) | | | | | NN | | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| x | Alphanumeric-Edited (ANE) | NN | NN(1) | NN(1) | | | | | NN | | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| x | Numeric-Edited (NE) | NN | NN(1) | NN(1) | | | | | NN | | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| x | Figurative Constant (FC(2)) | | | NN(1) | | | | | NN | | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| x | Nonnumeric Literal (NNL) | | | NN(1) | | | | | NN | | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| | Numeric Operand | |______________________________________________________________________________________________________________________________________| x | Figurative Constant ZERO (ZR) | | | NU | NU | NU | NU | NU | NU | | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| x | Numeric Literal (NL) | | | NU | NU | NU | NU | NU | NU | | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| x | External Decimal (ED) | NU | NU | NU | NU | NU | NU | NU | NU | NU | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| x | Binary (BI) | NU | NU | NU | NU | NU | NU | NU | NU | NU | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| x | Arithmetic Expression (AE) | NU | NU | NU | NU | NU | NU | NU | NU | NU | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| x | Internal Decimal (ID) | NU | NU | NU | NU | NU | NU | NU | NU | NU | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| x | Internal Floating-Point (IFP) | NU | NU | NU | NU | NU | NU | NU | NU | NU | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| x | External Floating-Point (EFP) | NU | NU | NU | NU | NU | NU | NU | NU | NU | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| x | Floating-Point Literal (FPL) | | | NU | NU | NU | NU | NU | NU | | |__________________________________________________________|________|_______|________|_______|________|_______|________|_______|_______| | Note: | | | | (1) Integer item only. | | (2) Includes all figurative constants except ZERO. | |______________________________________________________________________________________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.5.5.2 Comparing Nonnumeric Operands

| Comparisons of nonnumeric operands are made with respect to the collating | sequence of the character set in use, according to the following rules:

o For the EBCDIC character set, the EBCDIC collating sequence is used.

o For the ASCII character set, the ASCII collating sequence is used. (See Appendix B, "EBCDIC and ASCII Collating Sequences" in topic APPENDIX1.2.)

o When the PROGRAM COLLATING SEQUENCE clause is specified in the OBJECT-COMPUTER paragraph, the collating sequence associated with the alphabet-name clause in the SPECIAL-NAMES paragraph is used.

The size of each operand is the total number of characters in that operand; the size affects the result of the comparison. There are two cases to consider:

Operands of Equal Size

o Characters in corresponding positions of the two operands are compared, beginning with the leftmost character and continuing through the rightmost character.

o If all pairs of characters through the last pair test as equal, the operands are considered as equal.

o If a pair of unequal characters is encountered, the characters are tested to determine their relative positions in the collating sequence. The operand containing the character higher in the sequence is considered the greater operand.

Operands of Unequal Size

o If the operands are of unequal size, the comparison is made as though the shorter operand were extended to the right with enough spaces to make the operands equal in size.

Table 19 summarizes permissible comparisons with nonnumeric operands.

______________________________________________________________________________________________ | Table 19. Permissible Comparisons with Nonnumeric Second Operands | |______________________________________________________________________________________________| | | Second Operand | | First Operand |______________________________________________________| | | GR | AL | AN | ANE | NE | FC(2) | NNL | |_______________________________________|_______|_______|_______|_______|_______|_______|______| | Nonnumeric Operand | |______________________________________________________________________________________________| | Group (GR) | NN | NN | NN | NN | NN | NN | NN | |_______________________________________|_______|_______|_______|_______|_______|_______|______| | Alphabetic (AL) | NN | NN | NN | NN | NN | NN | NN | |_______________________________________|_______|_______|_______|_______|_______|_______|______| | Alphanumeric (AN) | NN | NN | NN | NN | NN | NN | NN | |_______________________________________|_______|_______|_______|_______|_______|_______|______| | Alphanumeric-Edited (ANE) | NN | NN | NN | NN | NN | NN | NN | |_______________________________________|_______|_______|_______|_______|_______|_______|______| | Numeric-Edited (NE) | NN | NN | NN | NN | NN | NN | NN | |_______________________________________|_______|_______|_______|_______|_______|_______|______| | Figurative Constant (FC(2)) | NN | NN | NN | NN | NN | | | |_______________________________________|_______|_______|_______|_______|_______|_______|______| | Nonnumeric Literal (NNL) | NN | NN | NN | NN | NN | | | |_______________________________________|_______|_______|_______|_______|_______|_______|______| | Numeric Operand | |______________________________________________________________________________________________| | Figurative Constant ZERO (ZR) | NN | NN | NN | NN | NN | | | |_______________________________________|_______|_______|_______|_______|_______|_______|______| | Numeric Literal (NL) | NN(1) | NN(1) | NN(1) | NN(1) | NN(1) | | | |_______________________________________|_______|_______|_______|_______|_______|_______|______| | External Decimal (ED) | NN(1) | NN(1) | NN(1) | NN(1) | NN(1) | NN(1) | NN(1)| |_______________________________________|_______|_______|_______|_______|_______|_______|______| | Binary (BI) | | | | | | | | |_______________________________________|_______|_______|_______|_______|_______|_______|______| | Arithmetic Expression (AE) | | | | | | | | |_______________________________________|_______|_______|_______|_______|_______|_______|______| | Internal Decimal (ID) | | | | | | | | |_______________________________________|_______|_______|_______|_______|_______|_______|______| x | Internal Floating-Point (IFP) | | | | | | | | |_______________________________________|_______|_______|_______|_______|_______|_______|______| x | External Floating-Point (EFP) | NN | NN | NN | NN | NN | NN | NN | |_______________________________________|_______|_______|_______|_______|_______|_______|______| x | Floating-Point Literal (FPL) | | | | | | | | |_______________________________________|_______|_______|_______|_______|_______|_______|______| | Note: | | | | (1) Integer item only. | | (2) Includes all figurative constants except ZERO. | |______________________________________________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.5.5.3 Comparing Numeric and Nonnumeric Operands

The nonnumeric comparison rules discussed above apply. In addition, when numeric and nonnumeric operands are being compared, their USAGE must be the same. In such comparisons:

o The numeric operand must be described as an integer literal or data item. o Non-integer literals and data items must not be compared with nonnumeric operands. x o External floating-point items can be compared with nonnumeric x operands.

If either of the operands is a group item, the nonnumeric comparison rules discussed above apply. In addition to those rules:

o If the nonnumeric operand is a literal or an elementary data item, the numeric operand is treated as though it were moved to an alphanumeric elementary data item of the same size, and the contents of this alphanumeric data item were then compared with the nonnumeric operand.

o If the nonnumeric operand is a group item, the numeric operand is treated as though it were moved to a group item of the same size, and the contents of this group item were compared then with the nonnumeric operand.

See "MOVE Statement" in topic 3.22.

x Note: This element may exhibit different behavior when the CMPR2 x compiler option is in effect. For more information, see VS COBOL II x Migration Guide for MVS and CMS or VS COBOL II Migration Guide for x VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.5.5.4 Comparing Index-Names and Index Data Items

Comparisons involving index-names and/or index data items conform to the following rules:

o The comparison of two index-names is actually the comparison of the corresponding occurrence numbers.

o In the comparison of an index-name with a data item (other than an index data item), or in the comparison of an index-name with a literal, the occurrence number that corresponds to the value of the index-name is compared with the data item or literal.

x o In the comparison of an index-name with an arithmetic expression, the x occurrence number that corresponds to the value of the index-name is x compared with the arithmetic expression.

o In the comparison of an index data item with an index-name or another index data item, the actual values are compared without conversion. Results of any other comparison involving an index data item are undefined.

Table 20 shows valid comparisons for index-names and index data items.

________________________________________________________________________ | Table 20. Permissible Comparisons for Index-Names and Index Data Items | |________________________________________________________________________| | | | | | Data Item | Literal | | | | | | (Numeric | (Numeric | | x | Operands | Index- | Index Data | Integer | Integer | Arithmetic| x | Compared | Name | Item | Only) | Only) | Expression| |___________|___________|____________|___________|___________|___________| x | Index-Name| Compare | Compare | Compare | Compare | Compare | x | | occurrence| without | occurrence| occurrence| occurrence| x | | number | conversion | number | number | number | x | | | | with | with | with | x | | | | data-name | literal | arithmetic| x | | | | | | expression| |___________|___________|____________|___________|___________|___________| | Index | Compare | Compare | Illegal | Illegal | Illegal | | Data Item | without | without | | | | | | conversion| conversion | | | | |___________|___________|____________|___________|___________|___________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

x 2.8.5.5.5 Comparing DBCS Operands

x The rules for comparing DBCS operands are as follows:

x o DBCS items can be compared only with other DBCS items.

x o The comparison is based on the binary collating sequence of the x hexadecimal values of the DBCS characters.

x o The PROGRAM COLLATING SEQUENCE clause is not applied to comparisons of x DBCS items.

x o If the DBCS items being compared are not the same length, the smaller x item is padded on the right with DBCS spaces.

x o All relational operators can be used when comparing DBCS items.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

x 2.8.5.5.6 Comparing Pointer Data Items

x Only EQUAL and NOT EQUAL can be used as relational operators when x specifying pointer data items. Pointer data items can be defined x explicitly (as USAGE IS POINTER) or implicitly (as ADDRESS OF special x registers).

x The operands are equal if the two addresses used in the comparison would x both result in the same storage location.

x This relation condition is allowed in IF, PERFORM, EVALUATE, and SEARCH x Format 1 statements. It is not allowed in SEARCH Format 2 (SEARCH ALL) x statements, because there is no meaningful ordering that can be applied to x pointer data items.

___ comparing-pointer-data-items _______________________________ | | | >>_____ADDRESS__OF__identifier-1_____________________________> | | |__identifier-2_______________| |__IS__| |__NOT__| | | |__NULL_______________________| | | |__NULLS______________________| | | | | >______EQUAL__________________ADDRESS__OF__identifier-3_____>< | | | |__TO__| | |__identifier-4_______________| | | |__=________________| |__NULL_______________________| | | |__NULLS______________________| | | | |________________________________________________________________| x identifier-1, identifier-3 x Can specify a Linkage Section data item of any level except level-66 x and level-88.

x identifier-2, identifier-4 x Must be described as USAGE IS POINTER.

x NULL(S) x Can be used only if the other operand is defined explicitly or x implicitly as USAGE IS POINTER. NULL=NULL is not allowed.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.5.6 Sign Condition

The sign condition determines whether or not the algebraic value of a numeric operand is greater than, less than, or equal to zero.

___ sign-condition _____________________________________ | | | >>__operand-1__________________________POSITIVE_____>< | | |__IS__| |__NOT__| |__NEGATIVE__| | | |__ZERO______| | | | |________________________________________________________| operand Must be defined as a numeric identifier, or it must be defined as an arithmetic expression that contains at least one reference to a x variable. The operand can be defined as a floating-point identifier.

The operand is:

o POSITIVE if its value is greater than zero o NEGATIVE if its value is less than zero o ZERO if its value is equal to zero.

An unsigned operand is either POSITIVE or ZERO.

NOT One algebraic test is executed for the truth value of the sign condition. For example, NOT ZERO is regarded as true when the operand tested is positive or negative in value.

x Note: If you are using the NUMPROC compiler option, the results of x the sign condition test may be affected. For details, see VS COBOL II x Application Programming Guide for MVS and CMS or VS COBOL II x Application Programming Guide for VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.5.7 Switch-Status Condition

The switch-status condition determines the on or off status of an UPSI switch.

@@ Diagram switch-status-condition ADAPTED. @@ Allowed for proper condition-name reference not just names. ___ switch-status-condition ______ | | | >>__condition-name-reference__>< | | | |__________________________________| condition-name Must be defined in the SPECIAL-NAMES paragraph as associated with the ON or OFF value of an UPSI switch. (See "SPECIAL-NAMES Paragraph" in topic 2.3.3.)

The switch-status condition tests the value associated with the condition-name. (The value associated with the condition-name is considered to be alphanumeric.) The result of the test is true if the UPSI switch is set to the value (0 or 1) corresponding to condition-name. See "UPSI" in VS COBOL II Application Programming Guide for MVS and CMS or VS COBOL II Application Programming Guide for VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.5.8 Complex Conditions

A complex condition is formed by combining simple conditions, combined conditions, and/or complex conditions with logical operators, or negating these conditions with logical negation.

Each logical operator must be preceded and followed by a space. The following chart shows the logical operators and their meanings.

________________________________________________________________________ | Table 21. Logical Operators and Their Meanings | |________________________________________________________________________| | Logical | | | | Operator | Name | Meaning | |_____________|______________|___________________________________________| | AND | Logical | The truth value is true when both | | | conjunction | conditions are true. | |_____________|______________|___________________________________________| | OR | Logical | The truth value is true when either or | | | inclusive OR | both conditions are true. | |_____________|______________|___________________________________________| | NOT | Logical | Reversal of truth value (the truth value | | | negation | is true if the condition is false). | |_____________|______________|___________________________________________|

Unless modified by parentheses, the following precedence rules (from highest to lowest) apply:

1. Arithmetic operations 2. Simple conditions 3. NOT 4. AND 5. OR.

The truth value of a complex condition (whether parenthesized or not) is the truth value that results from the interaction of all the stated logical operators on either of the following:

o The individual truth values of simple conditions o The intermediate truth values of conditions logically combined or logically negated.

A complex condition can be either of the following:

o A negated simple condition o A combined condition (which can be negated).


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.5.9 Negated Simple Conditions

A simple condition is negated through the use of the logical operator NOT.

___ negated-simple-condition ___ | | | >>__NOT__condition-1________>< | | | |________________________________| The negated simple condition gives the opposite truth value of the simple condition. That is, if the truth value of the simple condition is true, then the truth value of that same negated simple condition is false, and vice versa.

Placing a negated simple condition within parentheses does not change its truth value. That is, the following two statements are equivalent:

NOT A IS EQUAL TO B. NOT (A IS EQUAL TO B).


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.5.10 Combined Conditions

Two or more conditions can be logically connected to form a combined condition.

@@ Diagram combined-condition ADAPTED. @@ Required combinable conditions rather than any kind of condition. ___ combined-condition _________________________________________________ | | | <____________________________________ | | >>__combinable-condition-1_______AND_____combinable-condition-2__|__>< | | |__OR___| | | | |________________________________________________________________________| The condition to be combined can be any of the following:

o A simple-condition

o A negated simple-condition

o A combined condition

o A negated combined condition (that is, the NOT logical operator followed by a combined condition enclosed in parentheses)

o Combinations of the preceding conditions that are specified according to the rules in the following table.

________________________________________________________________________ | Table 22. Combined Conditions--Permissible Element Sequences | |________________________________________________________________________| | Combined | Leftmost| When not | Right- | When not | | condition | | leftmost, can be | most | rightmost, can be | | element | | immediately | | immediately | | | | preceded by: | | followed by: | |____________|_________|___________________|_________|___________________| | simple- | Yes | OR | Yes | OR | | condition | | NOT | | AND | | | | AND | | ) | | | | ( | | | |____________|_________|___________________|_________|___________________| | OR | No | simple-condition | No | simple-condition | | AND | | ) | | NOT | | | | | | ( | |____________|_________|___________________|_________|___________________| | NOT | Yes | OR | No | simple-condition | | | | AND | | ( | | | | ( | | | |____________|_________|___________________|_________|___________________| | ( | Yes | OR | No | simple-condition | | | | NOT | | NOT | | | | AND | | ( | | | | ( | | | |____________|_________|___________________|_________|___________________| | ) | No | simple-condition | Yes | OR | | | | ) | | AND | | | | | | ) | |____________|_________|___________________|_________|___________________|

Parentheses are never needed when either ANDs or ORs (but not both) are used exclusively in one combined condition. However, parentheses may be needed to modify the implicit precedence rules to maintain the correct logical relation of operators and operands.

There must be a one-to-one correspondence between left and right parentheses, with each left parenthesis to the left of its corresponding right parenthesis.

Table 23 illustrates the relationships between logical operators and conditions C1 and C2.

________________________________________________________________________ | Table 23. Logical Operators and Evaluation Results of Combined | | Conditions | |________________________________________________________________________| | | | | | | | NOT | NOT | | NOT | | | Value | | | C1 | | (C1 | C1 | NOT | C1 | | | for | Value | | AND | C1 OR | AND | AND | (C1 OR | OR | | | C1 | for C2 | | C2 | C2 | C2) | C2 | C2) | C2 | |_______|________|____|_______|________|________|_______|________|_______| | True | True | | True | True | False | False | False | True | |_______|________|____|_______|________|________|_______|________|_______| | False | True | | False | True | True | True | False | True | |_______|________|____|_______|________|________|_______|________|_______| | True | False | | False | True | True | False | False | False | |_______|________|____|_______|________|________|_______|________|_______| | False | False | | False | False | True | False | True | True | |_______|________|____|_______|________|________|_______|________|_______|

Order of Evaluation of Conditions: Parentheses, both explicit and implicit, define the level of inclusiveness within a complex condition. Two or more conditions connected by only the logical operators AND or OR at the same level of inclusiveness establish a hierarchical level within a complex condition. An entire complex condition, therefore, is a nested structure of hierarchical levels with the entire complex condition being the most inclusive hierarchical level.

Within this context, the evaluation of the conditions within an entire complex condition begins at the left of the condition. The constituent connected conditions within a hierarchical level are evaluated in order from left to right, and evaluation of that hierarchical level terminates as soon as a truth value for it is determined, regardless of whether all the constituent connected conditions within that hierarchical level have been evaluated.

Values are established for arithmetic expressions if and when the conditions containing them are evaluated. Similarly, negated conditions are evaluated if and when it is necessary to evaluate the complex condition that they represent.

For example:

NOT A IS GREATER THAN B OR A + B IS EQUAL TO C AND D IS POSITIVE

is evaluated as if parenthesized as follows:

(NOT (A IS GREATER THAN B)) OR (((A + B) IS EQUAL TO C) AND (D IS POSITIVE))

Order of Evaluation:

1. (NOT (A IS GREATER THAN B)) is evaluated, giving some intermediate truth value, t1. If t1 is true, the combined condition is true, and no further evaluation takes place. If t1 is false, evaluation continues as follows.

2. (A + B) is evaluated, giving some intermediate result, x.

3. (x IS EQUAL TO C) is evaluated, giving some intermediate truth value, t2. If t2 is false, the combined condition is false, and no further evaluation takes place. If t2 is true, the evaluation continues as follows.

4. (D IS POSITIVE) is evaluated, giving some intermediate truth value, t3. If t3 is false, the combined condition is false. If t3 is true, the combined condition is true.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.5.11 Abbreviated Combined Relation Conditions

When relation-conditions are written consecutively, any relation-condition after the first can be abbreviated in one of two ways:

o Omission of the subject o Omission of the subject and relational operator.

@@ Diagram abbreviated-combined-relation-condition ADAPTED. @@ Enabled some more uses parentheses. ___ abbreviated-combined-relation-condition _______________________________________________________________________________ | | | >>_____relation-condition__abbreviation-rest___________________________________________________________________________>< | | |__arithmetic-expression__relational-operator__(_____________arithmetic-expression__abbreviation-rest__)________| | | | |__NOT__| | | | |__arithmetic-expression__(________________________________________arithmetic-expression__abbreviation-rest__)__| | | |__NOT__| |__relational-operator__| | | | |___________________________________________________________________________________________________________________________| @@ Diagram object ADDED after diagram abbreviated-combined-relation-condition. @@ Implemented by reading between the lines. ___ object ____________________ | | | >>__arithmetic-expression__>< | | | |_______________________________| @@ Diagram abbreviation-rest EXTRACTED from diagram abbreviated-combined-relation-condition. @@ Enabled subsequent reuse. @@ Diagram abbreviation-rest ADAPTED. @@ Enabled some uses of parentheses. ___ abbreviation-rest _______________________________________________________________________________ | | | <_________________________________________________________________________________________ | | >>_______AND______________________________________________object______________________________|__>< | | |__OR___| |__NOT__| |__relational-operator__| |__(__object__abbreviation-rest__)__| | | | |_____________________________________________________________________________________________________| In any consecutive sequence of relation-conditions, both forms of abbreviation can be specified. The abbreviated condition is evaluated as if:

1. The last stated subject is the missing subject. 2. The last stated relational operator is the missing relational operator.

The resulting combined condition must comply with the rules for element sequence in combined conditions, as shown in Table 22 in topic 2.8.5.10.

If the word immediately following NOT is GREATER THAN, >, LESS THAN, <, EQUAL TO, and =, then the NOT participates as part of the relational operator.

| NOT in any other position in which it is legal is considered a logical operator (and thus results in a negated relation-condition).

x Using Parentheses in Abbreviated Combined Relation Conditions: You can x use parentheses in combined relation conditions to specify an intended x order of evaluation. Using parentheses can also help you to improve the x readability of conditional expressions.

x The following rules govern the use of parentheses in abbreviated combined x relation conditions:

x 1. Parentheses can be used to change the order of evaluation of the x logical operators AND and OR.

x 2. The word NOT participates as part of the relational operator when it x is immediately followed by GREATER THAN, >, LESS THAN, <, EQUAL TO, x and =.

x 3. NOT in any other position is considered a logical operator and thus x results in a negated relation-condition. If you use NOT as a logical x operator, only the relation condition immediately following the NOT is x negated; the negation is not propagated through the abbreviated x combined relation condition along with the subject and relational x operator.

x 4. The logical NOT operator can appear within a parenthetical expression x that immediately follows a relational operator.

x 5. When a left parenthesis appears immediately after the relational x operator, the relational operator is distributed to all objects x enclosed in the parentheses. In the case of a "distributed" x relational operator, the subject and relational operator remain x current after the right parenthesis which ends the distribution. The x following three restrictions apply to cases where the relational x operator is distributed throughout the expression:

x a. A simple condition cannot appear within the scope of the x distribution. x b. Another relational operator cannot appear within the scope of the x distribution. x c. The logical operator NOT cannot appear immediately after the left x parenthesis, which defines the scope of the distribution.

x 6. Evaluation proceeds from the least to the most inclusive condition.

x 7. There must be a one-to-one correspondence between left and right x parentheses, with each left parenthesis to the left of its x corresponding right parenthesis. If the parentheses are unbalanced, x the compiler inserts a parenthesis and issues an E-level message. x Note, however, that if the compiler-inserted parenthesis results in x the truncation of the expression, you will receive an S-level x diagnostic message.

x 8. The last stated subject is inserted in place of the missing subject.

x 9. The last stated relational operator is inserted in place of the x missing relational operator.

x 10. Insertion of the omitted subject and/or relational operator ends when:

x a. Another simple condition is encountered, x b. A condition-name is encountered, x c. A right parenthesis is encountered that matches a left parenthesis x that appears to the left of the subject.

x 11. In any consecutive sequence of relation conditions, you can use both x abbreviated relation conditions that contain parentheses and those x that don't.

x 12. Consecutive logical NOT operators cancel each other and result in an x S-level message. Note, however, that an abbreviated combined relation x condition can contain two consecutive NOT operators when the second x NOT is part of a relational operator. For example, you can abbreviate x the first condition as the second condition listed below.

x A = B and not A not = C x A = B and not not = C

x The following chart summarizes the rules for forming an abbreviated x combined relation condition.

________________________________________________________________________ x | Table 24. Abbreviated Combined Conditions--Permissible Element | x | Sequences | |________________________________________________________________________| x | Combined | | When not | | When not | x | Condition | | leftmost, | | rightmost, | x | Element | Left- | can be | Right- | can be | x | | most | immediately | most | immediately | x | | | preceded by: | | followed by: | |____________|_________|___________________|_________|___________________| x | Subject | Yes | NOT | No | Relational | x | | | ( | | operator | |____________|_________|___________________|_________|___________________| x | Object | No | Relational | Yes | AND | x | | | operator | | OR | x | | | AND | | ) | x | | | OR | | | x | | | NOT | | | x | | | ( | | | |____________|_________|___________________|_________|___________________| x | Relational | No | Subject | No | Object | x | operator | | AND | | ( | x | | | OR | | | x | | | NOT | | | |____________|_________|___________________|_________|___________________| x | AND | No | Object | No | Object | x | OR | | ) | | Relational | x | | | | | operator | x | | | | | NOT | x | | | | | ( | |____________|_________|___________________|_________|___________________| x | NOT | Yes | AND | No | Subject | x | | | OR | | Object | x | | | ( | | Relational | x | | | | | operator | x | | | | | ( | |____________|_________|___________________|_________|___________________| x | ( | Yes | Relational | No | Subject | x | | | operator | | Object | x | | | AND | | NOT | x | | | OR | | ( | x | | | NOT | | | x | | | ( | | | |____________|_________|___________________|_________|___________________| x | ) | No | Object | Yes | AND | x | | | ) | | OR | x | | | | | ) | |____________|_________|___________________|_________|___________________|

The following examples illustrate abbreviated combined relation conditions, with and without parentheses, and their unabbreviated equivalents.

________________________________________________________________________ | Table 25. Abbreviated Combined Conditions--Unabbreviated Equivalents | |________________________________________________________________________| | Abbreviated Combined Relation | Equivalent | | Condition | | |____________________________________|___________________________________| | | ((A = B) AND (A NOT < C)) OR (A | | A = B AND NOT < C OR D | NOT < D) | |____________________________________|___________________________________| | A NOT > B OR C | (A NOT > B) OR (A NOT > C) | |____________________________________|___________________________________| | NOT A = B OR C | (NOT (A = B)) OR (A = C) | |____________________________________|___________________________________| x | NOT (A = B OR < C) | NOT ((A = B) OR (A < C)) | |____________________________________|___________________________________| x | NOT (A NOT = B AND C AND NOT D) | NOT ((((A NOT = B) AND (A NOT = | x | | C)) AND (NOT (A NOT = D)))) | | | | |____________________________________|___________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.6 Statement Categories

There are four categories of COBOL statements:

o Imperative o Conditional o Delimited scope o Compiler directing.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.6.1 Imperative Statements

An imperative statement either specifies an unconditional action to be taken by the program, or is a conditional statement terminated by its explicit scope terminator (see "Delimited Scope Statements" in topic 2.8.6.3). A series of imperative statements can be specified whenever an imperative statement is allowed. A conditional statement that is terminated by its explicit scope terminator is also classified as an imperative statement (see "Delimited Scope Statements" in topic 2.8.6.3). Table 26 lists COBOL imperative statements.

________________________________________________________________________ | Table 26. Imperative Statements | |________________________________________________________________________| | Arithmetic | | ADD(1) | | COMPUTE(1) | | DIVIDE(1) | | MULTIPLY(1) | | SUBTRACT(1) | |________________________________________________________________________| | | Data Manipulation | | ACCEPT (DATE,DAY,DAY-OF-WEEK,TIME) | | INITIALIZE | | INSPECT | | MOVE | | SET | | STRING(2) | | UNSTRING(2) | |________________________________________________________________________| | Ending | | STOP RUN | | EXIT PROGRAM | x | GOBACK | |________________________________________________________________________| | Input-Output | | ACCEPT identifier | | CLOSE | | DELETE(3) | | DISPLAY | | OPEN | | READ(4) | | REWRITE(3) | | START(3) | | STOP literal | | WRITE(5) | |________________________________________________________________________| | Ordering | | MERGE | | RELEASE | | RETURN(6) | | SORT | |________________________________________________________________________| | Procedure Branching | | ALTER | | EXIT | | GO TO | | PERFORM | |________________________________________________________________________| | Subprogram Linkage | | CALL(7) | | CANCEL | |________________________________________________________________________| | Table Handling | | SET | |________________________________________________________________________| | Note: | | | | (1) Without the ON SIZE ERROR and/or the NOT ON SIZE ERROR phrase. | | (2) Without the ON OVERFLOW and/or the NOT ON OVERFLOW phrase. | | (3) Without the INVALID KEY and/or the NOT INVALID KEY phrase. | | (4) Without the AT END, NOT AT END, INVALID KEY, and/or NOT INVALID | | KEY phrases. | | (5) Without the INVALID KEY, NOT INVALID KEY, END-OF-PAGE, and/or NOT | | END-OF-PAGE phrases. | | (6) Without the AT END and/or NOT AT END phrase. | | | (7) Without the ON OVERFLOW, ON EXCEPTION, and/or NOT ON EXCEPTION | | | phrases. | |________________________________________________________________________|


@@ Diagram series-of-imperative-statements ADDED at the end of this section.
@@ Implemented series of imperative statements.

    ___ series-of-imperative-statements ___
   |                                       |
   |     <_______________________          |
   | >>____imperative-statement__|______>< |
   |                                       |
   |_______________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.6.2 Conditional Statements

A conditional statement specifies that the truth value of a condition is to be determined, and that the subsequent action of the object program is dependent on this truth value. (See "Conditional Expressions" in topic 2.8.5.) Table 27 lists COBOL statements that become conditional when a condition (for example, ON SIZE ERROR or ON OVERFLOW) is included, and when the statement is not terminated by its explicit scope terminator.

________________________________________________________________________ | Table 27. Conditional Statements | |________________________________________________________________________| | Arithmetic | | ADD ... ON SIZE ERROR | | ADD ... NOT ON SIZE ERROR | | COMPUTE ... ON SIZE ERROR | | COMPUTE ... NOT ON SIZE ERROR | | DIVIDE ... ON SIZE ERROR | | DIVIDE ... NOT ON SIZE ERROR | | MULTIPLY ... ON SIZE ERROR | | MULTIPLY ... NOT ON SIZE ERROR | | SUBTRACT ... ON SIZE ERROR | | SUBTRACT ... NOT ON SIZE ERROR | |________________________________________________________________________| | | Data Manipulation | | STRING ... ON OVERFLOW | | STRING ... NOT ON OVERFLOW | | UNSTRING ... ON OVERFLOW | | UNSTRING ... NOT ON OVERFLOW | |________________________________________________________________________| | | Procedure Branching | | EVALUATE | | GO TO ... DEPENDING ON | | IF | |________________________________________________________________________| | Input-Output | | DELETE ... INVALID KEY | | DELETE ... NOT INVALID KEY | | READ ... AT END | | READ ... NOT AT END | | READ ... INVALID KEY | | READ ... NOT INVALID KEY | | REWRITE ... INVALID KEY | | REWRITE ... NOT INVALID KEY | | START ... INVALID KEY | | START ... NOT INVALID KEY | | WRITE ... AT END-OF-PAGE | | WRITE ... NOT AT END-OF-PAGE | | WRITE ... INVALID KEY | | WRITE ... NOT INVALID KEY | |________________________________________________________________________| | Ordering | | RETURN ... AT END | | RETURN ... NOT AT END | |________________________________________________________________________| | Subprogram Linkage | | CALL ... ON OVERFLOW | | CALL ... ON EXCEPTION | | CALL ... NOT ON EXCEPTION | |________________________________________________________________________| | Table Handling | | SEARCH | |________________________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.6.3 Delimited Scope Statements

In general, a delimited scope statement uses an explicit scope terminator to turn a conditional statement into an imperative statement; the resulting imperative statement can then be nested. Explicit scope terminators can also be used, however, to terminate the scope of an imperative statement. Explicit scope terminators are provided for all COBOL verbs that can have conditional phrases.

Unless explicitly specified otherwise, a delimited scope statement can be specified wherever an imperative statement is allowed by the rules of the language.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.6.3.1 Explicit Scope Terminators

An explicit scope terminator marks the end of certain Procedure Division statements. A conditional statement that is delimited by its explicit scope terminator is considered an imperative statement and must follow the rules for imperative statements.

The following are explicit scope terminators:

END-ADD END-READ END-CALL END-RETURN END-COMPUTE END-REWRITE END-DELETE END-SEARCH END-DIVIDE END-START END-EVALUATE END-STRING END-IF END-SUBTRACT END-MULTIPLY END-UNSTRING END-PERFORM END-WRITE


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.6.3.2 Implicit Scope Terminators

At the end of any sentence, an implicit scope terminator is a separator period that terminates the scope of all previous statements not yet terminated.

Note: Except for nesting conditional statements within IF statements, nested statements must be imperative statements, and must follow the rules for imperative statements. You should not nest conditional statements.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.6.4 Compiler-Directing Statements

Statements that direct the compiler to take a specified action are discussed in "Part 4. Compiler-Directing Statements" in topic 4.0.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.7 Common Phrases for Arithmetic and Data Manipulation Statements

| The following phrases and concepts are common to arithmetic and data | manipulation statements and are described below:

| o CORRESPONDING phrase | o GIVING phrase | o ROUNDED phrase | o SIZE ERROR phrases | o Overlapping operands

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.7.1 CORRESPONDING Phrase

The CORRESPONDING (CORR) phrase allows ADD, SUBTRACT, and MOVE operations to be performed on elementary data items of the same name if the group items to which they belong are specified.

Both identifiers following the keyword CORRESPONDING must name group items. In this discussion, these identifiers are referred to as identifier-1 and identifier-2.

A pair of data items (subordinate items), one from identifier-1 and one from identifier-2, correspond if the following conditions are true:

o In an ADD or SUBTRACT statement, both of the data items are elementary numeric data items. Other data items are ignored.

o In a MOVE statement, at least one of the data items is an elementary item, and the move is permitted by the move rules.

o The two subordinate items have the same name and the same qualifiers up to but not including identifier-1 and identifier-2.

o The subordinate items are not identified by the keyword FILLER.

o Neither identifier-1 nor identifier-2 is described as a level 66, 77, or 88 item, nor is either described as a USAGE IS INDEX item. Neither identifier-1 nor identifier-2 can be reference-modified.

o The subordinate items do not include a REDEFINES, RENAMES, OCCURS, or USAGE IS INDEX clause in their descriptions.

However, identifier-1 and identifier-2 themselves can contain or be subordinate to items containing a REDEFINES or OCCURS clause in their descriptions.

x o Neither identifier-1 nor identifier-2 nor the two subordinate items x are described as USAGE IS POINTER items.

x o Identifier-1 and/or identifier-2 can be subordinate to a FILLER item.

For example, if two data hierarchies are defined as follows:

| 05 ITEM-1 OCCURS 6 TIMES INDEXED BY X. 10 ITEM-A PIC S9(3). 10 ITEM-B PIC +99.9. 10 ITEM-C PIC X(4). 10 ITEM-D REDEFINES ITEM-C PIC 9(4). 10 ITEM-E USAGE COMP-1. 10 ITEM-F USAGE INDEX. 05 ITEM-2. 10 ITEM-A PIC 99. 10 ITEM-B PIC +9V9. 10 ITEM-C PIC A(4). 10 ITEM-D PIC 9(4). 10 ITEM-E PIC 9(9) USAGE COMP. 10 ITEM-F USAGE INDEX.

Then, if ADD CORR ITEM-2 TO ITEM-1(X) is specified, ITEM-A and ITEM-A(X), ITEM-B and ITEM-B(X), and ITEM-E and ITEM-E(X) are considered to be corresponding and are added together. ITEM-C and ITEM-C(X) are not included because they are not numeric. ITEM-D and ITEM-D(X) are not included because ITEM-D(X) includes a REDEFINES clause in its data description. ITEM-F and ITEM-F(X) are not included because they are defined as USAGE IS INDEX. Note that ITEM-1 is valid as either identifier-1 or identifier-2.

If any of the individual operations in the ADD CORRESPONDING statement produces a size error condition, imperative-statement-1 in the ON SIZE ERROR phrase is not executed until all of the individual additions are completed.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.7.2 GIVING Phrase

The value of the identifier that follows the word GIVING is set equal to the calculated result of the arithmetic operation. Because this identifier is not involved in the computation, it can be a numeric-edited item.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.7.3 ROUNDED Phrase

After decimal point alignment, the number of places in the fraction of the result of an arithmetic operation is compared with the number of places provided for the fraction of the resultant identifier.

When the size of the fractional result exceeds the number of places provided for its storage, truncation occurs unless ROUNDED is specified. When ROUNDED is specified, the least significant digit of the resultant identifier is increased by 1 whenever the most significant digit of the excess is greater than or equal to 5.

When the resultant identifier is described by a PICTURE clause containing rightmost Ps, and when the number of places in the calculated result exceeds the number of integer positions specified, rounding or truncation occurs, relative to the rightmost integer position for which storage is allocated.

x In a floating-point arithmetic operation, the ROUNDED phrase has no x effect; the result of a floating-point operation is always rounded. For x more information on floating-point arithmetic expressions, see VS COBOL II x Application Programming Guide for MVS and CMS or VS COBOL II Application x Programming Guide for VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.7.4 SIZE ERROR Phrases

A size error condition can occur in three different ways:

o When the absolute value of the result of an arithmetic evaluation, after decimal point alignment, exceeds the largest value that can be contained in the result field

o When division by zero occurs

o In an exponential expression, as indicated in the following table:

________________________________________________________________________ | Table 28. Exponentiation Size Error Conditions | |________________________________________________________________________| | | Action taken when | Action taken when | | | a SIZE ERROR clause | a SIZE ERROR clause | | Size error | is present | is not present | |_______________________|________________________|_______________________| | Zero raised to zero | The SIZE ERROR | The value returned is | | power | imperative is | 1, and a message is | | | executed. | issued. | |_______________________|________________________|_______________________| | Zero raised to a | The SIZE ERROR | Program is terminated | | negative number | imperative is | abnormally. | | | executed. | | |_______________________|________________________|_______________________| | A negative number | The SIZE ERROR | The absolute value of | | raised to a | imperative is | the base is used, and | | fractional power | executed. | a message is issued. | |_______________________|________________________|_______________________|

The size error condition applies only to final results, not to any intermediate results.

If the resultant identifier is defined with USAGE IS BINARY, x COMPUTATIONAL, or COMPUTATIONAL-4, the largest value that can be contained in it is the maximum value implied by its associated decimal PICTURE character-string.

If the ROUNDED phrase is specified, rounding takes place before size error checking.

When a size error occurs, the subsequent action of the program depends on whether or not the ON SIZE ERROR phrase is specified.

| If the ON SIZE ERROR phrase is not specified and a size error condition | exists after the execution of the arithmetic operations specified by an | arithmetic statement, the values of the affected resultant identifiers are | undefined. After completion of the arithmetic operations, control is | transferred to the end of the arithmetic statement and the NOT ON SIZE | ERROR phrase, if specified, is ignored.

If the ON SIZE ERROR phrase is specified and a size error condition occurs, the value of the resultant identifier affected by the size error is not altered--that is, the error results are not placed in the receiving identifier. After completion of the execution of the arithmetic operation, the imperative statement in the ON SIZE ERROR phrase is executed, control is transferred to the end of the arithmetic statement, and the NOT ON SIZE ERROR phrase, if specified, is ignored.

For ADD CORRESPONDING and SUBTRACT CORRESPONDING statements, if an individual arithmetic operation causes a size error condition, the ON SIZE ERROR imperative statement is not executed until all the individual additions or subtractions have been completed.

If the NOT ON SIZE ERROR phrase has been specified and, after execution of an arithmetic operation, a size error condition does not exist, the NOT ON SIZE ERROR phrase is executed.

When both ON SIZE ERROR and NOT ON SIZE ERROR phrases are specified, and the statement in the phrase that is executed does not contain any explicit transfer of control, then, if necessary, an implicit transfer of control is made after execution of the phrase to the end of the arithmetic statement.


@@ Diagram on-size-error ADDED at the end of this section.
@@ Capture conditional phrase for reuse.

    ___ on-size-error ________________________________________________
   |                                                                  |
   | >>____________SIZE__ERROR__series-of-imperative-statements-1__>< |
   |     |__ON__|                                                     |
   |                                                                  |
   |__________________________________________________________________|


@@ Diagram not-on-size-error ADDED at the end of this section.
@@ Capture conditional phrase for reuse.

    ___ not-on-size-error _________________________________________________
   |                                                                       |
   | >>__NOT____________SIZE__ERROR__series-of-imperative-statements-2__>< |
   |          |__ON__|                                                     |
   |                                                                       |
   |_______________________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.7.5 Overlapping Operands

| When operands in an arithmetic or data manipulation statement share part | of their storage (that is, when the operands overlap), the result of the | execution of such a statement is unpredictable.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.8 Arithmetic Statements

The arithmetic statements are used for computations. Individual operations are specified by the ADD, SUBTRACT, MULTIPLY, and DIVIDE statements. These operations can be combined symbolically in a formula, using the COMPUTE statement.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.8.1 Arithmetic Statement Operands

The data description of operands in an arithmetic statement need not be the same. Throughout the calculation, the compiler performs any necessary data conversion and decimal point alignment.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.8.1.1 Size of Operands

The maximum size of each operand is 18 decimal digits. The composite of operands is a hypothetical data item resulting from aligning the operands at the decimal point and then superimposing them on one another. It must not contain more than 18 decimal digits.

| For example, assume that each item is defined as follows in the Data | Division:

| 77 A PICTURE 9(7)V9(5). | 77 B PICTURE 9(11)V9(2). | 77 C PICTURE 9(12)V9(3).

If the following statement is executed, the composite of operands consists of 17 decimal digits:

ADD A B TO C

It has the following implicit description:

77 COMPOSITE-OF-OPERANDS PICTURE 9(12)V9(5).

x The composite of operands can be more than 18 digits. See the section on x intermediate results in VS COBOL II Application Programming Guide for MVS x and CMS or VS COBOL II Application Programming Guide for VSE for more x information.

In the ADD and SUBTRACT statements, if the composite of operands is 18 digits or less, the compiler ensures that enough places are carried so that no significant digits are lost during execution. The following table shows how the composite of operands is determined for arithmetic statements:

__________________________________________________________________ | Table 29. How the Composite of Operands is Determined | |__________________________________________________________________| | Statement | Determination of the Composite of Operands | |_______________|__________________________________________________| | ADD | Superimposing all operands in a given statement | | SUBTRACT | (except those following the word GIVING) | |_______________|__________________________________________________| | MULTIPLY | Superimposing all receiving data items | |_______________|__________________________________________________| | DIVIDE | Superimposing all receiving data items, except | | | the REMAINDER data item | |_______________|__________________________________________________| | COMPUTE | Restriction does not apply | |_______________|__________________________________________________|

In all arithmetic statements, it is important to define data with enough digits and decimal places to ensure the desired accuracy in the final result.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.8.1.2 Multiple Results

When an arithmetic statement has multiple results, execution conceptually proceeds as follows:

o The statement performs all arithmetic operations to find the result to be placed in the receiving items, and stores that result in a temporary location.

o A sequence of statements transfers or combines the value of this temporary result with each single receiving field. The statements are considered to be written in the same left-to-right order as the multiple results are listed.

For example, executing the following statement:

ADD A, B, C, TO C, D(C), E.

is equivalent to executing the following series of statements:

ADD A, B, C GIVING TEMP. ADD TEMP TO C. ADD TEMP TO D(C). ADD TEMP TO E.

In the above example, TEMP is a compiler-supplied temporary result field. When the addition operation for D(C) is performed, the subscript C contains the new value of C.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.9 Input-Output Statements

COBOL input-output statements transfer data to and from files stored on external media, and also control low-volume data that is obtained from or sent to an input/output device.

In COBOL, the unit of file data made available to the program is a record, and you need only be concerned with such records. Provision is automatically made for such operations as the movement of data into buffers and/or internal storage, validity checking, error correction (where feasible), blocking and deblocking, and volume switching procedures.

The description of the file in the Environment Division and Data Division governs which input-output statements are allowed in the Procedure Division. Permissible statements for each type of file organization are shown in Table 37 in topic 3.24.4 and Table 38 in topic 3.24.4.

Discussions in the following section use the terms volume and reel. The term volume refers to all non-unit-record input-output devices. The term reel applies only to tape devices. Treatment of direct access devices in the sequential access mode is logically equivalent to the treatment of tape devices.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.9.1 Common Processing Facilities for Input-Output Statements

| The following common processing facilities apply to more than one | input-output statement:

o Status key o Invalid key condition o INTO/FROM identifier phrase o File position indicator.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

2.8.9.1.1 Status Key

If the FILE STATUS clause is specified in the FILE-CONTROL entry, a value is placed in the specified status key during execution of any request on that file; the value indicates the status of that request. The value is placed in the status key before execution of any EXCEPTION/ERROR declarative or INVALID KEY/AT END phrase associated with the request.

| There are two status key data items. One is for QSAM, SAM, or VSAM files, | and it is described by data-name-1 in the FILE STATUS clause of the | FILE-CONTROL entry. This is a 2-character data item with the first | character known as status key 1 and the second character known as status | key 2. The combinations of possible values and their meanings are shown | in Table 30.

x The other status key data item is for VSAM files only, and it is described x by data-name-8 in the FILE STATUS clause of the FILE-CONTROL entry. For x more information on the VSAM file status key, see "FILE STATUS Clause" in x topic 2.4.13.

x Note: This element may exhibit different behavior when the CMPR2 compiler x option is in effect. For more information, see VS COBOL II Migration x Guide for MVS and CMS or VS COBOL II Migration Guide for VSE.

________________________________________________________________________ | Table 30. Status Key Values and Meanings | |________________________________________________________________________| | | | | | | High-| | Low- | | | Order| | Order| | | Digit| Meaning | Digit| Meaning | | | | | | |______|_____________|______|____________________________________________| | 0 | Successful | 0 | No further information | | | Completion |______|____________________________________________| | | | 2 | The input-output statement was | | | | | successfully executed, but a duplicate key | | | | | was detected. For a READ statement the | | | | | key value for the current key of reference | | | | | was equal to the value of the same key in | | | | | the next 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. | | | |______|____________________________________________| | | | 4 | A READ statement was successfully | | | | | executed, but the length of the record | | | | | being processed did not conform to the | | | | | fixed file attributes for that file. | | | |______|____________________________________________| | | | 5 | An OPEN statement is successfully executed | | | | | but the referenced optional file is not | | | | | present at the time the OPEN statement is | | | | | | executed. If the open mode is I-O or | | | | | | EXTEND, the file has been created. For a | x | | | | VSAM sequential file, if the open mode is | x | | | | I-O or EXTEND, the file has not been | x | | | | created, and file status 0 is returned. | | | |______|____________________________________________| | | | 7 | For a CLOSE statement with the NO REWIND, | | | | | REEL/UNIT, or FOR REMOVAL phrase or for an | | | | | OPEN statement with the NO REWIND phrase, | | | | | the referenced file was on a non-reel/unit | | | | | medium. | |______|_____________|______|____________________________________________| | 1 | At end | 0 | A sequential READ statement was attempted | | | condition | | and no next logical record existed in the | | | | | file because the end of the file had been | | | | | reached, or the first READ was attempted | | | | | on an optional input file that was not | | | | | present. | | | |______|____________________________________________| | | | 4 | A sequential READ statement was attempted | | | | | for a relative file and the number of | | | | | significant digits in the relative record | | | | | number was larger than the size of the | | | | | relative key data item described for the | | | | | file. | |______|_____________|______|____________________________________________| | 2 | Invalid key | 1 | A sequence error exists for a sequentially | | | condition | | accessed indexed file. The prime record | | | | | key value has been changed by the program | | | | | between the successful execution of a READ | | | | | statement and the execution of the next | | | | | REWRITE statement for that file, or the | | | | | ascending requirements for successive | | | | | record key values were violated. | | | |______|____________________________________________| | | | 2 | An attempt was made to write a record that | | | | | would create a duplicate key in a relative | | | | | file; or an attempt was made to write or | | | | | rewrite a record that would create a | | | | | duplicate prime record key or a duplicate | | | | | alternate record key without the | | | | | DUPLICATES phrase in an indexed file. | | | | | This key value applies to an indexed file | | | | | in which the alternate key has been | | | | | declared 'UNIQUE'. | | | |______|____________________________________________| | | | 3 | 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 | | | | | was not present. | | | |______|____________________________________________| | | | 4 | An attempt was made to write beyond the | | | | | externally defined boundaries of a | | | | | relative or indexed file. Or, a | | | | | sequential WRITE statement was attempted | | | | | for a relative file and the number of | | | | | significant digits in the relative record | | | | | number was larger than the size of the | | | | | relative key data item described for the | | | | | file. | |______|_____________|______|____________________________________________| | 3 | Permanent | 0 | No further information | | | error |______|____________________________________________| | | condition | 4 | A permanent error exists because of a | | | | | boundary violation; an attempt was made to | | | | | write beyond the externally-defined | | | | | boundaries of a sequential file. | | | |______|____________________________________________| | | | 5 | An OPEN statement with the INPUT, I-O, or | | | | | EXTEND phrase was attempted on a | | | | | non-optional file that was not present. | | | |______|____________________________________________| | | | 7 | An OPEN statement was attempted on a file | | | | | that would not support the open mode | | | | | specified in the OPEN statement. Possible | | | | | violations are: | | | | | | | | | | 1. The EXTEND or OUTPUT phrase was | | | | | specified but the file would not | | | | | support write operations. | | | | | 2. The I-O phrase was specified but the | | | | | file would not support the input and | | | | | output operations permitted. | | | | | 3. The INPUT phrase was specified but the | | | | | file would not support read | | | | | operations. | | | |______|____________________________________________| | | | 8 | An OPEN statement was attempted on a file | | | | | previously closed with lock. | | | |______|____________________________________________| | | | 9 | The OPEN statement was unsuccessful | | | | | because a conflict was detected between | | | | | the fixed file attributes and the | | | | | attributes specified for that file in the | | | | | program. These attributes include the | | | | | organization of the file (sequential, | | | | | relative, or indexed), the prime record | | | | | key, the alternate record keys, the code | | | | | set, the maximum record size, and the | | | | | record type (fixed or variable). | |______|_____________|______|____________________________________________| | 4 | Logic error | 1 | An OPEN statement was attempted for a file | | | condition | | in the open mode. | | | |______|____________________________________________| | | | 2 | A CLOSE statement was attempted for a file | | | | | not in the open mode. | | | |______|____________________________________________| | | | 3 | For a mass storage file in the sequential | | | | | access mode, the last input-output | | | | | statement executed for the associated file | | | | | prior to the execution of a REWRITE | | | | | statement was not a successfully executed | | | | | READ statement. | | | | | | | | | | For relative and indexed files in the | | | | | sequential access mode, the last | | | | | input-output statement executed for the | | | | | file prior to the execution of a DELETE or | | | | | REWRITE statement was not a successfully | | | | | executed READ statement. | | | |______|____________________________________________| | | | 4 | A boundary violation exists because an | | | | | attempt was made to rewrite a record to a | | | | | file and the record was not the same size | | | | | as the record being replaced, or an | | | | | attempt was made to write or rewrite a | | | | | record that was larger than the largest or | | | | | smaller than the smallest record allowed | | | | | by the RECORD IS VARYING clause of the | | | | | associated file-name. | | | |______|____________________________________________| | | | 6 | A sequential READ statement was attempted | | | | | on a file open in the input or I-O mode | | | | | and no valid next record had been | | | | | established because: | | | | | | | | | | | 1. The preceding START statement was | | | | | | unsuccessful, or | | | | | 2. The preceding READ statement was | | | | | unsuccessful but did not cause an at | | | | | end condition, or | | | | | 3. The preceding READ statement caused an | | | | | at end condition. | | | |______|____________________________________________| | | | 7 | The execution of a READ statement was | | | | | attempted on a file not open in the input | | | | | or I-O mode. | | | |______|____________________________________________| | | | 8 | The execution of a WRITE statement was | | | | | attempted on a file not open in the I-O, | | | | | output, or extend mode. | | | |______|____________________________________________| | | | 9 | The execution of a DELETE or REWRITE | | | | | statement was attempted on a file not open | | | | | in the I-O mode. | |______|_____________|______|____________________________________________| | 9 | Implementor-| 0 | No further information. | | | defined |______|____________________________________________| | | condition | 1 | For VSAM only: Password failure. | | | |______|____________________________________________| | | | 2 | Logic error. | | | |______|____________________________________________| | | | 3 | For VSAM only: Resource not available. | | | |______|____________________________________________| x | | | 4 | For VSAM with CMPR2 compiler-option only: | x | | | | No file position indicator for sequential | x | | | | request. | | | |______|____________________________________________| | | | 5 | For VSAM only: Invalid or incomplete file | | | | | information. | | | |______|____________________________________________| | | | 6 | For VSAM only: No DD statement specified | | | | | for this file. | | | |______|____________________________________________| | | | 7 | For VSAM only: OPEN statement execution | | | | | successful: File integrity verified. | |______|_____________|______|____________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.9.1.2 Invalid Key Condition

The invalid key condition can occur during execution of a START, READ, WRITE, REWRITE, or DELETE statement. (For details of the causes for the condition, see the appropriate statement in "Part 3. Procedure Division Statements" in topic 3.0.) When an invalid key condition occurs, the input-output statement that caused the condition is unsuccessful.

When the invalid key condition is recognized, actions are taken in the following order:

1. If the FILE STATUS clause is specified in the FILE-CONTROL entry, a value is placed into the status key to indicate an invalid key condition. (See Table 30 in topic 2.8.9.1.1.)

2. If the INVALID KEY phrase is specified in the statement causing the condition, control is transferred to the INVALID KEY imperative-statement. Any EXCEPTION/ERROR declarative procedure specified for this file is not executed. Execution then continues according to the rules for each statement specified in the imperative-statement.

3. If the INVALID KEY phrase is not specified in the input-output statement for a file, an EXCEPTION/ERROR procedure must be specified, and that procedure is executed. The NOT INVALID KEY phrase, if specified, is ignored.

x Both the INVALID KEY phrase and the EXCEPTION/ERROR procedure can be x omitted.

If the invalid key condition does not exist after execution of the input-output operation, the INVALID KEY phrase is ignored, if specified, and the following actions are taken:

1. If an exception condition which is not an invalid key condition exists, control is transferred according to the rules of the USE statement following the execution of any USE AFTER EXCEPTION procedure.

2. If no exception condition exists, control is transferred to the end of the input-output statement or the imperative statement specified in the NOT INVALID KEY phrase, if it is specified.


@@ Diagram not-invalid-key ADDED at the end of this section.
@@ Capture conditional phrase for reuse.

    ___ not-invalid-key ______________________________________________
   |                                                                  |
   | >>__NOT__INVALID_____________series-of-imperative-statements__>< |
   |                   |__KEY__|                                      |
   |                                                                  |
   |__________________________________________________________________|


@@ Diagram invalid-key ADDED at the end of this section.
@@ Capture conditional phrase for reuse.

    ___ invalid-key _____________________________________________
   |                                                             |
   | >>__INVALID_____________series-of-imperative-statements__>< |
   |              |__KEY__|                                      |
   |                                                             |
   |_____________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.9.1.3 INTO/FROM Identifier Phrase

This phrase is valid for READ, RETURN, RELEASE, REWRITE, and WRITE statements. The identifier specified must be the name of an entry in the Working-Storage Section or the Linkage Section, or of a record description for another previously opened file. Record-name/file-name and identifier must not refer to the same storage area.

___ into-from-identifier-phrase _________________________________________________ | | | >>________READ_______file-name-1_____________________________________________>< | | | |__RETURN__| |__RECORD__| |__INTO__identifier-1__| | | | |_____RELEASE_____record-name-1_______________________________________| | | |__REWRITE__| |__FROM__identifier-1__| | | |__WRITE____| | | | |_________________________________________________________________________________| o The INTO phrase can be specified in a READ or RETURN statement.

The result of the execution of a READ or RETURN statement with the INTO phrase is equivalent to the application of the following rules in the order specified:

- The execution of the same READ or RETURN statement without the INTO phrase.

- The current record is moved from the record area to the area specified by identifier-1 according to the rules for the MOVE statement without the CORRESPONDING phrase. The size of the current record is determined by rules specified in the RECORD clause. If the file description entry contains a RECORD IS VARYING clause, the implied move is a group move. The implied MOVE statement does not occur if the execution of the READ or RETURN statement was unsuccessful. Any subscripting or reference-modification associated with identifier-1 is evaluated after the record has been read or returned and immediately before it is moved to the data item. The record is available in both the record area and the data item referenced by identifier-1.

o The FROM phrase can be specified in a RELEASE, REWRITE, or WRITE statement.

The result of the execution of a RELEASE, REWRITE, or WRITE statement with the FROM phrase is equivalent to the execution of the following statements in the order specified:

MOVE identifier-1 TO record-name-1

The same RELEASE, REWRITE, or WRITE statement without the FROM phrase.

After the execution of the RELEASE, REWRITE or WRITE statement is complete, the information in the area referenced by identifier-1 is available, even though the information in the area referenced by record-name-1 is not available, except specified by the SAME RECORD AREA clause.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.9.1.4 File Position Indicator

The file position indicator is a conceptual entity used in this document to facilitate exact specification of the next record to be accessed within a given file during certain sequences of input-output operations. The setting of the file position indicator is affected only by the OPEN, CLOSE, READ and START statements. The concept of a file position indicator has no meaning for a file opened in the output or extend mode.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 2.8.10 Procedure Branching Statements

Statements, sentences, and paragraphs in the Procedure Division are executed sequentially, except when a procedure branching statement such as x EXIT, GO TO, PERFORM, GOBACK, or STOP is used.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.0 Part 3. Procedure Division Statements

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.1 ACCEPT Statement

The ACCEPT statement transfers data into the specified identifier. There | is no editing or error checking of the incoming data. The ACCEPT | statement has two formats:

| o Format 1 (Data Transfer) | o Format 2 (System Information Transfer)

Subtopics:


@@ Diagram accept-statement ADDED at the end of this section.
@@ Different formats of ACCEPT statements.

    ___ accept-statement _____________________
   |                                          |
   | >>_____accept-statement-format-i______>< |
   |     |__accept-statement-format-ii__|     |
   |                                          |
   |__________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 3.1.1 Format 1 (Data Transfer)

___ accept-statement-format-i __________________________________________ | | | >>__ACCEPT__identifier-1____________________________________________>< | | |__FROM_____mnemonic-name-1____________| | | |__{__environment-name__}__| | | | |________________________________________________________________________| Format 1 transfers data from an input/output device into identifier-1. When the FROM phrase is omitted, the system input device is assumed.

Format 1 is useful for exceptional situations in a program when operator intervention (to supply a given message, code, or exception indicator) is required. The operator must, of course, be supplied with the appropriate messages with which to reply.

identifier-1 Can be any group item, or an elementary alphabetic, alphanumeric, alphanumeric-edited, numeric-edited or external decimal item.

x It can also be a DBCS data item or an external floating-point item.

mnemonic-name-1 Must be associated in the SPECIAL-NAMES paragraph with an input/output device: either a system input device or a console typewriter. For more information on acceptable values for mnemonic-name-1, see "SPECIAL-NAMES Paragraph" in topic 2.3.3.

o System input device

The maximum logical record length allowed is 256 characters.

The system input device is read until identifier-1 is filled or EOF is encountered. If the length of identifier-1 is not an even multiple of the system input device record length, the final record will be truncated as required. If EOF is encountered after data has been moved, and before identifier-1 has been filled, identifier-1 is padded with blanks. If EOF is encountered before any data has been moved to identifier-1, padding will not take place and identifier-1 contents will remain unchanged. Each input record is concatenated with the previous input record.

If the input record is of the fixed-length format, the entire input record is used. No editing is performed to remove trailing or leading blanks.

If the input record is of the variable-length format, the actual record length is used to determine the amount of data received. With variable format records, the Record Definition Word (RDW) is removed from the beginning of the input record. Only the actual input data is transferred to identifier-1.

o Console typewriter

1. A system-generated message code is automatically displayed, followed by the literal AWAITING REPLY. The maximum length of an input message is 114 characters.

2. Execution is suspended.

3. After the message code (the same code as in item 1) is entered from the console and recognized by the system, ACCEPT statement execution is resumed. The message is moved to identifier-1 and left-justified, regardless of its PICTURE

The ACCEPT statement is terminated after any of the following occurs:

- If no data is received from the console. For example, if the operator hits the ENTER key - The identifier is filled with data - Fewer than 114 characters of data are entered.

If 114 bytes of data are entered and the identifier is still not filled with data, then more requests for data are issued to the console. If more than 114 characters of data are entered, only the first 114 characters will be recognized by the system.

If the identifier is longer than the incoming message, the rightmost characters are padded with spaces. If the incoming message is longer than the identifier, the character positions beyond the length of the identifier are truncated.

x environment-name x A valid environment-name can be specified in the FROM phrase. See x Table 6 in topic 2.3.3 for a list of valid environment-names.

Note: If the device specified in an ACCEPT statement is the same device used for READ statements, results are unpredictable.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

| 3.1.2 Format 2 (System Information Transfer)

System information contained in the specified conceptual data items DATE, DAY, DAY-OF-WEEK, or TIME can be transferred into the identifier. The transfer must follow the rules for the MOVE statement without the CORRESPONDING phrase. See "MOVE Statement" in topic 3.22.

___ accept-statement-format-ii ________________________ | | | >>__ACCEPT__identifier-2__FROM_____DATE____________>< | | |__DAY__________| | | |__DAY-OF-WEEK__| | | |__TIME_________| | | | |_______________________________________________________| | identifier-2 Can be a group, elementary alphanumeric, alphanumeric-edited, x numeric-edited, external decimal, internal decimal, binary, internal x floating-point, or external floating-point item.

| Format 2 accesses the current date (in either of two formats using DATE or | DAY), the day of the week, and the time of day, as carried by the system. This can be useful in identifying when a particular run of an object program was executed. It can also be used to supply the date in headings and footings.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.1.3 DATE, DAY, DAY-OF-WEEK, and TIME

The conceptual data items DATE, DAY, DAY-OF-WEEK, and TIME implicitly have USAGE DISPLAY. Because DATE, DAY, DAY-OF-WEEK, and TIME are conceptual data items, they cannot be described in the COBOL program.

DATE Has the implicit PICTURE 9(6).

The sequence of data elements (from left to right) is:

2 digits for year of century 2 digits for month of year 2 digits for day of month

| Thus 25 December 1993 is expressed as: 931225

DAY Has the implicit PICTURE 9(5).

The sequence of data elements (from left to right) is:

2 digits for year of century 3 digits for day of year

| Thus 25 December 1993 is expressed as: 93359

DAY-OF-WEEK Has the implicit PICTURE 9(1).

The single data element represents the day of the week according to the following values:

1 represents Monday 5 represents Friday 2 represents Tuesday 6 represents Saturday 3 represents Wednesday 7 represents Sunday 4 represents Thursday

Thus Wednesday is expressed as: 3

TIME Has the implicit PICTURE 9(8).

The sequence of data elements (from left to right) is:

2 digits for hour of day 2 digits for minute of hour 2 digits for second of minute 2 digits for hundredths of second

Thus 2:41 PM is expressed as: 14410000


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.2 ADD Statement

The ADD statement sums two or more numeric operands and stores the result.

@@ Diagram add-statement-format-i ADAPTED. @@ 1 imperative statement = many imperative statements (see 2.8.6.1) @@ Diagram add-statement-format-i FOLDED according to on-size-error. @@ Factored out clause for conciseness. @@ Diagram add-statement-format-i FOLDED according to not-on-size-error. @@ Factored out clause for conciseness. ___ add-statement-format-i _________________________________________________ | | | <_____________________ <______________________________ | | >>__ADD_______identifier-1_____|__TO____identifier-2_________________|___> | | |__literal-1_____| |__ROUNDED__| | | | | >________________________________________________________________________> | | |__on-size-error__| | | | | >________________________________________________________________________> | | |__not-on-size-error__| | | | | >_______________________________________________________________________>< | | |__END-ADD__| | | | |____________________________________________________________________________| In Format 1, all identifiers or literals preceding the key word TO are | added together, and this sum is stored in a temporary data item. This | temporary data item is then added to each successive occurrence of | identifier-2, in the left-to-right order in which identifier-2 is | specified.

@@ Diagram add-statement-format-ii ADAPTED. @@ 1 imperative statement = many imperative statements (see 2.8.6.1) @@ Diagram add-statement-format-ii FOLDED according to on-size-error. @@ Factored out clause for conciseness. @@ Diagram add-statement-format-ii FOLDED according to not-on-size-error. @@ Factored out clause for conciseness. ___ add-statement-format-ii ________________________________________ | | | <_____________________ | | >>__ADD_______identifier-1_____|_______________identifier-2______> | | |__literal-1_____| |__TO__| |__literal-2_____| | | | | <______________________________ | | >___GIVING____identifier-3_________________|_____________________> | | |__ROUNDED__| | | | | >________________________________________________________________> | | |__on-size-error__| | | | | >________________________________________________________________> | | |__not-on-size-error__| | | | | >_______________________________________________________________>< | | |__END-ADD__| | | | |____________________________________________________________________| In Format 2, the values of the operands preceding the word GIVING are added together, and the sum is stored as the new value of each data item referenced by identifier-3.

@@ Diagram add-statement-format-iii ADAPTED. @@ 1 imperative statement = many imperative statements (see 2.8.6.1) @@ Diagram add-statement-format-iii FOLDED according to on-size-error. @@ Factored out clause for conciseness. @@ Diagram add-statement-format-iii FOLDED according to not-on-size-error. @@ Factored out clause for conciseness. ___ add-statement-format-iii _____________________________________ | | | >>__ADD_____CORRESPONDING_____identifier-1__TO__identifier-2___> | | |__CORR___________| | | | | >______________________________________________________________> | | |__ROUNDED__| |__on-size-error__| | | | | >______________________________________________________________> | | |__not-on-size-error__| | | | | >_____________________________________________________________>< | | |__END-ADD__| | | | |__________________________________________________________________| In Format 3, elementary data items within identifier-1 are added to and stored in the corresponding elementary items within identifier-2.

For all Formats:

identifier In Format 1, must name an elementary numeric item.

In Format 2, must name an elementary numeric item, except when following the word GIVING. Each identifier following the word GIVING must name an elementary numeric or numeric-edited item.

In Format 3, must name a group item.

literal Must be a numeric literal.

x Floating-point data items and literals can be used anywhere a numeric x data item or literal can be specified.

The composite of operands must not contain more than 18 digits. The compiler ensures that enough places are carried so that no significant digits are lost during execution.

x The composite of operands can be more than 18 digits. For information on x arithmetic intermediate results, see VS COBOL II Application Programming x Guide for MVS and CMS or VS COBOL II Application Programming Guide for x VSE.

o In Format 1, the composite of operands is determined by using all of the operands in a given statement.

o In Format 2, the composite of operands is determined by using all of the operands in a given statement excluding the data items that follow the word GIVING.

o In Format 3, the composite of operands is determined separately for each pair of corresponding data items.

Subtopics:


@@ Diagram add-statement ADDED at the end of this section.
@@ Different formats of ADD statements.

    ___ add-statement ______________________
   |                                        |
   | >>_____add-statement-format-i_______>< |
   |     |__add-statement-format-ii___|     |
   |     |__add-statement-format-iii__|     |
   |                                        |
   |________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.2.1 ROUNDED Phrase

For Formats 1, 2, and 3, see "ROUNDED Phrase" in topic 2.8.7.3.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.2.2 SIZE ERROR Phrases

For Formats 1, 2, and 3, see "SIZE ERROR Phrases" in topic 2.8.7.4.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.2.3 CORRESPONDING Phrase (Format 3)

See "CORRESPONDING Phrase" in topic 2.8.7.1.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.2.4 END-ADD Phrase

| This explicit scope terminator delimits the scope of the ADD statement. | END-ADD converts a conditional ADD statement to an imperative statement so | that it can be nested in another conditional statement. END-ADD can also be used with an imperative ADD statement.

For more information, see "Delimited Scope Statements" in topic 2.8.6.3.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.3 ALTER Statement

The ALTER statement changes the transfer point specified in a GO TO statement.

Note: The ALTER statement is an obsolete element and encourages the use | of unstructured programming practices; it will be deleted from the next | revision of the COBOL 85 Standard. The EVALUATE statement provides | function that is similar to the ALTER statement and helps to ensure that your program will be well structured.

___ alter-statement ____________________________________________________ | | | >>__ALTER____________________________________________________________> | | | | <____________________________________________________________ | | >_____procedure-name-1__TO_____________________procedure-name-2__|__>< | | |__PROCEED__TO__| | | | |________________________________________________________________________| The ALTER statement modifies the GO TO statement in the paragraph named by procedure-name-1. Subsequent executions of the modified GO TO statement(s) transfer control to procedure-name-2.

procedure-name-1 Must name a Procedure Division paragraph that contains only one sentence: a GO TO statement without the DEPENDING ON phrase.

procedure-name-2 Must name a Procedure Division section or paragraph.

Before the ALTER statement is executed, when control reaches the paragraph specified in procedure-name-1, the GO TO statement transfers control to the paragraph specified in the GO TO statement. After execution of the ALTER statement, however, the next time control reaches the paragraph specified in procedure-name-1, the GO TO statement transfers control to the paragraph specified in procedure-name-2.

The ALTER statement acts as a program switch, allowing, for example, one sequence of execution during initialization and another sequence during the bulk of file processing.

Altered GO TO statements in programs with the INITIAL attribute are returned to their initial states each time the program is entered.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.3.1 Segmentation Considerations

A GO TO statement in a section whose priority is greater than or equal to 50 must not be referred to by an ALTER statement in a section with a different priority. All other uses of the ALTER statement are valid and are performed, even if the GO TO to which the ALTER refers is in a fixed overlayable segment.

Altered GO TO statements in independent segments are returned to their initial states when control is transferred to the independent segment that contains the ALTERED GO TO from another independent segment with a different priority.

This transfer of control can take place because of:

o The effect of previous statements o An explicit transfer of control with a PERFORM or GO TO statement o A sort or merge statement with the INPUT or OUTPUT phrase specified.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.4 CALL Statement

The CALL statement transfers control from one object program to another within the run unit.

The program containing the CALL statement is the calling program; the program identified in the CALL statement is the called subprogram.

| Called programs can contain CALL statements; however, a called program | must not execute a CALL statement that directly or indirectly calls the | calling program.

| To understand the methods of exiting your called program, see "Program | Termination Statements" in topic 3.4.14.

@@ Diagram call-statement-format-i ADAPTED. @@ 1 imperative statement = many imperative statements (see 2.8.6.1) @@ Diagram call-statement-format-i FOLDED according to call-using-phrase. @@ Factored out clause for conciseness. @@ Diagram call-statement-format-i FOLDED according to on-overflow. @@ Factored out clause for conciseness. ___ call-statement-format-i _______________ | | | >>__CALL_____identifier-1_______________> | | |__literal-1_____| | | | | >_______________________________________> | | |__call-using-phrase__| | | | | >______________________________________>< | | |__on-overflow__| |__END-CALL__| | | | |___________________________________________| @@ Diagram call-statement-format-ii ADAPTED. @@ 1 imperative statement = many imperative statements (see 2.8.6.1) @@ Diagram call-statement-format-ii FOLDED according to call-using-phrase. @@ Factored out clause for conciseness. @@ Diagram call-statement-format-ii FOLDED according to on-exception. @@ Factored out clause for conciseness. @@ Diagram call-statement-format-ii FOLDED according to not-on-exception. @@ Factored out clause for conciseness. ___ call-statement-format-ii ___________________ | | | >>__CALL_____identifier-1____________________> | | |__literal-1_____| | | | | >____________________________________________> | | |__call-using-phrase__| | | | | >____________________________________________> | | |__on-exception__| | | | | >___________________________________________>< | | |__not-on-exception__| |__END-CALL__| | | | |________________________________________________| identifier-1, literal-1 | Identifier-1 must be an alphanumeric data item. Literal-1 must be a | nonnumeric literal. Literal-1 or identifier-1 must contain the | program-name specified in the PROGRAM-ID paragraph of the called | program. (See "PROGRAM-ID Paragraph" in topic 2.2.1.)

x Identifier-1 can be an alphabetic or zoned decimal data item

When the called subprogram is to be entered at the beginning of the Procedure Division, literal-1 or the contents of identifier-1 must specify the program-name of the called subprogram.

x When the called subprogram is entered through an ENTRY statement, x literal-1 or the contents of identifier-1 must be the same as the name x specified in the called subprogram's ENTRY statement.

Subtopics:


@@ Diagram call-using-phrase ADDED at the end of this section.
@@ Identified USING phrase of subprogram call.

    ___ call-using-phrase ___________________________________________________________________________
   |                                                                                                 |
   |            <______________________________________________________________________________      |
   |                                            <________________________________________      |     |
   | >>__USING_______________________________________identifier-2________________________|_____|__>< |
   |              |  |____________REFERENCE__|    |__{__ADDRESS__OF__identifier-3__}__|     |        |
   |              |     |__BY__|                  |__{__file-name-1__}________________|     |        |
   |              |                     <_____________________________________________      |        |
   |              |____________CONTENT_______________________________identifier-2_____|_____|        |
   |                 |__BY__|             |  |__{__LENGTH__OF__}__|                |                 |
   |                                      |__{__ADDRESS__OF__identifier-3__}_______|                 |
   |                                      |__{__literal-2__}_______________________|                 |
   |                                                                                                 |
   |_________________________________________________________________________________________________|


@@ Diagram call-statement ADDED at the end of this section.
@@ Different formats of CALL statements.

    ___ call-statement _____________________
   |                                        |
   | >>_____call-statement-format-i______>< |
   |     |__call-statement-format-ii__|     |
   |                                        |
   |________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.4.1 USING Phrase

Included in the CALL statement only if there is a USING phrase in the x Procedure Division header or the ENTRY statement through which the called program is invoked. The number of operands in each USING phrase must be identical. For more information on the USING phrase see "The USING Phrase" in topic 2.8.1.1.

x The number of operands in the USING phrases need not be identical.

The sequence of appearance of the identifiers in the USING phrase of the CALL statement and in the corresponding USING phrase in the called subprogram's Procedure Division header determines the correspondence between the identifiers used by the calling and called programs. This correspondence is positional.

x The sequence of appearance of the identifiers in the USING phrase of the x CALL statement and in the corresponding USING phrase in the called x program's ENTRY statement determines the correspondence between the x identifiers used by the calling and called programs.

x An ADDRESS OF special register can be specified in the USING phrase of the x CALL statement.

The values of the parameters referenced in the USING phrase of the CALL statement are made available to the called subprogram at the time the CALL | statement is executed. The description of the data item in the called | program must describe the same number of character positions as the | description of the corresponding data item in the calling program.

| Both the BY CONTENT and BY REFERENCE phrases apply to parameters that | follow them until another BY CONTENT or BY REFERENCE phrase is | encountered. If neither the BY CONTENT nor BY REFERENCE phrase is | specified prior to the first parameter, BY REFERENCE is assumed.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.4.2 BY REFERENCE Phrase

If the BY REFERENCE phrase is either specified or implied for a parameter, the corresponding data item in the calling program occupies the same storage area as the data item in the called program.

identifier-2 Must be defined as a level-01, level-77, or elementary data item in x the File Section, Working-Storage Section or Linkage Section. It can x be:

x o A data item of any level in the Data Division

x o A data item defined implicitly or explicitly as USAGE IS POINTER

x o A floating-point data item

x o A DBCS data item

x o A file-name for a QSAM file under MVS. See VS COBOL II x Application Programming Guide for MVS and CMS for details on using x file-name with the CALL statement.

x o A file-name for a SAM file under VSE. Note, however, the file x must first be opened or the results will be unpredictable. For x more information about using SAM file-names with the CALL x statement, see VS COBOL II Application Programming Guide for VSE.

x identifier-3 x Must be a level-01 or level-77 data item in the Linkage Section.

x ADDRESS OF special register x For information on the ADDRESS OF special register, see topic 1.1.1.9.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.4.3 BY CONTENT Phrase

 | If the BY CONTENT phrase is specified or implied for a parameter, the 
 | called program cannot change the value of this parameter as referenced in 
 | the CALL statement's USING phrase, though the called program can change 
 | the value of the data item referenced by the corresponding data-name in 
 | the called program's Procedure Division Division header.  Changes to the 
 | parameter in the called program do not effect the corresponding argument 
 | in the calling program. 

identifier-2 Must be defined as a level-01, level-77, or elementary data item in the File Section, Working-Storage Section, or Linkage Section. x It can be:

x o A data item of any level in the Data Division x o A data item defined implicitly or explicitly as USAGE IS POINTER x o A floating-point data item x o A DBCS data item.

x identifier-3 x Must be a level-01 or level-77 data item in the Linkage Section.

x literal-2 x Can be:

x o A nonnumeric literal x o A figurative constant x o A DBCS literal.

x LENGTH OF special register x For information on the LENGTH OF special register, see topic 1.1.1.9.

x ADDRESS OF special register x For information on the ADDRESS OF special register, see topic 1.1.1.9.

x For nonnumeric literals, the called subprogram should describe the x parameter as PIC X(n) USAGE DISPLAY, where n is the number of characters x in in the literal.

x For DBCS literals, the called subprogram should describe the parameter as x PIC G(n) USAGE DISPLAY-1, where n is the length of the literal.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.4.4 ON EXCEPTION Phrase

An exception condition occurs when the called subprogram cannot be made available. At that time, one of the following two actions will occur:

1. If the ON EXCEPTION phrase is specified in the CALL statement, control is transferred to imperative-statement-1. Execution then continues according to the rules for each statement specified in imperative-statement-1. If a procedure branching or conditional statement that causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the CALL statement and the NOT ON EXCEPTION phrase, if specified, is ignored.

2. If the ON EXCEPTION phrase is not specified in the CALL statement, the NOT ON EXCEPTION phrase, if specified, is ignored.


@@ Diagram on-exception ADDED at the end of this section.
@@ Capture conditional phrase for reuse.

    ___ on-exception _______________________________________________
   |                                                                |
   | >>____________EXCEPTION__series-of-imperative-statements-1__>< |
   |     |__ON__|                                                   |
   |                                                                |
   |________________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.4.5 NOT ON EXCEPTION Phrase

If an exception condition does not occur (that is, the called subprogram can be made available), control is transferred to the called program. After control is returned from the called program, the ON EXCEPTION phrase, if specified, is ignored and control is transferred to the end of the CALL statement or, if the NOT ON EXCEPTION phrase is specified, to imperative-statement-2. If control is transferred to imperative-statement-2, execution continues according to the rules for each statement specified in imperative-statement-2. If a procedure branching or conditional statement that causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the CALL statement.


@@ Diagram not-on-exception ADDED at the end of this section.
@@ Capture conditional phrase for reuse.

    ___ not-on-exception ________________________________________________
   |                                                                     |
   | >>__NOT____________EXCEPTION__series-of-imperative-statements-2__>< |
   |          |__ON__|                                                   |
   |                                                                     |
   |_____________________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.4.6 ON OVERFLOW Phrase

The ON OVERFLOW phrase has the same effect as the ON EXCEPTION phrase.

x Note: This element may exhibit different behavior when the CMPR2 compiler x option is in effect. For more information, see VS COBOL II Migration x Guide for MVS and CMS or VS COBOL II Migration Guide for VSE.


@@ Diagram on-overflow ADDED at the end of this section.
@@ Capture conditional phrase for reuse.

    ___ on-overflow _______________________________________________
   |                                                               |
   | >>____________OVERFLOW__series-of-imperative-statements-1__>< |
   |     |__ON__|                                                  |
   |                                                               |
   |_______________________________________________________________|


@@ Diagram not-on-overflow ADDED at the end of this section.
@@ Capture conditional phrase for reuse.

    ___ not-on-overflow ________________________________________________
   |                                                                    |
   | >>__NOT____________OVERFLOW__series-of-imperative-statements-2__>< |
   |          |__ON__|                                                  |
   |                                                                    |
   |____________________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.4.7 END-CALL Phrase

| This explicit scope terminator delimits the scope of the CALL statement. | END-CALL converts a conditional CALL statement to an imperative statement | so that it can be nested in another conditional statement. END-CALL can also be used with an imperative CALL statement.

For more information, see "Delimited Scope Statements" in topic 2.8.6.3.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.4.8 Resolving CALL to Program-Name Found in Multiple Programs

More than one program in the run unit may have the same program-name, and the reference in a CALL statement to such a program-name is resolved by using the scope of names conventions for program-names (see "Scope of Program-Names" in topic 2.2.1.1).

When only two programs in the run unit have the same name as that specified in a CALL statement:

1. One of those two programs must also be contained directly or indirectly either within the separately compiled program that includes that CALL statement or within the separately compiled program that itself directly or indirectly contains the program that includes that CALL statement, and

2. The other of those two programs must be a different separately compiled program.

The mechanism used is as follows:

1. If a program has the same name as that specified in the CALL statement is directly contained within the program that includes that CALL statement, that program is called.

2. If a program has the same name as that specified in the CALL statement and possesses the COMMON attribute and is directly contained within another program that directly or indirectly contains the program that includes the CALL statement, that common program is called unless the calling program is contained within that common program.

3. Otherwise, the call is resolved to a separately-compiled program.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.4.9 Mode of a CALL Statement

For calls to separately-compiled programs, the mode of the CALL statement (static or dynamic) is specified through the compiler option DYNAM.

o Dynamic call

CALL literal with DYNAM CALL identifier (always dynamic)

o Static call

CALL literal with NODYNAM

See your installation's system programmer for the compiler option defaults.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.4.10 Static CALL Statement

In the static CALL statement, the COBOL program and all called programs are part of the same load module. When control is transferred to the called program, it is already resident in storage, and a branch to the called program takes place. Subsequent executions of the CALL statement make the called program available in its last-used state, unless the called program has the INITIAL attribute. If the called program possesses the INITIAL attribute, it and each program directly or indirectly contained within it is placed into its initial state every time the called program is called within a run unit.

x If alternate entry points are specified, a static CALL statement can use x any alternate entry point to enter the called subprogram.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.4.11 Dynamic CALL Statement

In this form of the CALL statement, the called COBOL subprogram is not link-edited with the main program, but is instead link-edited into a separate load module, and, at run time, is loaded only if and when it is required (that is, when called).

Each subprogram invoked with a dynamic CALL statement may be part of a different load module that is a member of the system link library or of a user-supplied private library. The execution of the dynamic CALL statement to a subprogram that is not resident in storage results in the loading of that subprogram from secondary storage into the region/partition containing the main program and a branch to the subprogram.

Thus, the first dynamic CALL to a subprogram obtains a fresh copy of the subprogram. Subsequent calls to the same subprogram (by either the original caller or by any other subprogram within the same region/partition) result in a branch to the same copy of the subprogram in its last-used state, provided the subprogram does not possess the INITIAL attribute. Thus, the reinitialization of either of the following items is your responsibility:

o GO TO statements that have been altered o Data items.

When a CANCEL statement is issued for a subprogram, the storage occupied by the subprogram is freed, and a subsequent CALL to the subprogram will function as though it were the first. A CANCEL statement referring to a called subprogram can be issued by a program other than the original caller.

x If the called subprogram has more than one entry point, differing entry x points must not be specified in the dynamic CALL statement until an x intervening CANCEL statement has been executed.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.4.12 CALL Statement Examples

A static CALL statement is illustrated in the following example:

| IDENTIFICATION DIVISION. | PROGRAM-ID. MAIN1.

| ENVIRONMENT DIVISION.

DATA DIVISION. WORKING-STORAGE SECTION. 01 RECORD-2 PIC X. 01 RECORD-1. 05 PAY PIC S9(5)V99. 05 HOURLY-RATE PIC S9V99. 05 HOURS PIC S99V9.

PROCEDURE DIVISION. CALL "SUBPROG" USING RECORD-1. CALL "PAYMASTR" USING RECORD-1 RECORD-2. STOP RUN.

A dynamic CALL statement is illustrated in the following example:

| IDENTIFICATION DIVISION. | PROGRAM-ID. MAIN2.

| ENVIRONMENT DIVISION.

DATA DIVISION. WORKING-STORAGE SECTION. 77 PGM-NAME PIC X(8). 01 RECORD-2 PIC X. 01 RECORD-1. 05 PAY PIC S9(5)V99. 05 HOURLY-RATE PIC S9V99. 05 HOURS PIC S99V9.

PROCEDURE DIVISION. MOVE "SUBPROG" TO PGM-NAME. CALL PGM-NAME USING RECORD-1. CANCEL PGM-NAME. MOVE "PAYMASTR" TO PGM-NAME. CALL PGM-NAME USING RECORD-1 RECORD-2. STOP RUN.

The following called subprogram is called by each of the two preceding calling programs:

| IDENTIFICATION DIVISION. | PROGRAM-ID. SUBPROG.

| ENVIRONMENT DIVISION.

DATA DIVISION. LINKAGE SECTION. 01 PAYREC. 10 PAY PIC S9(5)V99. 10 HOURLY-RATE PIC S9V99. 10 HOURS PIC S99V9. 77 PAY-CODE PIC 9.

PROCEDURE DIVISION USING PAYREC. .....

EXIT PROGRAM.

ENTRY "PAYMASTR" USING PAYREC PAY-CODE. .....

GOBACK.

Processing begins in the calling program. When the first CALL statement is executed, control is transferred to the first statement of the Procedure Division in SUBPROG, which is the called program.

In each of the CALL statements, the operand of the first USING option is identified as RECORD-1.

When SUBPROG receives control, the values within RECORD-1 are made available to SUBPROG; however, in SUBPROG they are referred to as PAYREC.

The PICTURE character-strings within PAYREC and PAY-CODE contain the same number of characters as RECORD-1 and RECORD-2, although the descriptions are not identical.

When processing within SUBPROG reaches the EXIT PROGRAM statement, control is returned to the calling program. Processing continues in that program until the second CALL statement is issued.

x Note: In a statically linked program, the CANCEL statement would not be x valid.

x In the example of a dynamically-linked program, however, because the x second CALL statement refers to another entry point within SUBPROG, a x CANCEL statement is issued before the second CALL statement.

x With the second CALL statement in the calling program, control is again x transferred to SUBPROG, but this time processing begins at the statement x following the ENTRY statement in SUBPROG. The values within RECORD-1 are | again made available to SUPPROG. In addition, the value in RECORD-2 is x now made available to SUPPROG through the corresponding USING operand x PAY-CODE.

x When processing reaches the GOBACK statement, control is returned to the x calling program at the statement immediately following the second CALL x statement.

x When control is transferred the second time from the statically linked x program, SUBPROG is made available in its last-used state (that is, if any x values in SUBPROG storage were changed during the first execution, those x changed values are still in effect). When control is transferred from the x dynamically linked program, however, SUBPROG is made available in its x initial state.

In any given execution of these two programs, if the values within RECORD-1 are changed between the time of the first CALL and the second, the values passed at the time of the second CALL statement will be the changed, not the original, values. If the user wants to use the original values, they must be saved.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.4.13 Subprogram Linkage

Called subprograms that are invoked at object time by the dynamic CALL statement must be members of the system link library or of a user-supplied private library.

The static call statement results in the called subprogram being link-edited with the main program into one load module. Thus, the program-name and the alternate entry point can be specified in any order in the main program's CALL statements.

Static and dynamic CALL statements can both be specified in the same program. The CALL literal-1 statement results, in this case, in the subprogram invoked being link-edited with the main program into one load module. The CALL identifier-1 statement results in the dynamic invocation of a separate load module.

When a dynamic CALL statement and a static CALL statement to the same subprogram are issued within one program, a second copy of the subprogram is loaded into storage. Because this doesn't guarantee that the subprogram will be left in its last-used state, results may be unpredictable.

Note: Under MVS, linking two load modules together results logically in a single program with a primary entry point and an alternate entry point, each with its own name. Each name by which a subprogram is to be dynamically invoked must be known to the system. Each such name must be specified in linkage editor control statements as either a NAME or an ALIAS of the load module containing the subprogram.

This does not apply to link-editing under VSE, however. For information about link-editing under VSE systems, see VS COBOL II Application Programming Guide for VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.4.14 Program Termination Statements

A main program is the highest-level COBOL program invoked in a run unit. A subprogram is a COBOL program invoked by another COBOL program.

The table below shows the action taken for each program termination statement in both a main program and a subprogram.

________________________________________________________________________ | Table 31. Effects of various termination statements | |________________________________________________________________________| | Termination | | | | Statement | Main Program | Subprogram | |_______________|____________________________|___________________________| | EXIT PROGRAM | No action taken. | Return to calling | | | | program. | |_______________|____________________________|___________________________| | STOP RUN | Return to calling | Return directly to the | | | program.(1) (May be the | program that called the | | | system and cause job to | main program.(1) (May be | | | end.) | the system and cause job | | | | to end.) | |_______________|____________________________|___________________________| x | GOBACK | Return to calling | Return to calling | x | | program.(1) (May be the | program. | x | | system and cause job to | | x | | end.) | | |_______________|____________________________|___________________________|

(1) If the main program is called by a program written in another language that does not follow COBOL linkage conventions, return will be to this calling program.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.5 CANCEL Statement

The CANCEL statement ensures that the next time the referenced subprogram is called it will be entered in its initial state.

___ cancel-statement ____________________ | | | <_____________________ | | >>__CANCEL_______identifier-1_____|__>< | | |__literal-1_____| | | | |_________________________________________| identifier-1, literal-1 | Identifier-1 must be an alphanumeric data item. Literal-1 must be a | nonnumeric literal. Literal-1 or identifier-1 must contain the | program-name specified in the PROGRAM-ID paragraph of the program | being canceled. (See "PROGRAM-ID Paragraph" in topic 2.2.1.)

x Identifier-1 can be an alphabetic or zoned decimal data item.

Each literal or contents of the identifier specified in the CANCEL statement must be the same as the literal or contents of the identifier specified in an associated CALL statement.

After a CANCEL statement for a called subprogram has been executed, that subprogram no longer has a logical connection to the program. The contents of data items in external data records described by the subprogram are not changed when that subprogram is canceled. If a CALL statement is executed later by any program in the run unit naming the same subprogram, that subprogram will be entered in its initial state.

When a CANCEL statement is executed, all programs contained within the program referenced by the CANCEL statement are also canceled. The result is the same as if a valid CANCEL were executed for each contained program in the reverse order in which the programs appear in the separately compiled program.

A CANCEL statement closes all open files that are associated with an internal file connector in the program named in the explicit CANCEL statement. Any USE procedures associated with any of these files are not executed.

You can cancel a called subprogram by referencing it as the operand of a CANCEL statement, by terminating the run unit of which the subprogram is a x member, or by executing an EXIT PROGRAM statement or GOBACK statement in the called subprogram if that subprogram possesses the INITIAL attribute.

No action is taken when a CANCEL statement is executed, naming a program that either:

1. Has not been dynamically called in this run unit by another VS COBOL II or OS/VS COBOL program.

2. Has been called and subsequently canceled.

Called subprograms can contain CANCEL statements. However, a called program must not execute a CANCEL statement that directly or indirectly cancels the calling program itself, or any other program higher than itself in the calling hierarchy. In such a case, the run unit is terminated.

A program named in a CANCEL statement must not refer to any program that x has been called and has not yet executed an EXIT PROGRAM or a GOBACK statement.

A program can, however, cancel a program that it did not call, providing that, in the calling hierarchy, it is higher than or equal to the program it is canceling. For example:

A calls B and B calls C (When A receives control, it can cancel C.) A calls B and A calls C (When C receives control, it can cancel B.)


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.6 CLOSE Statement

The CLOSE statement terminates the processing of volumes and files, with optional rewind and/or lock or removal, where applicable.

___ close-statement-format-i ___________________________________________________ | | | >>__CLOSE____________________________________________________________________> | | | | <____________________________________________________________________ | | >_____file-name-1________________________________________________________|__>< | | |_____REEL_________________________________________| | | | |__UNIT__| |_____________REMOVAL____________| | | | | | |__FOR__| | | | | | |__{______________NO__REWIND__}__| | | | | |__WITH__| | | | |_________________NO__REWIND_______________________| | | |__WITH__| |__LOCK________| | | | |________________________________________________________________________________| ___ close-statement-format-ii ___________________________ | | | <______________________________________ | | >>__CLOSE____file-name-1__________________________|__>< | | |______________LOCK__| | | |__WITH__| | | | |_________________________________________________________| file-name-1 Designates the file upon which the CLOSE statement is to operate. If more than one file-name is specified, the files need not have the same organization or access. File-name-1 must not be a sort or merge file.

A CLOSE statement can be executed only for a file in an open mode. After successful execution of a CLOSE statement without the REEL/UNIT phrase:

o The record area associated with the file-name is no longer available. | Unsuccessful execution of a CLOSE statement leaves availability of the | record area undefined.

o An OPEN statement for the file must be executed before any other input/output statement.

If the FILE STATUS clause is specified in the FILE-CONTROL entry, the associated status key is updated when the CLOSE statement is executed.

If the file is in an open status and the execution of a CLOSE statement is unsuccessful, the EXCEPTION/ERROR procedure (if specified) for this file is executed.

Subtopics:


@@ Diagram close-statement ADDED at the end of this section.
@@ Different formats of CLOSE statements.

    ___ close-statement _____________________
   |                                         |
   | >>_____close-statement-format-i______>< |
   |     |__close-statement-format-ii__|     |
   |                                         |
   |_________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.6.1 QSAM or SAM Files

| The REEL/UNIT phrases can be specified only for QSAM or SAM multivolume or | single volume files. The terms REEL and UNIT are interchangeable.

The WITH NO REWIND and FOR REMOVAL phrases apply only to tape files. If they are specified for storage devices to which they do not apply, they are ignored.

If the SELECT OPTIONAL clause is specified in the FILE-CONTROL entry for this file, and the file is not present at run time, standard end-of-file processing is not performed. The file position indicator and current volume pointer are unchanged.

QSAM and SAM files are divided into the following types:

o Non-Reel/Unit: A file whose input or output medium is such that rewinding, reels, and units have no meaning.

o Sequential Single Volume: A sequential file contained entirely on one volume. More than one file may be contained on this volume.

o Sequential Multivolume: A sequential file contained on more than one volume.

Table 32 summarizes the permissible combinations of CLOSE statement phrases for each file type. The meaning of each key letter is shown in Table 34 in topic 3.6.2.

____________________________________________________________________ | | Table 32. QSAM and SAM File Types and CLOSE Statement Phrases | |____________________________________________________________________| | | | Sequential | Sequential | | | Non-Reel/ | Single | Multi- | | CLOSE Statement Format | Unit | Volume | Volume | |_________________________|____________|_______________|_____________| | CLOSE | C | C, G | A, C, G | |_________________________|____________|_______________|_____________| | CLOSE REEL/UNIT | F | F, G | F, G | |_________________________|____________|_______________|_____________| | | F | B, F | B, F | x | CLOSE REEL/UNIT WITH | | | | x | NO REWIND | | | | | | | | | |_________________________|____________|_______________|_____________| | CLOSE REEL/UNIT FOR | D | D | D | | REMOVAL | | | | |_________________________|____________|_______________|_____________| | CLOSE WITH NO REWIND | C, H | B, C | A, B, C | |_________________________|____________|_______________|_____________| | CLOSE WITH LOCK | C, E | C, E, G | A, C, E, G | |_________________________|____________|_______________|_____________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.6.2 VSAM Files

Whether a VSAM file is contained on a single volume or on multiple volumes is of no concern. Thus the concept of volumes has no meaning for these types of files. If an input VSAM file is described as SELECT OPTIONAL in the FILE-CONTROL entry and the file is not present during this execution of the object program, end-of-file processing is not performed. Table 33 summarizes the permissible combinations of CLOSE statement phrases for VSAM files. The meaning of each key letter is shown in Table 34.

_________________________________________________________________ | Table 33. VSAM File Types and CLOSE Statement Phrases | |_________________________________________________________________| | CLOSE Statement Format | Indexed, Relative | |________________________________|________________________________| | CLOSE | C | |________________________________|________________________________| | CLOSE WITH LOCK | C,E | |________________________________|________________________________|

________________________________________________________________________ | | Table 34. Meanings of Key Letters for the Two Preceding Tables | |________________________________________________________________________| | Key | Actions Taken | |_____|__________________________________________________________________| | A | Previous Volumes Unaffected | | | | | | Input and Input-Output Files--Standard volume-switch processing | | | is performed for all previous volumes (except those controlled | | | by a previous CLOSE REEL/UNIT statement). Any subsequent | | | volumes are not processed. | | | | | | Output Files--Standard volume-switch processing is performed for | | | all previous volumes (except those controlled by a previous | | | CLOSE REEL/UNIT statement). | |_____|__________________________________________________________________| | B | No Rewinding of Current Reel--the current volume is left in its | | | current position. | |_____|__________________________________________________________________| | C | Close File | | | | | | Input and Input-Output Files--If the file is at its end, and | | | label records are specified, the standard ending label procedure | | | is performed. Standard system closing procedures are then | | | performed. | | | | | | If the file is at its end, and label records are not specified, | | | label processing does not take place, but standard system | | | closing procedures are performed. | | | | | | If the file is not at its end, standard system closing | | | procedures are performed, but there is no ending label | | | processing. | | | | | | Output Files--If label records are specified, standard ending | | | label procedures are performed. Standard system closing | | | procedures are then performed. | | | | | | If label records are not specified, ending label procedures are | | | not performed, but standard system closing procedures are | | | performed. | |_____|__________________________________________________________________| | | D | Volume Removal--Under MVS and CMS, CLOSE REEL/UNIT FOR REMOVAL | | | | is treated as documentation. Under VSE, CLOSE REEL/UNIT FOR | | | | REMOVAL determines the disposition of the tape when the file is | | | | closed. | |_____|__________________________________________________________________| | E | File Lock--The compiler ensures that this file cannot be opened | | | again during this execution of the object program. | |_____|__________________________________________________________________| | F | Close Volume | | | | | | Input and Input-Output Files--If the current reel/unit is the | | | last and/or only reel/unit for the file or if the reel is on a | | | non-reel/unit medium, no volume switching is performed. If | | | another reel/unit exists for the file, the following operations | | | are performed: a volume switch, beginning volume label | | | procedure, and the first record on the new volume is made | | | available for reading. If no data records exist for the current | | | volume, another volume switch occurs. | | | | | | Output (Reel/Unit Media) Files--The following operations are | | | performed: the ending volume label procedure, a volume switch, | | | and the beginning volume label procedure. The next executed | | | WRITE statement places the next logical record on the next | | | direct access volume available. A close statement with the REEL | | | phrase does not close the output file; only an end-of-volume | | | condition occurs. | | | | | | Output (Non-Reel/Unit Media) Files--Execution of the CLOSE | | | statement is considered successful. The file remains in the open | | | mode and no action takes place except that the value of the I-O | | | status associated with the file is updated. | |_____|__________________________________________________________________| | G | Rewind--The current volume is positioned at its physical | | | beginning. | |_____|__________________________________________________________________| | H | Optional Phrases Ignored--The CLOSE statement is executed as if | | | none of the optional phrases were present. | |_____|__________________________________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.7 COMPUTE Statement

The COMPUTE statement assigns the value of an arithmetic expression to one or more data items.

With the COMPUTE statement, arithmetic operations can be combined without the restrictions on receiving data items imposed by the rules for the ADD, SUBTRACT, MULTIPLY, and DIVIDE statements.

When arithmetic operations are combined, the COMPUTE statement may be more efficient than the separate arithmetic statements written in a series.

@@ Diagram compute-statement ADAPTED. @@ 1 imperative statement = many imperative statements (see 2.8.6.1) @@ Diagram compute-statement FOLDED according to on-size-error. @@ Factored out clause for conciseness. @@ Diagram compute-statement FOLDED according to not-on-size-error. @@ Factored out clause for conciseness. ___ compute-statement ________________________________________________ | | | <______________________________ | | >>__COMPUTE____identifier-1_________________|_____=________________> | | |__ROUNDED__| |__{__EQUAL__}__| | | | | >___arithmetic-expression__________________________________________> | | | | >__________________________________________________________________> | | |__on-size-error__| | | | | >__________________________________________________________________> | | |__not-on-size-error__| | | | | >_________________________________________________________________>< | | |__END-COMPUTE__| | | | |______________________________________________________________________| identifier-1 Must name elementary numeric item(s) or elementary numeric-edited item(s).

x Can name an elementary floating-point data item.

x The word EQUAL can be used in place of =.

arithmetic-expression Can be any arithmetic expression, as defined in "Arithmetic Expressions" in topic 2.8.4.

When the COMPUTE statement is executed, the value of the arithmetic expression is calculated, and this value is stored as the new value of each data item referenced by identifier-1.

An arithmetic expression consisting of a single identifier or literal allows the user to set the value of the data item(s) referenced by identifier-1 equal to the value of that identifier or literal.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.7.1 ROUNDED Phrase

For a discussion of the ROUNDED phrase, see "ROUNDED Phrase" in topic 2.8.7.3.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.7.2 SIZE ERROR Phrases

For a discussion of the SIZE ERROR phrases, see "SIZE ERROR Phrases" in topic 2.8.7.4.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.7.3 END-COMPUTE Phrase

| This explicit scope terminator delimits the scope of the COMPUTE | statement. END-COMPUTE converts a conditional COMPUTE statement to an | imperative statement so that it can be nested in another conditional | statement. END-COMPUTE can also be used with an imperative COMPUTE statement.

For more information, see "Delimited Scope Statements" in topic 2.8.6.3.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.8 CONTINUE Statement

The CONTINUE statement allows you to specify a no operation statement. CONTINUE indicates that no executable instruction is present.

___ continue-statement ___ | | | >>__CONTINUE__________>< | | | |__________________________| The CONTINUE statement can be used anywhere a conditional statement or an imperative statement can be used. It has no effect on the execution of the program.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.9 DELETE Statement

The DELETE statement removes a record from an indexed or relative file. For indexed files, the key can then be reused for record addition. For relative files, the space is then available for a new record with the same RELATIVE KEY value.

When the DELETE statement is executed, the associated file must be open in I-O mode.

| Note: The Procedure Division DELETE statement is different from the | extended source library DELETE statement described on topic 4.5.

@@ Diagram delete-statement ADAPTED. @@ 1 imperative statement = many imperative statements (see 2.8.6.1) @@ Diagram delete-statement FOLDED according to not-invalid-key. @@ Factored out clause for conciseness. @@ Diagram delete-statement FOLDED according to invalid-key. @@ Factored out clause for conciseness. ___ delete-statement ______________________ | | | >>__DELETE__file-name-1_________________> | | |__RECORD__| | | | | >_______________________________________> | | |__invalid-key__| | | | | >_______________________________________> | | |__not-invalid-key__| | | | | >______________________________________>< | | |__END-DELETE__| | | | |___________________________________________|

file-name-1 Must be defined in an FD entry in the Data Division and must be the name of an indexed or relative file.

After successful execution of a DELETE statement, the record is removed from the file and can no longer be accessed. Execution of the DELETE statement does not affect the contents of the record area associated with file-name-1 or the content of the data item referenced by the data-name specified in the DEPENDING ON phrase of the RECORD clause associated with file-name-1.

If the FILE STATUS clause is specified in the File-Control entry, the associated status key is updated when the DELETE statement is executed.

The file position indicator is not affected by execution of the DELETE statement.

| Sequential Access Mode: For a file in sequential access mode, the last | input/output statement must have been a successfully executed READ | statement. When the DELETE statement is executed, the system removes the record retrieved by that READ statement.

For a file in sequential access mode, the INVALID KEY and NOT INVALID KEY phrases must not be specified. However, an EXCEPTION/ERROR procedure can be specified.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.9.1 Random or Dynamic Access Mode

In random or dynamic access mode, DELETE statement execution results depend on the file organization: indexed or relative.

When the DELETE statement is executed, the system removes the record identified by the contents of the prime RECORD KEY data item for VSAM indexed files, or the RELATIVE KEY data item for VSAM relative files. If the file does not contain such a record, an INVALID KEY condition exists. | (See "Invalid Key Condition" in topic 2.8.9.1.2.)

The INVALID KEY phrase must be specified for a DELETE statement that references a file in random or dynamic access and for which an EXCEPTION/ERROR procedure is not specified.

x The INVALID KEY phrase does not need to be specified for a DELETE x statement that references a file in random or dynamic access and for which x an EXCEPTION/ERROR procedure is not specified.

Transfer of control after the successful execution of a DELETE statement, with the NOT INVALID KEY phrase specified, is to the imperative statement associated with the phrase.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.9.2 END-DELETE Phrase

| This explicit scope terminator delimits the scope of the DELETE statement. | END-DELETE converts a conditional DELETE statement to an imperative | statement so that it can be nested in another conditional statement. END-DELETE can also be used with an imperative DELETE statement.

For more information, see "Delimited Scope Statements" in topic 2.8.6.3.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.10 DISPLAY Statement

The DISPLAY statement transfers the contents of each operand to the output device. The contents are displayed on the output device in the order, left to right, in which the operands are listed.

___ display-statement ______________________________ | | | <_____________________ | | >>__DISPLAY_______identifier-1_____|_____________> | | |__literal-1_____| | | | | >________________________________________________> | | |__UPON_____mnemonic-name-1______________| | | |__{__environment-name-1__}__| | | | | >_______________________________________________>< | | |______________NO__ADVANCING__| | | |__WITH__| | | | |____________________________________________________| identifier-1 If it is numeric and is not described as an external decimal, then identifier-1 is converted automatically to external format, as follows:

o Binary or internal decimal items are converted to external decimal. Negative signed values cause a low-order sign overpunch.

x o Internal floating-point numbers are converted to external x floating-point numbers for display, such that:

x - A COMP-1 item will display as if it had an external x floating-point PICTURE clause of -.9(8)E-99 x - A COMP-2 item will display as if it had an external x floating-point PICTURE clause of -.9(17)E-99

No other identifiers require conversion.

x Data items defined with USAGE IS POINTER are converted to an external x decimal number that would have a PICTURE clause of PIC 9(10).

x Index names or data items defined with USAGE IS INDEX cannot be x specified in a DISPLAY statement.

x DBCS data items (explicitly defined as USAGE DISPLAY-1) are x transferred to the sending field of the output device. For proper x results, the output device must have the capability to recognize DBCS x shift-out and shift-in control characters.

x Both DBCS and non-DBCS operands can be specified in a single DISPLAY x verb.

literal-1 Can be any figurative constant. When a figurative constant is specified, only a single occurrence of that figurative constant is displayed.

Each numeric literal must be an unsigned integer.

x Signed numeric literals and non-integer numeric literals are allowed.

x Floating-point literals are allowed.

x DBCS literals are allowed.

x The ALL figurative constant can be used with DBCS literals in a x DISPLAY verb.

UPON x Mnemonic-name-1 or environment-name-1 must be associated in the SPECIAL-NAMES paragraph with an output device. A maximum logical record size is assumed for each device, as follows:

The system logical output device = 120 characters The system punch device = 72 characters The console typewriter = 100 characters.

Note: On the system punch device, characters 73 through 80 are used for PROGRAM-ID name.

When the UPON phrase is omitted, the system's logical output device is x assumed. The list of valid environment-names in a DISPLAY statement x is contained in Table 6 in topic 2.3.3.

WITH NO ADVANCING When specified, the positioning of the output device will not be changed in any way following the display of the last operand. If the output device is capable of positioning to a specific character position, it will remain positioned at the character position immediately following the last character of the last operand displayed. If the output device is not capable of positioning to a specific character position, only the vertical position, if applicable, is affected. This may cause overprinting.

If the WITH NO ADVANCING phrase is not specified, then after the last operand has been transferred to the output device, the positioning of the output device will be reset to the leftmost position of the next line of the device.

The DISPLAY statement transfers the data in the sending field to the output device. The size of the sending field is the total character count of all operands listed. If the output device is capable of receiving data of the same size as the data item being transferred, then the data item is transferred. If the output device is not capable of receiving data of the same size as the data item being transferred, then one of the following applies:

o If the total character count is less than the device maximum character count, the remaining rightmost characters are padded with spaces.

o If the total character count exceeds the maximum, as many records are written as are needed to display all operands. Any operand being printed or displayed when the end of a record is reached is continued in the next record.

x If a DBCS operand must be split across multiple records, it will be split x only on a double-byte boundary. The shift code compensation is required x under this case. That is, when a DBCS operand is split across multiple x records, the shift-in character needs to be inserted at the end of the x current record, and the shift-out character needs to be inserted at the x beginning of the next record. A space is padded after the shift-in x character, if necessary. These additional inserted shift codes and spaces x are included in the count while the compiler is calculating the number of x records required.

After the last operand has been transferred to the output device, the device is reset to the leftmost position of the next line of the device.

x If a DBCS data item or literal is specified in a DISPLAY verb, the size of x the sending field is the total character count of all operands listed, x with each DBCS character counted twice, plus the necessary shift codes for x DBCS.

Notes:

1. The DISPLAY statement causes the printer to space before printing.

2. The DISPLAY statement can be used to identify data records that have caused one of the following conditions:

a. A size error b. An invalid key c. An overflow condition d. A status key returned as a value other than zero

| Such records can be displayed, with an identifying message, on some | other device than the one used for valid output. Thus, all records | that need special handling can be identified.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.11 DIVIDE Statement

The DIVIDE statement divides one numeric data item into or by other(s) and sets the values of data items equal to the quotient and remainder.

@@ Diagram divide-statement-format-i ADAPTED. @@ 1 imperative statement = many imperative statements (see 2.8.6.1) @@ Diagram divide-statement-format-i FOLDED according to on-size-error. @@ Factored out clause for conciseness. @@ Diagram divide-statement-format-i FOLDED according to not-on-size-error. @@ Factored out clause for conciseness. ___ divide-statement-format-i ______________________________________________ | | | <______________________________ | | >>__DIVIDE_____identifier-1_____INTO____identifier-2_________________|___> | | |__literal-1_____| |__ROUNDED__| | | | | >________________________________________________________________________> | | |__on-size-error__| | | | | >________________________________________________________________________> | | |__not-on-size-error__| | | | | >_______________________________________________________________________>< | | |__END-DIVIDE__| | | | |____________________________________________________________________________| | In Format 1, the value of identifier-1 or literal-1 is divided into the | value of identifier-2, and the quotient is then stored in identifier-2. | For each successive occurrence of identifier-2, the division takes place | in the left-to-right order in which identifier-2 is specified.

@@ Diagram divide-statement-format-ii ADAPTED. @@ 1 imperative statement = many imperative statements (see 2.8.6.1) @@ Diagram divide-statement-format-ii FOLDED according to on-size-error. @@ Factored out clause for conciseness. @@ Diagram divide-statement-format-ii FOLDED according to not-on-size-error. @@ Factored out clause for conciseness. ___ divide-statement-format-ii _______________________________ | | | >>__DIVIDE_____identifier-1_____INTO_____identifier-2______> | | |__literal-1_____| |__literal-2_____| | | | | <______________________________ | | >___GIVING____identifier-3_________________|_______________> | | |__ROUNDED__| | | | | >__________________________________________________________> | | |__on-size-error__| | | | | >__________________________________________________________> | | |__not-on-size-error__| | | | | >_________________________________________________________>< | | |__END-DIVIDE__| | | | |______________________________________________________________| | In Format 2, the value of identifier-1 or literal-1 is divided into the | value of identifier-2 or literal-2. The value of the quotient is stored | in each data item referenced by identifier-3.

@@ Diagram divide-statement-format-iii ADAPTED. @@ 1 imperative statement = many imperative statements (see 2.8.6.1) @@ Diagram divide-statement-format-iii FOLDED according to on-size-error. @@ Factored out clause for conciseness. @@ Diagram divide-statement-format-iii FOLDED according to not-on-size-error. @@ Factored out clause for conciseness. ___ divide-statement-format-iii ____________________________ | | | >>__DIVIDE_____identifier-1_____BY_____identifier-2______> | | |__literal-1_____| |__literal-2_____| | | | | <______________________________ | | >___GIVING____identifier-3_________________|_____________> | | |__ROUNDED__| | | | | >________________________________________________________> | | |__on-size-error__| | | | | >________________________________________________________> | | |__not-on-size-error__| | | | | >_______________________________________________________>< | | |__END-DIVIDE__| | | | |____________________________________________________________| | In Format 3, the value of identifier-1 or literal-1 is divided by the | value of identifier-2 or literal-2. The value of the quotient is stored | in each data item referenced by identifier-3.

@@ Diagram divide-statement-format-iv ADAPTED. @@ 1 imperative statement = many imperative statements (see 2.8.6.1) @@ Diagram divide-statement-format-iv FOLDED according to on-size-error. @@ Factored out clause for conciseness. @@ Diagram divide-statement-format-iv FOLDED according to not-on-size-error. @@ Factored out clause for conciseness. ___ divide-statement-format-iv _______________________________________ | | | >>__DIVIDE_____identifier-1_____INTO_____identifier-2______________> | | |__literal-1_____| |__literal-2_____| | | | | >___GIVING__identifier-3_________________REMAINDER__identifier-4___> | | |__ROUNDED__| | | | | >__________________________________________________________________> | | |__on-size-error__| | | | | >__________________________________________________________________> | | |__not-on-size-error__| | | | | >_________________________________________________________________>< | | |__END-DIVIDE__| | | | |______________________________________________________________________| | In Format 4, the value of identifier-1 or literal-1 is divided into | identifier-2 or literal-2. The value of the quotient is stored in | identifier-3, and the value of the remainder is stored in identifier-4.

@@ Diagram divide-statement-format-v ADAPTED. @@ 1 imperative statement = many imperative statements (see 2.8.6.1) @@ Diagram divide-statement-format-v FOLDED according to on-size-error. @@ Factored out clause for conciseness. @@ Diagram divide-statement-format-v FOLDED according to not-on-size-error. @@ Factored out clause for conciseness. ___ divide-statement-format-v ________________________________________ | | | >>__DIVIDE_____identifier-1_____BY_____identifier-2________________> | | |__literal-1_____| |__literal-2_____| | | | | >___GIVING__identifier-3_________________REMAINDER__identifier-4___> | | |__ROUNDED__| | | | | >__________________________________________________________________> | | |__on-size-error__| | | | | >__________________________________________________________________> | | |__not-on-size-error__| | | | | >_________________________________________________________________>< | | |__END-DIVIDE__| | | | |______________________________________________________________________| | In Format 5, the value of identifier-1 or literal-1 is divided by | identifier-2 or literal-2. The value of the quotient is stored in | identifier-3, and the value of the remainder is stored in identifier-4.

For all Formats:

identifier-1, identifier-2 Must name an elementary numeric item.

identifier-3, identifier-4 Must name an elementary numeric or numeric-edited item.

literal-1, literal-2 Must be a numeric literal.

x In Format 1, 2 and 3, floating-point data items and literals can be used x anywhere that a numeric data item or literal can be specified.

x In Format 4 and 5, floating-point data items or literals cannot be used.

Subtopics:


@@ Diagram divide-statement ADDED at the end of this section.
@@ Different formats of DIVIDE statements.

    ___ divide-statement ______________________
   |                                           |
   | >>_____divide-statement-format-i_______>< |
   |     |__divide-statement-format-ii___|     |
   |     |__divide-statement-format-iii__|     |
   |     |__divide-statement-format-iv___|     |
   |     |__divide-statement-format-v____|     |
   |                                           |
   |___________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.11.1 ROUNDED Phrase

For Format 1, 2, and 3, see "ROUNDED Phrase" in topic 2.8.7.3.

For Format 4 and 5, the quotient used to calculate the remainder is in an intermediate field. The value of the intermediate field is truncated rather than rounded.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.11.2 REMAINDER Phrase

The result of subtracting the product of the quotient and the divisor from the dividend is stored in identifier-4. If identifier-3, the quotient, is a numeric-edited item, the quotient used to calculate the remainder is an intermediate field that contains the unedited quotient.

x The REMAINDER phrase is invalid if the receiver or any of the operands is x a floating-point item.

Any subscripts for identifier-4 in the REMAINDER phrase are evaluated after the result of the divide operation is stored in identifier-3 of the GIVING phrase.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.11.3 SIZE ERROR Phrases

For Format 1, 2, and 3, see "SIZE ERROR Phrases" in topic 2.8.7.4.

x Note: This element may exhibit different behavior when the CMPR2 compiler x option is in effect. For more information, see VS COBOL II Migration x Guide for MVS and CMS or VS COBOL II Migration Guide for VSE.

For Format 4 and 5, if a size error occurs in the quotient, no remainder calculation is meaningful. Therefore the contents of the quotient field (identifier-3) and the remainder field (identifier-4) are unchanged.

If a size error occurs in the remainder, the contents of the remainder field (identifier-4) are unchanged.

In either of these cases, you must analyze the results to determine which situation has actually occurred.

For information on the NOT ON SIZE ERROR phrase, see topic 2.8.7.4.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.11.4 END-DIVIDE Phrase

| This explicit scope terminator delimits the scope of the DIVIDE statement. | END-DIVIDE converts a conditional DIVIDE statement to an imperative | statement so that it can be nested in another conditional statement. END-DIVIDE can also be used with an imperative DIVIDE statement.

For more information, see "Delimited Scope Statements" in topic 2.8.6.3.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

x 3.12 ENTRY Statement

x The ENTRY statement establishes an alternate entry point into a COBOL x called subprogram. The ENTRY statement cannot be used in a contained x program. See "Nested Programs" in topic 2.1 for description of a x contained program.

x When a CALL statement naming the alternate entry point is executed in a x calling program, control is transferred to the next executable statement x following the ENTRY statement.

___ entry-statement ___________________________________________ | | | >>__{__ENTRY__literal-1_________________________________}__>< | | | <______________ | | | |__USING____data-name-1__|__| | | | |_______________________________________________________________| x literal x Must be nonnumeric and conform to the rules for the formation of a x program-name in the outermost program (see "PROGRAM-ID Paragraph" in x topic 2.2.1).

x Must not match the program-id or any other ENTRY literal in this x program.

x Must not be a figurative constant.

x data-name-1 x Can be a USAGE DISPLAY-1 (DBCS), floating-point, or USAGE IS POINTER x item.

x Execution of the called program begins at the first executable statement x following the ENTRY statement whose literal corresponds to the CALL x statement literal or identifier.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

x 3.12.1 USING Phrase

x For a discussion of the USING phrase, see "The USING Phrase" in x topic 2.8.1.1.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.13 EVALUATE Statement

The EVALUATE statement provides a shorthand notation for a series of nested IF statements. It can evaluate multiple conditions. That is, the IF statements can be made up of compound conditions. The subsequent action of the object program depends on the results of these evaluations.

@@ Diagram evaluate-statement ADAPTED. @@ 1 imperative statement = many imperative statements (see 2.8.6.1) @@ Diagram evaluate-statement UNFOLDED according to expression. @@ expression-1/2 became arithmetic-expression | condition. @@ Diagram evaluate-statement UNFOLDED according to e-phrase-a. @@ Inline clause for conciseness. @@ Diagram evaluate-statement UNFOLDED according to e-phrase-b. @@ Inline clause for conciseness. ___ evaluate-statement ______________________________________________________________________ | | | >>__EVALUATE_____identifier-1_____________________________________________________________> | | |__literal-1______________| | <____________________________________ | | | |__arithmetic-expression__| |____ALSO_____identifier-2______________|__| | | |__condition______________| |__literal-2______________| | | |__TRUE___________________| |__arithmetic-expression__| | | |__FALSE__________________| |__condition______________| | | |__TRUE___________________| | | |__FALSE__________________| | | | | <______________ | | >_____when-phrase__|______________________________________________________________________> | | | | >________________________________________________________________________________________>< | | |__when-other-phrase__| |__END-EVALUATE__| | | | |_____________________________________________________________________________________________| @@ Diagram expression DELETED. @@ Obsolete as a result of unfolding in evaluate-statement. @@ Diagram e-phrase ADDED after diagram evaluate-statement. @@ Capture subscript-free syntax fragment used in evaluate-statement. ___ e-phrase ___________________________________________________________________________________________ | | | >>_____ANY__________________________________________________________________________________________>< | | |__condition_________________________________________________________________________________| | | |__TRUE______________________________________________________________________________________| | | |__FALSE_____________________________________________________________________________________| | | |________________identifier__________________________________________________________________| | | |__NOT__| |__literal________________| |_____THROUGH________identifier________________| | | |__arithmetic-expression__| |__THRU_____| |__literal________________| | | |__arithmetic-expression__| | | | |________________________________________________________________________________________________________| @@ Diagram when-phrase EXTRACTED from diagram evaluate-statement. @@ Capture conditional phrase for conciseness ___ when-phrase ___________________________________________________________________________ | | | <____________________________________________ | | >>____WHEN__e-phrase_____________________________|__series-of-imperative-statements-1__>< | | | <_________________ | | | |____ALSO__e-phrase__|__| | | | |___________________________________________________________________________________________| @@ Diagram when-other-phrase EXTRACTED from diagram evaluate-statement. @@ Capture conditional phrase for conciseness ___ when-other-phrase __________________________________ | | | >>__WHEN__OTHER__series-of-imperative-statements-2__>< | | | |________________________________________________________| @@ Diagram e-phrase-a DELETED. @@ Not needed anymore as a result of refactoring. @@ Diagram e-phrase-a FOLDED according to e-phrase. @@ Factored out clause for conciseness. @@ Diagram e-phrase-b DELETED. @@ Not needed anymore as a result of refactoring. @@ Diagram e-phrase-b FOLDED according to e-phrase. @@ Factored out clause for conciseness. Operands before the WHEN phrase Are interpreted in one of two ways, depending on how they are specified:

o Individually, they are called selection subjects o Collectively, they are called a set of selection subjects.

Operands in the WHEN phrase Are interpreted in one of two ways, depending on how they are specified:

o Individually, they are called selection objects o Collectively, they are called a set of selection objects.

ALSO Separates selection subjects within a set of selection subjects; separates selection objects within a set of selection objects.

THROUGH and THRU Are equivalent.

Two operands connected by a THRU phrase must be of the same class. The two operands thus connected constitute a single selection object.

The number of selection objects within each set of selection objects must be equal to the number of selection subjects.

Each selection object within a set of selection objects must correspond to the selection subject having the same ordinal position within the set of selection subjects, according to the following rules:

o Identifiers, literals, or arithmetic expressions appearing within a selection object must be valid operands for comparison to the corresponding operand in the set of selection subjects.

o Condition-1, condition-2, or the word TRUE or FALSE appearing as a selection object must correspond to a conditional expression or the word TRUE or FALSE in the set of selection subjects.

o The word ANY can correspond to a selection subject of any type.

x o Where identifiers are permitted, they can reference DBCS data items, x floating-point data items, or USAGE POINTER data items.

x o Where nonnumeric literals are permitted, DBCS literals are permitted.

x o Where numeric literals are permitted, floating-point literals are x permitted.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.13.1 END-EVALUATE Phrase

| This explicit scope terminator delimits the scope of the EVALUATE | statement. END-EVALUATE converts a conditional EVALUATE statement to an | imperative statement so that it can be nested in another conditional | statement.

For more information, see "Delimited Scope Statements" in topic 2.8.6.3.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.13.2 Determining Values

The execution of the EVALUATE statement operates as if each selection subject and selection object were evaluated and assigned a numeric or nonnumeric value, a range of numeric or nonnumeric values, or a truth value. These values are determined as follows:

o Any selection subject specified by identifier-1, identifier-2, . . . and any selection object specified by identifier-3 and/or identifier-5 without the NOT or THRU phrase, are assigned the value and class of the data item that they reference.

o Any selection subject specified by literal-1, literal-2, . . . and any selection object specified by literal-3 and/or literal-5 without the NOT or THRU phrase, are assigned the value and class of the specified literal. If literal-3 and/or literal-5 is the figurative constant ZERO, it is assigned the class of the corresponding selection subject.

o Any selection subject in which expression-1, expression-2, . . . is specified as an arithmetic expression, and any selection object without the NOT or THRU phrase in which arithmetic-expression-1 and/or arithmetic-expression-3 is specified, are assigned numeric values according to the rules for evaluating an arithmetic expression. (See "Arithmetic Expressions" in topic 2.8.4.)

o Any selection subject in which expression-1, expression-2, . . . is specified as a conditional expression, and any selection object in which condition-1 and/or condition-2 is specified, are assigned a truth value according to the rules for evaluating conditional expressions. (See "Conditional Expressions" in topic 2.8.5.)

o Any selection subject or any selection object specified by the words TRUE or FALSE is assigned a truth value. The truth value "true" is assigned to those items specified with the word TRUE, and the truth value "false" is assigned to those items specified with the word FALSE.

o Any selection object specified by the word ANY is not further evaluated.

o If the THRU phrase is specified for a selection object without the NOT phrase, the range of values is all values that, when compared to the selection subject, are greater than or equal to the first operand and less than or equal to the second operand, according to the rules for comparison. If the first operand is greater than the second operand, there are no values in the range.

o If the NOT phrase is specified for a selection object, the values assigned to that item are all values not equal to the value, or range of values, that would have been assigned to the item had the NOT phrase been omitted.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.13.3 Comparing Selection Subjects and Objects

The execution of the EVALUATE statement then proceeds as if the values assigned to the selection subjects and selection objects were compared to determine whether any WHEN phrase satisfies the set of selection subjects. This comparison proceeds as follows:

1. Each selection object within the set of selection objects for the first WHEN phrase is compared to the selection subject having the same ordinal position within the set of selection subjects. One of the following conditions must be satisfied if the comparison is to be satisfied:

a. If the items being compared are assigned numeric or nonnumeric values, or a range of numeric or nonnumeric values, the comparison is satisfied if the value, or one value in the range of values, assigned to the selection object is equal to the value assigned to the selection subject, according to the rules for comparison.

b. If the items being compared are assigned truth values, the comparison is satisfied if the items are assigned identical truth values.

c. If the selection object being compared is specified by the word ANY, the comparison is always satisfied, regardless of the value of the selection subject.

2. If the above comparison is satisfied for every selection object within the set of selection objects being compared, the WHEN phrase containing that set of selection objects is selected as the one satisfying the set of selection subjects.

3. If the above comparison is not satisfied for every selection object within the set of selection objects being compared, that set of selection objects does not satisfy the set of selection subjects.

4. This procedure is repeated for subsequent sets of selection objects in the order of their appearance in the source program, until either a WHEN phrase satisfying the set of selection subjects is selected or until all sets of selection objects are exhausted.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.13.4 Executing the EVALUATE Statement

After the comparison operation is completed, execution of the EVALUATE statement proceeds as follows:

o If a WHEN phrase is selected, execution continues with the first imperative-statement-1 following the selected WHEN phrase. Note that multiple WHEN statements are allowed for a single imperative-statement-1.

o If no WHEN phrase is selected and a WHEN OTHER phrase is specified, execution continues with imperative-statement-2.

o If no WHEN phrase is selected and no WHEN OTHER phrase is specified, execution continues with the next executable statement following the scope delimiter.

o The scope of execution of the EVALUATE statement is terminated when execution reaches the end of the scope of the selected WHEN phrase or WHEN OTHER phrase, or when no WHEN phrase is selected and no WHEN OTHER phrase is specified.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.14 EXIT Statement

The EXIT statement provides a common end point for a series of paragraphs.

@@ Diagram exit-statement ADAPTED. @@ Removed all illustrative parts which are not part of the statement. ___ exit-statement ___ | | | >>__EXIT__________>< | | | |______________________| The EXIT statement assigns a name to a given point in a program. The EXIT statement has no other effect on the compilation or execution of the program. The EXIT statement must be preceded by a paragraph-name and must appear in a sentence by itself. This sentence must be the only sentence in the paragraph.

x This sentence need not be the only sentence in the paragraph.

The EXIT statement is useful for documenting the end point in a series of paragraphs. If an EXIT paragraph is written as the last paragraph in a declarative procedure or a series of performed procedures, it identifies the point at which control will be transferred.

o When control reaches such an EXIT paragraph and the associated declarative or PERFORM statement is active, control is transferred to the appropriate part of the Procedure Division.

o When control reaches an EXIT paragraph that is not the end of a range of procedures governed by an active PERFORM or USE statement, control passes through the EXIT statement to the first statement of the next paragraph.

Without an EXIT statement, the end of the sequence is difficult to determine, unless you know the logic of the program.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.15 EXIT PROGRAM Statement

The EXIT PROGRAM statement specifies the end of a called program and returns control to the calling program. It must not be used in a declarative procedure in which the GLOBAL phrase is specified.

@@ Diagram exit-program-statement ADAPTED. @@ Removed "." which is not part of the statement. ___ exit-program-statement ___ | | | >>__EXIT__PROGRAM_________>< | | | |______________________________| If control reaches an EXIT PROGRAM statement in a program that does not possess the INITIAL attribute while operating under the control of a CALL | statement (that is, the CALL statement is active), control returns to that | CALL statement in the calling program. The program state of the calling program is identical to that which existed at the time it executed the CALL statement. The contents of data items and the contents of data files shared between the calling and called program may have been changed. The program state of the called program is not altered except that the ends of the ranges of all PERFORM statements executed by that called program are considered to have been reached.

x Note: This element may exhibit different behavior when the CMPR2 compiler x option is in effect. For more information, see VS COBOL II Migration x Guide for MVS and CMS or VS COBOL II Migration Guide for VSE.

The execution of an EXIT PROGRAM statement in a called program that | possesses the INITIAL attribute is equivalent to executing a CANCEL | statement referencing that program.

If control reaches an EXIT PROGRAM statement, and no CALL statement is active, control passes through the exit point to the next executable statement.

The EXIT PROGRAM statement must appear as the only statement, or as the last statement, in a series of imperative statements in a sentence.

x The EXIT PROGRAM statement does not have to be the last statement in a x sequence of imperative statements, but the statements following the EXIT x PROGRAM statement will not be executed if a CALL statement is active.

When there is no next executable statement in a called program, an implicit EXIT PROGRAM statement is executed.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

x 3.16 GOBACK Statement

x The GOBACK statement functions like the EXIT PROGRAM statement when it is x coded as part of a called program and like the STOP RUN statement when x coded in a main program.

x The GOBACK statement specifies the logical end of a called program.

___ goback-statement ___ | | | >>__GOBACK__________>< | | | |________________________| x A GOBACK statement should appear as the only statement or as the last of a x series of imperative statements in a sentence because any statements x following the GOBACK are not executed.

x If control reaches a GOBACK statement while a CALL statement is active, x control returns to the point in the calling program immediately following x the CALL statement, as in the EXIT PROGRAM statement.

x In addition, the execution of a GOBACK statement in a called program that x possesses the INITIAL attribute is equivalent to executing a CANCEL x statement referencing that program.

x The table below shows the action taken for the GOBACK statement in both a x main program and a subprogram.

________________________________________________________________________ x | Termination | | | x | Statement | Main Program | Subprogram | |______________|____________________________|____________________________| x | GOBACK | Return to calling program. | Return to calling program. | x | | (May be the system and | | x | | thus causes the job to | | x | | end.) | | |______________|____________________________|____________________________|

x Note: This element may exhibit different behavior when the CMPR2 compiler x option is in effect. For more information, see VS COBOL II Migration x Guide for MVS and CMS or VS COBOL II Migration Guide for VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.17 GO TO Statement

The GO TO statement transfers control from one part of the Procedure | Division to another. The GO TO statement has four formats:

| o Format 1 (Unconditional GO TO) | o Format 2 (Conditional GO TO) | o Format 3 (Altered GO TO) x o Format 4 (MORE-LABELS GO TO)

Subtopics:


@@ Diagram go-to-statement ADDED at the end of this section.
@@ Different formats of GO statements.

    ___ go-to-statement _____________________
   |                                         |
   | >>_____go-to-statement-format-i______>< |
   |     |__go-to-statement-format-ii__|     |
   |     |__altered-go-to______________|     |
   |     |__go-to-statement-format-iv__|     |
   |                                         |
   |_________________________________________|


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.17.1 Format 1 (Unconditional GO TO)

The unconditional GO TO statement transfers control to the first statement in the paragraph or section named in procedure-name, unless the GO TO statement has been modified by an ALTER statement. (See "ALTER Statement" in topic 3.3.)

___ go-to-statement-format-i ___________ | | | >>__GO____________procedure-name-1__>< | | |__TO__| | | | |________________________________________| procedure-name-1 Must name a procedure or a section in the same Procedure Division as the GO TO statement.

An unconditional GO TO statement, when it appears in a sequence of imperative statements, must be the last statement in the sequence.

x The unconditional GO TO statement does not have to be the last statement x in a sequence of imperative statements, but the statements following the x GO TO are not executed.

When a paragraph is referred to by an ALTER statement, the paragraph must consist of a paragraph-name followed by an unconditional or altered GO TO statement.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.17.2 Format 2 (Conditional GO TO)

The conditional GO TO statement transfers control to one of a series of procedures, depending on the value of the identifier.

___ go-to-statement-format-ii ____________________________________ | | | <___________________ | | >>__GO______________procedure-name-1__|__DEPENDING_____________> | | |__TO__| |__ON__| | | | | >___identifier-1______________________________________________>< | | | |__________________________________________________________________| procedure-name-1 Must be a procedure or a section in the same Procedure Division as the GO TO statement. The number of procedure-names must not exceed 255.

identifier-1 Must be a numeric elementary data item which is an integer.

If equal to 1, control is transferred to the first statement in the procedure named by the first occurrence of procedure-name-1;

If equal to 2, control is transferred to the first statement in the procedure named by the second occurrence of procedure-name-1, and so forth.

If the value of identifier is anything other than a value within the range of 1 through n (where n is the number of procedure-names specified in this GO TO statement), no control transfer occurs. Instead, control passes to the next statement in the normal sequence of execution.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.17.3 Format 3 (Altered GO TO)

The altered GO TO statement transfers control to the first statement of the paragraph named in the ALTER statement.

| Note: The altered GO TO statement is an obsolete element and will be | deleted from the next revision of the COBOL 85 Standard.

___ go-to-statement-format-iii ______________ | | | >>__paragraph-name__.__altered-go-to__.__>< | | | |_____________________________________________| @@ Diagram altered-go-to EXTRACTED from diagram go-to-statement-format-iii. @@ Treat altered GOs as statements and not paragraphs. ___ altered-go-to ____ | | | >>__GO____________>< | | |__TO__| | | | |______________________| An ALTER statement referring to the paragraph containing this GO TO statement must have been executed before this GO TO statement is executed.

x If an ALTER statement referring to the paragraph containing this GO TO x statement has not been executed before this GO TO statement is executed, x this GO TO statement acts like a CONTINUE statement.

When an ALTER statement refers to a paragraph, the paragraph must consist only of the paragraph-name followed by an unconditional or altered GO TO statement.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

x 3.17.4 Format 4 (MORE-LABELS GO TO)

x The GO TO MORE-LABELS statement can only be specified in a LABEL x declarative.

___ go-to-statement-format-iv ___________ | | | >>__{__GO____________MORE-LABELS__}__>< | | |__TO__| | | | |_________________________________________| x For more information, see VS COBOL II Application Programming Guide for x MVS and CMS or VS COBOL II Application Programming Guide for VSE.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.18 IF Statement

The IF statement evaluates a condition and provides for alternative actions in the object program, depending on the evaluation.

@@ Diagram if-statement ADAPTED. @@ Restricted statement sequences in IF statements ___ if-statement ___________________________________________ | | | >>__IF__condition-1_________________statements___________> | | |__THEN__| |__NEXT__SENTENCE__| | | | | >_______________________________________________________>< | | |__ELSE_____statements_________| |__END-IF__@1__| | | |__NEXT__SENTENCE__| | | | |____________________________________________________________| ________________________________________________________________________ | | | Note: | x | (1) END-IF can be specified when NEXT SENTENCE is specified as an | x | IBM extension. | | | |________________________________________________________________________|

condition Can be any simple or complex condition, as described in "Conditional Expressions" in topic 2.8.5.

statement-1, statement-2 Can be any one of the following:

o An imperative statement o A conditional statement o An imperative statement followed by a conditional statement.

NEXT SENTENCE If the NEXT SENTENCE phrase is specified, then the END-IF phrase must not be specified.

x END-IF can be specified with NEXT SENTENCE. However, if the NEXT x SENTENCE phrase is executed, control will not pass to the next x statement following the END-IF but instead will pass to the statement x after the closest following period.

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.18.1 END-IF Phrase

| This explicit scope terminator delimits the scope of the IF statement. | END-IF converts a conditional IF statement to an imperative statement so | that it can be nested in another conditional statement.

For more information, see "Delimited Scope Statements" in topic 2.8.6.3.

The scope of an IF statement can be terminated by any of the following:

o An END-IF phrase at the same level of nesting o A separator period o If nested, by an ELSE phrase associated with an IF statement at a higher level of nesting.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.18.2 Transferring Control

   If the condition tested is true, one of the following actions takes place: 

| o If statement-1 is specified, it is executed. If statement-1 contains a procedure branching or conditional statement, control is transferred, according to the rules for that statement. If statement-1 does not contain a procedure-branching statement, the ELSE phrase, if specified, is ignored, and control passes to the next executable statement after the corresponding END-IF or separator period.

| o If NEXT SENTENCE is specified, control passes to an implicit CONTINUE | statement immediately preceding the next separator period.

If the condition tested is false, one of the following actions takes place:

| o If ELSE statement-2 is specified, it is executed. If statement-2 contains a procedure-branching or conditional statement, control is transferred, according to the rules for that statement. If statement-2 does not contain a procedure-branching or conditional statement, control is passed to the next executable statement after the corresponding END-IF or separator period.

| o If ELSE NEXT SENTENCE is specified, control passes to an implicit | CONTINUE statement immediately preceding the next separator period.

o If neither ELSE statement-2 nor ELSE NEXT SENTENCE is specified, control passes to the next executable statement after the corresponding END-IF or separator period.

Note: When the ELSE phrase is omitted, all statements following the condition and preceding the corresponding END-IF or the separator period for the sentence are considered to be part of statement-1.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.18.3 Nested IF Statements

| If an IF statement appears as statement-1 or statement-2, or as part of | statement-1 or statement-2, it is said to be nested.

| IF statements within IF statements are considered matched IF, ELSE, and | END-IF combinations proceeding from left to right. Thus, any ELSE | encountered is matched with the nearest preceding IF that either has not | been already matched with an ELSE or has not been implicitly or explicitly | terminated. Any END-IF encountered is matched with the nearest preceding | IF that has not been implicitly or explicitly terminated.


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.19 INITIALIZE Statement

The INITIALIZE statement sets selected categories of data fields to predetermined values. It is functionally equivalent to one or more MOVE statements.

___ initialize-statement ____________________________________________________________________ | | | <_______________ | | >>__INITIALIZE____identifier-1__|_________________________________________________________> | | | | >________________________________________________________________________________________>< | | | <________________________________________________________________ | | | |__REPLACING_______ALPHABETIC__________________________BY_____identifier-2_____|__| | | |__ALPHANUMERIC_________| |__DATA__| |__literal-1_____| | | |__NUMERIC______________| | | |__ALPHANUMERIC-EDITED__| | | |__NUMERIC-EDITED_______| | | |__{__DBCS__}___________| | | |__{__EGCS__}___________| | | | |_____________________________________________________________________________________________| identifier-1 Receiving area(s).

identifier-2, literal-1 Sending area(s).

A subscripted item can be specified for identifier-1. A complete table can be initialized only by specifying identifier-1 as a group that contains the complete table.

| The description of the data item referenced by identifier-1 or any items | subordinate to identifier-1 cannot contain the DEPENDING ON phrase of the | OCCURS clause.

x A floating-point data item or literal can be used anywhere a numeric x identifier or literal is specified.

x A DBCS data item or literal can be used anywhere an identifier or literal x is specified.

The data description entry for identifier-1 must not contain a RENAMES clause. An index data item cannot be an operand of INITIALIZE.

Special registers can be specified for identifier-1 and identifier-2 only if they are valid receiving fields or sending fields, respectively, for the implied MOVE statement(s).

Subtopics:


Disclaimer: This is not an official IBM document. Make sure that you understand the full disclaimer text as a prerequisite to using the present document.

3.19.1 REPLACING Phrase

When the REPLACING phrase is used:

o The category of identifier-2 or literal-1 must be compatible with the category indicated in the corresponding REPLACING phrase, according to x the rules for MOVE. A floating-point data item or floating-point x literal will be treated as if it is in the NUMERIC category.

o The same category cannot be repeated in a REPLACING phrase.

o The keyword following the word REPLACING corresponds to a category of data shown in "Classes and Categories of Data" in topic 2.5.3.5.

When the REPLACING phrase is not used:

o SPACE is the implied sending field for alphabetic, alphanumeric, x alphanumeric-edited, and DBCS items.

o ZERO is the implied sending field for numeric and numeric-edited items.

x DBCS, EGCS x Refer to the characters allowed for DBCS literals. EGCS (extended x graphic character set) is equivalent to DBCS.


Disclaimer: This is not an official IBM document. Make sure that you understand the full