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.