1 09/11/85  report_writer_.table_mgr
  2 
  3 Function:  The table_manager procedure is written by the application
  4 programmer, and is part of the application that uses report_writer_.
  5 The table_manager procedure is responsible for retrieving rows from the
  6 source data file (or files) that the application wishes to use in
  7 formatting the report.
  8 
  9 
 10 Entry points in table_manager:
 11    (List is generated by the help command)
 12 
 13 
 14 :Entry: create_table: 09/03/85  table_manager$create_table
 15 
 16 Function:  This entry is called by report_writer_ when the display
 17 request is invoked with the -new_retrieval control argument (Default).
 18 It performs any initialization required to perform its data retrieval
 19 function.  It then retrieves the first row from its source data file,
 20 and places it in the row_value buffer.
 21 
 22 
 23 Usage:
 24 dcl table_manager$create_table entry (ptr, fixed bin(35));
 25 call table_manager$create_table (info_ptr, code);
 26 
 27 
 28 Arguments:
 29 info_ptr (Input)
 30    is the pointer to the application's info structure that is passed to
 31    the ssu_$create_invocation entrypoint by the application when the
 32    ssu_ invocation is created.
 33 code (Output)
 34    is a standard Multics error code.  If this entry finds the source
 35    data file empty when the retrieval of the first row is attempted, it
 36    sets this code to rw_error_$no_data.  If this entry executes
 37    successfully it sets this code to zero.  If this entry encounters
 38    any other problem during execution, it sets the code to indicate
 39    what the source of the problem is.
 40 
 41 
 42 Notes:  The application's info structure must contain the row_info_ptr
 43 passed to report_writer_$define_columns.  This points to the row_info
 44 structure, which in turn points to row_value buffer.
 45 table_manager$create_table must move the first row of data into this
 46 row_value buffer, either by a PL/I assignment or substr pseudovariable,
 47 or by calling report_writer_$convert_and_move_row.
 48 
 49 
 50 :Entry: delete_table: 09/03/85  table_manager$delete_table
 51 
 52 Function:  This entry is called by report_writer_ when the formatting
 53 of the report is completed.  After the last data row is retrieved, it
 54 performs any termination steps required by the application.
 55 
 56 
 57 Usage:
 58 dcl table_manager$delete_table entry (ptr, fixed bin(35));
 59 call table_manager$delete_table (info_ptr, code);
 60 
 61 
 62 Arguments:
 63 info_ptr (Input)
 64    is the pointer to the application's info structure that is passed to
 65    the ssu_$create_invocation entrypoint by the application when the
 66    ssu_ invocation is created.
 67 code (Output)
 68    is a standard Multics error code.  If this entry executes
 69    successfully it sets this code to zero.  If this entry encounters
 70    any problem during execution, it sets the code to indicate what the
 71    source of the problem is.
 72 
 73 
 74 :Entry: get_query: 09/03/85  table_manager$get_query
 75 
 76 Function:  This entry is called by report_writer_ when the
 77 save_format_options request is invoked with the -query control
 78 argument.  It returns to report_writer_ the requests needed to select
 79 the data currently being displayed, so that these requests can be saved
 80 along with the report layout.  If the application does not support user
 81 requests to select data, this entrypoint should not be provided.
 82 
 83 
 84 Usage:
 85 dcl table_manager$get_query entry (ptr, ptr, bin(21),
 86      fixed bin(35));
 87 call table_manager$get_query (info_ptr, query_segment_ptr,
 88      query_length, code);
 89 
 90 
 91 Arguments:
 92 info_ptr (Input)
 93    is the pointer to the application's info structure that is passed to
 94    the ssu_$create_invocation entrypoint by the application when the
 95    ssu_ invocation is created.
 96 query_segment_ptr (Input)
 97    is the pointer to a segment provided by report_writer_, where the
 98    data selection requests are placed by this entrypoint.
 99 query_length (Output)
100    is the length in characters of the returned data selection requests.
101    This entrypoint sets the length to let report_writer_ know how many
102    characters are being returned.
103 code (Output)
104    is a standard Multics error code.  If this entry executes
105    successfully it sets this code to zero.  If this entry encounters
106    any problem during execution, it sets the code to indicate what the
107    source of the problem is.
108 
109 
110 Notes:  The data selection requests are dependent on the application,
111 and should contain whatever requests are necessary to select the data
112 currently being displayed.  These requests are executed from within a
113 subsystem exec_com when the saved report layout is restored by the
114 report_writer_ restore_format_options request.  An example of data
115 selection statments specific to the LINUS subsystem follows.
116 
117    input_query -force -brief -terminal_input
118    select * from employee
119    .
120    translate_query
121 
122 If any ampersands are found within the data selection requests that
123 would be interpreted by exec_com when the report layout is restored,
124 they are protected by save_format_options with double ampersands before
125 being placed in the saved report layout file.  In the case of a
126 subsystem like LINUS, a portion of a select statement that looked like:
127 
128    & name = "Smith"
129 
130 would be saved as:
131 
132    && name = "Smith"
133 
134 
135 :Entry: get_row: 09/03/85  table_manager$get_row
136 
137 Function:  This entry is called by report_writer_ when a row is needed
138 during the formatting of the report.  It retrieves a row from its
139 source data file and places it in the report_writer_ row value buffer.
140 
141 
142 Usage:
143 dcl table_manager$get_row entry (ptr, fixed bin(35));
144 call table_manager$get_row (info_ptr, code);
145 
146 
147 Arguments:
148 info_ptr (Input)
149    is the pointer to the application's info structure that is passed to
150    the ssu_$create_invocation entrypoint by the application when the
151    ssu_ invocation is created.
152 code (Output)
153    is a standard Multics error code.  If this entry executes
154    successfully it sets this code to zero.  If this entry encounters an
155    end-of-file on the source data file, it sets this code to
156    error_table_$end_of_info.  If this entry encounters any other
157    problem during execution, it sets the code to indicate what the
158    source of the problem is.
159 
160 
161 Notes:  The application's info structure must contain the row_info_ptr
162 passed to report_writer_$define_columns.  This points to the row_info
163 structure, which in turn points to row_value buffer.
164 table_manager$get_row must move the first row of data into this
165 row_value buffer, either by a PL/I assignment or substr pseudovariable,
166 or by calling report_writer_$convert_and_move_row.