Compiler-directing statements

These are the compiler-directing statements:

BASIS statement

This extended source program library statement provides a complete COBOL program as the source for a compilation. For rules of formation and processing, see the description of text-name for the COPY statement.

CALLINTERFACE directive

The CALLINTERFACE directive specifies the interface convention for CALL and SET statements. The convention specified stays in effect until another CALLINTERFACE directive is encountered in the source.

The CALLINTERFACE directive can be used only in the procedure division and its effect is limited to the current compilation unit.

*CONTROL (*CBL) statement

This compiler-directing statement selectively suppresses or allows output to be produced. The names *CONTROL and *CBL are synonymous.

COPY statement

COPY statement syntax

This library statement places prewritten text into a COBOL program.

Neither text-name nor library-name need to be unique within a program. They can be identical to other user-defined words in the program, except that they cannot contain the underscore.

The uniqueness of text-name and library-name is determined after the formation and conversion rules for a system-dependent name have been applied. If library-name is omitted, SYSLIB is assumed.

Compiling with JCL:

text-name, library-name, and literal-1 and literal-2 are processed as follows:

• The name (which can be from one to 30 characters long) is truncated to eight characters. Only the first eight characters of text-name and library-name are used as the identifying name. These eight characters must be unique within any COBOL library.
• The name is folded to uppercase.
• Hyphens that are not the first or last character are translated to zero (0), and a warning message is issued.
• If the first character is numeric, then the characters 1-9 are translated to A-I, zero (0) is converted to J, and a warning message is issued.

For example:

COPY INVOICES1Q
COPY "Company-#Employees" IN Personellib

In the IN/OF phrase, library-name is the ddname that identifies the partitioned data set to be copied from. Use a DD statement such as in the following example to define library-name:

//COPYLIB DD DSNAME=ABC.COB,VOLUME=SER=111111,
//           DISP=SHR,UNIT=3380

To specify more than one copy library, use either JCL or a combination of JCL and the IN/OF phrase. Using just JCL, concatenate data sets in your DD statement for SYSLIB. Alternatively, define multiple DD statements and include the IN/OF phrase in your COPY statements.

The maximum block size for the copy library depends on the device on which your data set resides.

Compiling in the z/OS UNIX shell:

When you compile using the cob2 command, copybooks are included from the z/OS UNIX file system. text-name, library-name, and literal-1 and literal-2 are processed as follows:

• User-defined words are folded to uppercase. Literals are not folded. Because UNIX is case sensitive, if your file-name is lowercase or mixed case, you must specify it as a literal.
• If text-name is a literal and library-name is omitted, text-name is used directly: as a file-name, a relative path name, or an absolute path name (if the first character is /). For example:

  
  COPY "MyInc"
  COPY "x/MyInc"
  COPY "/u/user1/MyInc"
  

• If text-name is a user-defined word, and an environment variable of that name is defined, the value of the environment variable is used as the name of the file that contains the copybook.
  If an environment variable of that name is not defined, the copybook is searched for under the following names, in this order:

  1. text-name.cpy
  2. text-name.CPY
  3. text-name.cbl
  4. text-name.CBL
  5. text-name.cob
  6. text-name.COB
  7. text-name
• If library-name is a literal, it is treated as the actual path, relative or absolute, from which to copy file text-name.
• If library-name is a user-defined word, it is treated as an environment variable. The value of the environment variable is used as the path. If the environment variable is not set, an error occurs.
• If both library-name and text-name are specified, the compiler forms the path name for the copybook by concatenating library-name and text-name with a path separator (/) inserted between the two values. For example, suppose you have the following setting for COPY MYCOPY OF MYLIB:

  
  export MYCOPY=mystuff/today.cpy
  export MYLIB=/u/user1
  

  These settings result in:

  
  /u/user1/mystuff/today.cpy
  

If library-name is an environment variable that identifies the path from which copybooks are to be copied, use an export command to define library-name, as in this example:

export COPYLIB=/u/mystuff/copybooks

The name of the environment variable must be uppercase. To specify more than one copy library, set the environment variable to multiple path names delimited by colon (:).

If library-name is omitted and text-name is not an absolute path name, the copybook is searched for in this order:

1. In the current directory
2. In the paths specified on the -I cob2 option
3. In the paths specified in the SYSLIB environment variable

For additional information about the COPY statement, for example, the rules for text replacement, see the related reference.

DEFINE directive

The DEFINE directive defines or undefines a compilation variable. The compilation variables can be used within any of the conditional compilation directives (DEFINE, EVALUATE, and IF). The compilation variable is treated as a symbolic reference to the literal value it currently represents.

DELETE statement

This extended source library statement removes COBOL statements from the BASIS source program.

EJECT statement

This compiler-directing statement specifies that the next source statement is to be printed at the top of the next page.

ENTER statement

The statement is treated as a comment.

EVALUATE directive

The EVALUATE directive provides a multi-branch method of choosing the source lines to include in a compilation group.

IF directive

The IF directive provides for a one-way or two-way conditional compilation.

INLINE directive

The INLINE directive lets you selectively prevent the compiler from considering procedures eligible for inlining.

INSERT statement

This library statement adds COBOL statements to the BASIS source program.

PROCESS (CBL) statement

This statement, which you place before the IDENTIFICATION DIVISION header of an outermost program, indicates which compiler options are to be used during compilation of the program.

REPLACE statement

This statement is used to replace source program text.

SERVICE LABEL statement

This statement is generated by the CICS® translator to indicate control flow, and should be used at the resume point for a call to CEE3SRP. It is not intended for general use.

SKIP1/2/3 statement

These statements indicate lines to be skipped in the source listing.

TITLE statement

This statement specifies that a title (header) should be printed at the top of each page of the source listing.

USE statement

The USE statement provides declaratives to specify these elements:

• Error-handling procedures: EXCEPTION/ERROR
• Debugging lines and sections: DEBUGGING