HP OpenVMS Systems Documentation

HP COBOL
User Manual

You must define each data name from the Procedure Division header's USING data name list in the called subprogram's Linkage Section. For example:

LINKAGE SECTION.

01 PART     PICTURE...
01 AMOUNT   PICTURE...
01 INVOICE  PICTURE...
01 COLOR    PICTURE...
01 COST     PICTURE...

PROCEDURE DIVISION USING PART, AMOUNT, COLOR, COST.

Of those data items you define in the Linkage Section, only those named in the calling program's Procedure Division header's USING phrase are accessible to the called program. In the previous example, INVOICE is not accessible from the called program.

When a subprogram references a data name from the Procedure Division header's USING data name list, the subprogram processes it according to the definition in its Linkage Section.

A called program's Procedure Division can reference data names in its Linkage Section only if it references one of the following:

• Any data item named in the Procedure Division USING data-name-list
• A data item that is subordinate to a Linkage Section data item in the Procedure Division USING data-name-list
• Any other association with a data item in the Procedure Division USING data-name-list; for example, index-name, redefinition, and so on

In Figure 12-4, SUB is called by MAINPROG. Because MAINPROG names FILE-RECORD and WORK-RECORD in its CALL "SUB" USING statement, SUB can reference these data names just as if they were in its own Data Division. However, SUB accesses these two data items with its own data names, F-RECORD and W-RECORD.

Figure 12-4 Defining Data Names in the Linkage Section

A contained COBOL program is a subprogram nested in another COBOL program (the containing program). The complete source of the contained program is found within the containing program. A contained program can also be a containing program.

A COBOL containing/contained program provides you with program and data attributes that noncontained COBOL programs do not have. These attributes, described in the next several sections, often allow you to more easily share and more conveniently access COBOL data items and other program resources.

This COBOL programming and data structuring capability encourages modular programming. In modular programming, you divide the solution of a large data processing problem into individual parts (the contained programs) that can be developed relatively independently.

Consequently, the use of the COBOL containing/contained block structure as a modular programming design can increase program efficiency and assist in program modification and maintainability.

The contained program uses all calling procedures described in Sections 12.3 and 12.4. However, when a contained program includes the COMMON clause (a program attribute) and the GLOBAL clause (a data and file trait), the additional rules described in the following sections apply.

12.5.1 The COMMON Clause

The COMMON clause is a program attribute that can be applied to a directly contained program. The COMMON clause is a means of overriding normal scoping rules for program names, namely that a program that does not possess the common attribute and that is directly contained within another program can be referenced only by statements included in that containing program. For more information on Scope of Names rules, refer to the HP COBOL Reference Manual.

The common attribute is attained by specifying the COMMON clause in a program's Identification Division. A program that possesses the common attribute can be referenced by statements included in that containing program and by any programs directly or indirectly contained in that containing program, except the program possessing the common attribute and any programs contained within it.

Example 12-7 shows a run unit that has a COBOL program (PROG-MAIN) ((1)) with three contained programs ((2), (3), and (4)); one of which (((2)) has the COMMON clause. The example indicates which programs can call the common program.

                IDENTIFICATION DIVISION.
                PROGRAM-ID. PROG-MAIN.   (1)
                .
                .
                .

                CALL PROG-NAME-B
                .
                .
                .
                IDENTIFICATION DIVISION.
                PROGRAM-ID. PROG-NAME-B IS COMMON PROGRAM.  (2)
                .
                .
                .
                IDENTIFICATION DIVISION.
                PROGRAM-ID. PROG-NAME-D.  (3)
                .
                .
                .
                .
                .
                END PROGRAM PROG-NAME-D.
                END PROGRAM PROG-NAME-B.

                IDENTIFICATION DIVISION.
                PROGRAM-ID. PROG-NAME-C.  (4)
                .
                CALL PROG-NAME-B
                .
                .
                END PROGRAM PROG-NAME-C.
                END PROGRAM PROG-MAIN.

PROG-NAME-B ((2)) and PROG-NAME-C ((4)) are directly contained in PROG-MAIN ((1)); PROG-NAME-D ((3)) is indirectly contained in PROG-MAIN.

PROG-MAIN ((1)) can call PROG-NAME-B ((2)) because PROG-MAIN directly contains PROG-NAME-B. PROG-NAME-B ((2)) can call PROG-NAME-D ((3)) because PROG-NAME-B directly contains PROG-NAME-D.

PROG-NAME-C ((4)) can call PROG-NAME-B ((2)) because:

• PROG-NAME-C is not contained in PROG-NAME-B
• PROG-NAME-B has the common attribute
• PROG-NAME-C is contained by PROG-MAIN

However, PROG-NAME-D ((3)) cannot call PROG-NAME-B ((2)) because PROG-NAME-D ((3)) is contained within PROG-NAME-B ((2)). Similarly, PROG-NAME-D ((3)) cannot call PROG-NAME-C ((4)) because PROG-NAME-C ((4)) is not visible to PROG-NAME-D ((3)). If PROG-NAME-C ((4)) was made COMMON it could call PROG-NAME-D ((3)). Additionally, PROG-NAME-C ((4)) cannot call PROG-NAME-D ((3)) because PROG-NAME-C ((4)) is outside the scope of PROG-NAME-B ((2)).

12.5.2 The GLOBAL Clause

Data and files can be described as either global or local. A local name can be referenced only by the program that declares it. A global name is declared in only one program but can be referenced by both that program and any program contained in the program that declares the global name.

Some names are always global, other names are always local, and some names are either local or global depending on specifications in the program that declares the names. For more information on Scope of Names rules, refer to the HP COBOL Reference Manual.

12.5.2.1 Sharing GLOBAL Data

A data name is global if the GLOBAL clause is specified in the Data Description entry by which the data name is declared or in another entry to which that Data Description entry is subordinate. If a program is contained within another program, both programs may reference data possessing the global attribute. The following example shows the Working-Storage Section of a containing program MAINPROG. Any contained program in MAINPROG, as well as program MAINPROG, can reference that data (unless the contained program declares other data with the same name).

WORKING-STORAGE SECTION.
01    CUSTOMER-FILE-STATUS   PIC XX      GLOBAL.
01    REPLY                  PIC X(10)   GLOBAL.
01    ACC-NUM                PIC 9(18)   GLOBAL.

A file connector is global if the GLOBAL clause is specified in the File Description entry for that file connector. If a program is contained within another program, both programs may reference a file possessing the global attribute. The following example shows a file (CUSTOMER-FILE) with the GLOBAL clause in a containing program MAINPROG. Any contained program in MAINPROG, as well as program MAINPROG, can reference that file.

IDENTIFICATION DIVISION.
PROGRAM-ID.   MAINPROG.
.
.
.
DATA DIVISION.
FILE SECTION.
FD    CUSTOMER-FILE
      GLOBAL
.
.
.

Any special registers associated with a GLOBAL file are also global.