MTB 677-00 Multics Technical Bulletin To: MTB Distribution From: Al Dupuis Date: 09/10/84 Subject: The Report Writer Subroutine Interface Design Issues Resolution: ABSTRACT MTB 668 documented the open design issues for the Report Writer subroutine interface, report_writer_. This MTB discusses how these design issues have been resolved. 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-6674 or (602) 249-6674 ________________________________________ Multics Project internal working documentation. Not to be reproduced outside the Multics Project. MTB 677-00 Multics Technical Bulletin Report Writer Requests The simple case of one report_writer_ invocation per ssu_ invocation, where the report_writer_ display request is used by the subsystem, remains as documented previously. The entrypoints report_writer_$display, report_writer_$set_format_options, etc. will not be provided as originally documented in MTB668. Instead, a subsystem that needs to access any of these will do so through the ssu_$execute_string, ssu_$execute_line, and ssu_$evaluate_active_string entrypoints. This type of usage can be found in the pl1_example directory, as "display_employee2.pl1". A compare_ascii between this and display_employee.pl1 in the same directory, will show the differences between an interactive subsystem approach and a non-interactive subsystem approach. The case where there is one report_writer_ invocation per ssu_ invocation, but there are multiple display_xxx type requests, will be handled as follows. This case is best described by using an example, and this example can be found in the display_mrds_model_dir directory under the pl1_example directory. The subsystem is called display_mrds_model, and it interfaces with the mrds model interface subroutine (mmi_). The subsystem knows exactly what it has to display, and the exact report format that it should use, based on what is being displayed. It needs to have the ssu_ standard requests. In addition, it needs the display_mrds_model requests: display_authorization_mode; display_creation_info; display_relation_attributes; and display_relation_names. It doesn't want any of the report_writer_ standard requests to be available to the interactive user. This subsystem would have the following differences when compared to the display_employee example shown in the report writer manual. When the report_writer_ invocation is created, the name of a dummy table manager procedure with the correct entrypoints is supplied to report_writer_. This is done because each of the display_xxx requests listed above would have their own table manager procedure. After the call to create the invocation, a call to ssu_$delete_request_table is done to get rid of the report_writer_ standard requests. This is followed by a call to ssu_$listen. When any of the display_xxx requests are typed, ssu_ calls the appropriate display_mrds_model request. The first thing the request does is to call the new entrypoint report_writer_$set_table_manager, passing it's own name as the table manager procedure. This causes report_writer_ to forget MTB 677-00 Multics Technical Bulletin about the previously specified dummy table manager procedure, and find the new entry points in the request module. The request procedure then allocates and fills in the report_writer_ row_info structure to describe it's requirements, and calls report_writer_$define_columns with it. The report_writer_ standard requests have been previously deleted, so it: calls ssu_$add_request_table to have the report_writer_ display request added; calls ssu_$execute_string with the parameter "display"; and then calls ssu_$delete_request_table to have the report_writer_ display request removed. All of the report_writer_ requests are available when using ssu_$add_request_table through report_writer_request_table_$standard_requests. This provides adding or removing them all in one operation. Each report_writer_ request is available individually as report_writer_request_table_$di_request, report_writer_request_table_$lsfo_request, report_writer_request_table_$sfo_request, etc. Unfortunately, the short request names had to be used instead of names like "report_writer_request_table_$display_request", etc. because of a name length restriction. The case where there are multiple report_writer_ invocations per ssu_ invocation, and each display_xxx type request has it's own report_writer_ invocation, is handled as follows. Another version of the display_mrds_model subsystem is located in the display_mrds_model_dir2, under the pl1_example directory. It is basically the same as the previously described version, but has the following differences. The main line procedure creates 4 report_writer_ invocations instead of 1, and deletes the report_writer_ standard requests after creating each invocation. It wishes to provide the list_format_options and set_format_options requests to the interactive user, so it calls ssu_ to have these two requests added. Instead of supplying a dummy table manager procedure when the report_writer_ invocations are created, it supplies the name of the correct table manager for each individual invocation. When a request procedure is called by ssu_, instead of calling report_writer_$set_table_manager, the request procedure calls report_writer_$set_report_writer_info_ptr to make it's report_writer_ invocation current. It only allocates the row_info structure and calls report_writer_$define_columns once in an ssu_ invocation. The major difference seen by a terminal user when using the first and second version of display_mrds_model is as follows. The first version doesn't provide the user with any way to change the report format, and every time they type a display_xxx request it MTB 677-00 Multics Technical Bulletin creates a new default report layout. The second version provides the list_format_options and set_format_options requests so a user can change the format of the report. After each display_xxx type request executes, it's report_writer_ invocation is current until the next display_xxx request executes. A default report format for each display_xxx request is only created once per ssu_ invocation. So a user can type something like "display_relation_attributes", and then use the list_format_options and set_formations requests until the report format suits them. They could then use another one of the display_xxx requests, and when they switched back to "display_relation_attributes", the old report format they defined for it would still be current. In summary, the new entry points report_writer_$set_table_manager and report_writer_$set_report_info_ptr provide for the multiplexing of table manager procedures and report_writer_ invocations. The first entrypoint provides for the case of N display requests with one report_writer_ invocation for the one ssu_ invocation. The second entrypoint provides for the case of N display requests and N report_writer_ invocations for the one ssu_ invocation. The report_writer_request_table_ provides for the adding and deleting of the report_writer_ requests as a whole, or selectively. Temp Segment And Area Cleanup The report_writer_ will remain unchanged in this aspect from the MR10.2 version. If a display is running that uses the -temp_dir control argument and the user's process dies before the display cleanup handler is invoked, there could be segments left around in the specified temporary directory. If a display has completed that uses the -temp_dir and -keep_retrieval control arguments, and the report_writer_$destroy_invocation entrypoint isn't called, once again there could be temporary segments left around in the specfied directory. Users haven't complained that this was a problem in the MR10.2 version, so it is not expected to be a major problem in this version. A future version of report_writer_ will use the general Multics solution to this problem, when it is invented. report_writer_$convert_and_move_row Code will be added to this module to handle the conditions that can occur can the user program has incorrectly set the value pointers. An error code and error message parameter will be added to the calling sequence, and they will indicate what went wrong. Information returned through these parameters could MTB 677-00 Multics Technical Bulletin include: what condition occured; what row and column it occured on; what page was being formatted when the error took place, etc. Product Completion With these issues resolved, the remaining work can now be completed. The next version of report_writer_ made available will be the finished product. This will be available on system M and in the Ford exl library sometime in early October for exposure.