RPGIV @ Work

A unique site for RPG and System i Lovers

Welcome!

Hi, this site will provide all what you need in System i and RPG developments.

My Name is Chamara Withanachchi, System i Expert and RPG Developer. And in the field for last 11 years.

I hope you will find lot of valuable information from this site

RPG Compiler Directives Print E-mail
User Rating: / 0
PoorBest 
Written by Chamara Withanachchi   

The compiler directive statements /FREE... /END-FREE denote a free-form calculation specification block. The compiler directive statements /TITLE, /EJECT, /SPACE, /COPY, and /INCLUDE allow you to specify heading information for the compiler listing, to control the spacing of the compiler listing, and to insert records from other file members during a compile. The conditional compilation directive statements /DEFINE, /UNDEFINE, /IF, /ELSEIF, /ELSE, /ENDIF, and /EOF allow you to select or omit source records. The compiler directive statements must precede any compile-time array or table records, translation records, and alternate collating sequence records (that is, ** records).


/FREE... /END-FREE (Positions 7-11)
Positions
Entry
7-11
/FREE or /END-FREE
12-80
Blank

The /FREE compiler directive specifies the beginning of a free-form calculation specifications block. /END-FREE specifies the end of the block. Positions 12 through 80 must be blank. The remaining positions may be used for comments. See Free-Form Syntax for information on using free-form statements.


/TITLE (Positions 7-12)

Use the compiler directive /TITLE to specify heading information (such as security classification or titles) that is to appear at the top of each page of the compiler listing. The following entries are used for /TITLE:

Positions
Entry
7-12
/TITLE
13
Blank
14-100
Title information

A program can contain more than one /TITLE statement. Each /TITLE statement provides heading information for the compiler listing until another /TITLE statement is encountered. A /TITLE statement must be the first RPG specification encountered to print information on the first page of the compiler listing. The information specified by the /TITLE statement is printed in addition to compiler heading information.

The /TITLE statement causes a skip to the next page before the title is printed. The /TITLE statement is not printed on the compiler listing.


/EJECT (Positions 7-12)
Positions
Entry
7-12
/EJECT
13-49
Blank
50-100
Comments

Enter /EJECT in positions 7 through 12 to indicate that subsequent specifications are to begin on a new page of the compiler listing. Positions 13 through 49 of the /EJECT statement must be blank. The remaining positions may be used for comments. If the spool file is already at the top of a new page, /EJECT will not advance to a new page. /EJECT is not printed on the compiler listing.


/SPACE (Positions 7-12)

Use the compiler directive /SPACE to control line spacing within the source section of the compiler listing. The following entries are used for /SPACE:

Positions
Entry
7-12
/SPACE
13
Blank
14-16
A positive integer value from 1 through 112 that defines the number of lines to space on the compiler listing. The number must be left-adjusted.
17-49
Blank
50-100
Comments

If the number specified in positions 14 through 16 is greater 112, 112 will be used as the /SPACE value. If the number specified in positions 14 through 16 is greater than the number of lines remaining on the current page, subsequent specifications begin at the top of the next page.

/SPACE is not printed on the compiler listing, but is replaced by the specified line spacing. The line spacing caused by /SPACE is in addition to the two lines that are skipped between specification types.


/COPY or /INCLUDE

The /COPY and /INCLUDE directives have the same purpose and the same syntax, but are handled differently by the SQL preprocessor. If your program does not have embedded SQL, you can freely choose which directive to use. If your program has embedded SQL, see Using /COPY, /INCLUDE in Source Files with Embedded SQL for information about which directive to use.

The /COPY and /INCLUDE compiler directives cause records from other files to be inserted, at the point where the directive occurs, with the file being compiled. The inserted files may contain any valid specification including /COPY and /INCLUDE up to the maximum nesting depth specified by the COPYNEST keyword (32 when not specified).

/COPY and /INCLUDE files can be either physical files or IFS files. To specify a physical file, code your /COPY and /INCLUDE statement in the following way :

  • /COPY or /INCLUDE followed by exactly one space followed by the file name or path
  • when specifying a physical file, the library, file, and member name, can be in one of these formats:
    libraryname/filename,membername  
    filename,membername  
    membername     
    • A member name must be specified.
    • If a file name is not specified, QRPGLESRC is assumed.
    • If a library is not specified, the library list is searched for the file. All occurrences of the specified source file in the library list are searched for the member until it is located or the search is complete.
    • If a library is specified, a file name must also be specified.
  • When specifying an IFS (Integrated File System) file, the path can be either absolute (beginning with /) or relative.
    • The path can be enclosed in single or double quotes. If the path contains blanks, it must be enclosed in quotes.
    • If the path does not end with a suffix (for example ".txt"), the compiler will search for the file as named, and also for files with suffixes of ".rpgle" or ".rpgleinc".
    • See the WebSphere Development Studio: ILE RPG Programmer's Guidefor information on using IFS /COPY files.
  • Optionally, at least one space and a comment.

/COPY members are considered fixed-form by default, even if the /COPY directive is coded within a free-form group. If the /COPY member will contain free-form specifications, these must be delimited with /FREE and /END-FREE directives.

TIP

To facilitate application maintenance, you may want to place the prototypes of exported procedures in a separate source member. If you do, be sure to place a /COPY or /INCLUDE directive for that member in both the module containing the exported procedure and any modules that contain calls to the exported procedure.

Figure 3 shows some examples of the /COPY and /INCLUDE directive statements.

Figure 3. Examples of the /COPY and /INCLUDE Compiler Directive Statements


C/COPY MBR1 (1)     
I/INCLUDE SRCFIL,MBR2 (2)     
O/COPY SRCLIB/SRCFIL,MBR3 (3)     
O/INCLUDE "SRCLIB!"/"SRC>3","MBR¬3" (4)     
O/COPY /dir1/dir2/file.rpg (5)     
O/COPY /dir1/dir2/file (6)     
O/COPY dir1/dir2/file.rpg (7)     
O/COPY "ifs file containing blanks"  (8)     
O/COPY 'ifs file containing blanks'  (8)              
(1)
Copies from member MBR1 in source file QRPGLESRC. The current library list is used to search for file QRPGLESRC. If the file is not found in the library list, the search will proceed to the IFS, looking for file MBR1, MBR1.rpgle or MBR1.rpgleinc in the include search path. See the WebSphere Development Studio: ILE RPG Programmer's Guide, SC09-2507-04 for information on using IFS source files.
(2)
Copies from member MBR2 in file SRCFIL. The current library list is used to search for file SRCFIL. Note that the comma is used to separate the file name from the member name. If the file is not found in the library list, the search will proceed to the IFS, looking for file SRCFIL, MBR1 in the include search path, possibly with the .rpgle or .rpgleinc suffixes.
(3)
Copies from member MBR3 in file SRCFIL in library SRCLIB or from the IFS file SRCFIL, MBR3 in directory SRCLIB.
(4)
Copies from member "MBR¬3" in file "SRC>3" in library "SRCLIB!"
(5)
Copies from the IFS file file.rpg in directory /dir1/dir2.
(6)
Copies from file, or file.rpgleinc or file.rpgle in directory /dir1/dir2
(7)
Copies from the IFS file file.rpg in directory dir1/dir2, searching for directory dir1/dir2 using the IFS search path.
(8)
Copies from a file whose name contains blanks.
Results of the /COPY or /INCLUDE during Compile

During compilation, the specified file members are merged into the program at the point where the /COPY or /INCLUDE statement occurs. All members will appear in the COPY member table.

Nested /COPY or /INCLUDE

Nesting of /COPY and /INCLUDE directives is allowed. A /COPY or /INCLUDE member may contain one or more /COPY or /INCLUDE directives (which in turn may contain further /COPY or /INCLUDE directives and so on). The maximum depth to which nesting can occur can be set using the COPYNEST control specification keyword. The default maximum depth is 32.

TIP

You must ensure that your nested /COPY or /INCLUDE files do not include each other infinitely. Use conditional compilation directives at the beginning of your /COPY or /INCLUDE files to prevent the source lines from being used more than once.

For an example of how to prevent multiple inclusion, see Figure 4.

Using /COPY, /INCLUDE in Source Files with Embedded SQL

The /COPY and /INCLUDE directives are identical except that they are handled differently by the SQL pre-processor:

  • The /COPY directive is expanded by the preprocessor. The copied file can contain embedded SQL or host variables.
  • The /INCLUDE directive is not expanded by the preprocessor. The included file cannot contain embedded SQL or host variables.

If you use only the /COPY directive, you may encounter the following problems:

  • The SQL preprocessor does not allow nested /COPY commands.
  • The SQL preprocessor does not always handle conditional compilation directives correctly.

To get around these problems:

  • Specify /COPY in a program with embedded SQL if the copy file contains embedded SQL or host variable definitions.
  • Specify /INCLUDE within the copied file to include any nested files.
  • Specify either /COPY or /INCLUDE if you are not using embedded SQL.

Conditional Compilation Directives

The conditional compilation directive statements allow you to conditionally include or exclude sections of source code from the compile.

  • Condition-names can be added or removed from a list of currently defined conditions using the defining condition directives /DEFINE and /UNDEFINE.
  • Condition expressions DEFINED(condition-name) and NOT DEFINED(condition-name) are used within testing condition /IF groups.
  • Testing condition directives, /IF/ELSEIF/ELSE and /ENDIF, control which source lines are to be read by the compiler.
  • The /EOF directive tells the compiler to ignore the rest of the source lines in the current source member.
Defining Conditions

Condition-names can be added to or removed from a list of currently defined conditions using the defining condition directives /DEFINE and /UNDEFINE.

/DEFINE (Positions 7-13)

The /DEFINE compiler directive defines conditions for conditional compilation. The entries in the condition-name area are free-format (do not have to be left justified). The following entries are used for /DEFINE:

Positions
Entry
7 - 13
/DEFINE
14
Blank
15 - 80
condition-name
81 - 100
Comments

The /DEFINE directive adds a condition-name to the list of currently defined conditions. A subsequent /IF DEFINED(condition-name) would be true. A subsequent /IF NOT DEFINED(condition-name) would be false.

Note:
The command parameter DEFINE can be used to predefine up to 32 conditions on the CRTBNDRPG and CRTRPGMOD commands.
/UNDEFINE (Positions 7-15)

Use the /UNDEFINE directive to indicate that a condition is no longer defined. The entries in the condition-name area are free-format (do not have to be left justified).

Positions
Entry
7 - 15
/UNDEFINE
16
Blank
17 - 80
condition-name
81 - 100
Comments

The /UNDEFINE directive removes a condition-name from the list of currently defined conditions. A subsequent /IF DEFINED(condtion-name) would be false. A subsequent /IF NOT DEFINED(condition-name) would be true.

Note:
Any conditions specified on the DEFINE parameter will be considered to be defined when processing /IF and /ELSEIF directives. These conditions can be removed using the /UNDEFINE directive.
Predefined Conditions

Several conditions are defined for you by the RPG compiler. These conditions cannot be used with /DEFINE or /UNDEFINE. They can only be used with /IF and /ELSEIF.

Conditions Relating to the Environment
*ILERPG
This condition is defined if your program is being compiled by the ILE RPG IV compiler (the compiler described in this document).
      * This module is to be defined on different platforms.  With
      * the ILE RPG compiler, the BNDDIR keyword is used to
      * indicate where procedures can be found.  With a different 
      * compiler, the BNDDIR keyword might not be valid.
      /IF DEFINED(*ILERPG)
     H BNDDIR('QC2LE')
      /ENDIF  

To learn what conditions are available with another version of the RPG IV compiler, consult the reference for the compiler. For example, for VisualAge RPG see VisualAge RPG Language Reference, SC09-2451-04.

Conditions Relating to the Command Being Used
*CRTBNDRPG
This condition is defined if your program is being compiled by the CRTBNDRPG command, which creates a program.
      /IF DEFINED(*CRTBNDRPG)
     H DFTACTGRP(*NO) 
      /ENDIF  
*CRTRPGMOD
This condition is defined if your program is being compiled by the CRTRPGMOD command, which creates a module.
      * This code might appear in a generic Control specification 
      * contained in a /COPY file.  The module that contains the
      * main procedure would define condition THIS_IS_MAIN before
      * coding the /COPY directive.
      * If the CRTRPGMOD command is not being used, or if
      * THIS_IS_MAIN is defined, the NOMAIN keyword will not
      * be used in this Control specification. 
      /IF DEFINED(*CRTRPGMOD)
      /IF NOT DEFINED(THIS_IS_MAIN)
     H NOMAIN
      /ENDIF
      /ENDIF  

Conditions Relating to the Target Release

*VxRxMx
This condition is defined if your program is being compiled for a version that is greater than or equal to the release in the condition, starting with *V4R4M0 (Version 4 Release 4 Modification 0).

Use this condition if you will run the same program on different target releases, and want to take advantage of features that are not available in every release. Support for this condition is available starting with *V4R4M0 systems with the appropriate PTF installed.

      /IF DEFINED(*V5R1M0)

      * Specify code that is valid in V5R1M0 and subsequent releases

     I/INCLUDE SRCFIL,MBR2

      /ELSE
      * Specify code that is available in V4R4M0

     I/COPY SRCFIL,MBR2 

      /ENDIF  
Condition Expressions

A condition expression has one of the following forms:

  • DEFINED(condition-name)
  • NOT DEFINED(condition-name)

The condition expression is free-format but cannot be continued to the next line.

Testing Conditions

Conditions are tested using /IF groups, consisting of an /IF directive, followed by zero or more /ELSEIF directives, followed optionally by an /ELSE directive, followed by an /ENDIF directive.

Any source lines except compile-time data, are valid between the directives of an /IF group. This includes nested /IF groups.

Note:
There is no practical limit to the nesting level of /IF groups.
/IF Condition-Expression (Positions 7-9)

The /IF compiler directive is used to test a condition expression for conditional compilation. The following entries are used for /IF:

Positions
Entry
7 - 9
/IF
10
Blank
11 - 80
Condition expression
81 - 100
Comments

If the condition expression is true, source lines following the /IF directive are selected to be read by the compiler. Otherwse, lines are excluded until the next /ELSEIF, /ELSE or /ENDIF in the same /IF group.

/ELSEIF Condition-Expression (Positions 7-13)

The /ELSEIF compiler directive is used to test a condition expression within an /IF or /ELSEIF group. The following entries are used for /ELSEIF:

Positions
Entry
7 - 13
/ELSEIF
14
Blank
15 - 80
Condition expression
81 - 100
Comments

If the previous /IF or /ELSEIF was not satisfied, and the condition expression is true, then source lines following the /ELSEIF directive are selected to be read. Otherwise, lines are excluded until the next /ELSEIF, /ELSE or /ENDIF in the same /IF group is encountered.

/ELSE (Positions 7-11)

The /ELSE compiler directive is used to unconditionally select source lines to be read following a failed /IF or /ELSEIF test. The following entries are used for /ELSE:

Positions
Entry
7 - 11
/ELSE
12 - 80
Blank
81 - 100
Comments

If the previous /IF or /ELSEIF was not satisfied, source lines are selected until the next /ENDIF.

If the previous /IF or /ELSEIF was satisfied, source lines are excluded until the next /ENDIF.

/ENDIF (Positions 7-12)

The /ENDIF compiler directive is used to end the most recent /IF, /ELSEIF or /ELSE group. The following entries are used for /ENDIF:

Positions
Entry
7 - 12
/ENDIF
13 - 80
Blank
81 - 100
Comments

Following the /ENDIF directive, if the matching /IF directive was a selected line, lines are unconditionally selected. Otherwise, the entire /IF group was not selected, so lines continue to be not selected.

Rules for Testing Conditions
  • /ELSEIF, and /ELSE are not valid outside an /IF group.
  • An /IF group can contain at most one /ELSE directive. An /ELSEIF directive cannot follow an /ELSE directive.
  • /ENDIF is not valid outside an /IF, /ELSEIF or /ELSE group.
  • Every /IF must be matched by a subsequent /ENDIF.
  • All the directives associated with any one /IF group must be in the same source file. It is not valid to have /IF in one file and the matching /ENDIF in another, even if the second file is in a nested /COPY. However, a complete /IF group can be in a nested /COPY.
The /EOF Directive

The /EOF directive tells the compiler to ignore the rest of the source lines in the current source member.

/EOF (Positions 7-10)

The /EOF compiler directive is used to indicate that the compiler should consider that end-of-file has been reached for the current source file. The following entries are used for /EOF:

Positions
Entry
7 - 10
/EOF
11 - 80
Blank
81 - 100
Comments

/EOF will end any active /IF group that became active during the reading of the current source member. If the /EOF was in a /COPY file, then any conditions that that were active when the /COPY directive was read will still be active.

Note:
If excluded lines are being printed on the listing, the source lines will continue to be read and listed after /EOF, but the content of the lines will be completely ignored by the compiler. No diagnostic messages will ever be issued after /EOF.
TIP

Using the /EOF directive will enhance compile-time performance when an entire /COPY member is to be used only once, but may be copied in multiple times. (This is not true if excluded lines are being printed).

The following is an example of the /EOF directive.

Figure 4. /EOF Directive


      *-----------------------------------------------------------------
      * Main source file      
      *-----------------------------------------------------------------
        ....
      /IF DEFINED(READ_XYZ)                       (1)
      /COPY XYZ   
      /ENDIF                                      (2)
       ....
      *-----------------------------------------------------------------
      * /COPY file XYZ 
      *-----------------------------------------------------------------
      /IF DEFINED(XYZ_COPIED)                     (3)
      /EOF 
      /ELSE   
      /DEFINE XYZ_COPIED 
     D .....  
      /ENDIF     

The first time this /COPY member is read, XYZ_COPIED will not be defined, so the /EOF will not be considered.

The second time this member is read, XYZ_COPIED is defined, so the /EOF is processed. The /IF DEFINED(XYZ_COPIED) ((3)) is considered ended, and the file is closed. However, the /IF DEFINED(READ_XYZ) ((1)) from the main source member is still active until its own /ENDIF ((2)) is reached.

<Previous   Next>