MTB 668-00 Multics Technical Bulletin
To: MTB Distribution
From: Al Dupuis
Date: 07/18/84
Subject: The Report Writer Subroutine Interface:
report_writer_
ABSTRACT
Customers have requested that the LINUS Report Writer be
separated from LINUS and made generally available through a
subroutine interface, with the ability to create a report from
data extracted from sources other than MRDS data bases. This MTB
references a manual that describes the subroutine interface to
the Report Writer, as well as the general structure of the system
and how newly written applications will interface to it. It also
details some of the design issues that will be resolved before
the MCR is submitted for approval.
Comments may be made:
Via forum:
>udd>Multics>meetings>report_writer_,
short name rw_
Via electronic mail:
Dupuis.Multics on System M
Via telephone:
(HVN) 357-6632 or (602) 862-6632
________________________________________
Multics Project internal working documentation. Not to be
reproduced outside the Multics Project.
MTB 668-00 Multics Technical Bulletin
Introduction
The Multics Report Writer is a new product for MR11. It has been
created from the MR10.2 LINUS Report Writer, at the request of
customers who wanted the report writing capabilities available to
format data extracted from sources other than MRDS data bases.
The version of the Report Writer described in this MTB is a
prototype that has been developed to let people assess the
design. The software is available for people to try out, but it
is only a partially completed product. It will be finished after
people have had a chance to evaluate the design, and after the
MCR has been submitted and approved. The first few transactions
in the report_writer_ meeting list some of the restrictions in
this prototype version.
Report Writer Changes
The only user visible change to the Report Writer, with its
removal from LINUS, will be to the default page length. This is
an area of the product that users have complained about, and the
default page length is changed from 66 to 0, resulting in
unpaginated reports by default. This change is made in the
prototype version of the Report Writer.
Report Writer Manual
The LINUS MR10.2 manual had substantial portions of it dedicated
to describing the Report Writer. These sections have been
removed from the LINUS manual and included in the Report Writer
manual planned for MR11. The manual can be found in the info
directory under the report_writer_dir directory, with the name
report_writer_manual. This document is suitable for line
printing only; it is fairly large and many of the lines/pages do
not conform to standard sizes. The formatting of the manual
doesn't conform to documentation standards; it is the draft input
that the documentation people will receive to create a finished
manual from. The documentation unit probably doesn't need
comments on the formatting errors, but comments on the content
would be welcomed.
Section 4 of the LINUS manual was an overview and a tutorial on
the Report Writer. This section has been broken into two
sections for the new manual; section 2 which is the overview, and
section 3 which is the tutorial. There are some changes in both
sections that have been made to reflect the removal of this
product from LINUS. Change bars have been included in the manual
to let readers easily see what the differences are, although they
won't be included in the version of the manual that will be made
available to customers. Also, in the tutorial portion, the user
MTB 668-00 Multics Technical Bulletin
session will have to be re-run and any differences due to its
removal from LINUS will have to be made to this section. The
only difference expected should be from the default page length
change.
Section 5 of the LINUS manual included the descriptions for the
Report Writer requests. These have been moved to section 4 of
the new manual, and contain change bars to let readers easily see
any differences because of their removal from LINUS. Once again,
these change bars won't be included in the final version of the
manual.
The rest of the manual is new. Section 1 is a brief introduction
to the Report Writer and an overview of the manual. Section 5 is
the report_writer_ subroutine overview. Section 6 is the
report_writer_ subroutine tutorial, and section 7 is the
report_writer_ subroutine reference. Section 8 is a PL/1 example
that illustrates how a Multics subsystem would use
report_writer_. This PL/1 example is the same program that will
be used to generate section 3, the user session that was
previously generated by LINUS.
Open Design Issues
There are several issues that must be investigated before the
design is complete. The rest of this MTB is dedicated to
discussing these issues. It is hoped that for the most part,
additional investigation and prototyping over the next few weeks
will resolve these open issues. It is suggested that a person
reading this MTB should look at the manual before reading about
these design issues, as the following discussion assumes
familiarity with report_writer_.
Report Writer Requests
The new Report Writer manual does not describe any interface to
the Report Writer requests, except through
ssu_$evaluate_active_string, ssu_$execute_string, and
ssu_$execute_line. This is a temporary condition in the
prototype. There will also be the following report_writer_
entrypoints: column_value, display, display_builtins,
list_format_options, restore_format_options, save_format_options,
and set_format_options. Each entrypoint will take one parameter;
the report_writer_ info pointer. They will process their
arguments through the replaceable ssu_ argument processing
procedures, and will use the replaceable ssu_$abort_line for
error situations.
There are three expected usages of report_writer_. The first is
where a Multics subsystem has one report_writer_ invocation per
MTB 668-00 Multics Technical Bulletin
ssu_ invocation, with one display request (i.e. LINUS). The
second is where a subsystem has many display_xxxx type requests,
and they all share one report_writer_ invocation in the one ssu_
invocation (no such subsystem exists yet). The third is where
there are many display_xxxx type requests, and they each have
their own report_writer_ invocation in the one ssu_ invocation
(no such subsystem exists yet). These three cases are dealt with
individually in the following paragraphs.
It is expected that the most frequent use will be the first case,
and steps have been taken to make this easier for programmers to
code. When the report_writer_ invocation is being created, it
calls ssu_$add_request_table to add the standard Report Writer
requests, specifying different entrypoints in the same PL/1
procedure for each different request. When a user at the
terminal types "display" and this report_writer_ PL/1 procedure
is invoked, it is passed the ssu_ info pointer and an info
pointer for the Multics subsystem that included the Report
Writer. It requires the report_writer_ info pointer to execute,
so looks through a static array of pointer pairs until it finds a
match between the ssu_ info pointer passed as a parameter, and an
ssu_ info pointer that was stashed away when the invocation was
created. Once it finds a match, it picks up the report_writer_
info pointer in the static array that corresponds to the ssu_
info pointer, and calls the correct report_writer_ request
entrypoint passing the report_writer_ info pointer as the only
parameter. As described, this only works correctly for the first
case.
If the above wasn't done, each subsystem writer would have to add
entries to its request table to be invoked when any of the
report_writer_ request names were typed by the user at the
terminal. They would have to write a shell for each request,
that picked up the report_writer_ info pointer from its own info
structure, and then call the report_writer_ request entrypoint
with the report_writer_ info pointer as the parameter. Every
subsystem writer would have to duplicate this code, which is
essentially what can be done once in the report_writer_, as
described in the above paragraph. Also, every subsystem writer
would be required to add additional code to pick up any new
requests offered in new versions of report_writer_. It should be
pointed out that a subsystem could choose to ignore this
convenience, and do the duplicate coding described in this
paragraph. Code that functions this way still has to be written
to determine what additional steps are necessary. It is my guess
that a call to ssu_$delete_request_table and ssu_$delete_info_dir
will prevent the standard report writer requests from showing up
or being executed by a terminal user, and the display_xxxx
requests can call report_writer_$display to have the work done.
MTB 668-00 Multics Technical Bulletin
For the second and third cases, they will have to manage their
own report_writer_ info pointer, or pointers, depending on how
many report_writer_ invocations are present. This isn't expected
to be a problem, because each display_xxxx request will know what
it is supposed to be displaying and where its particular
report_writer_ info pointer lives in the subsystems own info
structure. A display_xxxx request would call
report_writer_$display with the correct report_writer_ info
pointer. In such an environment for the second case, the
replaceable table manager procedures could become complex,
because each display_xxxx request would probably retrieve data
from distinctly different sources. A new entrypoint,
report_writer_$set_table_manager would allow the different
display_xxxx requests to switch table manager procedures as they
were about to execute.
The display_employee PL/1 example in section 8 of the Report
Writer manual works as described above for the first case.
During the next week the second and third cases will be coded to
determine if the design is correct.
Temp Segment And Area Cleanup
All of the temp segment acquisitions are done through
ssu_$get_temp_segment. All of the area acquisitions are done
through ssu_$get_area. If a program calls
ssu_$destroy_invocation and doesn't call
report_writer_$destroy_invocation, the report_writer_ environment
will be cleaned up properly when ssu_ gets rid of the temp
segments and areas. (I think; code still has to be written to
test this.) Unfortunately, retrievals from MRDS data bases can
easily overflow the process directory quota. The -temp_dir
control argument to display provides a method for specifying
another directory with more quota, but ssu_$get_temp_segment does
not allow the specification of segments in places other than the
process directory. To overcome this, these additional temp
segments are acquired through other means. A program that calls
ssu_$destroy_invocation without calling
report_writer_$destroy_invocation will not have everything
cleaned up correctly. Some experimentation needs to be done in
this area to determine how extensive this problem will be.
report_writer_$convert_and_move_row
The calling sequence should be changed to include a code and
error message. This hasn't been done yet because the only thing
that can go wrong, is if one of the value_ptrs is pointing to
someplace where it shouldn't be. The define_columns entrypoint
stashes away the descriptors handed to it, generates the
character descriptors based on the stashed away descriptors, and
MTB 668-00 Multics Technical Bulletin
provides the conversion space. So none of these items should
cause a problem. The actual conversion is done by
assign_$assign_round, and I've seen some fairly strange things
come out of it when I set the value_ptrs incorrectly. Tests will
have to be made to see which of size, conversion,
illegal_procedure, etc. can come back when converting from one
data type to character. It currently shows you when something is
wrong very quickly, because it doesn't have any condition
handlers established. It probably should establish condition
handlers for everything appropriate, and pass back information on
the column the error occured on, etc. through the new code and
error message parameters. The establishment of these condition
handlers on a row by row basis could prove to be a performance
consideration when several hundred thousand rows are being
retrieved.
Product Completion
There are still a number of things left to do before the product
is complete. Sorting isn't implemented yet, the get_query table
manager function isn't implemented yet, the area management has
been half converted over to a new scheme, etc. After the design
has been evaluated by people and the MCR has been approved, the
remaining work will be done.