HP 3000 Manuals

HP ALLBASE/4GL Developer Reference Manual Vol. 1

File Linkages Screen 

This screen allows you to define linkages to KSAM files and HP
TurboIMAGE/iX data sets other than the primary report file.

These link files are accessed when the report generator prints a report
line group.  You can optionally specify that the records read from these
files are reported.

Screen Image 


            

Field Descriptions 

Report Name   Enter the name of a report defined on the report header
screen.

Secured   Display-only field indicating the status of the secured field
on the report header screen.

Link Number   A number in the range 1 to 999 that identifies this link.
If you are defining a new file linkage, the number in this field becomes
the number of the next available linkage, even if you enter a larger
number.

Action   Enter the action to be performed on this link number.  It can be
one of the following:

 A   add new linkage

 C   change this linkage

 I   insert a new linkage before
     this one

 D   delete this linkage

Link From Line Group   Enter the report print line group that initiates
the file linkage.  It can be any report line group including link print
line groups.

Print Line Group   Optional.  Enter the line group to be printed if the
linkage is successful.

If you specify a line group in this field, the report generator continues
to read the link file and print this line group until one of the
following occurs:

   *   The end of the link file is detected.

   *   A post-read function sets the switch *ENDLINE on to indicate that
       no more records are to be read from this link file.

   *   The value contained in the key field of the record just read no
       longer matches the value specified by *KEY=.

If you specify a line group in this field, you must not specify the same
line group as that specified in the Link From Line Group field.

End of Link Line Group   Optional.  Enter a line group to be printed when
one of the following occurs:

   *   The end of the link file is reached.

   *   You specify that no more records are to be read from the link file
       by setting the switch *ENDLINE on.

   *   The value contained in the key field of the record just read
       changes from the value specified by *KEY=.

If you specify a line group in this field, it must not be the same line
type as that specified in the Link From Line Group field.

Post Read Function   Optional.  Enter the name of a function that is
executed immediately after each record is read from the link file.  The
function can set the switch *ENDLINE onto indicate that no more records
are to be read.

This function can also set the switch *BYPASS to on to indicate that the
record is to be bypassed.  If you do bypass a record read from the link
file, the report generator does not perform any selection criteria tests
(if defined) for the record.  However, the after-selection function (if
defined) is still executed.

Link File [.Record]   Enter the name of the KSAM file or HP TurboIMAGE/iX
data set to be read for the link.  The record layout name is optional.
The report generator uses the default record layout for the file if you
don't specify a record layout name.

Index Number   Enter the number of the index used to read the link file.
The entry in this field defaults to 1, specifying that the report
generator uses the primary index to read the file.  If you do specify an
index number, it must correspond to an index number declared for the
default record layout for the link file.

*KEY=   This field defines the value of the key the report generator uses
to access the link file.  The entry in this field can be any of the
following:

   *   Literal.

   *   Alphanumeric constant.

   *   Variable or calculated item.

   *   Screen field reference.

   *   Scratch-pad field reference.

   *   File record field reference.

   *   Work area field reference.

   *   Non-numeric communication area field.

Must the Record be Present   Enter Y if the first read of this link file
must be successful.  That is, the link is critical and a record with the
specified key value must exist on the link file.

Enter N if the existence of a link file record is optional.

Refer to Additional Information below for a description of the actions
taken by the report generator if the link file record is not found.

Function Keys 

f1       Header  Cancels the current screen and displays the report
        header screen.

f2       Record Select  Cancels the current screen and displays the
        selection criteria screen.

f3       Line Header  Cancels the current screen and displays the report
        line header screen.

f4       Generate Report  Generates the report.

Additional Information 

The report generator allows you to specify up to 999 file linkages for
each report.

Critical Linkages.     

You can specify that a link is critical by entering Y in the Must Record 
be Present field.  This action specifies that the report generator must
find a record that matches the required key value the first time the file
is read.  If you specify that the link is critical, and the report
generator does not find the specified record in the link file or reaches
the end of the link file, the following actions occur:

   *   The value in the communication area field *IOSTATUS is set to the
       value of the file error condition encountered.  (Refer to appendix
       C for file error codes.)

   *   The buffer for the file is cleared.

   *   The switch *ENDLINE is set on and the report generator does not
       print the line group that initiated the file linkage.

If the link file read failure is caused by any error condition other than
a failure to find the record or reaching the end of the link file, HP
ALLBASE/4GL aborts the report.

Non-Critical Linkages.     

If you specify that the link is not critical, and the report generator
fails to find a record in a link file, the following actions occur:

   *   The communication area field *IOSTATUS is set to the value of the
       file error condition encountered.  (Refer to appendix C for file
       error codes.)

   *   The file record buffer is cleared. 

   *   The report generator executes the post-read function associated
       with this link.  The report generator then prints the end of link
       print line group if you have specified one.

Limitations 

The report can use any type of file as the primary report file, but you
can only define linkages to KSAM data files or HP TurboIMAGE/iX data
sets.  Linkages to SQL tables, select lists, or serial files cannot be
defined.

MPE/iX 5.0 Documentation