HP 3000 Manuals HP 3000 Manuals
File Insertion, and Merging and Editing Operations
There are essentially two types of file merging functions available to
you through the preprocessor. The first uses the preprocessor command,
$INCLUDE. The second merging function is done using any of the operating
system's COBOL commands, and optionally, the $EDIT preprocessor command.
$INCLUDE Command
The $INCLUDE command allows you to specify an entire file to be sent,
line by line, to the compiler as part of your source file. See also COPY
statement.
The $INCLUDE command has the following format:
$INCLUDE filename
where filename is the name of the file whose records are to be sent to
the compiler.
$INCLUDE commands may be nested. That is, the file that is being
included may itself have an $INCLUDE command in it. This nesting may go
to a depth of ten.
When the $INCLUDE command is encountered in a source file, the following
actions take place:
1. The file named in the $INCLUDE command is opened.
2. This file then becomes the input file. Each line of the file is
processed and the results are sent to the compiler. If sequence
numbers exist for the lines (records) of the file, they are
preserved.
3. When the end-of-file is reached for the included file, it is
closed.
4. The next line in the original source code is processed and sent to
the compiler.
Note that the $INCLUDE command has no effect upon the text, master or
newfiles. The $INCLUDE command, if used, and the included file data is
sent to the listfile, while only the $INCLUDE command is sent to the
newfile resulting from the compilation process.
Example
000100$INCLUDE INITFILE
001000 ENVIRONMENT DIVISION.
001100 CONFIGURATION SECTION.
:
If INITFILE contains the records,
000200$CONTROL SUBPROGRAM
000300 IDENTIFICATION DIVISION.
000400 PROGRAM-ID. SUBDUMMY.
000500 AUTHOR. JPW.
000600 INSTALLATION. GSD.
000700 DATE-WRITTEN. DUMMY-WRITTEN-05/08/85.
000800 DATE-COMPILED. WHEN-USED.
000900 SECURITY. NONE-ON-DUMMY.
Then when the $INCLUDE statement above is executed, the results are as
follows.
000100$INCLUDE INITFILE
000200$CONTROL SUBPROGRAM
000300 IDENTIFICATION DIVISION.
000400 PROGRAM-ID. SUBDUMMY.
000500 AUTHOR. JPW.
000600 INSTALLATION. GSD.
000700 DATE-WRITTEN. DUMMY-WRITTEN-05/08/85.
000800 DATE-COMPILED. WHEN-USED.
000900 SECURITY. NONE-ON-DUMMY.
001000 ENVIRONMENT DIVISION.
001100 CONFIGURATION SECTION.
:
Merging Files and the $EDIT Command
This section is obsolete and its use is not recommended.
Merging and editing operations are done prior to other preprocessor
functions. The following editing and merging operations are available to
you at compile-time:
1. Merge corrections or additional source text in the textfile with
an existing source program (masterfile) to produce a new source
program and commands.
2. Omit sections of the old source program during merging.
3. Check source-record sequence numbers for ascending order.
Merging Files
Merging is done at compile-time by using the textfile, masterfile, and
newfile parameters of the operating system's COBOL commands.
(For a detailed description of these commands, refer to "MPE XL System
Dependencies" in Appendix H .)
Prior to merging, the records in both textfile and masterfile must be
arranged in ascending order according to the values in their sequence
fields, or sequence fields may be blank.
The order of sequencing is based on the ASCII collating sequence.
The merging operation is based on nonblank ascending sequence fields.
During merging, nonblank sequence fields of records in both files are
checked for ascending order. If their order is improper, the appropriate
diagnostic messages are sent to your listfile.
Blank sequence fields are never considered out of sequence. They are
assumed to have the same sequence value as the last preceding record
which contains a nonblank sequence value. The sequence fields of some or
all of the records in either file may be blank, and such records may
appear anywhere in the files.
During each comparison in the merging process, one record is read from
each file, and these records are compared, with one of three results,
depending upon whether the value of the field in the record of the
textfile is equal to, greater than, or less than the value of the
sequence field in the record of the masterfile.
If the values of the sequence fields are equal, the textfile record is
sent to the compiler, and the record of the masterfile is ignored.
If the value of the sequence field in the textfile is greater than the
value of the sequence field in the masterfile, the record of the
masterfile is sent to the compiler, and the record of the textfile is
retained for comparison with the next record of the masterfile.
If the value of the sequence field in the textfile is less than the value
of the sequence field in the masterfile, the record of the textfile is
sent to the compiler, and the masterfile record is retained for
comparison with the next textfile record.
Records with a blank sequence field (from either file) are assumed to
have the same sequence field value as that of the last record with a
nonblank sequence field read from the same file. If no record with a
nonblank sequence field has yet been encountered, the blank records are
assumed to have a null sequence field.
The above description implies that records from the masterfile with blank
sequence fields are always compiled. This is because the records of the
masterfile with blank sequence fields will either eventually be less than
a sequence field for a textfile record, or the entire textfile will have
been used.
When an end-of-file condition is encountered on either textfile or
masterfile, merging terminates (except for the continuing influence of an
unterminated VOID parameter in an EDIT command). At this point, the
subsequent records on the remaining file are checked for proper sequence,
and are then compiled (except for masterfile records within the range of
a VOID parameter in a $EDIT command).
Note that masterfile records that were replaced in the merging process
are not listed in your listfile during compilation. Also, files sent to
the compiler by a $INCLUDE command have no sequence field checking
performed on them.
Sequence Field Checking.
Sequence fields are checked for proper order during the merging process
provided that both a text and a masterfile are present.
If you do not have a textfile, or if you have no masterfile, and you
still wish to have sequence fields checked, you can equate the missing
file to $NULL. If the sequence fields are out of order, a warning message
is generated and sent to the listfile. However, improperly arranged
sequence fields will not cause the compilation of the specified file to
fail.
$EDIT Command
The $EDIT preprocessor command can be used to bypass all records of the
masterfile whose sequence fields contain a certain value, and renumber
the numeric sequence fields of records in the newfile created by merging
a textfile and a masterfile.
The $EDIT command has the following format:
$EDIT [ parameter=subparameter ] [, parameter=subparameter ] [...]
Parameters.
parameter either VOID, SEQNUM, NOSEQ, or INC.
subparameter either a sequence value, a sequence number, or an
increment number. Which one is used depends on the
parameter.
VOID Parameter.
The VOID parameter is the only parameter of the $EDIT command that has
any effect upon the compilation process. The other parameters have an
effect only upon the newfile created by the merge process. If no newfile
is specified in the operating system command that initiates the
compilation process, all $EDIT commands other than $EDIT VOID=sequence
value are ignored.
If VOID is specified, then the subparameter must be a sequence value.
This parameter indicates that all records on the masterfile whose
sequence values are less than or equal to the specified sequence value,
and any subsequent records with blank sequence fields, are to be ignored.
Thus, such records are not sent to the compiler.
This voiding of masterfile records continues until a record of the
masterfile with a sequence value higher than that specified in the $EDIT
VOID command is encountered. When this occurs, the merging process
continues as described on earlier pages.
The sequence value of the VOID parameter can be either a sequence number
or a character string. If the sequence value is less than the length of
the sequence field for the masterfile, it is left filled with zeroes (if
a number), or it is left filled with blanks (if a character string).
Note that if the sequence fields for records in the masterfile contain
only numerals, and the sequence value of the VOID parameter is a
character string, all of the masterfile is voided.
SEQNUM Parameter.
SEQNUM allows you to renumber sequence fields in the newfile. If SEQNUM
is used as a parameter in the $EDIT command, it has no effect upon the
master or textfile.
Initially, renumbering of records in a newfile is disabled.
SEQNUM requires a sequence number as its subparameter. This sequence
number is the value used for the first record when resequencing begins.
Subsequent records are renumbered using an increment of 100, unless the
INC parameter of $EDIT is used to specify a different one. The records
to be renumbered start with the first record to be sent to the newfile
following the $EDIT SEQNUM command. This renumbering continues until a
$EDIT NOSEQ command is encountered in the file where the $EDIT SEQNUM
command appears.
If the sequence number subparameter of the SEQNUM command is of
insufficient length to fill the sequence field of the newfile, sufficient
zeroes are appended to the left of the sequence number to fill the
sequence field of the records in the newfile.
NOSEQ Parameter.
The NOSEQ parameter of the $EDIT command is used to terminate the
resequencing of a newfile initiated by a $EDIT SEQNUM command. If a
$EDIT NOSEQ command is issued after a $EDIT SEQNUM command, resequencing
of newfile records is terminated, and remaining records sent to the
newfile retain their old sequence values until a new $EDIT SEQNUM command
is encountered.
If a $EDIT NOSEQ command is issued when no resequencing has been
specified, it is ignored. Therefore, because no resequencing takes place
unless you issue a $EDIT SEQNUM command, the $EDIT NOSEQ command is the
default. In this case, sequence fields are retained and passed to the
newfile as records are sent to the compiler.
INC Parameter.
If INC is used as a parameter of the $EDIT command, it must have an
increment value associated with it. This increment value is used when a
$EDIT SEQNUM command is issued to renumber lines of the newfile. The
increment value may range from 1 through 999999. Note, however, that a
very large increment is of limited value, because it may cause the
sequence number to be long for the sequence field.
If no $EDIT INC command is issued, the default value is 100. This
default value stays in effect until an INC parameter specifying a new
increment value is encountered.
In general, if you wish to provide for a different increment during a
resequencing operation, the $EDIT INC command must be specified before
the $EDIT SEQNUM command is executed. As with the default value, the
increment value specified in the $EDIT INC command stays in effect until
a new increment value is specified.
$EDIT commands are normally part of the textfile. You may use them in
the masterfile, but it is not recommended because any $EDIT command using
the VOID parameter in the masterfile could void its own continuation
records. $EDIT commands themselves are never sent to the newfile. While
sequence fields are allowed, and indeed usually necessary, on records
containing $EDIT commands, continuation records for such commands should
have blank sequence fields.
During merging, a group of one or more masterfile records with blank
sequence fields are never replaced by lines from the textfile. They can
only be deleted by using the VOID parameter of $EDIT. This is
accomplished by using a sequence value subparameter at least as great as
the contents of the last nonblank sequence field preceding the group of
records with blank sequence fields. Because voided records are never
passed to the compiler or newfile, their sequence fields are never
checked for proper sequence, and they never generate an out-of-sequence
diagnostic message.
Any masterfile record replaced by a textfile record is treated as if
voided, except that following records with blank sequence fields are not
also voided. If a replaced record is out of sequence, the textfile
record that replaces it produces an out-of-sequence diagnostic message.
In general, whenever a record sent to the newfile has a nonblank sequence
field lower in value than that of the last record with a nonblank
sequence field, a diagnostic message is printed.