PreviousProcedure Division - SEARCH - WRITE Compiler-directing StatementsNext

Chapter 17: Object COBOL Language Extensions

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.

17.1 Directives

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.

17.2 Class Definition

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

  1. The words PROTECTED and RESTRICTED are equivalent.

  2. If the EXTERNAL clause is specified, neither the DATA nor the INHERITS clause may be specified.
  3. 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.

  4. Class-name-2 must not be the same as class-name-1.

  5. Class-name-2 must not inherit from class-name-1 directly or indirectly.

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

  1. Class-name-1 identifies the class being declared.

  2. The ABSTRACT clause indicates that class-name-1 is an abstract class. You cannot create an instance of an abstract class.

  3. The EXTERNAL phrase indicates that class-name-1 is an external class. No code is produced.

  4. The RESTRICTED phrase enables subclasses to directly access data inherited from class-name-1.

  5. The PRIVATE phrase prevents subclasses from directly accessing data inherited from class-name-1.

  6. The INHERITS phrase specifies that class-name-2 is a parent class of class-name-1.

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

  8. The WITH DATA phrase specifies that class-name-1 is able to access directly data inherited from class-name-2.

17.3 Class Extension

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

  1. Extension-name-1 must not be the same as class-name-1.

  2. Extension-name-1 in the END CLASS header must be identical to the extension-name-1 specified in the preceding CLASS-ID paragraph.

  3. Class-name-1 must be the name of a class specified in the CLASS-CONTROL paragraph.

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

  5. Statements in the class extension may reference data declared in class-name-1 only when:

General Rules

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

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

17.4 Class-body

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
  1. Class-name-3 must not be specified more than once in the CLASS-CONTROL paragraph.

  2. Class-name-3 may be the same as the class-name specified in the CLASS-ID paragraph.

  3. The Data Division may not contain a Linkage Section.
Format 1
  1. The Data Division may not contain an Object-Storage Section.

  2. Data items declared in the Data Division may be referenced from instance methods and class methods.
Format 2
  1. 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.

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

  3. Data items declared in the Object-Storage Section may be referenced from class methods.

General Rules

All Formats
  1. Class-name-3 is implicitly defined as USAGE IS OBJECT REFERENCE.

  2. Class-name-3 is the name of a class that may be used throughout the scope of the containing Environment Division.

  3. External-name-1 specifies the external name of the file containing the class.

  4. Method-1 is a class method.

  5. Only data items in the Object-Storage Section are inherited by subclasses.
Format 1
  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
  1. 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.

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

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


  4. Data items declared in the Object-Storage Section remain in their last used state between invocations of class methods.

17.5 Class-object

The class object is an object that acts as a creator of objects.

General Format

General Rules

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

  2. Data is in its initial state at the start of the run unit and remains in its last used state between method invocations.

  3. Method-1 is a class method.

17.6 Object-program

The object program contains the definition of data and methods for all instances of the class.

General Format

General Rules

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

  2. Data items are in their initial state at the start of the run unit and remain in their last used state between method invocations.

  3. Method-1 is an instance method.

17.7 Method

Format

Syntax Rules

  1. Method-name-1 in the END METHOD header must be identical to the method-name-1 declared in the preceding METHOD-ID paragraph.

  2. Data declared in the Data Division of a method is accessible only within that method.

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


  4. A method definition must be contained in a Class Definition.

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

  1. Method-name-1 names the method declared by this method definition.

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


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

  4. Method-name-1 may be used in a method invocation with an object identifier that references an object containing this method.

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

17.8 Method Interface Definition

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

  1. A method interface definition must be nested within an external class.

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

  3. When the FUNCTION phrase is specified in the verb-signature, the RETURNING phrase must be specified in the procedure division header.

  4. Verb-1 must be a COBOL word that is neither a reserved word nor a procedure-name.

  5. The words <OBJECT>, <SELF> and <THIS> are equivalent. One of them must be present once and only once in each verb-signature.

  6. Data-name-3 must be preceded by "<" and followed by ">".

  7. Compulsory-word must be a COBOL word.

  8. Noise-word must be a COBOL word and must be preceded by "[" and followed by "]".

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


  10. A verb-signature must not be a subset of another verb-signature.

General Rules

  1. When method-name-1 is invoked using verb-signature, <SELF> is replaced with the object reference to the receiving object.

  2. Noise-words are for readability and are optional when the syntax is used to invoke a method.

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

17.9 Data Division

The Object-Storage Section is used to declare object data. A new usage, OBJECT REFERENCE, is used to declare a reference to an object.

17.9.1 Object-storage Section

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

  1. Data declared in the Object-Storage Section of the class object may only be accessed in class methods.

  2. Data declared in the Object-Storage Section of an object-program may only be accessed in instance methods.

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

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

  1. Data declared in the Object-Storage Section can be inherited by subclasses.

  2. Each new instance object is allocated its own unique storage for data items declared in the Object-Storage Section.

  3. When the Compiler directive OOCTRL(+W) is specified, the Working-Storage Section is treated as the Object-Storage Section.

17.9.2 The USAGE Clause

Data items declared with USAGE IS OBJECT REFERENCE are used for storing references to objects.

General Format

Syntax Rules

  1. The REDEFINES clause must not be specified for a data item that specifies the USAGE IS OBJECT REFERENCE clause.

  2. A data item whose declaration contains a USAGE IS OBJECT REFERENCE clause must not be specified in a REDEFINES clause.

  3. An elementary data item declared with the USAGE IS OBJECT REFERENCE clause must not contain a PICTURE clause.

  4. The USAGE IS OBJECT REFERENCE clause must not be specified in the data description entry for a group item.

  5. The KEY IS clause must not be specified for a data-item that specifies the USAGE IS OBJECT REFERENCE clause.

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

  1. A data item whose declaration contains USAGE IS OBJECT REFERENCE contains a reference to an object, which can be of any class.

  2. The size and format of a data item whose declaration contains USAGE IS OBJECT REFERENCE is not necessarily the same for every object reference.

17.10 Procedure Division

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.

17.10.1 Conditional Expressions

You can compare two object references to see if they refer to the same object.

General Format

Syntax Rules

  1. Only one operand in the comparison can be the figurative constant NULL.

General Rules

  1. The operands are equal if they identify the same object, otherwise they are unequal.

17.10.2 The EXIT Statement

The EXIT METHOD statement marks the logical end of an invoked method.

General Format

Syntax Rules

  1. An EXIT METHOD statement may only be specified in the Procedure Division of a method.

General Rules

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

17.10.3 The INVOKE Statement

The INVOKE statement causes a method to be invoked.

General Format

Syntax Rules

  1. Object-identifier-1 must be an object identifier.

  2. Identifier-1 must be a four-byte data item.

  3. Literal-1 must be alphanumeric and must be a valid method-name.

  4. Neither literal-1, literal-2, nor literal-3 may be a figurative constant.

  5. Identifier-2 must be defined as an alphanumeric data item such that its value can be a COBOL or non-COBOL method-name.

  6. Neither identifier-3, identifier-4, identifier-5, identifier-6, identifier-7, nor identifier-8 can be a function-identifier.

  7. Integer-1 may be signed or zero.

  8. GIVING and RETURNING are equivalent.

  9. Identifier-9 must be 4 bytes in size.

  10. Identifier-10 must be defined as a data item in the Linkage Section with a level number of 01 or 77.

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

General Rules

  1. Object-identifier-1 and identifier-1 identify the object on which the method is invoked.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  18. Invoked methods may contain INVOKE statements. An invoked method may execute an INVOKE statement that directly or indirectly invokes the invoking method.

17.10.4 The SET Statement

The SET statement is used to assign object references.

General Format

Syntax Rules

  1. Object-identifier-1 and object-identifier-2 must be usage object reference.

General Rules

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

PreviousProcedure Division - SEARCH - WRITE Compiler-directing StatementsNext