| Procedure Division - SEARCH - WRITE |
|
Compiler-directing Statements | |
This chapter describes the COBOL syntax that has been added to support
object orientation. Since all of this syntax is an extension to ANS X3.23 - 1985
that is specific to Micro Focus COBOL, the box around this chapter has
been omitted. For a full description of the object orientation facility,
see OO Programming with Object COBOL.
In addition to the 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.
-
ALIGN - specifies the memory boundaries on which data
items of 01-level or 77-level are aligned.
-
IBMCOMP - turns on word-storage mode.
-
MAPNAME - impacts the handling of non-alphabetic characters in
the method-name.
-
MF-OO - enables the syntax used for OO
-
REPOSITORY - tells the compiler whether to create a repository
entry for a class, ignore the repository entry for a class, or check
against the repository entry for a class.
-
OOCTRL - provides specific switches for OO options. The
settings can be enabled or disabled by use of the + and - signs,
respectively, preceding the option character. The default is
OOCTRL(-G-N-P+Q-W). The meaning of the options is:
+G |
Makes class data global for instances.
Note: The use of this option is not recommended. It is
provided for compatibility with earlier releases.
|
+N |
Enables the use of CLASS-OBJECT and END CLASS-OBJECT syntax.
|
+P |
Makes parameter type information available to the Object COBOL
runtime system.
Note: Needed for messages sent to OLE and SOM.
|
+Q |
Disables the use of IN and OF any place that could possibly
follow a data name in the verb-signature of a Method Interface
Definition.
Disables the use of any verb (see the section Categories of
Statements in the chapter Concepts of a COBOL Program)
in the verb-signature of a Method Interface Definition. |
-Q |
Enables the use of IN and OF in the verb-signature of a Method
Interface Definition. Disables the use of qualification in a
verb-signature that invokes a method.
Enables the use of verbs (see the section Categories of
Statements in the chapter Concepts of a COBOL Program)
in the verb-signature of a Method Interface Definition. |
+W |
Uses Working-Storage in the object and class object to mean
Object-Storage.
Note: Provides compatibility with the developing ISO
COBOL standard.
|
A Class describes an Object COBOL Class object and its instance objects.
It contains nested programs for class methods and instance methods.
General Format
Syntax Rules
- The words PROTECTED and RESTRICTED are equivalent.
- If the EXTERNAL clause is specified, neither the DATA nor the
INHERITS clause may be specified.
- If the WITH DATA phrase is specified in the INHERITS clause, the DATA
IS PRIVATE clause must not be specified explicitly or implicitly in the
source code for class-name-2.
- Class-name-2 must not be the same as class-name-1.
- Class-name-2 must not inherit from class-name-1 directly or
indirectly.
- Class-name-1 in the END CLASS header must be identical to the
class-name-1 specified in the preceding CLASS-ID paragraph.
General Rules
- Class-name-1 identifies the class being declared.
- The ABSTRACT clause indicates that class-name-1 is an abstract class.
You cannot create an instance of an abstract class.
- The EXTERNAL phrase indicates that class-name-1 is an external class.
No code is produced.
- The RESTRICTED phrase enables subclasses to directly access data
inherited from class-name-1.
- The PRIVATE phrase prevents subclasses from directly accessing data
inherited from class-name-1.
- The INHERITS phrase specifies that class-name-2 is a parent class of
class-name-1.
- If the INHERITS phrase is not specified, class-name-1 forms a new
root in the classification scheme. There can be one or more roots in a
classification scheme.
- The WITH DATA phrase specifies that class-name-1 is able to access
directly data inherited from class-name-2.
A class extension enables you to add extra functionality to an object
COBOL class without changing the original source code.
The difference between extending a class with a class extension as
opposed to using inheritance is that the class extensions are inherited by
all existing subclasses. For example, if class A has a subclass, class B.
(That is, B INHERITS FROM A.) You can add methods to class A by
subclassing it to create subclass C. However, class B will not inherit the
methods of class C, because it is a subclass of A. If you extend class A
with a class extension, X, the effect at run-time is the same as if you
had changed and recompiled class A. Class B inherits all the extra methods
in class X.
General Format
Syntax Rules
- Extension-name-1 must not be the same as class-name-1.
- Extension-name-1 in the END CLASS header must be identical to the
extension-name-1 specified in the preceding CLASS-ID paragraph.
- Class-name-1 must be the name of a class specified in the
CLASS-CONTROL paragraph.
- The Data Division of the class-body may contain an empty
Object-Storage Section. The only other sections that may be specified in
the Data Division of a Class Extension are the Working-Storage Section
and the Linkage Section.
- Statements in the class extension may reference data declared in
class-name-1 only when:
- the DATA IS PROTECTED or DATA IS RESTRICTED phrase is specified
in the CLASS-ID paragraph of class-name-1, and
- the WITH DATA phrase is specified in the CLASS-ID paragraph of
the class extension.
General Rules
- The EXTEND clause specifies a class extension. A class extension adds
methods to an object class. The methods specified in extension-name-1
are inherited by all subclasses, existing and new, of class-name-1.
- During the execution of a run unit, a COBOL call statement to
extension-name-1 must be executed before any of the methods in the class
extension are invoked. This will register the methods in the class
extension with the OO runtime system.
The class body contains all the code which defines class data and class
methods.
General Format
Format 1
(Used when the Compiler directive OOCTRL(+N) is specified)
Note: This is the preferred syntax
Format 2
(Used when the Compiler directive OOCTRL(-N) is specified)
Syntax Rules
All Formats
- Class-name-3 must not be specified more than once in the
CLASS-CONTROL paragraph.
- Class-name-3 may be the same as the class-name specified in the
CLASS-ID paragraph.
- The Data Division may not contain a Linkage Section.
Format 1
- The Data Division may not contain an Object-Storage Section.
- Data items declared in the Data Division may be referenced from
instance methods and class methods.
Format 2
- Data items declared in the Local-Storage Section, Report Section, and
Screen Section may be referenced only from the statements in the
procedure division of this class, not from any methods.
- Data items declared in the File Section or Working-Storage Section
can be referenced from instance methods and class methods and from the
Procedure Division of this class.
- Data items declared in the Object-Storage Section may be referenced
from class methods.
General Rules
All Formats
- Class-name-3 is implicitly defined as USAGE IS OBJECT REFERENCE.
- Class-name-3 is the name of a class that may be used throughout the
scope of the containing Environment Division.
- External-name-1 specifies the external name of the file containing
the class.
- Method-1 is a class method.
- Only data items in the Object-Storage Section are inherited by
subclasses.
Format 1
- Data items are in their initial state at the start of the run unit
and remain in their last used state between method invocations.
Format 2
- The statements in the class procedure division are executed before
the first time any class method or instance method of this class is
executed in the run unit.
- When execution of the class procedure division begins, the contents
of the data items in the Local-Storage Section are undefined. This
storage is deallocated immediately after execution of the class
procedure division.
- Data items declared in the File Section and Working-Storage Section
remain in their last used state between invocations of class and
instance methods.
Note: Working-Storage data is useful for class or instance
initialization data.
- Data items declared in the Object-Storage Section remain in their
last used state between invocations of class methods.
The class object is an object that acts as a creator of objects.
General Format
General Rules
- If a data-item is declared in the Object-Storage Section of a class
object, it is class data. Class data may be referenced only in class
methods. Class data can be inherited by subclasses.
- Data is in its initial state at the start of the run unit and remains
in its last used state between method invocations.
- Method-1 is a class method.
The object program contains the definition of data and methods for all
instances of the class.
General Format
General Rules
- If a data-item is declared in the Object-Storage Section of an object
program, it is instance data. Instance data may be referenced only in
instance methods.
- Data items are in their initial state at the start of the run unit
and remain in their last used state between method invocations.
- Method-1 is an instance method.
Format
Syntax Rules
- Method-name-1 in the END METHOD header must be identical to the
method-name-1 declared in the preceding METHOD-ID paragraph.
- Data declared in the Data Division of a method is accessible only
within that method.
- Quotation marks around method-name-1 are optional.
Note: They enable you to use reserved words as method-names
and to use non-COBOL characters.
- A method definition must be contained in a Class Definition.
- The format of the procedure division header for a method is the same
as the format 1 procedure division header for a program. The GIVING or
RETURNING data-name clause shown in the format 2 header may also be
specified. (See the section The PROCEDURE DIVISION Header for
details.)
General Rules
- Method-name-1 names the method declared by this method definition.
- Data declared in the Local-Storage Section of a method is allocated
separate storage for each invocation of the method and deallocated upon
return from the method. This data is in an undefined state each time the
method is invoked.
Note: It is recommended that data in a method be declared
in the Local-Storage Section because this prevents separate
invocations of the method from interfering with each other's data.
- Data and files declared in a method in sections other than the
Local-Storage Section or the Linkage Section are shared among all
invocations of the method and are in their last used state when the
method is invoked.
- Method-name-1 may be used in a method invocation with an object
identifier that references an object containing this method.
- If a RETURNING or GIVING phrase is specified in the procedure
division header of a method, the contents of the data item specified in
that phrase when the method terminates become the result of the method.
This result is placed in the identifier specified in the RETURNING or
GIVING phrase of the INVOKE statement.
A method interface definition defines the parameters for the method, how
they are passed, and any alternate syntax that can be used to invoke the
method.
Format
where verb-signature is:
Syntax Rules
- A method interface definition must be nested within an external
class.
- Procedure-division-header is a format 2 procedure-division-header as
specified for a program, except that neither mnemonic-name nor the
REPEATED phrase may be specified. The INVOKED phrase, shown in the
format above, may optionally be included in the header just before the
terminating period. (See the section The PROCEDURE DIVISION Header
for details.)
- When the FUNCTION phrase is specified in the verb-signature, the
RETURNING phrase must be specified in the procedure division header.
- Verb-1 must be a COBOL word that is neither a reserved word nor a
procedure-name.
- The words <OBJECT>, <SELF> and <THIS> are
equivalent. One of them must be present once and only once in each
verb-signature.
- Data-name-3 must be preceded by "<" and followed by ">".
- Compulsory-word must be a COBOL word.
- Noise-word must be a COBOL word and must be preceded by "["
and followed by "]".
- Open-parenthesis and close-parenthesis are "(" and ")"
respectively.
Note: They enable you to define functions that look like
intrinsic functions, with parameters enclosed in parentheses.
- A verb-signature must not be a subset of another verb-signature.
General Rules
- When method-name-1 is invoked using verb-signature, <SELF> is
replaced with the object reference to the receiving object.
- Noise-words are for readability and are optional when the syntax is
used to invoke a method.
- If verb-1 is also declared as a data-name in a program, then any
reference to that word in that program will be to the data-name.
The Object-Storage Section is used to declare object data. A new usage,
OBJECT REFERENCE, is used to declare a reference to an object.
The Object-Storage Section is an optional section of the data division
that enables you to declare class object data and instance object data.
Format
Syntax Rules
- Data declared in the Object-Storage Section of the class object may
only be accessed in class methods.
- Data declared in the Object-Storage Section of an object-program may
only be accessed in instance methods.
- If DATA IS RESTRICTED or DATA IS PROTECTED is specified in the
CLASS-ID paragraph, data declared in the Object-Storage Section may be
directly accessed in a subclass. Otherwise, this data may only be
accessed by invoking methods.
- The syntax rules for data declared in the Object-Storage Section are
the same as those for the Linkage Section except you must not specify
the DEPENDING ON phrase on an OCCURS clause when the ODOSLIDE Compiler
directive is specified.
General Rules
- Data declared in the Object-Storage Section can be inherited by
subclasses.
- Each new instance object is allocated its own unique storage for data
items declared in the Object-Storage Section.
- When the Compiler directive OOCTRL(+W) is specified, the
Working-Storage Section is treated as the Object-Storage Section.
Data items declared with USAGE IS OBJECT REFERENCE are used for storing
references to objects.
General Format
Syntax Rules
- The REDEFINES clause must not be specified for a data item that
specifies the USAGE IS OBJECT REFERENCE clause.
- A data item whose declaration contains a USAGE IS OBJECT REFERENCE
clause must not be specified in a REDEFINES clause.
- An elementary data item declared with the USAGE IS OBJECT REFERENCE
clause must not contain a PICTURE clause.
- The USAGE IS OBJECT REFERENCE clause must not be specified in the
data description entry for a group item.
- The KEY IS clause must not be specified for a data-item that
specifies the USAGE IS OBJECT REFERENCE clause.
- If the VALUE clause is specified for a data-item that specifies the
USAGE IS OBJECT REFERENCE clause, the only valid value is NULL.
General Rules
- A data item whose declaration contains USAGE IS OBJECT REFERENCE
contains a reference to an object, which can be of any class.
- The size and format of a data item whose declaration contains USAGE
IS OBJECT REFERENCE is not necessarily the same for every object
reference.
The Procedure Division for a method contains procedures to be executed.
The Procedure Division for an Object Definition and a Class Definition
contains the methods that may be invoked on the instance object or class
object, respectively.
You can compare two object references to see if they refer to the same
object.
General Format
Syntax Rules
- Only one operand in the comparison can be the figurative constant
NULL.
General Rules
- The operands are equal if they identify the same object, otherwise
they are unequal.
The EXIT METHOD statement marks the logical end of an invoked method.
General Format
Syntax Rules
- An EXIT METHOD statement may only be specified in the Procedure
Division of a method.
General Rules
- The execution of an EXIT METHOD statement causes execution to
continue with the next executable statement following the INVOKE
statement in the invoking program or method. If a RETURNING phrase is
present in the containing method definition, the value in the data item
referenced by the RETURNING phrase will become the result of the method
invocation.
The INVOKE statement causes a method to be invoked.
General Format
Syntax Rules
- Object-identifier-1 must be an object identifier.
- Identifier-1 must be a four-byte data item.
- Literal-1 must be alphanumeric and must be a valid method-name.
- Neither literal-1, literal-2, nor literal-3 may be a figurative
constant.
- Identifier-2 must be defined as an alphanumeric data item such that
its value can be a COBOL or non-COBOL method-name.
- Neither identifier-3, identifier-4, identifier-5, identifier-6,
identifier-7, nor identifier-8 can be a function-identifier.
- Integer-1 may be signed or zero.
- GIVING and RETURNING are equivalent.
- Identifier-9 must be 4 bytes in size.
- Identifier-10 must be defined as a data item in the Linkage Section
with a level number of 01 or 77.
- If the INVOKE statement specifies literal-1 (but not if it specifies
identifier-2), and if a method interface definition has been included in
the current compilation unit with a name that matches literal-1, then
the following items are validated during syntax checking:
- The number of parameters required
- The type of parameters
- The call convention
General Rules
- Object-identifier-1 and identifier-1 identify the object on which the
method is invoked.
- If the contents of the data item referenced by object-identifier-1 is
a class object, a class method is invoked; otherwise, an instance method
is invoked.
- Literal-1 or the content of the data item referenced by identifier-2
is the name of the method to be invoked. If the method to be invoked is
a COBOL method, literal-1 or the content of the data item referenced by
identifier-2 must contain the method-name contained in the METHOD-ID
paragraph of the invoked method. If the method to be invoked is not a
COBOL method, the rules for the formation of the method-name are
dependent upon the domain involved.
- The AS phrase enables you to invoke methods on a COBOL data item. If
template-1 is specified, it is used as a class template. Creation of
templates is a function provided by objects in the supplied Class
Library. (See the book OO Programming with Object COBOL
for details.)
- When an INVOKE statement is executed, the method specified is made
available for execution and control is transferred to the invoked
method. After control is returned from the method, control is
transferred to the end of the INVOKE statement.
- The run unit is not aware of whether an invoked method is a COBOL
method or a non-COBOL method until the invoked method has been located,
prior to being made available for execution. The form of the method-name
cannot be used to determine whether the method is a COBOL method or not.
- The process of invoking a method or exiting from an invoked method
does not alter the status or positioning of a file associated with any
external file connector.
- If the method being invoked is a COBOL method, the USING phrase is
included in the INVOKE statement only if there is a USING phrase in the
Procedure Division header of the invoked method, in which case the
number of operands in each USING phrase must be identical. If a
RETURNING phrase is specified on the INVOKE statement, the Procedure
Division header for the invoked method must contain a RETURNING phrase.
- If the method being invoked is not a COBOL method, the USING phrase
is included in the INVOKE statement only if one or more parameters are
declared for the invoked method, in which case the number of operands in
the USING phrase must be identical to the number of parameters in the
invoked method. (Some implementations of languages other than COBOL may
allow the number of operands to be other than identical.)
Note: The COBOL language places no restrictions on the
alignment of the addresses of data items, whereas non-COBOL languages
typically do make assumptions about addresses and will fail in some
way if a misaligned data item is referenced. Alignment can be achieved
by one or more of the following actions:
- modifying group items to include additional filler items
- ensuring operands in the USING phrase are level 01 or level 77
data items in conjunction with the ALIGN Compiler directive or
- use of the SYNCHRONIZED clause in conjunction with the IBMCOMP
Compiler directive
If a RETURNING phrase is specified on the INVOKE statement, the
non-COBOL method must return a result in the appropriate format.
- The sequence of appearance of the operands in the USING phrase of the
INVOKE statement and the USING phrase of the invoked method's Procedure
Division header determines the correspondence between the data items
used by the INVOKE statement and the invoked method. This correspondence
is positional and not by name equivalence; the first parameter in one
USING phrase corresponds to the first parameter in the other, the second
to the second, etc.
If a parameter is an index-name, no such correspondence is
established. Index-names in the invoked method and the invoking
program or method always refer to separate indices.
- The values of the parameters referenced in the USING phrase of the
INVOKE statement are made available to the invoked method at the time
the INVOKE statement is executed.
- The BY CONTENT, BY REFERENCE and BY VALUE phrases are transitive
across the parameters that follow them until another BY CONTENT, BY
REFERENCE or BY VALUE phrase is encountered.
If no BY CONTENT, BY REFERENCE or BY VALUE phrase is specified prior
to the first parameter, the BY REFERENCE phrase is assumed.
- If BY REFERENCE is specified explicitly or implicitly for
identifier-3, the invoked method operates as if the corresponding data
item in the invoked method occupies the same storage area as the data
item in the invoking program or method. The description of the data item
in the invoked method must describe the same number of character
positions as described by the description of the corresponding data item
in the invoking program.
If the BY REFERENCE ADDRESS OF phrase is specified or implied then
the method operates as if an additional data item had been declared
with USAGE POINTER and that data item passed BY REFERENCE with a value
acquired by a SET data item TO ADDRESS OF identifier-4 statement.
If identifier-4 is in the Linkage Section and has a level number
other than 01 or 77 or is in the Working-Storage Section, it is
equivalent to passing the item BY CONTENT and the address of
identifier-4 cannot be modified by the invoked method. If the BY
REFERENCE literal-2 phrase is specified or implied then the method
processes literal-2 as described for literal-3.
- If the BY CONTENT phrase is specified or implied for a parameter, the
invoked method cannot change the value of this parameter as referenced
in the INVOKE statement's USING phrase, although the invoked method can
change the value of the data item referenced by the corresponding
data-name in the invoked method's Procedure Division header. The data
description of each parameter in the BY CONTENT phrase of the INVOKE
statement must be the same, meaning no conversion or extension or
truncation, as the data description of the corresponding parameter in
the USING phrase of the PROCEDURE DIVISION header.
If the BY CONTENT phrase is specified or implied for a parameter,
the object program operates as if an additional data item had been
declared and this additional data item used as the parameter in a BY
REFERENCE phrase. If identifier-5 is specified then both the implied
data description of the additional data item and its contents are
identical to that of identifier-5. If literal-3 is specified then the
implied data description of the additional item is equivalent to an
alphanumeric data item with the same size as literal-3 and with its
contents set to the value of literal-3. If LENGTH OF identifier-6 is
specified, then the data description of the additional item is
equivalent to PIC S9(n) USAGE COMP-5, where the value of n is at least
9 and defines a data item that is large enough to hold the maximum
length of a data item in the COBOL system. The contents of the
additional data item are set to the number of bytes of storage
allocated to identifier-6.
- If the BY VALUE phrase is specified or implied for a parameter, the
invoked method cannot change the value of this parameter as referenced
in the INVOKE statement's USING phrase, though the invoked method can
change the value of the data item referenced by the corresponding
data-name in the invoked method's PROCEDURE DIVISION header. The method
operates, conceptually, as if an additional data item had been declared
in a system area (typically the stack), available to non-COBOL
languages for passing parameters and that this additional data item
occupies the same storage area as the data item in the invoked method.
If identifier-7 is specified and is BINARY, COMP-4, COMP-5 or
COMP-X, then the data description of the additional data item is
identical to that of identifier-7, except its usage is COMP-5. The
contents of the additional data item are identical to the COMP-5
representation of the contents of identifier-7. This conversion and
representation facilitates calling non-COBOL programs.
Otherwise, if identifier-7 is specified then the implied data
description of the additional data item and its contents are identical
to that of identifier-7.
If integer-1 is specified, then the data description of the
additional item is equivalent to a signed numeric item USAGE COMP-5
that occupies the number of bytes of storage indicated by the value of
integer-2, if specified, or the size of the system area otherwise
(typically the size of a POINTER on the system).
If LENGTH OF identifier-8 is specified, then the data description of
the additional item is equivalent to PIC S9(n) USAGE COMP-5, where the
value of n is at least 9 and defines a data item that is large enough
to hold the maximum length of a data item in the COBOL system. The
contents of the additional data item are set to the number of bytes of
storage allocated to identifier-8.
If the method being invoked is a COBOL method, each parameter in the
BY VALUE phrase of the INVOKE statement must have a corresponding
parameter declared in the USING phrase of the PROCEDURE DIVISION
header that also has the BY VALUE phrase specified or implied.
The additional data item generated as a result of the INVOKE
statement, described above, is related to this corresponding parameter
in the invoked method, as follows.
If the additional data item was subject to conversion from BINARY,
COMP-4, COMP-5 or COMP-X to COMP-5, then the data description of the
corresponding parameter in the invoked method must be identical to
that of the data description of the additional data item with the
exception that the corresponding parameter's usage can be any of
BINARY, COMP-4, COMP-5 or COMP-X. On entry to the invoked COBOL
method, a conversion from the USAGE COMP-5 of the additional data item
to the USAGE of the corresponding parameter in the invoked method is
performed.
If the additional data item was not subject to conversion to COMP-5,
the data description of each parameter in the invoked method must be
the same as the corresponding additional data item. This means there
is no conversion or extension or truncation, of the additional data
item to match the corresponding parameter in the invoked method.
If the method being invoked is non-COBOL, the details of when you
need to use the BY VALUE phrase are dependent on the domain involved.
- If identifier-9 is specified, its description must match that of the
data item specified in the RETURNING phrase of the procedure division
header of the invoked method. The result of the method is assigned to
identifier-9, using the rules for the SET statement if identifier-9 is
usage object reference or usage index, and the rules for the MOVE
statement otherwise. When control returns to the invoking program or
method, identifier-9 contains the return value.
- If identifier-10 is specified, the invoked method must return a value
with explicit or implicit USAGE POINTER. The result of the method is
assigned to identifier-10 using the rules for the SET statement.
- Invoked methods may contain INVOKE statements. An invoked method may
execute an INVOKE statement that directly or indirectly invokes the
invoking method.
The SET statement is used to assign object references.
General Format
Syntax Rules
- Object-identifier-1 and object-identifier-2 must be usage object
reference.
General Rules
- The SET statement takes the object reference for the object
identified by object-identifier-2 and places it into the storage
associated with each object-identifier-1 in the order specified.
Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Procedure Division - SEARCH - WRITE |
|
Compiler-directing Statements | |