1 09/11/85  report_writer_
  2 
  3 Function:  The report_writer_ subroutine provides a programmer
  4 interface to the MRW system.  Through it, application subsystems can
  5 include generalized report writing capabilities, with a minimal amount
  6 of coding required by the subsystem developer.
  7 
  8 
  9 Entry points in report_writer_:
 10    (List is generated by the help command)
 11 
 12 
 13 :Entry: convert_and_move_row: 09/11/85  report_writer_$convert_and_move_row
 14 
 15 Function:  This entry converts a row of differing data types to a row
 16 of character string values and places it in the row value buffer.
 17 
 18 
 19 Usage:
 20 dcl report_writer_$convert_and_move_row entry (ptr, (*) ptr);
 21 call report_writer_$convert_and_move_row (report_writer_info_ptr,
 22      value_ptrs);
 23 
 24 
 25 Arguments:
 26 report_writer_info_ptr (Input)
 27    is the pointer to the report_writer_ info structure returned by the
 28    create_invocation entrypoint.
 29 value_ptrs (Input)
 30    is an array of pointers that point to the individual column values
 31    that are to be converted.
 32 
 33 
 34 Notes:  The number of pointers in the array must be equivalent to the
 35 number of columns defined in the table.
 36 
 37 
 38 :Entry: create_invocation: 09/11/85  report_writer_$create_invocation
 39 
 40 Function:  This entry creates a report_writer_ invocation.  It adds the
 41 standard report_writer_ request table and the standard requests info
 42 segments directory at location 99999 (see Notes).
 43 
 44 
 45 Usage:
 46 dcl report_writer_$create_invocation entry (char(*), ptr, ptr, fixed
 47      bin(35), char(*), varying);
 48 call report_writer_$create_invocation (table_manager_name,sci_ptr,
 49      report_writer_ptr, code, message);
 50 
 51 
 52 Arguments:
 53 table_manager_name (Input)
 54    is the name of the table manager procedure for the application
 55    subsystem that is creating the report writer invocation.  If the
 56    name is blank, report_writer_ obtains the name of the application
 57    subsystem via the ssu_$get_subsystem_name subroutine and uses this
 58    as the table manager procedure name.  Entry variables are
 59    constructed by report_writer_ using the name of the table manager
 60    procedure.
 61 sci_ptr (Input)
 62    is the ssu_ info pointer returned to the application subsystem when
 63    the ssu_ invocation is created.  If this parameter is null, the
 64    report_writer_ invocation is not created.
 65 
 66 
 67 report_writer_info_ptr (Output)
 68    is the pointer to the report_writer_ info structure.  This pointer
 69    is passed as the first parameter to every other report_writer_
 70    entry.
 71 code (Output)
 72    is a standard error code.  If this is non-zero the invocation could
 73    not be created.
 74 message (Output)
 75    if code is non-zero, this parameter contains the reason why the
 76    invocation could not be created.  Declaring this argument as
 77    "character(128) varying" provides an area large enough to contain
 78    any returned error message.
 79 
 80 
 81 Notes:  The table manager procedure is a program supplied by the
 82 application subsystem to manage data retrieval from its source data
 83 file.  The report_writer_ creates entry variables of the form
 84 "table_manager_name$XX", where XX are the entries that must be
 85 available in the table manager procedure.  The required entries are
 86 create_table, delete_table, and get_row.  The optional entry is
 87 get_query.
 88 
 89 
 90 The report_writer_ request tables provide a mechanism to include all of
 91 the report_writer_ standard requests (the default when an invocation is
 92 created), or selected individual report_writer_ requests.  The request
 93 table "report_writer_request_table_$standard_requests" is used by the
 94 report_writer_$create_invocation entrypoint in a call to
 95 ssu_$add_request_table to add the report_writer_ standard requests to
 96 the subsystem's set of requests.  If the standard requests are not
 97 required, the subsystem should call ssu_$delete_request table with this
 98 as a parameter, after the call to report_writer_$create_invocation.
 99 The report_writer_ standard requests are:  column_value, display,
100 display_builtins, list_format_options, restore_format_options,
101 save_format_options, and set_format_options.  The other request tables
102 defined to allow the addition of single requests are
103 report_writer_request_table_$XXX_request, where XXX is the short name
104 of the request.  These can be chosen from:  clv, di, dib, lsfo, rsfo,
105 sfo, and svfo.
106 
107 
108 The report_writer_info_dirs_ data segment provides a mechanism to
109 include the directory containing the info segment for a request.  The
110 report_writer_info_dirs_$standard_requests is used by the
111 report_writer_$create_invocation entrypoint in a call to
112 ssu_$add_info_dir, to add the info directory containing the info
113 segments for the standard requests.  If the standard requests are not
114 required, the subsystem should call ssu_$delete_info_dir with this as a
115 parameter, after the call to report_writer_$create_invocation.  The
116 other data items defined to allow the addition of directories which
117 contain the info segment for a single request are
118 report_writer_info_dirs_$XXX_requests, where XXX is the short name of
119 the request.  These can be chosen from:  clv, di, dib, lsfo, rsfo, sfo,
120 and svfo.
121 
122 
123 :Entry: define_columns: 09/11/85  report_writer_$define_columns
124 
125 Function:  This entry is used to inform report_writer_ that a set of
126 columns have been selected.  All specific and general column options
127 have new values assigned based on the newly selected columns.
128 
129 
130 Usage:
131 dcl report_writer_$define_columns entry (ptr, ptr, fixed bin(35),
132      char(*) varying));
133 call report_writer_$define_columns (report_writer_info_ptr,
134      row_info_ptr, code, message);
135 
136 
137 Arguments:
138 report_writer_info_ptr (Input)
139    is the pointer to the report_writer_ info structure returned by the
140    create_invocation entrypoint.
141 row_info_ptr (Input)
142    is a pointer to the row_info structure described in the include file
143    rw_row_info.incl.pl1 (See "Notes" below.)  If this pointer is null,
144    any previously defined specific and general column option values are
145    deleted, and the only operations allowed are to general report
146    options until this entry is
147 
148 
149 code (Output)
150    is a standard error code.  If this code is non-zero the values of
151    any previously defined specific and general columns options will
152    remain unchanged.
153 message (Output)
154    if code is non-zero this parameter will contain the reason for the
155    failure.  Declaring this argument as "character(128) varying"
156    provides an area large enough to contain any returned error message.
157 
158 
159 Notes:  The row_info structure declared in the include file
160 rw_row_info.incl.pl1 is listed below, followed by a description of the
161 members of this structure.
162 
163    declare 1 row_info aligned based (row_info_ptr),
164            2 version char(8) unaligned,
165            2 value_ptr ptr,
166            2 value_length fixed bin(21),
167            2 number_of_columns fixed bin,
168            2 current_column_number fixed bin,
169            2 column (row_info_init_number_of_columns
170                      refer (row_info.number_of_columns)),
171              3 names char(128) varying,
172              3 descriptors bit(36),
173              3 lengths fixed bin(21),
174              3 indexes fixed bin(21);
175 
176 where:
177 
178 
179 version
180    specifies to report_writer_ that the application subsystem is using
181    a particular version of the structure.  The only version currently
182    supported by report_writer_ is version 1.  The value of
183    ROW_INFO_VERSION_1, declared in the same include file, should be
184    assigned to row_info.version by the subsystem.  (Input)
185 value_ptr
186    is filled in by report_writer_ and points to the buffer where the
187    row value is placed by the application subsystem's table manager
188    procedure or the report_writer_$convert_and_move_row entrypoint.
189    (Output)
190 value_length
191    is filled in by report_writer_ and is the length of the buffer for
192    the row value.  This is set to the exact number of characters needed
193    to contain the row value after conversion from internal data types
194    to the non-varying, unaligned character data types report_writer_
195    uses.  (Output)
196 
197 
198 number_of_columns
199    is filled in when the application subsystem allocates the row_info
200    structure, by setting the variable row_info_init_number_of_columns
201    to the number of columns that should be present in the table, before
202    the allocate statement is executed.  (Input)
203 current_column_number
204    is set to zero by report_writer_ and can be used by the application
205    subsystem's table manager procedure to place individual column
206    values into the row value buffer.  (Output)
207 names
208    are filled in by the application subsystem, andare the names of the
209    individual columns.  These names must not contain whitespace because
210    of the request line syntax of the report_writer_ standard requests.
211    (Input)
212 
213 
214 descriptors
215    are filled in by the application subsystem.  They are standard data
216    type descriptors for the column data as it appears in the source
217    file that the subsystem's table manager retrieves from.  In many
218    cases they describe columns that are not nonvarying, unaligned
219    character data types, and report_writer_ must convert the column
220    values to nonvarying character strings.  It uses these data
221    descriptors to do data conversion.  It also uses these descriptors
222    when generating default report column widths, column alignment
223    modes, etc.
224 
225    If a descriptor is completely zero, the column is assumed by
226    report_writer_ to be a nonvarying, unaligned character string.  In
227    this case, the lengths field is used to determine the length in
228    characters of the column.  The descriptor is then set by
229    report_writer_ to a nonvarying, unaligned character descriptor and
230    its size portion is set to the value found in the lengths field.
231 
232    Refer to the Programmer's Reference Manual, for a description of
233    Multics standard data type descriptors.  Refer to the include files
234    "arg_descriptor.incl.pl1" and "std_descriptor_types.incl.pl1" for
235    structures and named constants to set descriptors.  (Input/Output)
236 
237 
238 lengths
239    are filled in by report_writer_, and each is the number of
240    characters needed to contain the column value after conversion from
241    any supported data type to nonvarying, unaligned character format.
242    In the case where the descriptor is completely zero, lengths are set
243    by the caller.  The report_writer_ examines the value of this field
244    to determine the length in characters for the column.
245    (Input/Output)
246 
247 
248 indexes
249    are filled in by report_writer_, and each is the index into the row
250    value buffer for a particular column.  (Input)
251 
252    There are also three variables defined in this include file to
253    description of these variables follow.
254 
255    row_value variable
256       provides a method to refer to the complete row value.  Its
257       declaration is:
258 
259          declare row_value char(row_info.value_length)
260                  based (row_info.value_ptr);
261 
262       A PL/I program to set the row value completely blank could use
263       the PL/I statement:
264 
265          row_value = " ";
266 
267    row_value_as_an_array variable
268       provides a method to refer to any single character within the row
269       value.  Its declaration is:
270 
271          declare row_value_as_an_array (row_info.value_length)
272                  char(1) based (row_info.value_ptr);
273 
274       A PL/I program to set the 15th character within the row_value to
275       a blank could use the PL/I statement:
276 
277          row_value_as_an_array (15) = " ";
278 
279    column_value variable
280       provides a method to refer to a complete column value.  Its
281       declaration is:
282 
283          declare column_value
284                  char  (row_info.column.lengths
285                          (row_info.current_column_number))
286                  based (addr (row_value_as_an_array
287                          (row_info.column.indexes
288                            (row_info.current_column_number))));
289 
290       A PL/I program to set all of the columns to blanks could use the
291       PL/I code fragment:
292 
293          do row_info.current_column_number =
294              1 to row_info.number_of_columns; column_value = " ";
295          end;
296 
297 
298 :Entry: destroy_invocation: 09/11/85  report_writer_$destroy_invocation
299 
300 Function:  This entry destroys a report_writer_ invocation.
301 
302 
303 Usage:
304 dcl report_writer_$destroy_invocation entry (ptr);
305 call report_writer_$destroy_invocation (report_writer_info_ptr);
306 
307 
308 Arguments:
309 report_writer_info_ptr (Input/Output)
310    is the pointer to the report_writer_ info structure.  If this
311    pointer is null, the call is ignored.  This pointer is set to null
312    after the invocation is destroyed.
313 
314 
315 :Entry: set_report_writer_info_ptr: 09/11/85  report_writer_$set_report_writer_info_ptr
316 
317 Function:  This entry is used by complex subsystems that require more
318 than one report_writer_ invocation to be present in the subsystem
319 invocation.  It takes the caller provided report_writer_ info pointer
320 and places it in an internal location associated with the sci_ptr.
321 When the next report_writer_ standard request is invoked, it uses the
322 new report_writer_ info pointer now associated with its sci_ptr
323 parameter.
324 
325 
326 Usage:
327 dcl report_writer_$set_report_writer_info_ptr entry (ptr, ptr, fixed
328      bin(35), char(*) varying));
329 call report_writer_$set_report_writer_info_ptr (report_writer_info_ptr,
330      sci_ptr, code, message);
331 
332 
333 Arguments:
334 report_writer_ptr (Input)
335    is the pointer to a report_writer_ info structure.  This pointer
336    becomes the report_writer_ info pointer that is passed to the
337    report_writer_ standard requests.
338 sci_ptr (Input)
339    is the pointer to the ssu_ info structure returned to the subsystem
340    by the ssu_$create_invocation entrypoint.
341 code (Output)
342    is a standard error code.  If this code is non-zero, the current
343    report_writer_ info pointer remains in effect.
344 message (Output)
345    if code is non-zero this parameter contains the reason for the
346    failure.  Declaring this argument as "character (128) varying"
347    provides an area large enough to contain any returned error message.
348 
349 
350 Notes:  The most common type of subsystem using report_writer_ is one
351 where there is only one report_writer_ invocation present in the one
352 subsystem invocation.  If a subsystem requires more than one
353 report_writer_ invocation to be present in the one subsystem
354 invocation, call the report_writer_$create_invocation as many times as
355 required, saving the returned report_writer_ info pointer after each
356 call.  This entrypoint is then called with the desired report_writer_
357 info pointer before any of the report_writer_ standard requests are
358 used.  The call to this entrypoint ensures that the correct
359 report_writer_ info pointer is used by the report_writer_ standard
360 requests.
361 
362 
363 :Entry: set_table_manager: 09/11/85  report_writer_$set_table_manager
364 
365 Function:  This entry is used by complex subsystems that require more
366 than one table_manager procedure to be used in a report_writer_
367 invocation.  It takes the caller provided table_manager name and
368 creates entry variables to the expected entrypoints.  (See the
369 "report_writer_$create_invocation entrypoint" for more information on
370 the table_manager procedure.)  After this entrypoint is called, the
371 next invocation of the report_writer_ display request uses this new
372 table_manager procedure.
373 
374 
375 Usage:
376 dcl report_writer_$set_table_manager entry (ptr, char(*), fixed
377      bin(35), char(*) varying);
378 call report_writer_$set_table_manager (report_writer_info_ptr,
379      table_manager_name, code, message);
380 
381 
382 Arguments:
383 report_writer_info_ptr (Input)
384    is the pointer to the report_writer_ info structure returned by the
385    report_writer_$create_invocation entrypoint.
386 table_manager_name (Input)
387    is the name of the new table_manager procedure.
388 code (Output)
389    is a standard error code.  If this code is non-zero, the current
390    subsystem table_manager procedure remains in effect.
391 message (Output)
392    if code is non-zero, this parameter contains the reason for the
393    failure.  Declaring this argument as "character (128) varying"
394    provides an area large enough to contain any returned error message.
395 
396 
397 Notes:  The most common type of subsystem using report_writer_ is one
398 where there is only one table_manager procedure required for the one
399 report_writer_ invocation.  If a subsystem wishes to switch between
400 different table_manager procedures within one report_writer_
401 invocation, this entrypoint should be called with the name of the new
402 table_manager procedure.  The call to this entrypoint results in the
403 new table_manager procedure being called the next time the
404 report_writer_ display request is used.