This chapter provides entry skeletons for the file description entry
and the data description entry. Descriptions of all the clauses for these two
types of entries follow in alphabetical order.
Function
The file description comprises information concerning the physical
structure, identification, and record-names pertaining to a given file.
It determines the internal or
external attributes of a file connector, of the associated data records, and of
the associated data items. The file description entry also determines whether a
file-name is a local name or a global name.
General
Formats
Format 1 (Record Sequential Files)
Format 2 (Line Sequential Files)
Format 3 (Relative and Indexed Files)
Format 4 (Sort-Merge Files)
Syntax Rules
All Formats (All Files)
- The clauses which follow file-name-1 may appear in any order.
-
If the VALUE OF FILE-ID
clause is specified, literal-1 must be a nonnumeric literal and cannot be a
figurative constant.
Formats 1, 2 and 3 (Record Sequential,
Line
Sequential,
Relative and Indexed Files)
- The level indicator FD identifies the beginning of a file description
and must precede the file-name.
- One or more record description entries must follow the file
description entry.
-
The EXTERNAL clause and the
THREAD-LOCAL clause must not be specified in the same description entry.
Format 4 (Sort-Merge Files)
- The level indicator SD identifies the beginning of the sort-merge
file description and must precede the file-name.
- The clauses which follow the name of the file are optional and may
appear in any order.
- One or more record description entries must follow the sort-merge
file description entry. However, no input-output statements can be executed for
this file.
General Rules
Format 1 (Record Sequential Files)
- 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 special register
LINAGE-COUNTER is a global name.
Function
A data description entry specifies the characteristics of a particular
item of data
or the characteristics of a
programmer-defined type of data which can then be used to specify the
description of one or more particular items of data.
A level 01 data description entry within the Working-Storage Section or File
Section determines whether the data record and its subordinate data items have
local names or global names.
A level 01 data description
in the Working-Storage Section determines the internal or external attribute of
the data record and its subordinate data items.
General Formats
Format 1

Format 2

Format 3

Format 4

Syntax Rules
- The level-number in Format
1 can be any number from 01 through 49 or 77.
- The clauses can be written in any order with two exceptions: the
data-name-1 or FILLER clause
, if specified,
must immediately follow the level-number; the REDEFINES clause, when
used, must immediately follow the data-name-1 or FILLER clause
if either is specified;
otherwise it must immediately follow the level number.
- The PICTURE clause must be specified for every elementary item
except:
- an index data item
-
an object reference
a procedure pointer
a pointer
- an internal floating-point data item - USAGE
COMPUTATIONAL-1,
COMPUTATIONAL-2,
FLOAT-SHORT or
FLOAT-LONG
-
an event-pointer, a
monitor-pointer, a mutex-pointer, a semaphore-pointer or a thread-pointer
in which case use of this clause is prohibited.
- The words THRU and THROUGH are equivalent.
-
The EXTERNAL clause can be
specified only in data description entries in the Working-Storage Section whose
level-number is 01.
-
The EXTERNAL clause and the
REDEFINES clause must not be specified in the same data description entry.
-
The EXTERNAL clause and the
THREAD-LOCAL clause must not be specified in the same data description entry.
-
The GLOBAL clause can be
specified only in data description entries whose level-number is 01.
-
Data-name-1 must be
specified for any entry containing the GLOBAL or EXTERNAL clause, or for record
descriptions associated with a file description entry which contains the
EXTERNAL or GLOBAL clause.
-
The TYPEDEF clause can only
be specified in data description entries whose level-number is 01.
-
The TYPEDEF clause can only
be used when data-name-1 is also specified. In other words, it cannot be used
in the same data description with either an explicit or implicit FILLER clause.
Note that if the TYPEDEF
clause is specified for a group item, subordinate data descriptions can be
defined with either an implicit or explicit FILLER clause.
- The clauses SYNCHRONIZED, PICTURE, JUSTIFIED, and BLANK WHEN ZERO
must not be specified except for an elementary data item.
The SYNCHRONIZED clause
can be specified for a group item.
-
Literal-5 and integer-1
must not be floating-point values, must not be negative values and must not be
more than 18 digits.
- If literal-5 is used as part of an expression, it must be an integer.
-
Data-name-2 and
data-name-3 can be implicitly qualified.
-
The VALUE clause must not
be specified for data items of class index, object, or pointer.
General Rules
- Format 3 is used for each condition-name. Each condition-name
requires a separate entry with level-n
umber 88. Format 3 contains the name of the condition and the value, values, or
range of values associated with the condition-name. The condition-name entries
for a particular conditional variable must immediately follow the entry
describing the item with which the condition-name is associated. A
condition-name can be associated with any data description entry which contains
a level-number except the following:
- Another condition-name.
- A level 66 item.
- A group containing items with descriptions including JUSTIFIED,
SYNCHRONIZED or USAGE (other than USAGE IS DISPLAY).
- An index
or pointer
data item (see the section The USAGE IS INDEX Clause in
this chapter).
-
A constant-name.
-
Condition-names can be
associated with internal floating-point items.
Condition-names can be
associated with external floating-point items.
-
Format 4 defines a
constant-name, which is a symbolic name representing a constant value assigned
to it when the source code is passed through your COBOL system. Your COBOL
system replaces each reference to a constant-name by its value.
-
The TYPEDEF clause allows
you to declare a group or elementary data description as a type definition,
which allows instances of that data description to be declared as data items
using data-name-1 as typedef-name-1 in the USAGE clause. The type definition
itself is not a data item with allocated storage.
-
If the TYPEDEF clause is
specified at a group level, the components of the type definition are
implicitly declared for any data item of that type and are referenced using the
usual COBOL rules of qualification for the data item.
Function
The BLANK WHEN ZERO clause permits the blanking of an item when its
value is zero.
General Format

Syntax Rules
- The BLANK WHEN ZERO clause can be used only for an elementary item
whose PICTURE is specified as numeric (with implicit or explicit USAGE IS
DISPLAY) or numeric edited. (See the section The PICTURE Clause later in
this chapter.)
- The asterisk, when used as the zero suppression symbol, and the
clause BLANK WHEN ZERO should not appear in the same entry.
This construct is,
however, permitted in which case, zero suppression overrides the BLANK WHEN
ZERO clause.
General Rules
- When the BLANK WHEN ZERO clause is used, the item will contain
nothing but spaces if the value of the item is zero.
- When the BLANK WHEN ZERO clause is used for an item whose PICTURE is
numeric, the category of the item is considered to be numeric edited.
Function
The BLOCK CONTAINS clause specifies the size of a physical record.
Although it is a part of the
standard COBOL definition, this feature is explicitly excluded from the X/Open
COBOL language definitions and should not be used in a conforming X/Open COBOL
source program.
General Format

General Rules
-
This clause is documentary
only.
Function
The CODE-SET clause specifies the character code set used to represent
data on the external media.
It can be specified only for files with record sequential
and line sequential
organization.
Although it is a part of the
standard COBOL definition, this feature is explicitly excluded from the X/Open
COBOL language definitions and should not be used in a conforming X/Open COBOL
source program.
General Format

Directives
- In addition to Compiler directives which provide flagging and modify
the reserved word list, the following directive may impact either the syntax or
semantics described in this section.
- CHARSET - determines what is considered the native code-set.
Syntax Rules
- When the CODE-SET clause is specified for a file, all data in that
file must be described as usage is DISPLAY and any signed numeric data must be
described with the SIGN IS SEPARATE clause.
These restrictions do not
apply.
- The alphabet-name clause referenced by the CODE-SET clause must not
specify the literal phrase.
These restrictions do not
apply.
-
Identifier-1 can be
qualified, but must not be subscripted.
-
Each identifier-1 must be a
data item described in the same record description for the file, and must not
itself be a record description.
-
If the optional FOR phrase
is specified, the CODE-SET clause specifies the character code to be used for
the data items named. If the FOR phrase is not specified, the CODE-SET clause
specifies the character code to be used for the whole file.
- The native character set is used for any file, or data item in a
file, to which no CODE-SET clause applies.
General Rules
-
The data in the record area
is always in ASCII. If alphabet-name has been equated in the Special-Names
paragraph to EBCDIC, then data affected by the CODE-SET clause is translated
from ASCII to EDCDIC as it is written to the file; or from EBCDIC to ASCII as
it is read from the file. If alphabet-name has been equated in the
Special-Names paragraph to STANDARD-1, STANDARD-2, NATIVE, or ASCII, no
translation is necessary.
-
For the purposes of this
translation, any data item to which a CODE-SET clause applies is treated as
alphanumeric. No account is taken of the class and category of the item as
described in its data description.
-
If identifier-1 has an
OCCURS clause, the CODE-SET clause applies to only the first occurrence of it.
If identifier-1 has a subordinate item with an OCCURS clause, the CODE-SET
clause applies to the whole of identifier-1.
Function
The DATA RECORDS clause serves only as documentation for the names of
data records with their associated file.
The DATA RECORDS clause of
the file description entry is classed as an obsolete element in the ANSI'85
standard and is scheduled to be deleted from the next full revision of the ANSI
Standard.
All dialects in this COBOL
implementation fully support this syntax. The FLAGSTD Compiler directive can be
used to detect all occurrences of this syntax.
Although part of the standard
COBOL definition, this feature is explicitly excluded from the X/Open COBOL
language definitions and should not be used in a conforming X/Open COBOL source
program.
General Format

Syntax Rules
- Data-name-1 and data-name-2 are the names of data records and should
have 01 level-number record descriptions, with the same names, associated with
them.
These data-names do not
have to be associated with any data description entry in the program.
General Rules
- The presence of more than one data-name indicates that the file
contains more than one type of data record. These records can be of differing
sizes, different formats, and so on. The order in which they are listed is not
significant.
Note: When using multiple 01 level items within an FD, if
the SELECT statement contains key definitions, the key sizes must be contained
within the minimum record length of that FD.
- Conceptually, all data records within a file share the same area.
This is in no way altered by the presence of more than one type of data record
within the file.
Function
A data-name specifies the name of the data being described. The word
FILLER can be used to specify an elementary item of the logical record that
cannot be referred to explicitly.
General Format

Syntax Rules
- The data-name or FILLER clause
, if specified,
must be the first word following the level-number in a data
description entry.
General Rules
- The key word FILLER can be used to name an elementary item or group
in a record. Under no circumstances can a FILLER item be referred to
explicitly. However, a data item defined with the key word FILLER can be used
as a conditional variable because such use does not require explicit reference
to the FILLER item but only to the value contained therein.
-
If this clause is omitted,
the data item being described is treated as though FILLER had been specified.
Function
The EXTERNAL clause specifies that a data item or a file connector is
external. The constituent data items and group items of an external data record
are available to every runtime element in the run unit that describes that
record.
General Format

Syntax Rules
- The EXTERNAL clause can be specified only in file description
entries, or in record description entries in the Working-Storage Section.
- In the same source element, the externalized name of the subject of
the entry that includes the EXTERNAL clause must not be the same as the
externalized name of any other entry that includes the EXTERNAL clause.
- The VALUE clause must not be used in any data description entry that
includes, or is subordinate to an entry that includes, the EXTERNAL clause. The
VALUE clause can be specified for condition-name entries associated with such
data description entries.
-
Literal-1 must be a
nonnumeric or a national literal and must not be a figurative constant.
-
The EXTERNAL clause must
not be specified for a data item of class object.
General Rules
- The data contained in the record named by the data-name clause is
external and can be accessed and processed by any runtime element in the run
unit which describes and, optionally, redefines it subject to the following
general rules.
- Within a run unit, if two or more source elements 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 source element which describes an
external record can contain a data description entry including the REDEFINES
clause which redefines the complete external record, and this complete
redefinition need not occur identically in other source elements in the run
unit, unless the storage area required for the redefinition is larger than the
storage area required for the external data record. See the section The
REDEFINES Clause.
- Use of the EXTERNAL clause does not imply that the associated
file-name or data-name is a global name. See the section The GLOBAL
Clause later in this chapter.
- The file connector associated with this description entry is an
external file connector.
-
See your COBOL system
documentation on file handling for further information on files with the
EXTERNAL attribute.
-
Literal-1 identifies the
external name of an external data item or file connector. The same external
name must be used by all source elements that reference the same external data
item or file connector.
Function
The GLOBAL clause specifies that a data-name, a file-name, or a
report-name is a global name. A global name is available to every program
contained within the program which declares it.
General Format

Syntax Rules
- The GLOBAL clause can be specified only in data description entries
whose level-number is 01 in the File Section or the Working-Storage Section,
file description entries, or report description entries.
The GLOBAL clause can
also 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.
- 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.
General Rules
- A data-name, file-name or report-name described using a GLOBAL clause
is a global name. All data-names subordinate to a global name are global names.
All condition-names associated with a global name are global names.
- 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. See the section Scope of Names in the chapter
Concepts of the COBOL Language.
- If the GLOBAL clause is used in a data description entry which
contains the REDEFINES clause, it is only the subject of that REDEFINES clause
which possesses the global attribute.
Function
The JUSTIFIED clause specifies non-standard positioning of data within a
receiving data item.
General Format

Syntax Rules
- The JUSTIFIED clause can be specified only at the elementary item
level.
- JUST is an abbreviation for JUSTIFIED.
- The JUSTIFIED clause cannot be specified for any data item described
as numeric or for which editing is specified.
- The JUSTIFIED clause cannot be specified for an index data item (see
the section The USAGE IS INDEX Clause)
, or for a pointer data
item.
-
The JUSTIFIED clause
cannot be specified for external or internal floating-point data items.
General Rules
- When a receiving data item is described with the JUSTIFIED clause and
the sending data item is larger than the receiving data item, the leftmost
characters are truncated. When the receiving data item is described with the
JUSTIFIED clause and it is larger than the sending data item, the data is
aligned at the rightmost character position in the data item with space fill
for the leftmost character positions.
The contents of the sending data item are not taken into account,
that is, trailing spaces within the sending data item are not suppressed.
For example, if a data item PIC X(4) whose value is "A "
(that
is, A followed by three spaces) is moved into a data item PIC X(6) JUSTIFIED
the result will be " A "
. If the same data item is moved to one with PIC X(3)
JUSTIFIED the result will be " "
that is, the leftmost character is
truncated.
- When the JUSTIFIED clause is omitted, the standard rules for aligning
data within an elementary item apply. (See the section Standard Alignment
Rules in the chapter Concepts of the COBOL Language.)
Function
The LABEL RECORDS clause specifies whether labels are present.
The LABEL RECORDS clause is
classed as an obsolete element in the ANSI'85 standard and is scheduled to be
deleted from the next full revision of the ANSI Standard.
All dialects in this COBOL
implementation fully support this syntax. The FLAGSTD Compiler directive can be
used to detect all occurrences of this syntax.
Although it is a part of the
standard COBOL definition, this feature is explicitly excluded from the X/Open
COBOL language definitions and should not be used in a conforming X/Open COBOL
source program.
General Format

Syntax Rules
- This clause should be present in every file description entry.
It is not required.
-
Data-name-1 is the name of
a label record and should have a 01 level-number record description, with the
same name, associated with it.
-
Data-name-1 must not
appear in the DATA RECORDS clause for the file.
-
Both LABEL RECORDS IS and
LABEL RECORD ARE are accepted as valid syntax.
General Rule
-
This clause is documentary
only.
Function
The level-number shows the hierarchy of data within a logical record. In
addition, it is used to identify entries for working-storage items, linkage
items, condition-names
, constant-names
and the RENAMES clause.
General Format

Syntax Rules
- A level-number is required as the first element in each data
description entry.
- Data description entries subordinate to an FD
or SD entry must have level-numbers with the values 01 through 49, 66
,78
or 88. (See the section The FILE Description earlier in this
chapter.)
- Data description entries in the Report Section and Screen Section
must have level-numbers with the values 01 through 49
, or 78
- Data description entries in the Working-Storage Section
, Local-Storage
and Linkage Section must have level-numbers with the values 01
through 49, 66, 77
, 78
or 88.
- A level-number can be a one or two digit number.
General Rules
- The level-number 01 identifies the first entry in each record
description.
- Special level numbers have been assigned to certain entries where
there is no real concept of level hierarchy:
- The level-number 77 is assigned to identify noncontiguous
working-storage data items and noncontiguous linkage data items. It can be used
only as described by Format 1 of the data description skeleton earlier in this
chapter.
- Level number 66 is assigned to identify RENAMES entries and can
be used only as described in Format 2 of the data description skeleton earlier
in this chapter.
- Level number 88
is assigned to entries which define condition-names associated with a
conditional variable and can be used only as described in Format 3 of the data
description skeleton earlier in this chapter.
-
Level number 78 is
assigned to entries which define constant-names. It can be used only as
described in Format 4 of the data description skeleton earlier in this chapter.
- Multiple level 01 entries subordinate to an FD or SD entry represent
implicit redefinitions of the same area.
Function
The LINAGE clause allows the user to specify the depth of a logical page
in terms of number of lines. The user can also specify the size of the top and
bottom margins on the logical page, and the line number, within the page body,
at which the footing area begins.
It can be specified only for files with sequential organization.
General Format

Syntax Rules
- Data-name-1, data-name-2, data-name-3 and data-name-4 must reference
elementary unsigned integer data items.
- The value of integer-1 must be greater than zero.
- The value of integer-2 must not be greater than integer-1.
- The value of integer-3 and integer-4 can be zero.
General Rules
- The LINAGE
clause allows the user to specify the size of a logical page in terms of number
of lines. The logical page size is the sum of the values referenced by each
phrase except the FOOTING phrase. If the FOOTING phrase is not specified, the
values for these functions are zero and no end-of-page condition independent of
the page overflow condition exists.
There is not necessarily any relationship between the size of the
logical page and the size of a physical page.
- The value of integer-1 or the data item referenced by data-name-1
specifies the number of lines that can be written and/or spaced on the logical
page. The value must be greater than zero. That part of the logical page in
which these lines can be written and/or spaced is called the page body.
- The value of integer-2 or the data item referenced by data-name-2
specifies the line number within the page body at which the footing area
begins. The value must be greater than zero and not greater than the value of
integer-1 or the data item referenced by data-name-1.
The footing area comprises the area of the logical page between the
line represented by the value of integer-2 of the data item referenced by
data-name-2, and the line represented by the value of integer-1 or the data
item referenced by data-name-1, inclusive.
- The value of integer-3 or the data item referenced by data-name-3
specifies the number of lines that comprise the top margin on the logical page.
The value can be zero.
The value of integer-4 or the data item referenced by data-name-4
specifies the number of lines that comprise the bottom margin on the logical
page. The value can be zero.
- The value of integer-1, integer-3, and integer-4, if specified, will
be used at the time the file is opened by the execution of an OPEN statement
with the OUTPUT phrase, to specify the number of lines that comprise each of
the indicated sections of a logical page. The value of integer-2, if specified,
will be used at that time to define the footing area. These values are used for
all logical pages written for the file during a given execution of the runtime
element.
- The values of the data items referenced by data-name-1, data-name-3,
and data-name-4, if specified at the time an open statement with the OUTPUT
phrase is executed for the file, will be used to specify the number of lines
that are to comprise each of the indicated sections for the first logical page.
The value of the data item referenced by data-name-2, if specified,
will be used at the time an OPEN statement with the OUTPUT phrase is executed
for the file to define the footing area for the first logical page.
- A LINAGE-COUNTER is generated by the presence of a LINAGE clause. The
value in the LINAGE-COUNTER at any one time represents the line number at which
the device is positioned within the current page body. The rules governing the
LINAGE-COUNTER are as follows:
- A separate LINAGE-COUNTER is supplied for each file described in
the File Section whose file description entry contains a LINAGE clause.
- LINAGE-COUNTER can be referenced, but can not be modified, by
PROCEDURE DIVISION statements. Since more than one LINAGE-COUNTER can exist in
a source element, the user must qualify LINAGE-COUNTER by file-name when
necessary.
- Each logical page is contiguous to the next with no additional
spacing provided.
- The values of the data items, at the time a WRITE statement with the
ADVANCING PAGE phrase is executed or page overflow condition occurs (see the
section The WRITE Statement later in this chapter), will be used to
specify the number of lines that are to comprise each of the indicated sections
for the next logical page.
- The value of the data item referenced by data-name-2, if specified,
will be used at the time a WRITE statement with the ADVANCING PAGE phrase is
executed or a page overflow condition occurs, to define the footing area for
the next logical page.
- LINAGE-COUNTER is automatically modified, according to the following
rules, during the execution of a WRITE statement to an associated file:
- When the ADVANCING PAGE phrase of the WRITE statement is
specified, the LINAGE-COUNTER is automatically reset to one.
- When the ADVANCING identifier-2 or integer phrase of the WRITE
statement is specified, the LINAGE-COUNTER is incremented by integer or the
value of the data item referenced by identifier-2.
- When the ADVANCING phrase of the WRITE statement is not
specified, the LINAGE-COUNTER is incremented by the value one. (See the section
The WRITE Statement later in this chapter.)
- The value of LINAGE-COUNTER is automatically reset to one when
the device is repositioned to the first line that can be written on for each of
the succeeding logical pages. (See the section The WRITE Statement later
in this chapter.)
- The value of LINAGE-COUNTER is automatically set to one when an OPEN
statement is executed for the associated file.
Function
The OCCURS clause eliminates the need for separate entries for repeated
data items and supplies information required for the application of subscripts
or indices.
General Formats
Format 1

Format 2

Directives
-
In addition to Compiler directives which provide flagging and modify the
reserved word list, the following directives may impact either the syntax or
semantics described in this section.
- ODOOSVS - requests OS/VS COBOL compatible processing of the
OCCURS DEPENDING ON clause.
- ODOSLIDE - controls the processing of nested OCCURS DEPENDING ON
clauses and fixed data following an OCCURS DEPENDING ON clause.
Syntax Rules
- Where both integer-1 and integer-2 are used, integer-1 must be
greater than
or equal to
zero and integer-2 must be greater than
or equal to
integer-1.
In Format 2, if
"integer-1 TO" is omitted, the default value one is assumed.
- The data description of data-name-1 must describe an integer.
- Data-name-1, data-name-2, data-name-3, ... can be qualified.
- Data-name-2 must be either the name of the entry containing the
OCCURS clause or the name of an entry subordinate to the entry containing the
OCCURS clause.
This restriction is
removed.
- Data-name-3, and so on, must be the name of an entry subordinate to
the group item which is the subject of this entry.
This restriction is
removed.
- An INDEXED BY phrase is required if the subject of this entry, or an
entry subordinate to this entry, is to be referred to by indexing,
unless it is to be
indexed by an index defined for another table (see the section Indexing
in the chapter Concepts of the COBOL Language).
The index-name identified by this clause is not defined elsewhere,
and not being data, cannot be associated with any data hierarchy.
- A data description entry that contains Format 2 of the OCCURS clause
should only be followed, within that record description, by data description
entries which are subordinate to it.
A data description entry
that contains Format 2 of the OCCURS clause can be followed, within that record
description, by data description entries which are not subordinate to it. The
positions of these entries within the record will vary at run time with the
value of the data item referenced in the DEPENDING ON clause
unless the NOODOSLIDE
Compiler directive is set. In this case, the containing record is considered as
always containing the maximum number of occurrences of the Format 2 item,
irrespective of the value of data-name-1. If the ODOSLIDE Compiler directive is
set,
when the value of
data-name-1 is changed, the position referenced by identifiers following, but
not subordinate to, the table is changed. The data these items contain can be
lost.
- The OCCURS clause cannot be specified in a data description entry
that:
- has a 66 or 88 level-number
- describes an item whose size is variable. The size of an item is
variable if the data description of any subordinate item contains Format 2 of
the OCCURS clause.
An OCCURS clause can
be specified for a data description subordinate to another item with a Format 2
OCCURS clause.
- The OCCURS clause should not be specified in a data description entry
at the 01 level or as a 77 level-number.
This restriction is
removed.
- In Format 2, the data item defined by data-name-1 must not occupy a
character position within the range of the first character position defined by
the data description entry containing the OCCURS clause and the last character
position defined by the record description entry containing that OCCURS clause.
If the ODOSLIDE Compiler
directive is set, data-name-1 must have a fixed location.
- If data-name-2 is not the subject of this entry, then:
- all of the items identified by the data-names in the KEY IS
phrase must be within the group item which is the subject of this entry
- items identified by the data-name in the KEY IS phrase must not
contain an OCCURS clause
- there must not be any entry that contains an OCCURS clause
between the items identified by the data-names in the KEY IS phrase and the
subject of this entry.
- Index-name-1, index-name-2, ... must be unique words within the
source element.
Index-name-1,
index-name-2, ... need not be unique and can be qualified by the data-name
which is the subject of this entry.
-
The OCCURS clause can be
specified for external or internal floating-point data items.
-
The KEY clause must not be
specified for a data item of class object.
General Rules
- The OCCURS clause is used in defining tables and other homogenous
sets of repeated data items. Whenever the OCCURS clause is used, the data-name
which is the subject of this entry must be either subscripted or indexed
whenever it is referred to in a statement other than SEARCH
, SORT
or USE FOR DEBUGGING. Further, if the subject of this entry is the
name of a group item, then all data-names belonging to the group must be
subscripted or indexed whenever they are used as operands, except as the object
of a REDEFINES clause. (See the sections Subscripting, Indexing
and Identifier in the chapter Concepts of the COBOL
Language.)
- Except for the OCCURS clause itself, all data description clauses
associated with an item whose description includes an OCCURS clause apply to
each occurrence of the item described. (See the restriction in general rule 20
under Data Description Entries Other Than Condition-Names
and Constant-Names.)
- Data-name-1 must have a fixed location, and must not follow an item
that contains an OCCURS DEPENDING ON clause.
- The number of occurrences of the subject entry is defined as follows:
- In Format 1, the value of integer-2 represents the exact number
of occurrences.
- In Format 2, the current value of the data item referenced by
data-name-1 represents the number of occurrences.
This format specifies that the subject of this entry has a
variable number of occurrences. The value of integer-2 represents the maximum
number of occurrences and the value of integer-1 represents the minimum number
of occurrences. This does not imply that the length of the subject of the entry
is variable, but that the number of occurrences is variable.
The value of the data item referenced by data-name-1 must fall
within the range of integer-1 through integer-2. Reducing the value of this
data item makes the contents of data items, whose occurrence numbers now exceed
the value of the data item referenced by data-name-1, unpredictable.
-
When a group item, having subordinate to it an entry that specifies Format 2 of
the OCCURS clause, is referenced, the part of the table area used in the
operation is determined as follows:
- If the data item referenced by data-name-1 is outside the group,
only that part of the table area that is specified by the value of the data
item referenced by data-name-1 at the start of the operation will be used.
- If the data item referenced by data-name-1 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 data item
referenced by data-name-1 at the start of the operation will be used in the
operation. If the group is a receiving item, the maximum length of the group
will be used.
- The KEY IS phrase is used to indicate that the repeated data is
arranged in ascending or descending order according to the values contained in
data-name-2, data-name-3, and so on. The ascending or descending order is
determined according to the rules for comparison of operands (see the sections
Comparison of Numeric Operands and Comparison of Nonnumeric
Operands). The data-names are listed in their descending order of
significance.
Function
The PICTURE clause describes the general characteristics and editing
requirements of an elementary item.
General Format

Directives
-
In addition to Compiler directives which provide flagging and modify the
reserved word list, the following directive may impact either the syntax or
semantics described in this section.
- INTLEVEL - determines the maximum length allowed for numeric data
items when the dialect is MF.
Syntax Rules
- A PICTURE clause can be specified only at the elementary item level.
- A character-string consists of certain allowable combinations of
characters in the COBOL character set used as symbols. The allowable
combinations determine the category of the elementary item.
- The maximum number of characters allowed in the
character-string is 30.
The maximum number of
characters allowed in the character-string is 50.
- The PICTURE clause must not be specified for the subject of a RENAMES
clause.
- PIC is an abbreviation for PICTURE.
- The asterisk when used as the zero suppression symbol and the clause
BLANK WHEN ZERO should not appear in the same entry.
This construct is,
however, permitted, in which case zero suppression overrides the BLANK WHEN
ZERO clause.
- An integer in parentheses following a character indicates that the
character is repeated the number of times shown by the integer.
General Rules
There are six categories of data that can be described with a PICTURE
clause: alphabetic, numeric, alphanumeric, alphanumeric edited, numeric edited,
and external floating-point
. General rules within these categories are given below:
Alphabetic Data Rules
- Its PICTURE character-string can only contain the symbols
"A" and "B".
Its PICTURE
character-string can contain only the symbol "A".
- Its contents when represented in standard data format must be one or
more alphabetic characters.
Numeric Data Rules
- Its PICTURE character-string can contain only the symbols
"9", "P", "S", and "V". The number of
digit positions that can be described by the PICTURE character-string must
range from 1 to 18 inclusive.
The PICTURE character-string can contain up to 31 digit
positions.
The PICTURE
character-string can contain up to 38 digit positions.
- If unsigned, the data in standard data format must be a combination
of the Arabic numerals "0", "1", "2", "
3", "4", "5", "6", "7",
"8", and "9"; if signed, the item can also contain a
"+", "-", or other representation of an operational sign.
(See the sectionThe SIGN Clause later in this chapter.)
Numeric Data can also be held in formats other than standard data format
(see the section The USAGE Clause later in this chapter and the section
Selection Of Character Representation And Radix in the chapter
Concepts of the COBOL Language).
Alphanumeric Data Rules
- Its PICTURE character-string is restricted to certain combinations of
the symbols " A", "X", "9", and the item is
treated as if the character-string contained all X"s. A PICTURE
character-string which contains all A"s or all 9"s does not define an
alphanumeric item.
- Its contents when represented in standard data format can consist of
any characters in the computer's character set.
Alphanumeric Edited Data Rules
- Its PICTURE character-string is restricted to certain combinations of
the following symbols: "A", "X", " 9",
"B", "0", and "/" as follows:
- The character-string must contain at least one "B" and
at least one "X" or at least one "0" (zero) and at least
one "X" or at least one "/" (slash) and at least one
"X", or:
- The character-string must contain at least one "0"
(zero) and at least one "A" or at least one "/" (slash) and
at least one "A".
- Its contents when represented in standard data format can consist of
any characters in the computer's character set.
Numeric Edited Data Rules
- Its PICTURE character-string is restricted to certain combinations of
the symbols "B", "/", "P", "V" ,
"Z", "0", "9", ",", ".",
"*", "+", "-", "CR", "DB",
and the currency symbol. The allowable combinations are determined from the
order of precedence of symbols and the editing rules as follows:
- The number of digit positions that can be represented in the
PICTURE character-string must range from 1 to 18 inclusive.
The PICTURE character-string can
contain up to 31 digit positions.
The PICTURE
character-string can contain up to 38 digit positions.
- The character-string must contain at least one "0" ,
"B", "/", "Z", "*", "+",
",", ".", "-", "CR" , "DB",
or currency symbol.
- The contents of the character positions that represent a digit must
be one of the numerals.
- If all character positions in the PICTURE character-string are
represented by an insertion character, at least one of the insertion characters
must be positioned to the left of the decimal point.
External Floating-point Data Items
- The PICTURE string must have the following form:
A sign character must immediately precede both the
significand and
the exponent.
A "+" sign indicates that a positive sign will be used in
the output to represent positive values and that a negative sign will represent
negative values.
A "-"sign indicates that a blank will be used in the
output to represent positive values and that a negative sign will represent
negative values.
Each sign position occupies one byte of storage.
significand
The significand can contain the symbols:
9 . V
An actual decimal point can be represented with a period while an
assumed decimal point is represented by a V. Either an actual or an assumed
decimal point must be present in the
significand; the
decimal point can be leading, embedded or trailing. The
significand can
contain from 1 to 16 numeric characters.
E
Indicates the exponent.
exponent
The exponent must be a PIC "99".
- The OCCURS, REDEFINES and RENAMES clauses can be associated with
external floating-point items.
- The SIGN clause is documentary only and has no effect on the
representation of the sign.
- The SYNCHRONIZED clause is documentary only.
- The following clauses are invalid with external floating-point items:
BLANK WHEN ZERO
JUSTIFIED
VALUE
Elementary Item Size
The size of an elementary item, where size means the number of character
positions occupied by the elementary item in standard data format, is
determined by the number of allowable symbols that represent character
positions. An integer which is enclosed in parentheses following the symbols
"A", ",", "X" , "9", "P",
"Z", "*", "B", "/", "0",
"+", "-", or the currency symbol indicates the number of
replications of the symbol. Note that the following symbols can appear only
once in a given PICTURE: "S" , "V", ".",
"E",
"CR", and "DB".
Symbols Used
The functions of the symbols used to describe an elementary item are
explained as follows:
A |
Each "A" in the character-string represents
a character position which can contain only a letter of the alphabet or a
space. |
B |
Each "B" in the character-string represents
a character position into which the space character will be inserted. |
E |
Marks the start of the exponent in an external
floating-point item. The exponent occupies 1 byte of storage at run time. |
P |
Each "P" indicates an assumed decimal
scaling position and 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 numeric items. The
scaling position character "P" can appear only to the left or right
as a continuous string of "P"s within a PICTURE description; since
the scaling position character "P" implies an assumed decimal point
(to the left of "P" s if "P"s are leftmost PICTURE
characters and to the right if "P"s are rightmost PICTURE
characters), the assumed decimal point symbol "V" is redundant as
either the leftmost or rightmost character within such a PICTURE description.
The character "P" and the insertion character
"." (period) cannot both occur in the same PICTURE character-string.
If, in any operation involving conversion of data from one form of internal
representation to another, the data item being converted is described with the
PICTURE character "P", each digit position described by a
"P" is considered to contain the value zero, and the size of the data
item is considered to include the digit positions so described.
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:
- Any operation requiring a numeric sending operand.
- An elementary MOVE statement where the sending operand is
numeric and its PICTURE character-string contains the symbol "P".
- 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.
- 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 |
The letter "S" is used in a character-string
to indicate the presence, but neither the representation nor, necessarily, the
position of an operational sign; it must be written as the leftmost character
in the PICTURE. The "S" is not counted in determining the size (in
terms of standard data format characters) of the elementary item unless the
entry is subject to a SIGN clause which specifies the optional SEPARATE
CHARACTER phrase. (See the section The SIGN Clause in this chapter.)
|
V |
The letter "V" is used in a character-string
to indicate the location of the assumed decimal point and can only appear 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 |
Each "X" in the character-string is used to
represent a character position which contains any allowable character from the
computer's character set. |
Z |
Each "Z" in a character-string can only be
used to represent the leftmost numeric character positions which will be
replaced by a space character when the contents of that character position is
zero. Each "Z" is counted in the size of the item. |
9 |
Each "9" in the character-string represents
a character position which contains a numeral and is counted in the size of the
item. |
0 |
Each "0" (zero) in the character-string
represents a character position into which the numeral zero will be inserted.
The "0" is counted in the size of the item. |
/ |
Each "/" (slash) in the character-string
represents a character position into which the slash character will be
inserted. The "/" is counted in the size of the item. |
, |
Each "," (comma) in the character-string
represents a character position into which the character "," will be
inserted. This character position is counted in the size of the item. The
insertion character "," must not be the last character in the PICTURE
character-string.
The insertion character
"," can be the last character in the PICTURE character-string.
|
. |
When the character "." (period) appears in
the character-string it is an editing symbol which represents the decimal point
for alignment purposes and, in addition, represents a character position into
which the character "." will be inserted. The character "."
is counted in the size of the item. For a given source unit the functions of
the period and comma are exchanged if the clause DECIMAL-POINT IS COMMA is
stated 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. The insertion character "
." must not be the last character in the PICTURE character-string.
The insertion character
"." can be the last character in the PICTURE character-string.
|
+, -, CR, DB |
These symbols are used as editing sign control
symbols. When used, they represent the character position into which the
editing sign control symbol will be placed. The symbols are mutually exclusive
in any one character-string and each character used in the symbol is counted in
determining the size of the data item. |
* |
Each "*" (asterisk) in the character-string
represents a leading numeric character position into which an asterisk will be
placed when the contents of that position is zero. Each "*" is
counted in the size of the item. |
cs |
The currency symbol in the character-string represents
a character position into which a currency symbol is to be placed. The currency
symbol in a character-string is represented by either the currency sign or by
the single character specified in the CURRENCY SIGN clause in the SPECIAL-NAMES
paragraph. The currency symbol is counted in the size of the item. The
CURRENCY Compiler directive also
affects the currency symbol used. |
Editing Rules
Two general methods of performing editing in the PICTURE clause are
available: insertion or suppression and replacement. Four types of insertion
editing are available:
- Simple insertion
- Special insertion
- Fixed insertion
- Floating insertion
Two types of suppression and replacement editing are available:
- Zero suppression and replacement with spaces
- Zero suppression and replacement with asterisks
The type of editing which can be performed upon an item is dependent
upon the category to which the item belongs. Table 8-1 specifies which type of
editing can be performed upon a given category.
Table 8-1: Editing Types For Data Categories
Category |
Type of Editing |
Alphabetic |
Simple insertion "B" only 1 |
Numeric |
None |
Alphanumeric |
None |
Alphanumeric Edited |
Simple insertion "0", "B" and
"/" |
Numeric Edited |
All 2 |
DBCS |
Simple insertion |
External floating-point |
Special insertion |
Notes:
-
In the ANSI'74 standard,
PICTURE clauses containing both "A" and "B" are treated as
simple insertion in category Alphabetic. As the ANSI'85 standard does not
support "B" in the Alphabetic category, the ANSI'85 standard
considers this PICTURE as simple insertion in the Alphanumeric Edited category.
- Floating insertion editing and editing by zero suppression and
replacement are mutually exclusive in a PICTURE clause. Only one type of
replacement can be used with zero suppression in a PICTURE clause.
Simple
Insertion Editing
The "," (comma), "B" (space), "0" (zero),
and " /" (slash) are used as the insertion characters. The insertion
characters are counted in the size of the item and represent the position in
the item into which the character will be inserted.
Special Insertion Editing
This type of editing is
valid for either numeric edited items or external floating-point items.
The "." (period) is used as the insertion character. In
addition to being an insertion character it represents the decimal point for
alignment purposes. The insertion character used for the actual decimal point
is counted in the size of the item. The use of the assumed decimal point,
represented by the symbol "V" and the actual decimal point,
represented by the insertion character, in the same PICTURE character-string is
disallowed. The result of special insertion editing is the appearance of the
insertion character in the item in the same position as shown in the
character-string.
Fixed
Insertion Editing
The currency symbol and the editing sign control symbols "+" ,
"-", "CR", "DB" are the insertion characters.
Only one currency symbol and only one of the editing sign control symbols can
be used in a given PICTURE character-string. When the symbols "CR" or
"DB" are used, they represent two character positions in determining
the size of the item and they must represent the rightmost character positions
that are counted in the size of the item. The symbol "+" or
"-", when used, must be either the leftmost or rightmost character
position to be counted in the size of the item. The currency symbol must be the
leftmost character.
Table 8-2 : Editing Symbols in PICTURE Character-Strings
Editing Symbol in Picture
Character-string |
Result |
Data Item Positive or Zero |
Data Item Negative |
+ |
+ |
- |
- |
space |
- |
CR |
2 spaces |
CR |
DB |
2 spaces |
DB |
Floating Insertion Editing
The currency symbol and the editing sign control symbols "+"
and "-" are the floating insertion characters and as such are
mutually exclusive in a given PICTURE character-string.
Floating insertion editing is indicated in a PICTURE character-string by
using a string of at least two of the floating insertion characters. This
string of floating insertion characters can contain any of the simple insertion
characters or have simple insertion characters immediately to the right of this
string. These simple insertion characters are part of the floating string.
When the floating insertion character is the currency symbol, this
string of floating insertion characters can have one of the editing sign
control symbols "+", "-", "CR" or " DB"
immediately to the right of this string.
The leftmost character of the floating insertion string represents the
leftmost limit of the floating symbol in the data item. The rightmost character
of the floating string represents the rightmost limit of the floating symbols
in the data item.
The second floating character from the left represents the leftmost
limit of the numeric data that can be stored in the data item. Non-zero numeric
data can replace all the characters at or to the right of this limit.
Floating insertion editing can be represented in a PICTURE
character-string in only two ways. One way is to represent any or all of the
leading numeric character positions on the left of the decimal point by the
insertion character. The other way is to represent all of the numeric character
positions in the PICTURE character-string by the insertion character.
If the insertion characters are only to the left of the decimal point in
the PICTURE character-string, the result is that a single floating insertion
character will be placed into the character position immediately preceding
either the decimal point or the first non-zero digit in the data represented by
the insertion symbol string, whichever is farther to the left in the PICTURE
character-string. The character positions preceding the insertion character are
replaced with spaces.
If all numeric character positions in the PICTURE character-string are
represented by the insertion character, the result depends upon the value of
the data. If the value is zero, the entire data item will contain spaces. If
the value is not zero, the result is the same as when the insertion character
is only to the left of the decimal point.
If all numeric positions in
the PICTURE character string are represented by the insertion character, at
least one numeric position must be to the left of the assumed or actual decimal
point.
To avoid truncation, the minimum size of the PICTURE character-string
for the receiving data item must be the number of characters in the sending
data item, plus the number of non-floating insertion characters being edited
into the receiving data item, plus one for the floating insertion character.
Zero
Suppression Editing
The suppression of leading zeros in numeric character positions is
indicated by the use of the alphabetic character "Z" or the character
"*" (asterisk) as suppression symbols in a PICTURE character- string.
These symbols are mutually exclusive in a given PICTURE character-string. Each
suppression symbol is counted in determining the size of the item. If
"Z" is used, the replacement character will be the space and if the
asterisk is used, the replacement character will be "*".
Zero suppression and replacement is indicated in a PICTURE
character-string by using a string of one or more of the allowable symbols to
represent leading numeric character positions which are to be replaced when the
associated character position in the data contains a zero. Any of the simple
insertion characters embedded in the string of symbols or to the immediate
right of this string are part of the string.
Zero suppression can be represented in a PICTURE character-string in
only two ways. One way is to represent any or all of the leading numeric
character positions to the left of the decimal point by suppression symbols.
The other way is to represent all of the numeric character positions in the
PICTURE character-string by suppression symbols.
If the suppression symbols appear only to the left of the decimal point,
any leading zero in the data which corresponds to a symbol in the string is
replaced by the replacement character. Suppression terminates at the first
non-zero digit in the data represented by the suppression symbol string or at
the decimal point, whichever is encountered first.
If all numeric character positions in the PICTURE character-string are
represented by suppression symbols and the value of the data is not zero, the
result is the same as if the suppression characters were only to the left of
the decimal point. If the value is zero and the suppression symbol is
"Z", the entire data item will be spaces. If the value is zero and
the suppression symbol is "*", the data item will be all
"*" except for the actual decimal point.
The symbols "+", "-", "*", " Z"
and the currency symbol, when used as floating replacement characters, are
mutually exclusive within a given character-string.
Precedence Rules
Table 8-3 shows the order of precedence when using characters as symbols
in a character-string. An "X" at an intersection indicates that the
symbol(s) at the top of the column can precede, in a given character-string,
the symbol(s) at the left of the row. Arguments appearing in braces indicate
that the symbols are mutually exclusive. The currency symbol is indicated by
the symbol "cs". At least one of the symbols "A " ,
"X", "Z", " 9" or "*", or at least two
of the symbols "+" , "-" or "cs" must be present
in a PICTURE string.
In Table 8-3,
non-floating insertion symbols "+" and "" , floating
insertion symbols "Z", "*", " +", "-",
and "cs", and other symbol "P" appear twice in the PICTURE
character precedence chart. The leftmost column and uppermost row for each
symbol represents its use to the left of the decimal point position. The second
appearance of symbol in the row and column represents its use to the right of
the decimal point position.
Table 8-3: PICTURE Character Precedence Chart
First Symbol |
Non-Floating Insertion Symbols |
Floating Insertion Symbols |
Other Symbols |
Second Symbol |
|
B |
0 |
/ |
, |
. |
+ - |
+ - |
CR DB |
CS |
E |
Z * |
Z * |
+ - |
+ - |
CS |
CS |
9 |
A X |
S |
V |
P |
P |
G |
Non-Floating Insertion
Symbols |
B |
x |
x |
x |
x |
x |
x |
|
|
x |
|
x |
x |
x |
x |
x |
x |
x |
x |
|
x |
|
x |
x |
0 |
x |
x |
x |
x |
x |
x |
|
|
x |
|
x |
x |
x |
x |
x |
x |
x |
x |
|
x |
|
x |
|
/ |
x |
x |
x |
x |
x |
x |
|
|
x |
|
x |
x |
x |
x |
x |
x |
x |
x |
|
x |
|
x |
|
, |
x |
x |
x |
x |
x |
x |
|
|
x |
|
x |
x |
x |
x |
x |
x |
x |
|
|
x |
|
x |
|
. |
x |
x |
x |
x |
|
x |
|
|
x |
|
x |
|
x |
|
x |
|
x |
|
|
|
|
|
|
+ - |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
+ - |
x |
x |
x |
x |
x |
|
|
|
x |
x |
x |
x |
|
|
x |
x |
x |
|
|
x |
x |
x |
|
CR DB |
x |
x |
x |
x |
x |
|
|
|
x |
|
x |
x |
|
|
x |
x |
x |
|
|
x |
x |
x |
|
CS |
|
|
|
|
|
x |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
E |
|
|
|
x |
x |
|
|
|
|
|
|
|
|
|
|
|
x |
|
|
x |
|
|
|
Floating Insertion Symbols |
Z * |
x |
x |
x |
x |
|
x |
|
|
x |
|
x |
|
|
|
|
|
|
|
|
|
|
|
|
Z * |
x |
x |
x |
x |
x |
x |
|
|
x |
|
x |
x |
|
|
|
|
|
|
|
x |
|
x |
|
+ - |
x |
x |
x |
x |
|
|
|
|
x |
|
|
|
x |
|
|
|
|
|
|
|
|
|
|
+ - |
x |
x |
x |
x |
x |
|
|
|
x |
|
|
|
x |
x |
|
|
|
|
|
x |
|
|
|
CS |
x |
x |
x |
x |
|
x |
|
|
|
|
|
|
|
|
x |
|
|
|
|
|
|
|
|
CS |
x |
x |
x |
x |
x |
x |
|
|
|
|
|
|
|
|
x |
x |
|
|
|
x |
|
|
|
Other Symbols |
9 |
x |
x |
x |
x |
x |
x |
|
|
x |
x |
x |
|
x |
|
x |
|
x |
x |
x |
x |
|
x |
|
A X |
x |
x |
x |
|
|
|
|
|
|
|
|
|
|
|
|
|
x |
x |
|
|
|
|
|
S |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
V |
x |
x |
x |
x |
|
x |
|
|
x |
|
x |
|
x |
|
x |
|
x |
|
x |
|
x |
|
|
P |
x |
x |
x |
x |
|
x |
|
|
x |
|
x |
|
x |
|
x |
|
x |
|
x |
|
x |
|
|
P |
|
|
|
|
|
x |
|
|
x |
|
|
|
|
|
|
|
|
|
x |
x |
|
x |
|
G |
x |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
x |
Function
The PROPERTY clause
indicates that this data item is a property of the object
in which this data
description is contained and that GET and/or SET methods are to be
generated accordingly.
General Format

Syntax Rules
- The PROPERTY clause can be specified only in the working-storage
section of a factory definition or an object definition.
- The PROPERTY clause must not be specified for data items subordinate
to an OCCURS clause.
- The PROPERTY clause can be specified only for an elementary item
whose name does not require qualification for uniqueness of reference.
- The data-name for the subject of the entry must not be the same as a
property-name defined in a superclass.
Note: A property-name may be defined in a superclass either by
defining a method or a pair of methods with the PROPERTY phrase or by
describing a data description entry with the PROPERTY clause.
General Rules
- If the GET phrase is not specified, the PROPERTY clause causes a
method to be defined for the containing factory or object.
If the subject of this entry is of class index, object, or pointer,
the implicit definition of this method is as follows:
METHOD-ID. GET PROPERTY data-name.
DATA DIVISION.
LINKAGE SECTION.
01 LS-data-name data-description.
PROCEDURE DIVISION RETURNING LS-data-name.
par-name.
SET LS-data-name TO data-name
EXIT METHOD.
END METHOD.
If the subject of this entry is of category alphanumeric-edited,
national-edited, or numeric-edited, the implicit definition of this method is
as follows:
METHOD-ID. GET PROPERTY data-name.
DATA DIVISION.
LINKAGE SECTION.
01 LS-data-name data-description.
PROCEDURE DIVISION RETURNING LS-data-name.
par-name.
MOVE data-name TO LS-data-name (1:).
EXIT METHOD.
END METHOD.
Note: If the subject of the entry is edited, reference
modification of the receiving item as the whole of itself prevents the editing
rules from being reapplied to the data.
Otherwise, the implicit definition of this method is as follows:
METHOD-ID. GET PROPERTY data-name.
DATA DIVISION.
LINKAGE SECTION.
01 LS-data-name data-description.
PROCEDURE DIVISION RETURNING LS-data-name.
par-name.
MOVE data-name TO LS-data-name
EXIT METHOD.
END METHOD.
Where LS-data-name has the data description of the subject of the
entry, including its subordinate items, with the exception of:
- INDEXED BY phrases
- PROPERTY clauses
- VALUE clauses
- a REDEFINES clause in the description of the subject of the
entry.
- If the SET phrase is not specified, the PROPERTY clause causes a
method to be defined for the containing factory or object.
If the subject of this entry is of class index, object, or pointer,
the implicit definition of this method is as follows:
METHOD-ID. SET PROPERTY data-name.
DATA DIVISION.
LINKAGE SECTION.
01 LS-data-name data-description.
PROCEDURE DIVISION USING LS-data-name.
par-name.
SET data-name TO LS-data-name
EXIT METHOD.
END METHOD.
If the subject of this entry is of category alphanumeric-edited,
national-edited, or numeric-edited, the implicit definition of this method is
as follows:
METHOD-ID. SET PROPERTY data-name.
DATA DIVISION.
LINKAGE SECTION.
01 LS-data-name data-description.
PROCEDURE DIVISION USING LS-data-name.
par-name.
MOVE LS-data-name TO data-name (1:).
EXIT METHOD.
END METHOD.
Note: If the subject of the entry is edited, reference
modification of the receiving item as the whole of itself prevents the editing
rules from being reapplied to the data.
Otherwise, the implicit definition of this method is as follows:
METHOD-ID. SET PROPERTY data-name.
DATA DIVISION.
LINKAGE SECTION.
01 LS-data-name data-description.
PROCEDURE DIVISION USING LS-data-name.
par-name.
MOVE LS-data-name TO data-name
EXIT METHOD.
END METHOD.
Where LS-data-name has the data description of the subject of the
entry, including its subordinate items, with the exception of:
- INDEXED BY phrases
- PROPERTY clauses
- VALUE clauses
- a REDEFINES clause in the description of the subject of the
entry.
Function
The RECORD clause specifies
either the number of character positions in a fixed length record or the range
of character positions in a variable length record. If the number of character
positions varies, the clause specifies the minimum and maximum number of
character positions.
The concepts of FIXED and
VARIABLE format files used throughout this section do not directly apply to
LINE SEQUENTIAL files. See your COBOL system documentation on file handling for
details on the implications of using LINE SEQUENTIAL files in your COBOL
implementation.
Although it is a part of the
standard COBOL definition, the RECORD CONTAINS clause is explicitly excluded
from the X/Open COBOL language definitions and should not be used in a
conforming X/Open COBOL source program.
General Formats
Format 1
Format 2
Format 3
Syntax Rules
Format 1
- No record description entry for the file can specify a number of
character positions different from integer-1.
Format 2
-
Record descriptions for the
file must not describe records which contain fewer character positions than
specified by integer-2, nor records which contain a greater number of character
positions than that specified by integer-3.
-
Integer-3 must be greater
than integer-2.
-
Data-name-1 must describe
an elementary unsigned integer in the Working-Storage or Linkage Section.
General Rules
All Formats
- If the RECORD clause is not specified, the size of each data record
is completely defined in the record description entry.
-
If the associated file
connector is an external file connector, all file description entries in the
run unit which are associated with that file connector must specify the same
values for integer-1 or integer-2 and integer-3. If the RECORD clause is not
specified, all record description entries associated with this file connector
must be the same length.
-
Line sequential files are
neither truly fixed nor truly variable format files: the presence or absence of
any RECORDING MODE, RECORD CONTAINS or RECORD VARYING IN SIZE clause does not,
therefore, impact their performance.
Format 1
- Format 1 is used to specify fixed length records. Integer-1 specifies
the number of character positions contained in each record in the file.
Format 2
-
Format 2 is used to specify
variable length records. Integer-2 specifies the minimum number of character
positions to be contained in any record of the file. Integer-3 specifies the
maximum number of character positions in any record of the 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:
- 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.
- 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 integer-2 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.
-
If integer-3 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.
-
If data-name-1 is
specified, 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.
-
If data-name-1 is
specified, 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.
-
During the execution of a
RELEASE, REWRITE, or WRITE statement, the number of character positions in the
record is determined by the following conditions:
- If data-name-1 is specified, by the content of the data item
referenced by data-name-1.
- 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.
- If data-name-1 is not specified and the record does contain a
variable occurrence data item, by the sum of the fixed portion and that portion
of the table described by the number of occurrences at the time of execution of
the output statement.
If the number of character positions in the logical record which is
to be written is less than integer-2 or greater than integer-3, the output
statement is unsuccessful and, except during execution of a RELEASE statement,
the associated I/O status is set to a value indicating the cause of the
condition.
-
If data-name-1 is
specified, after the successful execution of a READ or RETURN statement for the
file, the contents of the data item referenced by data-name-1 will indicate the
number of character positions in the record just read.
-
If the INTO phrase is
specified in the READ or RETURN 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: a.
- If data-name-1 is specified, by the content of the data item
referenced by data-name-1.
- 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.
Format 3
- When format 3 of the RECORD clause is used, integer-4 and integer-5
refer to the minimum number of characters in the smallest size data record and
the maximum number of characters in the largest size data record respectively.
However, in this case, the size of each data record is completely defined in
the record description entry.
- The size of each data record is specified in terms of the number of
character positions required to store the logical record, regardless of the
types of characters used to represent the items within the logical record. The
size of a record is determined by the sum of the number of characters in all
fixed length elementary items plus the sum of the maximum number of characters
in any variable length item subordinate to the record. This sum can be
different from the actual size of the record. See the section Selection of
Character Representation and Radix in the chapter Concepts of the COBOL
Language, and the sections The SYNCHRONIZED Clause and The USAGE
Clause in this chapter.
Function
The RECORDING MODE clause specifies the format of the logical records in
the file.
General Formats
Format 1 (Record Sequential Files)
Format 2 (Line Sequential Files)
Format 3 (Relative and Indexed Files)
Syntax Rules
-
F and FIXED are synonyms.
-
V and VARIABLE are
synonyms.
General Rules
All Formats (All Files)
- Specifying RECORDING MODE IS F causes all the records in the file to
be the same length.
Format 1 (Record Sequential Files)
-
The "U" option is
documentary only.
Formats 1 and 3 (Record Sequential, Relative and Indexed
Files)
- When RECORDING MODE IS V is specified, the records in the file can be
either fixed or variable in length. Each data record includes a record length
field. These fields are not part of the record description.
Format 2
-
Line sequential files are
neither truly fixed nor truly variable format files: the presence or absence of
any RECORDING MODE, RECORD CONTAINS or RECORD VARYING IN SIZE clause does not,
therefore, impact their performance.
Function
The REDEFINES clause allows the same computer storage area to be
described by different data description entries.
General Format
Note that level-number and data-name-1
or FILLER
are shown in the above format to improve clarity. Level-number, and
data-name-1
and FILLER
are not part of the REDEFINES clause.
Syntax Rules
- The REDEFINES clause, when specified, must immediately follow
data-name-1
or FILLER,
or it can follow the
PICTURE or USAGE clause.
- The level-numbers of data-name-1 and data-name-2 must be identical
but must not be 66,
78
or 88.
- This clause must not be used in level 01 entries in the File Section,
since multiple level 01 entries subordinate to an FD or SD indicator represent
implicit redefinitions of the same areas. (See General Rule 2 of the section
The DATA RECORDS Clause in this chapter.)
This clause can be used
on level 01 entries in the File Section.
-
The data description for
data-name-2 can contain a REDEFINES clause and
data-name-2 can be subordinate to an entry which contains a
REDEFINES clause. Its data description cannot contain an OCCURS clause.
However, data-name-2 can be subordinate to an item whose data description entry
contains an OCCURS clause. In this case, the reference to data-name-2 in the
REDEFINES clause cannot be subscripted or indexed. Neither the original
definition nor the redefinition can include an item whose size is variable as
defined in the OCCURS clause. (See the section The OCCURS Clause in this
chapter.)
The data description for
data-name-2 can contain an OCCURS clause.
If the level number is
01, either or both of the original definition and the redefinition can include
an item whose size is variable as defined in the OCCURS clause.
- No entry having a level-number numerically lower than the
level-number of data-name-2 and data-name-1 can occur between the data
description entries of data-name-2 and data-name-1.
-
An external or internal
floating-point data item can be the subject or object of a REDEFINES clause.
-
Data-name-2 must not be
qualified even if it is not unique since no ambiguity of reference exists in
this case because of the required placement of the REDEFINES clause
.
Data-name-2 may be
qualified but any qualification specified is ignored.
- The entries giving the new description of the character positions
must not contain any VALUE clauses except in condition-name entries.
-
The REDEFINES clause must
not be specified for a data item of class object.
The REDEFINES clause may
be specified for a data item of class object.
-
Data-name-2 must not be of
class object.
Data-name-2 may be of
class object.
General Rules
- Redefinition starts at data-name-2 and ends when a level-number less
than or equal to that of data-name-2 is encountered.
- When the level-number of data-name-1 is other than 01, it must
specify the same number of character positions that the data item referenced by
data-name-2 contains
except that the
data-name-1 area can be either smaller than the data-name-2 area
or be larger than the
data-name-2 area. In this case, extra storage is reserved to provide sufficient
storage for the number of character positions in the largest of the redefining
or redefined items.
It is important to observe that the REDEFINES clause specifies the
redefinition of a storage area, not of the data items occupying the area.
- Multiple redefinitions of the same character positions are permitted.
The entries giving the new descriptions of the character positions must follow
the entries defining the area being redefined, without intervening entries that
define new character positions. Multiple redefinitions of the same character
positions must all use the data-name of the entry that originally defined the
area
or the data-name of any
other preceding redefinition of that entry.
- Multiple level 01 entries subordinate to any given level indicator
(FD
or SD) represent implicit redefinitions of the same area.
Function
The RENAMES clause permits alternative, possibly overlapping, groupings
of elementary items.
General Format
Level-number 66 and data-name-1 are shown in the above format to improve
clarity. Level-number and data-name-1 are not part of the RENAMES clause.
Syntax Rules
- Any number of RENAMES entries can be written for a logical record.
- All RENAMES entries referring to data items within a given logical
record must immediately follow the last data description entry of the
associated record description entry.
- Data-name-2 and data-name-3 must be names of elementary items or
groups of elementary items in the same logical record, and cannot be the same
data-name. A 66 level entry cannot rename another 66 level entry, nor can it
rename a 77,
78,
88, or 01 entry.
A 66 level entry may
rename another 66 level entry or a level 77 or level 01 entry.
- Data-name-1 cannot be used as a qualifier, and can be qualified only
by the names of the associated level 01, FD
or SD entries. Neither data-name-2 nor data-name-3 can have an OCCURS
clause in its data description entry, nor be subordinate to an item that has an
OCCURS clause in its data description entry. (See the section The OCCURS
Clause.)
- The beginning of the area described by data-name-3 must not be to the
left of the beginning of the area described by data-name-2. The end of the area
described by data-name-3 must be to the right of the end of the area described
by data-name-2. Data-name-3, therefore, cannot be subordinate to data-name-2.
- Data-name-2 and data-name-3 can be qualified.
- The words THRU and THROUGH are equivalent.
- None of the items within the range, including data-name-2 and
data-name-3, if specified, can be an item whose size is variable as defined in
the section The OCCURS Clause in this chapter.
General Rules
- When data-name-3 is specified, data-name-1 is a group item which
includes all elementary items starting with data-name-2 (if data-name-2 is an
elementary item) or the first elementary item in data-name-2 (if data-name-2 is
a group item), and concluding with data-name-3 (if data-name-3 is an elementary
item) or the last elementary item in data-name-3 (if data-name-3 is a group
item).
- When data-name-3 is not specified, all of the attributes of
data-name-2 become the data attributes for data-name-1.
-
When data-name-2 and
data-name-3 are not explicitly qualified and when no ambiguity of reference
exists, implied qualification of the 01 level item is used.
Function
The SIGN clause specifies the position and the mode of representation of
the operational sign when it is necessary to describe these properties
explicitly.
General Format
Syntax Rules
- The SIGN clause can be specified only for a numeric data description
entry whose PICTURE contains the character "S" , or a group item
containing at least one such numeric data description entry.
- The numeric data description entries to which the SIGN clause applies
must be described, implicitly or explicitly, as USAGE IS DISPLAY.
- At most one SIGN clause can apply to any given numeric data
description entry.
This rule is removed.
- If the CODE-SET clause is specified, any signed numeric data
description entries associated with that file description entry must be
described with the SIGN IS SEPARATE clause.
This restriction is not
enforced. See the section The CODE-SET Clause in this chapter.
General Rules
- The optional SIGN clause, if present, specifies the position and the
mode of representation of the operational sign for the numeric data description
entry to which it applies, or for each numeric data description entry
subordinate to the group to which it applies. The SIGN clause applies only to
numeric data description entries whose PICTURE contains the character
"S"; the "S" indicates the presence of, but neither the
representation nor, necessarily, the position of the operational sign.
- A numeric data description entry whose PICTURE contains the character
"S", but to which no optional SIGN clause applies, has an operational
sign, but neither the representation nor, necessarily, the position of the
operational sign is specified by the character "S". In this (default)
case, General Rules 3 through 5 do not apply to such signed numeric data items.
The representation of the default operational sign is defined in the
sectionSelection Of Character Representation And Radix in the chapter
Concepts of the COBOL Language.
- If the optional SEPARATE CHARACTER phrase is not present, then:
- the operational sign will be presumed to be associated with the
leading (or, respectively, trailing) digit position of the elementary numeric
data item in a manner defined in the section Selection Of Character
Representation And Radix in the chapter Concepts of the COBOL
Language.
- the letter "S" in a PICTURE character-string is not
counted in determining the size of the item (in terms of standard data format
characters).
- If the optional SEPARATE CHARACTER phrase is present, then:
- the operational sign will be presumed to be the leading (or,
respectively, trailing) character position of the elementary numeric data item;
this character position is not a digit position.
- the letter "S" in a PICTURE character-string is counted
in determining the size of the item (in terms of standard data format
characters).
- the operational signs for positive and negative are the standard
data format characters "+" and "", respectively.
- Every numeric data description entry whose PICTURE contains the
character "S" is a signed numeric data description entry. If a SIGN
clause applies to such an entry and conversion is necessary for purposes of
computation or comparisons, conversion takes place automatically.
-
If a SIGN clause is
specified for an item (either an elementary numeric data description entry or a
group item) which is subordinate to a group item for which a SIGN clause is
also specified, then the SIGN clause specified in the subordinate item takes
precedence.
-
The SIGN clause is
treated as documentary for external floating-point items. For internal
floating-point items, the SIGN clause is invalid and will result in a
diagnostic message.
Function
The SYNCHRONIZED clause specifies the alignment of an elementary item on
the natural boundaries of the computer memory.
Although it is a part of the
standard COBOL definition, this feature is explicitly excluded from the X/Open
COBOL language definitions and should not be used in a conforming X/Open COBOL
source program.
General Format
Directives
- In addition to Compiler directives which provide flagging and modify
the reserved word list, the following directive may impact either the syntax or
semantics described in this section.
- IBMCOMP When NOIBMCOMP is specified, the SYNCHRONIZED clause is
treated as documentary only.
Syntax Rules
- This clause should appear only with an elementary item.
The SYNCHRONIZED clause
can appear with a non-elementary item.
- SYNC is an abbreviation for SYNCHRONIZED.
General Rules
- SYNCHRONIZED RIGHT specifies that the elementary item is to be
positioned so that it will terminate on the right character position of the
natural boundary in which the elementary item is placed.
It takes effect only if the IBMCOMP Compiler directive is set.
- Specification of the LEFT phrase in the SYNCHRONIZED clause will have
no effect.
- The effect of the SYNCHRONIZED clause is, by definition,
implementation-dependent.
- This clause specifies that the subject data item is to be aligned in
the computer so that no other data item occupies any of the character positions
between the leftmost and rightmost natural boundaries of the computer memory
which delimits this data item.
If the number of character positions required to store this data
item is less than the number of character positions between those natural
boundaries, the unused character positions (or portions thereof) must not be
used for any other data item. Such unused character positions are, however,
included in:
- the size of any group item(s) to which the elementary item
belongs, and:
- the character positions redefined when this data item is the
object of a REDEFINES clause.
Thus the size of an elementary item is unchanged by the SYNCHRONIZED
clause, but extra character positions are assigned by the use of the clause.
- SYNCHRONIZED not followed by either RIGHT or LEFT specifies that the
elementary item is to be positioned between natural boundaries so that it uses
the elementary data item efficiently.
- Whenever a SYNCHRONIZED item is referenced
, the original size of the item, as shown in the PICTURE clause, is
used in determining any action that depends on size, such as justification,
truncation or overflow.
- If the data description of an item contains the SYNCHRONIZED clause
and an operational sign, the sign of the item appears in the normal operational
sign position, regardless of whether the item is SYNCHRONIZED LEFT or
SYNCHRONIZED RIGHT.
- When the SYNCHRONIZED clause is specified in a data description entry
of a data item that also contains an OCCURS clause, or in a data description
entry of a data item subordinate to a data description entry that contains an
OCCURS clause, then:
- each occurrence of the data item is SYNCHRONIZED.
- any implicit FILLER generated for other data items within that
same table is generated for each occurrence of those data items.
-
If the SYNCHRONIZED clause
is specified with a non-elementary item, then the clause applies to all the
items subordinate to that non-elementary item.
- The effect of using the SYNCHRONIZED clause is discussed in the
section Selection Of Character Representation And Radix in the chapter
Concepts of the COBOL Language.
Function
The THREAD-LOCAL clause specifies that there is a distinct copy of a
data item or file connector for each thread entering a program.
General Format
IS THREAD-LOCAL
Syntax Rules
- The THREAD-LOCAL clause can be specified only in file description
entries or in record description entries in the Working-Storage Section.
General Rules
- If the THREAD-LOCAL clause is specified, a separate copy of the file
connector or data item is created and set to its initial state for each new
thread of execution that enters the program. The file connector or data item is
only visible to the thread causing its creation. The file connector or data
item is destroyed when the creating thread's execution terminates or when a
CANCEL statement on the program is executed; otherwise, on subsequent calls to
the program within that thread, the data item or file connector is in its last
used state.
- If the THREAD-LOCAL clause is not specified, the file connector or
data item is shared by all threads entering the program.
- In a single-threaded environment, the clause is ignored and the
program behaves exactly as if the THREAD-LOCAL clause had not been specified.
Function
The TYPEDEF clause defines a record as a programmer-defined type
definition.
General Format
Syntax Rules
- The TYPEDEF clause can be specified only in data description entries
whose level-number is 01.
- If TYPEDEF is specified, the following clauses cannot be specified:
- EXTERNAL
- GLOBAL
- OCCURS
- REDEFINES
- SYNCHRONIZED/SYNC
- VALUE
If the TYPEDEF clause is specified for a group item, then
subordinate items can be specified with OCCURS or REDEFINES clauses.
The VALUE clause cannot be specified either in the data descriptions
specifying the TYPEDEF clause or in any subordinate item except for
condition-names (88 level entries) within the TYPEDEF structure.
- If the TYPEDEF clause is specified for a data description, then that
same data description must include a data-name, that is, it must not be
specified with either an implicit or explicit FILLER clause.
-
If a TYPEDEF clause is specified in
a call prototype (a
program with the EXTERNAL clause in its PROGRAM-ID paragraph) then that
TYPEDEF can be referenced in any subsequent source line of the compilation
group.
General Rules
- The purpose of using the TYPEDEF clause is to create a
programmer-defined usage or structure that can subsequently be referenced in
the USAGE clause.
- A record declared with the TYPEDEF clause does not allocate any
storage, but declares that data-name-1 can be specified in a subsequent data
description entry as typedef-name-1.
Function
The USAGE clause specifies the format of a data item in the computer
storage.
General Format
Directives
- In addition to Compiler directives which provide flagging and modify
the reserved word list, the following directives may impact either the syntax
or semantics described in this section.
- COBOL370 - controls whether four or eight bytes of storage are
allocated to USAGE PROCEDURE-POINTER data items.
- COMP-5 - controls the handling of the operational sign when
storing into a USAGE COMP-5 data item.
- IBMCOMP - controls the storage allocated for USAGE COMP and USAGE
COMP-5 data items.
Syntax Rules
- The USAGE clause may be written in any data description entry with an
entry-number other than 66 or 88.
- If the USAGE clause is written in the data description entry for a
group item, it may also be written in the data description entry for any
subordinate elementary item or group item, but the same usage must be specified
in both entries.
- An elementary data item whose declaration contains, or an elementary
data item subordinate to a group item whose declaration contains, a USAGE
clause specifying COMPUTATIONAL
, BINARY, PACKED-DECIMAL
, COMPUTATIONAL-3
, COMPUTATIONAL-4
, or COMPUTATIONAL-5
must be declared with a PICTURE character-string that describes a
numeric item (i.e. a PICTURE character-string that contains only the symbols
"P", "S", "V", and "9"). See the
section The PICTURE Clause earlier in this chapter.
An elementary data item
whose declaration contains no USAGE clause and that is subordinate to a group
item whose declaration contains a USAGE clause specifying a format from the
list may be declared with a PICTURE character-string that describes an
alphabetic, alphanumeric, alphanumeric-edited or numeric-edited data item.
-
An elementary data item whose declaration contains, or
an elementary data item subordinate to a group item whose declaration contains,
a USAGE clause specifying COMPUTATIONAL-5
or COMPUTATIONAL-X
must be declared with a picture
character-string that describes a numeric item
or describes an
alphanumeric item with a size of between one and eight bytes inclusive. If it
describes an alphanumeric item of size 1, 2, 3, 4, 5, 6, 7, or 8 bytes, then
this is equivalent to specifying an integer item with 2, 4, 7, 9, 12, 14, 16 or
18 decimal digit positions respectively.
When COMPUTATIONAL-X is
specified and the PICTURE character-string describes a numeric item, then that
item must be unsigned.
- The BLANK WHEN ZERO, JUSTIFIED and SIGN clauses must not be specified
for data items whose usage is not explicitly or implicitly DISPLAY.
- The SYNCHRONIZED and VALUE clauses must not be specified for data
items whose usage is INDEX.
The SYNCHRONIZED clause
can be specified for data items whose usage is INDEX.
- COMP is an abbreviation for COMPUTATIONAL.
COMP-1 is an
abbreviation for COMPUTATIONAL-1.
COMP-2 is an abbreviation for
COMPUTATIONAL-2.
COMP-3 is an
abbreviation for COMPUTATIONAL-3.
COMP-4 is an
abbreviation for COMPUTATIONAL-4.
COMP-5 is an abbreviation for
COMPUTATIONAL-5.
COMP-X is an
abbreviation for COMPUTATIONAL-X.
- An index item can be referenced explicitly only in a SEARCH or SET
statement, a relation condition, the USING phrase of a Procedure Division,
the USING statement of
an ENTRY statement,
or the USING phrase of a CALL statement.
-
A pointer
or procedure-pointer
item can be referenced
explicitly only in a SET statement, a relation condition, the USING phrase of a
CALL statement, the USING phrase of a Procedure Division, the USING statement
of an ENTRY statement
the USING phrase of an
INVOKE statement, the argument list of a function,
the GIVING phrase of a
CALL statement
or the GIVING phrase of
an INVOKE statement.
- An elementary data item described with usage INDEX,
OBJECT,
POINTER,
EVENT-POINTER,
MONITOR-POINTER, MUTEX-POINTER, PROCEDURE-POINTER, SEMAPHORE-POINTER or
THREAD-POINTER
clause must not be a conditional variable.
-
Typedef-name-1 must be
previously defined in the same source file as a record with the TYPEDEF clause.
-
If USAGE typedef-name-1 is
specified, the following clauses cannot also be specified:
- BLANK
- JUSTIFIED
- PICTURE
- SIGN
- SYNCHRONIZED
- VALUE
-
It is an error to specify
USAGE typedef-name-1 if there is an explicit USAGE clause at a higher level in
the same hierarchy.
-
It is an error to specify
any subordinate items (items with a higher level number other than 78)
immediately following an item defined with USAGE typedef-name-1.
-
The USAGE OBJECT
REFERENCE clause must not be specified in the data description entry for a
group item, but may be specified on subordinate elementary data items.
-
The USAGE OBJECT REFERENCE
clause must not be specified in the File Section.
The USAGE OBJECT
REFERENCE clause can be specified in the File Section.
Note:Whether the object reference still references an
active object depends on the application logic.
-
The ACTIVE-CLASS phrase can
be specified only in a factory definition, object definition, or method
definition.
-
A data item whose usage is
EVENT-POINTER can be referenced explicitly only in a CLOSE statement, an OPEN
statement, a SET statement, a WAIT statement or a USING phrase.
-
A data item whose usage is
MONITOR-POINTER, MUTEX-POINTER, or SEMAPHORE-POINTER can be referenced
explicitly only in a CLOSE statement, an OPEN statement, a SET statement or a
USING phrase.
-
A data item whose usage is
THREAD-POINTER can be referenced explicitly only in a START statement, a WAIT
statement or a USING phrase.
General Rules
- If the USAGE clause is written at the group level, it applies to each
elementary item in the group
except when there is a
PICTURE clause and the data item described is non-numeric
- The USAGE clause specifies the manner in which a data item is
represented in the storage of the computer. It does not affect the use of the
data item, although the specifications for some statements in the Procedure
Division may restrict the USAGE clause of the operands referred to. The USAGE
clause may affect the radix or type of character representation of the item.
See the section Selection of Character Representation and Radix in the
chapter Concepts of the COBOL Language for more details of the format of
each usage.
- The USAGE IS BINARY clause specifies that a radix of 2 is used to
represent a numeric item in the storage of the computer. This clause is
equivalent to specifying USAGE IS COMPUTATIONAL.
- The USAGE IS PACKED-DECIMAL clause specifies that a radix of 10 is
used to represent a numeric item in the storage of the computer. Furthermore,
this clause specifies that each digit position must occupy the minimum possible
configuration in computer storage.
This clause is
equivalent to specifying USAGE IS COMPUTATIONAL-3.
- The USAGE IS DISPLAY clause (whether specified explicitly or
implicitly) specifies that a standard data format is used to represent a data
item in the storage of the computer, and that the data item is aligned on a
character boundary.
-
The USAGE IS DISPLAY
clause is valid for the following types of items:
- Alphabetic
- Alphanumeric
- Alphanumeric edited
- Numeric edited
- External floating-point
- External decimal (numeric)
- If the USAGE clause is not specified for an elementary item, or for
any group to which the item belongs, the USAGE is implicitly DISPLAY.
- The USAGE IS INDEX clause specifies that a data item is an index data
item and contains a value which must correspond to an occurrence number of a
table element.
- When a MOVE statement or an input-output statement that references a
group item that contains an index,
or pointer,
or procedure-pointer
data item is executed, no conversion of the index,
or pointer
or procedure-pointer
data item takes place.
-
The USAGE IS
COMPUTATIONAL-4 clause is equivalent to specifying USAGE IS COMPUTATIONAL.
-
The USAGE IS POINTER
clause identifies a data item in which you can store the address of a data item
(see the section The SET Statement in this chapter).
-
The USAGE IS PROCEDURE-POINTER clause
specifies that a data item is a procedure pointer data item in which you can
store the address of a procedure. (See the SET statement in this chapter.) The
procedure can be written in any language: if COBOL, it represents the Procedure
Division of a program that is not nested and identified by either:
- the program-name of the PROGRAM-ID paragraph; or
- the entry-name of an ENTRY statement.
-
If typedef-name-1 was
specified as an elementary item, then the USAGE typedef-name-1 clause specifies
an elementary item with the same attributes as the programmer-defined usage
referenced by typedef-name-1.
-
If typedef-name-1 was
specified as a group item, then the USAGE typedef-name-1 clause specifies a
group item with an identical structure. The effect is as if the data
declarations subordinate to the data description entry identified by
typedef-name-1 had been specified identically, subordinate to the item declared
with the USAGE typedef-name-1 clause. Data-names of the subordinate data items
are identical to those declared within the programmer-defined structure
referenced by typedef-name-1 and can be uniquely referenced using
qualification.
-
A data item described with
a USAGE OBJECT REFERENCE clause is called an object reference. An object
reference is a data item of class object and category object-reference. It
shall contain either null or a reference to an object, subject to the following
rules:
- The amount of storage allocated for an object reference data item
is four bytes.
- If none of the optional phrases is specified, this data item is
called a universal object reference. Its content may be a reference to any
object.
- If interface-name-1 is specified, the object referenced by this
data item must conform to the interface referenced by interface-name-1.
- If class-name-1 is specified, the object referenced by this data
item must be an object of class-name-1 or of a subclass of class-name-1,
subject to the following rules:
- If the ONLY phrase is not specified:
- If the FACTORY phrase is specified, the object referenced
by this data item must be the factory object of the specified class or of a
subclass of the specified class.
- If the FACTORY phrase is not specified, the object
referenced by this data item must be an object of the specified class or of a
subclass of the specified class.
- If the ONLY phrase is specified:
- If the FACTORY phrase is specified, the object referenced
by this data item must be the factory object of the specified class.
- If the FACTORY phrase is not specified, the object
referenced by this data item must be an object of the specified class.
- If ACTIVE-CLASS is specified, the object referenced by this data
item must be an object of the class of the object that was used to invoke the
method in which the object referenced is specified, subject to the following
rules:
- If the FACTORY phrase is specified, the object referenced by
this data item must be the factory object of that class.
- If the FACTORY phrase is not specified, the object referenced
by this data item must be an object of that class.
-
The USAGE IS EVENT-POINTER
clause identifies an synchronization data item that flags an occurrence of a
software event. An event data item has a value of either TRUE or FALSE.
-
The USAGE IS
MONITOR-POINTER clause identifies a synchronization data item, known as a
monitor, on which one can request read locks, browse locks, and write locks.
Note:A monitor is typically used to protect a data
structure that different threads might want to read from or read from and write
to.
-
The USAGE IS MUTEX-POINTER
clause identifies a synchronization data item, known as a mutex, that can be
used to protect critical sections in a multi-threaded application. A mutex data
item has a value of either ON or OFF. Only one thread can have a mutex data
item in the ON state at a time.
-
The USAGE IS
SEMAPHORE-POINTER clause identifies a counting synchronization data item that
cannot go below zero.
-
The USAGE IS THREAD-POINTER
clause identifies a data item in which you can store the handle for a thread.
Function
The VALUE clause defines the value of constants, the initial value of
working storage items, and the values associated with a condition name.
Examples:
- An example of using the NEXT clause is provided in the
Examples chapter in your Additional Topics.
General Formats
Format 1
Format 2
Format 3
Syntax Rules
All Formats
- A signed numeric literal must have a signed numeric PICTURE
character-string associated with it.
- All numeric literals in a VALUE clause of an item must have values
which are within the range of values indicated by the PICTURE clause, and must
not have a value which would require truncation of nonzero digits. Nonnumeric
literals in a VALUE clause of an item must not exceed the size indicated by the
PICTURE clause.
- A figurative constant can be substituted in both Format 1 and Format
2 wherever a literal is specified.
Format 1
-
VALUES ARE can be used with
Format 1.
-
The VALUE clause may not
be used with external floating-point data items.
The VALUE clause may be
used with external floating-point data items.
-
The VALUE clause may be
used for an internal floating-point data item, that is an item defined with
USAGE COMP-1 or USAGE COMP-2. In this case literal-1 must either be a
floating-point literal, the figurative constant ZERO, or a numeric literal
representing the value zero.
Format 2
- The words THRU and THROUGH are equivalent.
- Any number of Format 2 entries can be written for a data item.
- Format 2 must be used only in connection with a condition-name.
- In a condition-name entry, the VALUE clause is required. The VALUE
clause and the condition-name itself are the only two clauses permitted in the
entry.
- Literal-2 must be less than literal-3.
-
Format 2 may be used to
define a conditional-variable associated with an internal floating-point data
item, but not an external floating-point data item. In this case, literal-2 and
literal-3 must be floating-point literals, the figurative constant ZERO, or
numeric literals representing the value zero.
Format 2 may be used to
define a condition-variable associated with an external floating-point data
item.
-
Literal-4 must not be equal
to any literal-2, and in any literal-2 THROUGH literal-3 pair, literal-4 cannot
be greater than or equal to literal-2 and less than or equal to literal-3.
Format 3
-
All identifiers must have
been defined before the declaration of the level 78 item. If either
identifier-1 or identifier-3 (LENGTH parameters) is a group item, the
definition of that group must have been completed before the level 78
declaration, by the appearance of another data item at the same or lower level
number.
General Rules
Formats 1 and 2
- The VALUE clause must not conflict with other clauses in the data
description of the item or in the data description within the hierarchy of the
item. The following rules apply:
- If the category of the item is numeric, all literals in the VALUE
clause must be numeric. If the literal defines the value of a working storage
item, the literal is aligned in the data item according to the standard
alignment rules. (See the section Standard Alignment Rules in the
chapter Concepts of the COBOL Language.)
- If the category of the item is alphabetic, alphanumeric,
alphanumeric edited or numeric edited all literals in the VALUE clause must be
nonnumeric. The literal is aligned in the data item as if the data item had
been described as alphanumeric. (See the section Standard Alignment
Rules in the chapter Concepts of the COBOL Language.) Editing
characters in the PICTURE clause are included in determining the size of the
data item (see the section The PICTURE Clause earlier in this chapter)
but have no effect on initialization of the data item. Therefore, the VALUE for
an edited item is presented in an edited form.
-
If the item is numeric
edited, the value can be a numeric literal or a nonnumeric literal. If the
value is a numeric literal, the value contained in the item will be the same as
if the numeric literal were moved to the numeric edited item.
- Initialization takes place independent of any BLANK WHEN ZERO or
JUSTIFIED clause that can be specified.
Data Description Entries Other than Condition-Names
and
Constant-Names
(Format 1)
- Rules governing the use of the VALUE clause differ with the
respective sections of the Data Division:
- In the File Section, the VALUE clause must be used in
condition-name entries only.
- In the Working-Storage Section,
the VALUE clause must be used in condition-name entries. The VALUE
clause can also be used to specify the initial value of a data item, in which
case the clause causes the item to assume the specified value at the time the
runtime element is placed into its initial state. If the VALUE clause is not
used in an item's description, the initial value of that data item is
undefined.
- In the Linkage Section, the VALUE clause must be used in
condition-name entries only.
-
In the File Section and
the Linkage Section,
and Local-Storage
Section,
the VALUE clause can be
used in data item entries, but is documentary only.
- The VALUE clause must not be stated in a data description entry that
contains a REDEFINES clause, or in an entry that is subordinate to an entry
containing a REDEFINES clause. This rule does not apply to condition-name
entries.
- If the VALUE clause is used in an entry at the group level, the
literal must be a figurative constant or a nonnumeric literal, and the group
area is initialized without consideration for the individual elementary or
group items contained within this group. The VALUE clause cannot be stated at
the subordinate levels within this group.
- The VALUE clause must not be written for a group containing items
with descriptions, including JUSTIFIED, SYNCHRONIZED, or USAGE (other than
USAGE IS DISPLAY).
-
The figurative constant NULL can be specified in the VALUE clause only if the
data item is defined with USAGE POINTER or USAGE PROCEDURE-POINTER. This is the
only value you can specify in the VALUE clause for such an item. The effect is
to set the pointer in such a way that it is guaranteed not to point to any data
item.
-
A VALUE clause specified in
a data description entry that contains an OCCURS clause, or in an entry that is
subordinate to an OCCURS clause, causes every occurrence of the associated data
item to be assigned the specified value.
-
If a VALUE clause is
specified in a data description entry of a data item which is associated with a
variable occurrence data item, the initialization of the data item behaves as
if the value of the data item referenced by the DEPENDING ON phrase in the
OCCURS clause specified for the variable occurrence data item is set to the
maximum number of occurrences as specified by that OCCURS clause. A data item
is associated with a variable occurrence data item in any of the following
cases:
- It is a group data item which contains a variable occurrence data
item.
- It is a variable occurrence data item.
- It is a data item that is subordinate to a variable occurrence
data item.
If a VALUE clause is associated with the data item referenced by a
DEPENDING ON phrase, that value is considered to be placed in the data item
after the variable occurrence data item is initialized.
-
A data item of class object
is initialized to null. The initial value takes effect when VALUE clauses take
effect and when storage for the data item is allocated.
-
A data item of class
pointer is initialized to null. The initial value takes effect when VALUE
clauses take effect and when storage for the data item is allocated.
Condition-Name Rules (Format 2)
- In a condition-name
entry, the VALUE clause is required. The VALUE clause and the condition-name
itself are the only two clauses permitted in the entry. The characteristics of
a condition-name are implicitly those of its conditional variable.
- Format 2 can be used only in connection with condition-names.
Wherever the THRU phrase is used, literal-2 must be less than literal-3.
- The FALSE phrase is meaningful only if the associated condition-name
is referenced in a SET condition-name TO FALSE statement. (See the section
The SET Statement later in this chapter.)
Constant-Name Rules (Format 3)
-
Format 3 can be used only
in a constant-name entry.
-
If literal-5 is specified
and not followed by an operator, the characteristic of the constant-name is
that of literal-5. Otherwise, the characteristic of the constant-name is that
of an integer.
-
Any number of arithmetic or logical operators can be used. The result is
evaluated using integer arithmetic in strict left to right order. No
parentheses can be used. If any intermediate result is less than zero, the
final value is undefined. A constant-name may be used in place of integer-1.
-
The logical operations AND
and OR act on the binary representation in a bit-wise manner.
-
LENGTH of identifier-1 or
identifier-3 is the size of the storage allocated for identifier-1 or
identifier-3, respectively. If the identifier is a group item, the length
includes all subordinate data items.
-
The value returned by NEXT
is the offset at which the next byte of storage occurs after the previous data
declaration. If that data declaration was of a table defined with an OCCURS
clause, the value returned by NEXT is the offset at which the next byte of
storage occurs after the first element of the table.
-
START of identifier-2 or
identifier-4 is the offset at which identifier-2 or identifier-4, respectively,
begins.
-
For rules 18 and 19, the
offset is defined as follows:
- If the identifier is part of an EXTERNAL record or a LINKAGE
record, the offset is calculated from the start of the associated 01-level;
- If the identifier is defined in LOCAL-STORAGE, the offset is
calculated from the start of the LOCAL-STORAGE SECTION;
- Otherwise the offset is calculated from the start of the DATA
DIVISION.
-
Offsets are not portable
across different COBOL implementations and no reliance should be placed on
particular values outside this compilation unit.
Function
The VALUE OF clause specifies the description of an item in the label
records associated with a file.
The VALUE OF clause of the
file description entry is classed as an obsolete element in the ANSI'85
standard and is scheduled to be deleted from the next full revision of the ANSI
Standard.
All dialects in this COBOL
implementation fully support this syntax. The FLAGSTD Compiler directive can be
used to detect all occurrences of this syntax.
Although it is a part of the
standard COBOL definition, this feature is explicitly excluded from the X/Open
COBOL language definitions and should not be used in a conforming X/Open COBOL
source program.
General Formats
Format 1 (All Files)
Format 2 (All Files)
Syntax Rules
Format 1 (All Files)
- Data-name-1 should be qualified when necessary but cannot be
subscripted or indexed, nor can it be an item described with the USAGE IS INDEX
clause.
Format 2 (All Files)
-
Data-name-2 must be in the
Working-Storage Section.
-
Literal-2 must be a
nonnumeric literal and cannot be a figurative constant.
-
The VALUE OF FILE-ID clause
cannot be used if external-file-reference, data-name-1 or literal-1 has been
specified in the ASSIGN clause in the File-Control Entry (see the section
The File-Control Entry earlier in this chapter).
General Rules
Format 1 (All Files)
-
This clause is documentary
only.
Format 2 (All Files)
-
The character-string
specified in literal-2 or data-name-2 is taken as the external file-name.
Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.