Directives

Complier Directives

Compiler Directive is an instruction or direction given to the compiler –

• To perform some specific tasks during compilation.
• To generate customize compiler listing report after compilation.

Compiler Directives can be used for many purposes, like :-

1. To control the spacing of the compiler listing.
2. To include source statement from another source member.
3. To do a free form calculation in our RPGLE/SQLRPGLE program.
4. To control the source records selection/omission based on some condition.
5. To control the heading information in compiler listing.

Compiler directives are divided into two types:

• Compiler directive statements. For example- /TITLE, /EJECT, /COPY and /INCLUDE etc.
• Conditional compiler directives, these allow us to select or omit the source line. For example- /IF, /ELSEIF, /ENDIF, /ELSE , /EOF etc.

Let’s go through the compiler directives one by one:

A. /TITLE

It is used to add heading information in the compiler listing. Its position on the source code is 7-12 in fixed format. From 14-100 we can give the information about the title.

Few important points:

• We can use more than one /TITLE statement in one program.
• Each /TITLE statement provides heading information for the segment of compiler listing until another /TITLE statement is encountered.
• The /TITLE statement is printed in addition to compiler heading information.
• Each /TITLE statement is printed on a new page.

Example:

In the below example, we have used TITLE directive and along with this, some information of that title, so in the compiler listing it will show this Title information and the last Title which is written as Main code in the example will be listed till last in the compiler listing.

After Compilation:

As we can see the title heading are listed in the compiler listing and the last heading MAIN CODE is listed till last as it was the last heading with directive /TITLE.

B. /EJECT

It is used to make the compiler add new pages in the compiler listing. The new pages will be added from the line where the /EJECT is specified in the code or source.

Its position on the source code is 7-12 in fixed format.

Example:

In the below example we have used /EJECT.

After Compilation:

After /EJECT the compiler will add a new page for the source listing from the line where /EJECT is used in the source code.

C. /FREE and /END-FREE

With the help of this, we can write the codes in free format. For this, we need to enclose our code between /FREE and /END-FREE.
It’s position on the source code is 7-11 in fixed format.

NOTE: It is no longer needed , it is required only if your IBM i does not have the PTF for “free format definition” RPG, that was released along with IBM i 7.1 TR7.

Example:

In the below example, we can see how we can use /Free and /End-Free directive in our code.

Here we can see we have first used the fixed format then if we want to do code in free format we can use this directive.

D. /COPY And /INCLUDE

Both /COPY and /INCLUDE is used to add source records to the current program from other source members. Both directives have the same purpose and syntax, but they are handled differently by SQL preprocessor.

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

/COPY and /INCLUDE files can be either physical files or IFS files. Its position on the source code is 7-12 in fixed format.

Syntax:

To specify a physical file, the library, file name, and member name, we can use any one of the below formats:

• Library name/source filename, member name.
  Example- /COPY PIOLIB/QRPGLESRC,COPY_SRC
• Source filename, member name.
  Example- /COPY QRPGLESRC,COPY_SRC
• Member name.
  Example- /COPY COPY_SRC

Important point regarding syntax:

• The member’s name must be specified.
• If the source file is not specified, then QRPGLESRC is assumed.
• If the Library is not specified, then library taken from the *LIBL (Library list).

Example: In the below example we have used a copy book.

After compilation:

When we compile the above program, in the compiler listing the /COPY is replaced by the actual source which we have written in the copy book source.

In the compiler listing

E. /SPACE

This directive is used to control the line spacing within the source section of compiler listing.

F. /SET And /RESTORE

/SET directive is used to temporarily set a new default value for definitions and to reverse the effect of /SET, we can use /RESTORE.

With /SET directive, we can use the following keywords:

• CCSID(*Char: ccsid)
  Syntax : CCSID(*Char: *JOBRUN or *JOBRUNMIX or *UTF8 or *HEX or number).
• CCSID(*GRAPH: ccsid)
  Syntax : CCSID(*GRAPH: *JOBRUN or *HEX or *SRC or *IGNORE or number).
• CCSID(*UCS2: ccsid)
  Syntax : CCSID(*UCS2: *UTF16 or number).
• DATFMT(format)
  Syntax : DATFMT( fmt{separator}).
• TIMFMT(format)
  Syntax : TIMFMT( fmt{separator}).

Efficient way of using these directives:

• We can specify the SET directive in a copy file so that all modules that include the copy file use the same values for the time and date formats and the CCSIDs.
• We can also code the /SET directive prior to the /COPY or /INCLUDE directive, and then code the /RESTORE directive after the /COPY or /INCLUDE directive to restore the defaults to the values that were previously in effect before the /SET directive.

Some important point :

• We can nest /SET directives.
• The keywords specified on a /RESTORE directive do not have to exactly match the keywords specified on the previous /SET directive.
• A /RESTORE directive can restore some or all the values set by any previous /SET directives.

Example:

In the below example, we have used /SET directive to set the ccsid of *char and used /RESTORE to reset the CCSID

After Compilation:

We got the below result, as we have declared the string2 variable after setting the ccsid of *char using /SET and just after declaring string2 variable we have restored the ccsid using /RESTORE directive. So we got the below result for string2.

String1 is declared before the setting ccsid and string3 is after resetting the ccsid ,so we get the character values of the string1 and string3.

G. /IF, /ELSEIF, /ELSE, /ENDIF, /DEFINE and /UNDEFINE

• /IF compiler directive is used to do the conditional compilation.
• /IF can be followed by one or more /ELSEIF, followed by an optional /ELSE, and finished with a /ENDIF.
• If the condition expression is true, source lines following the /IF directive are included in the current source to be read by the compiler. Otherwise, lines are excluded until the next /ELSEIF, /ELSE or /ENDIF in the same /IF group.
• /DEFINE directive “Set On” a condition and /UNDEFINE directive “Set Off” a condition.
• Basically, it is used to define an element that will be used as a condition element for /IF, /ELSEIF directive.

  Entry position of /IF :
  7-9 = /IF
  11-80 = conditional expressionEntry position of /ELSEIF :
  7-13 = /ELSEIF
  15-80 = conditional expression

  Entry position of /ELSE :
  7-11 = /ELSE

• The /ENDIF compiler directive is used to end the /IF, /ELSEIF or /ELSE group.
  Entry position of /ENDIF :
  7-12 = /ENDIF

Example:

The below example contains the usage of /IF,/ENDIF and /DEFINE directives.

In the below example ,we have set a condition ON using /DEFINE which is DIVIDE and then using /IF checked if the DIVIDE condition is set ON, then we will add copy book CALCDIV, otherwise not.

After Compilation:

As in the /IF the DIVIDE is defined using /DEFINE means it is ON, so in our source listing compiler will add the copy book in the source.

H. /EOF

By using this directive, we are instructing the compiler to ignore any source lines that come after this directive.

Example:

In the below example we can see how we used /EOF and when we compile this the compiler will not compile the source after the line containing /EOF.

Limitations:

There are some points we need to take care of, while using the directives.

• The compiler directive statements must precede any compile-time array or table records, translation records, and alternate collating sequence records.
• No directive can be specified within a single free-form calculation statement.
• The /IF, /ELSEIF, /ELSE, and /ENDIF directives can be specified within a single free-form control, file, definition, or procedure statement. No other directives can be specified within these statements.
• Within a free-form statement, when a line begins with what appears to be a directive that is not allowed within that statement, it is interpreted as a slash followed by a name.
• The special directive **FREE can only appear in column 1 of the first line of the source.