HP 3000 Manuals HP 3000 Manuals
The Compiler Subsystem Commands
Compiler subsystem commands are compiler directives that let you alter
the normal defaults used during compilation. For example, you can
suppress the listing of warning messages.
Compiler subsystem commands are part of the source program file and they
are identified by a $ in column 6. The compiler subsystem commands are
listed below and are described in detail later in this chapter:
Compiler Description
Subsystem
Command
$CONTROL Restricts access to the list file; suppresses source and
Cross-Reference listings of indicators, fields, tables, arrays and
files; suppresses warning messages; sets the maximum number of lines
listed per page; suppresses informational messages; sets the maximum
number of severe errors allowed; defines the delimiter character for
alphanumeric literals; supresses creation of a forms file for
WORKSTNC files.
$COPY Enables the source library facility of RPG.
$IF Determines whether portions of a program are compiled, based on
software switches.
$INCLUDE Inserts source library lines into the program. [REV BEG]
$INCLUDENOW Inserts source library lines into the program at the place this
command is specified.[REV END]
$PAGE Establishes or changes the title on the compiler listing and advances
the paper to top-of-form.
$SET Sets the software switches that determine whether compilation is
performed.
$TITLE Establishes or changes the title on the compiler listing.
The Sequence Number Field (columns 1-5) in compiler subsystem command
lines are not used (you may enter a number in this field if you wish).
You can enter the subsystem commands in either upper-case or lower-case;
they are interpreted as upper-case by the compiler.
The next three sections explain how to enter compiler system command
parameters and comments and how to continue the subsystem commands from
one line to the next. See the HP RPG Programmer's Guide for additional
examples on using the compiler subsystem commands.
Entering Subsystem Command Parameters
Most of the compiler subsystem commands have one or more parameters.
They specify various command options. You can enter parameters in any
order. Separate them by commas (spaces are ignored). You can enter
parameters in columns up to and including column 72. If you need more
space, continue the parameters on another line (see the section "Entering
Subsystem Command Continuation Lines").
When a subsystem command is executed, all of the parameters are read and
interpreted before the command is executed. Parameters are processed in
the order that you enter them. If you enter the same parameter twice or
you enter conflicting parameters, the outcome depends on where they occur
in the parameter list. For example, in the following $CONTROL subsystem
command, LIST and NOLIST appear twice:
$CONTROL LIST,NOLIST,NOLIST,LIST
When $CONTROL is executed, the effective parameter list is:
$CONTROL LIST
Entering Subsystem Command Comments
To clarify the purpose and meaning of a compiler subsystem command, you
may want to include comments with it. Comments are documentary and have
no effect on the command itself.
You can enter comments after the subsystem command name. You can also
enter comments before or after any parameter. Begin a comment with two
less-than signs (<<) and end it with two greater-than signs (>>). You
can enter comments through column 72 and you can include any ASCII
character in them except >.
Do not embed comments within a parameter and do not use the & character
to continue comments onto a second line. (See the next section,
"Entering Subsystem Command Continuation Lines", for information on
continuing comments onto a blank line.)
The following examples illustrate various ways to enter comments:
$PAGE<<PAGE EJECT,NO TITLE CHANGE.>>
$SET X1=ON,X2=ON,X3=ON<<SWITCHES 1-3 ON.>>
$SET X1=ON,X2=ON,<<LAST SW OFF>> X3=OFF
Entering Subsystem Command Continuation Lines
When a subsystem command and its parameters won't fit on one line,
continue it onto the next line. Follow the last parameter on the line
with an ampersand (&). Start the next line with a $ in column 6 and
continue the parameters starting in column 7.
When you use continuation lines, the compiler concatenates them beginning
with the character following the $. The $ and & are replaced by spaces.
When you use continuation lines, do not split a subsystem command, a
parameter or a parameter string.
For example, to split this subsystem command after the parameter MAP,
$CONTROL LIST,SOURCE,WARN,MAP,LINES=36
enter two lines as follows:
$CONTROL LIST,SOURCE,WARN,MAP,&
$LINES=36
To continue comments onto a blank line (that contains no command
parameters), enter the & after the ending >>. Continue the comments on
the next line just as you would normally, except enter a $ in column 6.
The following example shows how to continue comments onto blank lines:
$CONTROL NOWARN <<WARNING MESSAGES ON TRIVIAL ERRORS>>&
$ <<WILL NOT BE LISTED> BUT MESSAGES ON>>&
$ <<FATAL ERRORS WILL APPEAR.>>
The Compiler Subsystem Commands Reference
The sections which follow discuss the compiler subsystem commands in
detail. They are listed in alphabetical order.
$CONTROL.
This subsystem command lets you override one or more of the listing and
compiler defaults. You can place the $CONTROL subsystem command at the
beginning of the source program file and also interspersed within it.
You can use $CONTROL to:
* Restrict compiler access to the list file.[REV BEG]
* Request or suppress the source program and a Symbol Table
listing.[REV END]
* Define the number of lines per page for listing output.
* Print a Cross-Reference listing.
Syntax
$CONTROL [ERRORS=nnn] [,EXCQUIT] [,FKEYLBL] [,GEN] [,INFO][REV BEG]
[,LINES=nnnn] [,LIST] [,MAP] [,NAME=source] [,NEWSAVE] [,NOGEN]
[,NOINFO] [,NOLIST] [,NOMAP] [,NOOVFLOCHK] [,NOSOURCE] [,NOWARN]
[,NOVALD] [,OVFLOCHK] [,QUOTE= {" or '}] [,RSPACE=n][REV END]
[,SOURCE] [,WARN]
Parameters
ERRORS=nnn Sets the maximum number of severe errors allowed
during compilation to nnn. If there are more
errors, compilation terminates. If nnn is already
exceeded when this parameter is encountered,
compilation terminates immediately. If you omit
this parameter, the maximum number of severe
errors is 100.
EXCQUIT If a file open fails due to an EXCLUSIVE VIOLATION
error (FSERR 90 or 91), RPG closes files and
aborts the program immediately (instead of
aborting the program with a fatal file error and
printing a formatted dump). The system JCW is set
to FATAL90 or FATAL91. It can be tested by MPE
commands in a UDC or job stream as follows:
:RUN MYPROG (program includes $CONTROL EXCQUIT)
:IF JCW=FATAL90 OR JCW=FATAL91 THEN
: RUN WAITPROG
:ELSE
: RUN MYPROG2
:ENDIF[REV BEG]
FKEYLBL Allows applications using the RPG Screen Interface
(RSI) to specify labels for enabled function keys
f2 through f7. See the description of the SET
operation in Chapter 8, and "Redefining Function
Key Labels" in Chapter 11.[REV END]
GEN Allows the compiler to create an RSI CONSOLE forms
file from Input Specifications in the program.
The forms file is created if you omit this
parameter.
INFO Lists informational messages. Informational
messages flag source statements that, although
permissible, may not produce an intended result.
For example, omitting File Description
Specifications is legal but is not often done.
This parameter remains in effect until a NOINFO
parameter is encountered. If this parameter is
omitted, informational messages are listed.
LINES=nnnn Limits the number of lines printed on each list
file page to nnnn. When page overflow occurs, the
paper is advanced to top-of-form, the standard
page heading is printed (followed by two blank
lines) then the line that caused page overflow is
printed. When you enter nnnn, include the heading
and blank lines in it. This parameter remains in
effect until another LINES parameter is
encountered. If you omit this parameter, nnnn is
60 lines (for devices other than terminals) and
32767 lines for terminals.
LIST Gives the compiler unrestricted access to the list
file. (This enables you to use the SOURCE, MAP
and LINES parameters). This parameter remains in
effect until a NOLIST parameter is encountered.
If you omit this parameter, the compiler has
unrestricted access to the list file.
MAP Prints a Cross-Reference listing after the source
code listing (if LIST is in effect). This
parameter remains in effect until NOMAP is
encountered. If you omit this parameter at the
beginning of compilation, no Cross-Reference
listing is produced.
NAME=source Assigns a name to the source program. The name
must be a valid program name (see the Program Name
Field in Chapter 2). This parameter overrides the
name entered in the Program Name Field (columns
75-80) of the Header Specification.
NEWSAVE Keeps all new files as permanent files (normally,
new files are kept as temporary files). This
parameter is equivalent to using an MPE file
equation with the SAVE option.
NOGEN Prohibits the compiler from creating an RSI
CONSOLE forms file from Input Specifications in
the program.
NOINFO Stops the listing of informational messages. This
parameter cancels a previous INFO parameter and
remains in effect until another INFO parameter is
encountered.
NOLIST Lists (in the list file) only those source
statements that contain errors. It also lists
error messages and subsystem initiation and
completion messages. This parameter remains in
effect until LIST is encountered.
NOMAP Stops the Cross-Reference listing. This parameter
cancels a previous MAP parameter and remains in
effect until another MAP is encountered.[REV BEG]
NOOVFLOCHK Resets numeric overflow checking (after using
$CONTROL OVFLOCHK for full overflow checking) to
partial overflow checking (the default). This
allows RPG to left-truncate the computed value of
a numeric operation if the Result Field is too
small, and if the size of either the Factor 1
Field or the Factor 2 Field is as large as the
size needed for the computed value. Otherwise the
overflow trap is enabled.
[REV END]
NOSOURCE Stops the listing of source text. This parameter
cancels a previous SOURCE parameter.
NOWARN Stops the listing of warning messages. This
parameter cancels a previous WARN parameter and
remains in effect until another WARN parameter is
encountered.[REV BEG]
NOVALD Disables numeric validation. This allows
nonnumeric characters to be mixed in with digits
in numeric items. Beware, since this can cause
strange things to happen to your program. This
provides compatibility with RPG/V, where embedded
blanks in a numeric field are retained as blanks
if the field is output as an alphanumeric field.
RPG/iX converts the blanks to zeroes if you do not
specify this option.
OVFLOCHK Enables full overflow checking on the arithmetic
operations ADD, SUB, MULT, DIV, SQRT, XFOOT,
Z-ADD, and Z-SUB. This causes a trap to the error
routine if the computed value is too large for the
result field. The Result Field is not
automatically truncated as it can be with partial
overflow checking (the default) or if the $CONTROL
NOOVFLOCHK command is in effect.[REV END]
QUOTE= {"}
{'}
Defines the delimiter character for alphanumeric
literals. Enter either a quotation mark (") or an
apostrophe ('). You can use this parameter
anywhere in the program, but you typically enter
it at the beginning. If you omit this parameter,
a quotation mark is used.
This parameter does not apply to strings entered
with compiler subsystem commands.
RSPACE=n Adds additional spaces between output fields that
use relative end positions. Enter a number (1-9)
for n. If you omit this parameter, zero is used.
SOURCE Lists the source program statements (if LIST is in
effect). If you omit this parameter and the
source program file and list file are assigned to
a terminal, the source program statements and
Symbol Table listing are not listed; otherwise,
they are listed.
WARN Lists warnings with the source program. Warnings
are also written to the list file. This parameter
remains in effect until NOWARN is encountered. If
you omit this parameter, warnings are listed.
Example
The following $CONTROL subsystem command directs the compiler to list the
source program, warnings,[REV BEG] and a Cross-Reference listing.[REV
END] Only 36 lines are printed on each page of the listings.
$CONTROL LIST,SOURCE,WARN,MAP,LINES=36
$COPY. [REV BEG]
This subsystem command enables you to copy source statements into the
program from other source files or libraries. Place this command at the
beginning of the program when the program contains one or more $INCLUDE
or $INCLUDENOW compiler subsystem commands.
See the $INCLUDE and $INCLUDENOW compiler subsystem commands for rules on
using source libraries. The HP RPG/iX Programmer's Guide gives an
example of how to use $COPY and $INCLUDE.[REV END]
Syntax
$COPY
Parameters None.
$IF.
This subsystem command lets you compile parts of a program rather than
all of it. Place this command before and after sections of source code
to turn compilation ON and OFF.
$IF and $SET are used together. $SET turns up to ten software switches
ON or OFF. The $IF command tests these switches and compiles subsequent
code when they match. When they do not match, subsequent source code is
not compiled.
Even when compilation is turned OFF, source code is listed if the LIST
and SOURCE parameters of the $CONTROL subsystem command are in effect.
Syntax
$IF [Xn= {OFF}]
{ON }
Parameters
Xn{OFF}
{ON }
This parameter names the software switch to test
and the value to test for. If you omit this
parameter, subsequent source code is compiled.
Enter a number from 0 to 9 (for n) that names the
software switch.
To suspend compilation of subsequent source code,
enter a status (either OFF or ON) that does not
match the current status of the specified software
switch. (The actions of the subsystem commands
$PAGE and $TITLE are unaffected.) To resume
compilation of subsequent source code, enter a
status (either OFF or ON) that matches the current
status of the specified software switch.
Example
The $SET subsystem command in the code below turns ON switches X4 and X5.
Subsequent $IF statements turn compilation ON and OFF depending on the
status of X4 and X5. Source code block 1 is compiled because the $IF
test is true (X4 is turned ON). Source code block 2 is not compiled
because the result of the second $IF test is false. Source code block 3
is compiled because the third $IF has no parameters.
.
.
$SET X4=ON,X5=ON <<TURN SWITCHES X4 AND X5 ON.>>
.
.
$IF X4=ON <<COMPILE SOURCE BLOCK 1.>>
.
.
(source block 1)
.
.
$IF X5=OFF <<DO NOT COMPILE SOURCE BLOCK 2;>>&
$ <<CANCEL PREVIOUS $IF COMMAND.>>
.
.
(source block 2)
.
.
$IF <<CANCEL PREVIOUS $IF COMMANDS;>>&
$ <<COMPILE SOURCE BLOCK 3.>>
.
.
(source block 3)
.
.
$INCLUDE. [REV BEG]
This subsystem command copies source code from a source library into the
source program before compilation. Place this command at the point in
the source program where you want the source library facility to begin
processing statements from another file. To use $INCLUDE, you must
enable the source library facility by entering a $COPY subsystem command
at the beginning of the main program.
To understand how $INCLUDE works, it helps to understand the source
library facility (the preprocessor). Invoked when $COPY is the first
record in your source program, the preprocessor opens ten temporary files
to hold the following types of specifications:
1. Header and File Specifications
2. File Extension Specifications
3. Line Counter Specifications
4. Input Specifications (excluding DS records)
5. Input Specifications (DS records only)
6. Calculation Specifications (detail-time)
7. Calculation Specifications (total-time)
8. Calculation Specifications (subroutine)
9. Output Specifications
10. Table/Array Specifications
The preprocessor reads statements from the source program, placing them
sequentially in the appropriate temporary file based on the specification
type. Upon encountering a $INCLUDE command, the preprocessor stops
reading the main program source file and reads instead the entire file
named in the $INCLUDE command. The preprocessor adds the records from
this file, possibly a mixture of specification types, to the end of the
appropriate temporary file or files. When all library file records have
been processed, the preprocessor resumes reading the original source file
at the record following the $INCLUDE command. Any other $INCLUDE
commands in the main file are processed the same way. When all records
in the main file have been read, the preprocessor then copies the ten
temporary files in order by specification into a single file that is
passed to the compiler.
If your library file contains a Header Specification, the $INCLUDE
command referencing it must be placed before any File Specifications in
the source program. When the preprocessor encounters an Array/Table
Specification (type A), a Compiler Subsystem Command (type $), a comment
(type *), or a blank line, the statement is considered to be the same
type as the previous statement.[REV END] Do not use $INCLUDE within a
compile-time table or array appended to the end of the program (after the
first "**" separator line).
The $INCLUDE command line is listed on $STDLIST so you can verify its
location. The inserted lines from the library file are identified with a
C in column 5 of the source listing.
You can modify lines inserted from a source library. You do this by
following the $INCLUDE subsystem command with a specification that
identifies the line you want to modify and that contains the new
information. For a File Description Specification, identify the
specification by entering the same values in columns 7-14 as the
specification you want to modify and enter new information in columns
15-74. For an Input Specification, identify the specification by
entering the same values in columns 1-42 and 53-58 and enter new
information in columns 43-52 and 59-70. When you leave a field blank, it
remains unchanged. Enter an ampersand (&) in a field to blank it out.
See the HP RPG Programmer's Guide for an example of how to use $COPY and
$INCLUDE.[REV BEG] See also the related command $INCLUDENOW.[REV END]
Syntax
$INCLUDE file_name[.group[.account]]
Parameters
file_name Names the source library file containing the
source statements to be inserted.
group Identifies the MPE/iX group where the source
library resides.
account Identifies the MPE/iX account where the source
library resides.
Example
[REV BEG]
Imagine a program with the following statement in the middle of its
detail Calculation Specifications:
$INCLUDE PAF105.SOURCE
Also, a library file named PAF105 in the SOURCE group contains File
Specifications, detail-time Calculation Specifications, total-time
Calculation Specifications, and Output Specifications.
Because the first statement of the main program file is a $COPY
statement, RPG invokes the preprocessor when the program is compiled.
The preprocessor begins copying records from the main program into the
temporary file created for that particular specification type. By the
time the $INCLUDE command is encountered in the middle of the detail
Calculation Specifications, the preprocessor has copied a Header
Specification and some File Specifications to one temporary file, some
Input Specifications to another, and some detail Calculation
Specifications to another.
The $INCLUDE command directs the preprocessor to stop copying records
from the main program file and to begin copying records from the file
named in the statement, in this case PAF105. Since the first records in
file PAF105 are File Specifications and detail-time Calculation
Specifications, they are appended to the two appropriate temporary files,
one containing the File Specifications and the other containing
detail-time Calculation Specifications from the main program. Note
that when the preprocessor next reads the total-time Calculation
Specifications from the library file PAF105, the temporary file built to
contain the total-time Calculation Specifications is empty (no total-time
Calculation Specifications were read before the $INCLUDE command was
encountered in the main source program). The total-time calculations
from the library file will therefore precede any total-time calculations
that may subsequently be read from the main program. Similarly, the
Output Specifications from the library file will precede any Output
Specifications in the main program.
If you are not aware of how the preprocessor works, you may inadvertently
merge statements into your program in the wrong order, particularly if
the library file contains more than one specification type.
[REV END]
$INCLUDENOW. [REV BEG]
This subsystem command copies source code from a source library into the
source program before compilation. Place this command at the point in
the source program where you want the library source code inserted.
Unlike the $INCLUDE command, the records in the source library file named
in the $INCLUDENOW command must all be of the same specification type.
The entire file is added at the point the command appears. Also,
$INCLUDENOW positions Input Specification DS records and Calculation
Specification subroutine records correctly.
To use $INCLUDENOW, you must enable the source library facility by
entering a $COPY subsystem command as the first line of your program.
Do not use $INCLUDENOW within a compile-time table or array (after the
first "**" separator line).
The $INCLUDENOW command line is listed on $STDLIST so you can verify its
location. The inserted lines from the library file are identified with a
C in column 5 of the source listing.
The $INCLUDENOW command does not provide a way to modify source lines
brought in from source libraries.
See also the related command $INCLUDE.
Syntax
$INCLUDENOW file_name[.group[.account]]
Parameters
file_name Names the source library file containing the
source statements to insert.
group Identifies the MPE/iX group where the source
library resides.
account Identifies the MPE/iX account where the source
library resides.
Example
The following $INCLUDENOW command inserts all the records in the source
library file PAF106 into the source program at the point where the
command occurs. PAF106 resides in the SOURCE group.
$INCLUDENOW PAF106.SOURCE[REV END]
$PAGE.
This subsystem command advances the compiler listing to top-of-form, then
prints a heading followed by two blank lines. If you wish, you can enter
a title for the heading line of the new page (and for subsequent pages).
This command makes a program easier to read because it isolates blocks of
code and assigns descriptive titles to them.
If you do not enter a $PAGE or $TITLE command, the title is blank. $PAGE
does not apply to the first page of a compiler listing, to the
Cross-Reference pages or to listings directed to the terminal.
If the NOLIST parameter of the $CONTROL subsystem command is in effect,
no paper advance or printing takes place. However, if you enter a
parameter for this command, your entry becomes the current title for
subsequent printing.
Syntax
$PAGE [string[,string]...]
Parameters
string Enter one or more strings that, when concatenated,
form the title. Enclose the strings in quotation
marks (the quotation marks are not included in the
final string). You can enter any ASCII character
in the string including lower-case characters.
The final string can contain up to 104 characters
excluding the quotation marks and spaces between
strings. To include a quotation mark in the
string itself, enter two quotation marks.
The final string is printed in positions 29-132 of
the heading line.
If you omit this parameter, the current title (set
by a previous $PAGE or $TITLE subsystem command)
is printed on the new page.
Example
The following $PAGE subsystem command skips to a new page and prints the
title "GROSS PAY SUBROUTINE" in the heading line of the new page.
$PAGE "GROSS PAY SUBROUTINE"
$SET.
This subsystem command enables you to compile parts of a program rather
than all of it. Use this command to turn (up to 10) software switches ON
or OFF.
$IF and $SET are used together. $SET turns up to ten software switches
ON or OFF. The $IF command tests these switches and compiles subsequent
code when they match. When they do not match, subsequent source code is
not compiled.
Syntax
$SET [Xn= {OFF} [,Xn= {OFF} ]...]
{ON } {ON }
Parameters
Xn={OFF}
{ON }
This parameter names the software switch and
specifies whether to turn it ON or OFF. If you
omit this parameter, all 10 software switches are
turned OFF.
Enter a number from 0 to 9 (for n) that names the
software switch.
Enter ON to turn the switch ON or OFF to turn it
OFF.
Example
The $SET subsystem command in the code below turns ON switches X4 and X5.
Subsequent $IF statements turn compilation ON and OFF depending on the
status of X4 and X5. Source code block 1 is compiled because the $IF
test is true (X4 is turned ON). Source code block 2 is not compiled
because the result of the second $IF test is false. Source code block 3
is compiled because the third $IF has no parameters.
.
.
$SET X4=ON,X5=ON <<TURN SWITCHES X4 AND X5 ON.>>
.
.
$IF X4=ON <<COMPILE SOURCE BLOCK 1.>>
.
.
(source block 1)
.
.
$IF X5=OFF <<DO NOT COMPILE SOURCE BLOCK 2;>>&
$ <<CANCEL PREVIOUS $IF COMMAND.>>
.
.
(source block 2)
.
.
$IF <<CANCEL PREVIOUS $IF COMMANDS;>>&
$ <<COMPILE SOURCE BLOCK 3.>>
.
.
(source block 3)
.
.
$TITLE.
This subsystem command lets you specify the title to print in the heading
line of the compiler listing. The title is printed on each heading line
until another $TITLE command (or $PAGE command containing a new title) is
encountered. This command lets you tailor the compiler listings by
printing appropriate titles for them.
If you do not enter a $PAGE or $TITLE command, the title is blank.
$TITLE does not apply to the first page of a compiler listing, to
Cross-Reference pages or to listings directed to the terminal.
If the NOLIST parameter of the $CONTROL subsystem command is in effect,
the heading is not printed but you can still use this command to specify
a title to be used when printing resumes.
Syntax
$TITLE [string[,string]...]
Parameters
string Enter one or more strings to concatenate to form
the title. Enclose the strings in quotation marks
(the quotation marks are not included in the final
string). You can enter any ASCII character in the
string, including lower-case characters. To
include a quotation mark in the string itself,
enter two quotation marks. The final string can
contain up to 104 characters excluding quotation
marks and spaces between strings.
The final string is printed in positions 29-132 of
the heading line.
If you omit this parameter, a blank title is
printed.
Example
The following $TITLE subsystem command specifies the title, "PAW300 -
Calculate Withholding". This title is printed in the heading line of
each compiler listing page as long as LIST is in effect and until another
$TITLE or $PAGE command is encountered.
$TITLE "PAW300 - Calculate Withholding"