HP 3000 Manuals HP 3000 Manuals
RPG/iX Enhancements A.00.12
by Don Jenkins
Software Technology Division
Introduction
RPG/iX version A.00.12 includes four major enhancements provided in this
MPE/iX release.
* The first enhancement is the addition of a new compiler command,
$INCLUDENOW, which in effect is a subset of the $INCLUDE command.
It lets you insert RPG statements into your program at the
location of the $INCLUDENOW. ALL of the records in the file named
in this command are entered at this point. In particular,
$INCLUDENOW lets you insert RPG specifications into subroutines
and I-spec DS records, where the $INCLUDE previously had problems.
* The second enhancement is an expansion of the SORTA operator which
lets you sort numeric arrays. Previously, only alphanumeric
arrays could be sorted.
* The third enhancement is the addition of a new RESET operator.
This operator lets you reset files defined in F-specs as input or
update, or demand or full procedural, back to their initially
opened state. This lets you re-process the files without
re-running the program. The operator will work on MPE, KSAM, and
IMAGE files.
* The fourth enhancement lets you control the detection of overflow
on the ADD, SUB, MULT, DIV, SQRT, XFOOT, Z-ADD, and Z-SUB
operators. Two new compiler commands, $CONTROL OVFLOCHK and
$CONTROL NOOVFLOCHK, have been added for this purpose. They may
be interspersed as desired throughout your C-specs, letting you
check for overflow or do left-truncation of your result as
desired.
Overflow will be detected if the result computed from factor 1 and
factor 2 (as required by the operator) is larger than the number
of digits in the result field (i.e., left truncation will occur).
Right truncation of decimal places is not affected. H-spec
columns 55 and 65 may still be used to control the response to
overflow detection.
Overview of $INCLUDE
To understand how $INCLUDE is used, it is necessary to understand how the
pre-processor RPGCOPY works. When RPGCOPY is invoked (by $COPY as the
first record of your source program), it opens ten temporary files:
* F-specs (and the H-spec)
* E-specs
* L-specs
* I-specs (excluding any DS records)
* I-specs for DS records only
* Detail C-specs
* Total C-specs
* Subroutine C-specs
* O-specs
* Tables/arrays
RPGCOPY then begins reading the RPG source program, placing its records
sequentially in the appropriate temp files. When it encounters a
$INCLUDE record, it stops processing the RPG source program and instead
reads the entire INCLUDE file. This file may include a mix of
spec-types. Records from this file are appended to the appropriate temp
file. When all the records from this file have been processed, RPGCOPY
returns to the original source file.
You may have as many INCLUDE files in your program as you wish. Each is
processed as above. The final result is merged back into a single file
in appropriate order, and passed back to the compiler.
An example may help clarify the above. Suppose you have a program with
an INCLUDE statement in the middle of your detail C-specs. The INCLUDE
file contains some F-specs, I-specs, detail C-specs, total C-specs, and
O-specs. When the pre-processor is invoked, it reads your source file,
placing each record into the appropriate temp file. When the $INCLUDE is
encountered, source processing stops and the INCLUDE file records are
added to the temp files. In this example, the F-specs are appended to
the end of the F-spec temp file, the I-specs to the end of the I-spec
temp file, and so forth.
It is important to note that the detail C-specs are inserted at the point
of the $INCLUDE statement, the total C-specs become the first entries in
the total calculations since those from the source program have not yet
been processed, and the O-specs become the first O-specs of the final
program for the same reason.
Therefore, if you have multiple spec-types in your INCLUDE file, be
careful where you insert the $INCLUDE to be sure you get the final
desired result.
If your INCLUDE file contains only a single spec-type, you may insert the
$INCLUDE where you wish these specs to occur within your program. (With
the limitation noted above, i.e., if your INCLUDE file contains only
detail C-specs, and you place the $INCLUDE statement within your I-specs,
the C-specs will be placed before any of your source program C-specs).
If your INCLUDE file contains an H-spec, its $INCLUDE statement must be
placed prior to any F-specs in your source program.
Any other spec-type, (A-spec, $-spec, comment (* in column 6), blank
line, etc.), is placed in the section where the previous line was placed.
Description of $INCLUDENOW
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 text inserted.
To use $INCLUDENOW, you must enable the source library facility by
entering a $COPY compiler command as the first line of your program.
Only one $COPY command is needed, regardless of how many $INCLUDEs or
$INCLUDENOWs are in your program.
The records in the source library file named in the $INCLUDENOW command
must be of a single specification type, since all the records in the file
are inserted at the point of the command. Note that this differs from
$INCLUDE, in that the file named in this command may include a mix of
specification types. Also, $INCLUDE may not position I-spec DS records
or C-spec subroutine records correctly, depending on their format.
$INCLUDENOW does not have this problem.
Do not use $INCLUDENOW within a compile-time table or array (after the
first "**" separator line).
The $INCLUDENOW command lines are listed on $STDLIST so that you can
verify their location. The inserted lines from the library file are
identified with a "C" in column 5 of the source listing.
$INCLUDENOW does not support modification of lines.
SYNTAX.
$INCLUDENOW file_name[.group[.account]]
where
file_name The name of the source library file containing
the source statements to insert.
group The MPE/iX group where the library resides.
account The MPE/iX account where the 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:
$INCLUDENOW PAF106 (this assumes PAF106 is in your current
group.account)
SORTA with Numeric Arrays
There is no syntax change or addition for this enhancement. Where before
you could only name an alphanumeric array in factor 2 of this operator,
you may now name a numeric array. As before, tables are not allowed, nor
may it be an alternating array. When it is sorted, decimal points are
ignored, but signs are not.
RESET Operator
The RESET operator may be used to set a file named in an F-spec back to
its initial open condition. The file type must be INPUT or UPDATE, and
its designation must be DEMAND or FULL PROCEDURAL. It may be an MPE
(i.e., flat) file, KSAM, or IMAGE.
Typically, you would read the file sequentially until its end-of-file
indicator is set (or end-of-chain for IMAGE chained sequential reads),
and then use this indicator to condition the RESET operation to reset the
file to its initial state.
For MPE and KSAM files, RESET calls the MPE intrinsic FCONTROL with a
parameter of 5 (see the MPE/iX Intrinsics Reference Manual (32650-90028)
for details).
NOTE For KSAM files, FCONTROL 5 resets to the lowest primary key, so
this operation is not allowed if you are reading the file
chronologically (F-spec column 32 = "C").
For IMAGE files, RESET does a DBCLOSE with a mode of 3 (see the
TurboIMAGE/XL Database Management System Reference Manual (30391-90001)
for details).
To use RESET, columns 7-17 (control level, indicators) are optional,
factor 1 must be blank, and factor 2 must contain the filename of the
file to be reset, as specified in its F-specification. The result field,
decimal position, and half-adjust should be blank. A HIGH indicator
(columns 54-55) is required, and is set to ON if the RESET fails. Any
other indicators are ignored.
This operation is useful for processing a file multiple times without
having to re-run the program for each pass through the file.
Overflow Checking
The original design of RPG did not provide for any overflow checking on
arithmetic operations. It was up to the programmer to ensure that the
fields used in these operations were large enough to avoid this problem.
When Hewlett-Packard added RPG/V to the original HP 3000 system, a
minimal overflow test was added, but did not solve the general problem.
This test would give an overflow trap if the computed intermediate value
had more digits than the declared size of factor 1 and factor 2, and was
also too large to fit in the result field. If factor 1 or factor 2 were
large enough, the result would be left-truncated.
With the release of RPG/iX version A.00.12, Hewlett-Packard has
implemented full overflow checking. It applies to the operators ADD,
SUB, MULT, DIV, SQRT, XFOOT, Z-ADD, and Z-SUB. Two new compiler commands
have been added to control this capability. They are: $CONTROL OVFLOCHK
and $CONTROL NOOVFLOCHK. To protect your program, add the first one to
your source code (with the "$" in column 6) prior to any C-specifications
(or at least prior to the first operation you wish protected). If you
wish to protect some operations, and still allow left-truncation on
others (occasionally useful), use the OVFLOCHK command prior to the
operations you wish to protect, and the NOOVFLOCHK command prior to the
ones for which left-truncation is allowable. These commands may be
interspersed throughout your C-specs as often as desired.
NOTE The default is NOOVFLOCHK and is not needed unless you use OVFLOCHK
and wish to return to the default state later in your C-specs.
The response to any overflow trap may be controlled by H-specification
columns 55 and 65 as usual. See Chapter 3 of the HP RPG/iX Reference
Manual (30318-60002) for this information.