MTB 677-00 Multics Technical Bulletin
To: MTB Distribution
From: Al Dupuis
Date: 09/10/84
Subject: The Report Writer Subroutine Interface Design Issues
Resolution:
ABSTRACT
MTB 668 documented the open design issues for the Report Writer
subroutine interface, report_writer_. This MTB discusses how
these design issues have been resolved.
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-6674 or (602) 249-6674
________________________________________
Multics Project internal working documentation. Not to be
reproduced outside the Multics Project.
MTB 677-00 Multics Technical Bulletin
Report Writer Requests
The simple case of one report_writer_ invocation per ssu_
invocation, where the report_writer_ display request is used by
the subsystem, remains as documented previously.
The entrypoints report_writer_$display,
report_writer_$set_format_options, etc. will not be provided as
originally documented in MTB668. Instead, a subsystem that needs
to access any of these will do so through the
ssu_$execute_string, ssu_$execute_line, and
ssu_$evaluate_active_string entrypoints. This type of usage can
be found in the pl1_example directory, as
"display_employee2.pl1". A compare_ascii between this and
display_employee.pl1 in the same directory, will show the
differences between an interactive subsystem approach and a
non-interactive subsystem approach.
The case where there is one report_writer_ invocation per ssu_
invocation, but there are multiple display_xxx type requests,
will be handled as follows. This case is best described by using
an example, and this example can be found in the
display_mrds_model_dir directory under the pl1_example directory.
The subsystem is called display_mrds_model, and it interfaces
with the mrds model interface subroutine (mmi_). The subsystem
knows exactly what it has to display, and the exact report format
that it should use, based on what is being displayed. It needs
to have the ssu_ standard requests. In addition, it needs the
display_mrds_model requests: display_authorization_mode;
display_creation_info; display_relation_attributes; and
display_relation_names. It doesn't want any of the
report_writer_ standard requests to be available to the
interactive user.
This subsystem would have the following differences when compared
to the display_employee example shown in the report writer
manual. When the report_writer_ invocation is created, the name
of a dummy table manager procedure with the correct entrypoints
is supplied to report_writer_. This is done because each of the
display_xxx requests listed above would have their own table
manager procedure. After the call to create the invocation, a
call to ssu_$delete_request_table is done to get rid of the
report_writer_ standard requests. This is followed by a call to
ssu_$listen.
When any of the display_xxx requests are typed, ssu_ calls the
appropriate display_mrds_model request. The first thing the
request does is to call the new entrypoint
report_writer_$set_table_manager, passing it's own name as the
table manager procedure. This causes report_writer_ to forget
MTB 677-00 Multics Technical Bulletin
about the previously specified dummy table manager procedure, and
find the new entry points in the request module. The request
procedure then allocates and fills in the report_writer_ row_info
structure to describe it's requirements, and calls
report_writer_$define_columns with it. The report_writer_
standard requests have been previously deleted, so it: calls
ssu_$add_request_table to have the report_writer_ display request
added; calls ssu_$execute_string with the parameter "display";
and then calls ssu_$delete_request_table to have the
report_writer_ display request removed.
All of the report_writer_ requests are available when using
ssu_$add_request_table through
report_writer_request_table_$standard_requests. This provides
adding or removing them all in one operation. Each
report_writer_ request is available individually as
report_writer_request_table_$di_request,
report_writer_request_table_$lsfo_request,
report_writer_request_table_$sfo_request, etc. Unfortunately,
the short request names had to be used instead of names like
"report_writer_request_table_$display_request", etc. because of
a name length restriction.
The case where there are multiple report_writer_ invocations per
ssu_ invocation, and each display_xxx type request has it's own
report_writer_ invocation, is handled as follows. Another
version of the display_mrds_model subsystem is located in the
display_mrds_model_dir2, under the pl1_example directory. It is
basically the same as the previously described version, but has
the following differences. The main line procedure creates 4
report_writer_ invocations instead of 1, and deletes the
report_writer_ standard requests after creating each invocation.
It wishes to provide the list_format_options and
set_format_options requests to the interactive user, so it calls
ssu_ to have these two requests added. Instead of supplying a
dummy table manager procedure when the report_writer_ invocations
are created, it supplies the name of the correct table manager
for each individual invocation.
When a request procedure is called by ssu_, instead of calling
report_writer_$set_table_manager, the request procedure calls
report_writer_$set_report_writer_info_ptr to make it's
report_writer_ invocation current. It only allocates the
row_info structure and calls report_writer_$define_columns once
in an ssu_ invocation.
The major difference seen by a terminal user when using the first
and second version of display_mrds_model is as follows. The
first version doesn't provide the user with any way to change the
report format, and every time they type a display_xxx request it
MTB 677-00 Multics Technical Bulletin
creates a new default report layout. The second version provides
the list_format_options and set_format_options requests so a user
can change the format of the report. After each display_xxx type
request executes, it's report_writer_ invocation is current until
the next display_xxx request executes. A default report format
for each display_xxx request is only created once per ssu_
invocation. So a user can type something like
"display_relation_attributes", and then use the
list_format_options and set_formations requests until the report
format suits them. They could then use another one of the
display_xxx requests, and when they switched back to
"display_relation_attributes", the old report format they defined
for it would still be current.
In summary, the new entry points report_writer_$set_table_manager
and report_writer_$set_report_info_ptr provide for the
multiplexing of table manager procedures and report_writer_
invocations. The first entrypoint provides for the case of N
display requests with one report_writer_ invocation for the one
ssu_ invocation. The second entrypoint provides for the case of
N display requests and N report_writer_ invocations for the one
ssu_ invocation. The report_writer_request_table_ provides for
the adding and deleting of the report_writer_ requests as a
whole, or selectively.
Temp Segment And Area Cleanup
The report_writer_ will remain unchanged in this aspect from the
MR10.2 version. If a display is running that uses the -temp_dir
control argument and the user's process dies before the display
cleanup handler is invoked, there could be segments left around
in the specified temporary directory. If a display has completed
that uses the -temp_dir and -keep_retrieval control arguments,
and the report_writer_$destroy_invocation entrypoint isn't
called, once again there could be temporary segments left around
in the specfied directory.
Users haven't complained that this was a problem in the MR10.2
version, so it is not expected to be a major problem in this
version. A future version of report_writer_ will use the general
Multics solution to this problem, when it is invented.
report_writer_$convert_and_move_row
Code will be added to this module to handle the conditions that
can occur can the user program has incorrectly set the value
pointers. An error code and error message parameter will be
added to the calling sequence, and they will indicate what went
wrong. Information returned through these parameters could
MTB 677-00 Multics Technical Bulletin
include: what condition occured; what row and column it occured
on; what page was being formatted when the error took place, etc.
Product Completion
With these issues resolved, the remaining work can now be
completed. The next version of report_writer_ made available
will be the finished product. This will be available on system M
and in the Ford exl library sometime in early October for
exposure.