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.