MTB 677-00                             Multics Technical Bulletin

To:        MTB Distribution

From:      Al Dupuis

Date:      09/10/84

Subject:   The Report  Writer Subroutine Interface  Design Issues


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:
                                           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

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_$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.


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