09/11/85  report_writer_.table_mgr

Function:  The table_manager procedure is written by the application
programmer, and is part of the application that uses report_writer_.
The table_manager procedure is responsible for retrieving rows from the
source data file (or files) that the application wishes to use in
formatting the report.


Entry points in table_manager:
   (List is generated by the help command)


:Entry: create_table: 09/03/85  table_manager$create_table

Function:  This entry is called by report_writer_ when the display
request is invoked with the -new_retrieval control argument (Default).
It performs any initialization required to perform its data retrieval
function.  It then retrieves the first row from its source data file,
and places it in the row_value buffer.


Usage:
dcl table_manager$create_table entry (ptr, fixed bin(35));
call table_manager$create_table (info_ptr, code);


Arguments:
info_ptr (Input)
   is the pointer to the application's info structure that is passed to
   the ssu_$create_invocation entrypoint by the application when the
   ssu_ invocation is created.
code (Output)
   is a standard Multics error code.  If this entry finds the source
   data file empty when the retrieval of the first row is attempted, it
   sets this code to rw_error_$no_data.  If this entry executes
   successfully it sets this code to zero.  If this entry encounters
   any other problem during execution, it sets the code to indicate
   what the source of the problem is.


Notes:  The application's info structure must contain the row_info_ptr
passed to report_writer_$define_columns.  This points to the row_info
structure, which in turn points to row_value buffer.
table_manager$create_table must move the first row of data into this
row_value buffer, either by a PL/I assignment or substr pseudovariable,
or by calling report_writer_$convert_and_move_row.


:Entry: delete_table: 09/03/85  table_manager$delete_table

Function:  This entry is called by report_writer_ when the formatting
of the report is completed.  After the last data row is retrieved, it
performs any termination steps required by the application.


Usage:
dcl table_manager$delete_table entry (ptr, fixed bin(35));
call table_manager$delete_table (info_ptr, code);


Arguments:
info_ptr (Input)
   is the pointer to the application's info structure that is passed to
   the ssu_$create_invocation entrypoint by the application when the
   ssu_ invocation is created.
code (Output)
   is a standard Multics error code.  If this entry executes
   successfully it sets this code to zero.  If this entry encounters
   any problem during execution, it sets the code to indicate what the
   source of the problem is.


:Entry: get_query: 09/03/85  table_manager$get_query

Function:  This entry is called by report_writer_ when the
save_format_options request is invoked with the -query control
argument.  It returns to report_writer_ the requests needed to select
the data currently being displayed, so that these requests can be saved
along with the report layout.  If the application does not support user
requests to select data, this entrypoint should not be provided.


Usage:
dcl table_manager$get_query entry (ptr, ptr, bin(21),
     fixed bin(35));
call table_manager$get_query (info_ptr, query_segment_ptr,
     query_length, code);


Arguments:
info_ptr (Input)
   is the pointer to the application's info structure that is passed to
   the ssu_$create_invocation entrypoint by the application when the
   ssu_ invocation is created.
query_segment_ptr (Input)
   is the pointer to a segment provided by report_writer_, where the
   data selection requests are placed by this entrypoint.
query_length (Output)
   is the length in characters of the returned data selection requests.
   This entrypoint sets the length to let report_writer_ know how many
   characters are being returned.
code (Output)
   is a standard Multics error code.  If this entry executes
   successfully it sets this code to zero.  If this entry encounters
   any problem during execution, it sets the code to indicate what the
   source of the problem is.


Notes:  The data selection requests are dependent on the application,
and should contain whatever requests are necessary to select the data
currently being displayed.  These requests are executed from within a
subsystem exec_com when the saved report layout is restored by the
report_writer_ restore_format_options request.  An example of data
selection statments specific to the LINUS subsystem follows.

   input_query -force -brief -terminal_input
   select * from employee
   .
   translate_query

If any ampersands are found within the data selection requests that
would be interpreted by exec_com when the report layout is restored,
they are protected by save_format_options with double ampersands before
being placed in the saved report layout file.  In the case of a
subsystem like LINUS, a portion of a select statement that looked like:

   & name = "Smith"

would be saved as:

   && name = "Smith"


:Entry: get_row: 09/03/85  table_manager$get_row

Function:  This entry is called by report_writer_ when a row is needed
during the formatting of the report.  It retrieves a row from its
source data file and places it in the report_writer_ row value buffer.


Usage:
dcl table_manager$get_row entry (ptr, fixed bin(35));
call table_manager$get_row (info_ptr, code);


Arguments:
info_ptr (Input)
   is the pointer to the application's info structure that is passed to
   the ssu_$create_invocation entrypoint by the application when the
   ssu_ invocation is created.
code (Output)
   is a standard Multics error code.  If this entry executes
   successfully it sets this code to zero.  If this entry encounters an
   end-of-file on the source data file, it sets this code to
   error_table_$end_of_info.  If this entry encounters any other
   problem during execution, it sets the code to indicate what the
   source of the problem is.


Notes:  The application's info structure must contain the row_info_ptr
passed to report_writer_$define_columns.  This points to the row_info
structure, which in turn points to row_value buffer.
table_manager$get_row must move the first row of data into this
row_value buffer, either by a PL/I assignment or substr pseudovariable,
or by calling report_writer_$convert_and_move_row.


                                          -----------------------------------------------------------


Historical Background

This edition of the Multics software materials and documentation is provided and donated
to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. 
as a contribution to computer science knowledge.  
This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology,
Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL
and BULL HN Information Systems Inc. to the development of this operating system. 
Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970),
renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership
of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture 
for managing computer hardware properly and for executing programs. Many subsequent operating systems 
incorporated Multics principles.
Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., 
as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. .

                                          -----------------------------------------------------------

Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without
fee is hereby granted,provided that the below copyright notice and historical background appear in all copies
and that both the copyright notice and historical background and this permission notice appear in supporting
documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining
to distribution of the programs without specific prior written permission.
    Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc.
    Copyright 2006 by BULL HN Information Systems Inc.
    Copyright 2006 by Bull SAS
    All Rights Reserved