ILE COBOL Programmer's Guide

Calling Nested Programs

Nested programs give you a method to create modular functions for your application and maintain structured programming techniques. Nested programs allow you to define multiple separate functions, each with its own controlled scope, within a single compilation unit. They can be used like PERFORM procedures with the additional ability to protect local data items.

Nested programs are contained in the same module as their calling program when they are compiled. Therefore, nested programs always run in the same activation group as their calling programs.

Structure of Nested Programs

An ILE COBOL program may contain other ILE COBOL programs. The contained programs may themselves contain yet other programs. A contained program may be directly or indirectly contained within a program.

Figure 51 describes a nested program structure with directly and indirectly contained programs.

Figure 51. Nested Program Structure with Directly and Indirectly Contained Programs

diagram of nested programs

Conventions for Using Nested Program Structure

There are several conventions that apply when using nested program structures.

  1. The Identification Division is required in each program. All other divisions are optional.
  2. Program name in the PROGRAM-ID paragraph must be unique.
  3. Names of nested programs can be any valid COBOL word or a nonnumeric literal.
  4. Nested programs can not have a Configuration Section. The outermost program must specify any Configuration Section options that may be required.
  5. Each nested program is included in the containing program immediately before its END PROGRAM header (see Figure 51).
  6. Each ILE COBOL program must be terminated by an END PROGRAM header.
  7. Nested programs can only be called or canceled from an ILE COBOL program in the same module object.
  8. Calls to nested programs can only be made using either a CALL literal or CALL identifier statement. Calls to nested programs cannot be made using CALL procedure-pointer. Calls to nested programs follow the same rules as static procedure calls.

Calling Hierarchy for Nested Programs

A nested program may only be called by its directly containing program, unless the nested program is identified as COMMON in its PROGRAM-ID paragraph. In that case, the COMMON program may also be called by any program that is contained (directly or indirectly) within the same program as the one directly containing the COMMON program. Recursive calls are only allowed for nested programs that have the RECURSIVE clause, or when the nested program's direct or indirect containing program has the RECURSIVE clause.

Figure 52 shows the outline of a nested structure with some contained programs identified as COMMON.

Figure 52. Nested Program Structure with Directly and Indirectly Contained Programs

diagram of nested programs

The following table describes the calling hierarchy for the structure that is shown in Figure 52. Notice that A12, A2, and A3 are identified as COMMON and the resulting differences in calls associated with them.

Table 11. Calling Hierarchy for Nested Structures with COMMON Programs

This Program Can call these programs And can be called by these programs
A A1, A2, A3 None
A1 A11, A12, A2, A3 A
A11 A111, A12, A2, A3 A1
A111 A12, A2, A3 A11
A12 A2, A3 A1, A11, A111
A2 A3 A, A1, A11, A111, A12, A3
A3 A2 A, A1, A11, A111, A12, A2

You should note that:

Scope of Names within a Nested Structure

There are two classes of names within nested structures--local and global. The class will determine whether a name is known beyond the scope of the program which declares it.

Local Names

Names are local unless declared to be GLOBAL (except the program name). These local names are not visible or accessible to any program outside of the one where they were declared; this includes both contained and containing programs.

Global Names

A name that is specified as global (by using the GLOBAL clause) is visible and accessible to the program in which it is declared, and to all the programs that are directly and indirectly contained within the program. This allows the contained programs to share common data and files from the containing program, simply by referencing the name of the item.

Any item that is subordinate to the global item (including condition names and indexes) is automatically global.

The same name may be declared with the GLOBAL clause multiple times, providing that each declaration occurs in a different program. Be aware that masking, or hiding, a name within a nested structure is possible by having the same name occur within different programs of the same containing structure.

Searching for Name Declarations

When a name is referenced within a program, a search is made to locate the declaration for that name. The search begins within the program that contains the reference and continues outward to containing programs until a match is found. The search follows this process:

  1. Declarations within the program are searched first.
  2. If no match is found, then only global declarations are searched in successive outer containing programs.
  3. The search ends when the first matching name is found, otherwise an error exists if no match is found.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]