INCLUDE

INCLUDE   copycode-name   [operand1] 99

This document covers the following topics:

For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.

Function

The INCLUDE statement is used to include source lines from an external object of type copycode into another object at compilation.

The INCLUDE statement is evaluated at compilation time. The source lines of the copycode will not be physically included in the source of the program that contains the INCLUDE statement, but they will be included during the program compilation and thus in the resulting object module.

Caution:
A source code line which contains an INCLUDE statement must not contain any other statement.

Syntax Description

Operand Definition Table:

Operand Possible Structure Possible Formats Referencing Permitted Dynamic Definition
operand1 C         A U                       no no

Syntax Element Description:

Syntax Element Description
copycode-name
Copycode Name:

As copycode-name you specify the name of the copycode whose source is to be included. The case of the specified name is not translated.

copycode-name may contain an ampersand (&); at compile time, this character will be replaced by the one-character code corresponding to the current value of the Natural system variable *LANGUAGE. This feature allows the use of multilingual copycode names.

The object you specify must be of the type copycode. The copycode must be contained either in the same library as the program which contains the INCLUDE statement or in the respective steplib (the default steplib is SYSTEM).

When the source of a copycode is modified, all programs using that copycode must be compiled again to reflect the changed source in their object codes.

The source code of the copycode must consist of syntactically complete statements.

operand1
Insert Values for Dynamic Insertion:

You can dynamically insert values in the copycode which is included. These values are specified with operand1.

In the copycode, the values are referenced with the following notation: 

&n&

That is, you mark the position where a value is to be inserted with &n&. n is the sequential number of each value passed with the INCLUDE statement. For example, &3& would refer to the third value specified with the statement.

For every &n& notation in the copycode you must specify a value in the INCLUDE statement. For example, if the copycode contains &5&, operand1 must be specified at least five times.

You may write one copy code parameter (&n&) after another without blanks (that is, &1&&2&&3&). This method is used to concatenate multiple copy code parameters to a source.

A string may follow one or several copy code parameters without a blank (that is, &1&abc or &1&&2&abc). This method is used to concatenate a string to multiple copy code parameters.

Note:
Because &n& is a valid part of an identifier, this notation may not be used as a copy code parameter substitution in other positions described above (i.e. abc&1& or &1&abc&2&). In other words, a string may only come after copy code parameters, not before or between.

Values that are specified in the INCLUDE statement but not referenced in the copycode will be ignored.

Examples

Example 1 - INCLUDE Statement Including Copycode

Program containing the INCLUDE statement:

** Example 'INCEX1': INCLUDE  (include copycode)                        
************************************************************************
*                                                                       
WRITE 'Before copycode'                                                 
*                                                                       
INCLUDE INCEX1C                                                    
*                                                                       
WRITE 'After copycode'                                                  
*                                                                       
END

Copycode INCEX1C to be included:

** Example 'INCEX1C': INCLUDE (copycode used by INCEX1)                 
************************************************************************
*                                                                       
WRITE 'Inside copycode'

Output of Program INCEX1:

Page      1                                                  05-01-25  16:26:36
                                                                               
Before copycode                                                                
Inside copycode                                                                
After copycode

Example 2 - INCLUDE Statement Including Copycode with Parameters

Program INCEX2 containing the INCLUDE statement: 

** Example 'INCEX2': INCLUDE  (include copycode with parameters)        
************************************************************************
DEFINE DATA LOCAL                                                       
1 EMPL-VIEW VIEW OF EMPLOYEES                                           
  2 NAME                                                                
END-DEFINE                                                              
*                                                                       
*                                                                       
INCLUDE INCEX2C 'EMPL-VIEW' 'NAME' '''ARCHER''' '20' '''BAILLET'''     
*                                                                       
END

Copycode INCEX2C to be included:

** Example 'INCEX2C': INCLUDE (copycode used by INCEX2)                 
************************************************************************
* Transferred parameters from INCEX2:                                   
*                                                                       
* &1& : EMPL-VIEW                                                       
* &2& : NAME                                                            
* &3& : 'ARCHER'                                                        
* &4& : 20                                                              
* &5& : 'BAILLET'                                                       
*                                                                       
*                                                                       
READ (&4&) &1&  BY &2&  = &3&                                           
  DISPLAY &2&                                                           
  IF &2& = &5&                                                          
    WRITE 5X 'LAST RECORD FOUND' &2&                                    
    STOP                                                                
  END-IF                                                                
END-READ                                                                
*                                                                       
* Statements above will be completed to:  
*                                         
* READ (20) EMPL-VIEW  BY NAME  = 'ARCHER'
*   DISPLAY NAME                          
*   IF NAME = 'BAILLET'                   
*     WRITE 5X 'LAST RECORD FOUND' NAME   
*     STOP                                
*   END-IF                                
* END-READ

Output of Program INCEX2:

Page      1                                                  05-01-25  16:30:43
                                                                               
        NAME                                                                   
--------------------                                                           
                                                                               
ARCHER                                                                         
ARCONADA                                                                       
ARCONADA                                                                       
ARNOLD                                                                         
ASTIER                                                                         
ATHERTON                                                                       
ATHERTON                                                                       
ATHERTON                                                                       
AUBERT                                                                         
BACHMANN                                                                       
BAECKER                                                                        
BAECKER                                                                        
BAGAZJA                                                                        
BAILLET                                                                        
     LAST RECORD FOUND BAILLET

Example 3 - INCLUDE Statement Using Nested Copycodes

Program containing INCLUDE statement:

** Example 'INCEX3': INCLUDE  (using nested copycodes)                  
************************************************************************
DEFINE DATA LOCAL                                                       
1 #A (I4)                                                               
END-DEFINE                                                              
*                                                                       
MOVE 123 TO #A                                                          
WRITE 'Program  INCEX3  ' '=' #A                                        
*                                                                       
INCLUDE INCEX31C '#A' '5'            /* source line is #A := 5          
*                                                                       
*                                                                       
MOVE 300 TO #A                                                          
WRITE 'Program  INCEX3  ' '=' #A                                        
*                                                                       
INCLUDE INCEX32C '''#A'''  '''20'''  /* source line is #A := 20         
*                                                                       
WRITE 'Program  INCEX3  ' '=' #A                                        
END

Copycode INCEX31C to be included:

** Example 'INCEX31C': INCLUDE (copycode used by INCEX3)                
************************************************************************
* Transferred parameters from INCEX3:                                   
*                                                                       
* &1& : #A                                                              
* &2& : 5                                                               
*                                                                       
*                                                                       
&1& := &2&                                                              
*                                                                       
WRITE 'Copycode INCEX31C' '=' &1&

Copycode INCEX32C to be included:

** Example 'INCEX32C': INCLUDE (copycode used by INCEX3)                
************************************************************************
* Transferred parameters from INCEX3:                                   
*                                                                       
* &1& : '#A'                                                            
* &2& : '20'                                                            
*                                                                       
*                                                                       
WRITE 'Copycode INCEX32C' &1& &2&                                       
*                                                                       
INCLUDE INCEX31C &1& &2&

Output of Program INCEX3:

Page      1                                                  05-01-25  16:35:36
                                                                               
Program  INCEX3   #A:         123                                              
Copycode INCEX31C #A:           5                                              
Program  INCEX3   #A:         300                                              
Copycode INCEX32C #A 20                                                        
Copycode INCEX31C #A:          20                                              
Program  INCEX3   #A:          20

Example 4 - INCLUDE Statement with Concatenated Parameters in Copycode

Program containing INCLUDE statement:

** Example 'INCEX4': INCLUDE  (with concatenated parameters in copycode)
************************************************************************
DEFINE DATA LOCAL                                                       
1 #GROUP                                                                
  2  ABC(A10) INIT <'1234567890'>                                       
END-DEFINE                                                              
*                                                                       
INCLUDE INCEX4C  '#GROUP.'  'ABC'  'AB'                              
*                                                                       
END

Copycode INCEX4C to be included:

** Example 'INCEX4C': INCLUDE (copycode used by INCEX4)                 
************************************************************************
* Transferred parameters from INCEX4:                                   
*                                                                       
* &1& : #GROUP.                                                         
* &2& : ABC                                                             
* &3& : AB                                                              
*                                                                       
*                                                                       
WRITE  '=' &2&          /* 'ABC'             results into ABC           
WRITE  '=' &1&ABC       /* '#GROUP.' ABC     results into #GROUP.ABC    
WRITE  '=' &1&&2&       /* '#GROUP.' 'ABC'   results into #GROUP.ABC    
WRITE  '=' &1&&3&C      /* '#GROUP.' 'AB' C  results into #GROUP.ABC

Output of Program INCEX4:

Page      1                                                  05-01-25  16:37:59
                                                                               
ABC: 1234567890                                                                
ABC: 1234567890                                                                
ABC: 1234567890                                                                
ABC: 1234567890