09/11/85 report_writer_ Function: The report_writer_ subroutine provides a programmer interface to the MRW system. Through it, application subsystems can include generalized report writing capabilities, with a minimal amount of coding required by the subsystem developer. Entry points in report_writer_: (List is generated by the help command) :Entry: convert_and_move_row: 09/11/85 report_writer_$convert_and_move_row Function: This entry converts a row of differing data types to a row of character string values and places it in the row value buffer. Usage: dcl report_writer_$convert_and_move_row entry (ptr, (*) ptr); call report_writer_$convert_and_move_row (report_writer_info_ptr, value_ptrs); Arguments: report_writer_info_ptr (Input) is the pointer to the report_writer_ info structure returned by the create_invocation entrypoint. value_ptrs (Input) is an array of pointers that point to the individual column values that are to be converted. Notes: The number of pointers in the array must be equivalent to the number of columns defined in the table. :Entry: create_invocation: 09/11/85 report_writer_$create_invocation Function: This entry creates a report_writer_ invocation. It adds the standard report_writer_ request table and the standard requests info segments directory at location 99999 (see Notes). Usage: dcl report_writer_$create_invocation entry (char(*), ptr, ptr, fixed bin(35), char(*), varying); call report_writer_$create_invocation (table_manager_name,sci_ptr, report_writer_ptr, code, message); Arguments: table_manager_name (Input) is the name of the table manager procedure for the application subsystem that is creating the report writer invocation. If the name is blank, report_writer_ obtains the name of the application subsystem via the ssu_$get_subsystem_name subroutine and uses this as the table manager procedure name. Entry variables are constructed by report_writer_ using the name of the table manager procedure. sci_ptr (Input) is the ssu_ info pointer returned to the application subsystem when the ssu_ invocation is created. If this parameter is null, the report_writer_ invocation is not created. report_writer_info_ptr (Output) is the pointer to the report_writer_ info structure. This pointer is passed as the first parameter to every other report_writer_ entry. code (Output) is a standard error code. If this is non-zero the invocation could not be created. message (Output) if code is non-zero, this parameter contains the reason why the invocation could not be created. Declaring this argument as "character(128) varying" provides an area large enough to contain any returned error message. Notes: The table manager procedure is a program supplied by the application subsystem to manage data retrieval from its source data file. The report_writer_ creates entry variables of the form "table_manager_name$XX", where XX are the entries that must be available in the table manager procedure. The required entries are create_table, delete_table, and get_row. The optional entry is get_query. The report_writer_ request tables provide a mechanism to include all of the report_writer_ standard requests (the default when an invocation is created), or selected individual report_writer_ requests. The request table "report_writer_request_table_$standard_requests" is used by the report_writer_$create_invocation entrypoint in a call to ssu_$add_request_table to add the report_writer_ standard requests to the subsystem's set of requests. If the standard requests are not required, the subsystem should call ssu_$delete_request table with this as a parameter, after the call to report_writer_$create_invocation. The report_writer_ standard requests are: column_value, display, display_builtins, list_format_options, restore_format_options, save_format_options, and set_format_options. The other request tables defined to allow the addition of single requests are report_writer_request_table_$XXX_request, where XXX is the short name of the request. These can be chosen from: clv, di, dib, lsfo, rsfo, sfo, and svfo. The report_writer_info_dirs_ data segment provides a mechanism to include the directory containing the info segment for a request. The report_writer_info_dirs_$standard_requests is used by the report_writer_$create_invocation entrypoint in a call to ssu_$add_info_dir, to add the info directory containing the info segments for the standard requests. If the standard requests are not required, the subsystem should call ssu_$delete_info_dir with this as a parameter, after the call to report_writer_$create_invocation. The other data items defined to allow the addition of directories which contain the info segment for a single request are report_writer_info_dirs_$XXX_requests, where XXX is the short name of the request. These can be chosen from: clv, di, dib, lsfo, rsfo, sfo, and svfo. :Entry: define_columns: 09/11/85 report_writer_$define_columns Function: This entry is used to inform report_writer_ that a set of columns have been selected. All specific and general column options have new values assigned based on the newly selected columns. Usage: dcl report_writer_$define_columns entry (ptr, ptr, fixed bin(35), char(*) varying)); call report_writer_$define_columns (report_writer_info_ptr, row_info_ptr, code, message); Arguments: report_writer_info_ptr (Input) is the pointer to the report_writer_ info structure returned by the create_invocation entrypoint. row_info_ptr (Input) is a pointer to the row_info structure described in the include file rw_row_info.incl.pl1 (See "Notes" below.) If this pointer is null, any previously defined specific and general column option values are deleted, and the only operations allowed are to general report options until this entry is code (Output) is a standard error code. If this code is non-zero the values of any previously defined specific and general columns options will remain unchanged. message (Output) if code is non-zero this parameter will contain the reason for the failure. Declaring this argument as "character(128) varying" provides an area large enough to contain any returned error message. Notes: The row_info structure declared in the include file rw_row_info.incl.pl1 is listed below, followed by a description of the members of this structure. declare 1 row_info aligned based (row_info_ptr), 2 version char(8) unaligned, 2 value_ptr ptr, 2 value_length fixed bin(21), 2 number_of_columns fixed bin, 2 current_column_number fixed bin, 2 column (row_info_init_number_of_columns refer (row_info.number_of_columns)), 3 names char(128) varying, 3 descriptors bit(36), 3 lengths fixed bin(21), 3 indexes fixed bin(21); where: version specifies to report_writer_ that the application subsystem is using a particular version of the structure. The only version currently supported by report_writer_ is version 1. The value of ROW_INFO_VERSION_1, declared in the same include file, should be assigned to row_info.version by the subsystem. (Input) value_ptr is filled in by report_writer_ and points to the buffer where the row value is placed by the application subsystem's table manager procedure or the report_writer_$convert_and_move_row entrypoint. (Output) value_length is filled in by report_writer_ and is the length of the buffer for the row value. This is set to the exact number of characters needed to contain the row value after conversion from internal data types to the non-varying, unaligned character data types report_writer_ uses. (Output) number_of_columns is filled in when the application subsystem allocates the row_info structure, by setting the variable row_info_init_number_of_columns to the number of columns that should be present in the table, before the allocate statement is executed. (Input) current_column_number is set to zero by report_writer_ and can be used by the application subsystem's table manager procedure to place individual column values into the row value buffer. (Output) names are filled in by the application subsystem, andare the names of the individual columns. These names must not contain whitespace because of the request line syntax of the report_writer_ standard requests. (Input) descriptors are filled in by the application subsystem. They are standard data type descriptors for the column data as it appears in the source file that the subsystem's table manager retrieves from. In many cases they describe columns that are not nonvarying, unaligned character data types, and report_writer_ must convert the column values to nonvarying character strings. It uses these data descriptors to do data conversion. It also uses these descriptors when generating default report column widths, column alignment modes, etc. If a descriptor is completely zero, the column is assumed by report_writer_ to be a nonvarying, unaligned character string. In this case, the lengths field is used to determine the length in characters of the column. The descriptor is then set by report_writer_ to a nonvarying, unaligned character descriptor and its size portion is set to the value found in the lengths field. Refer to the Programmer's Reference Manual, for a description of Multics standard data type descriptors. Refer to the include files "arg_descriptor.incl.pl1" and "std_descriptor_types.incl.pl1" for structures and named constants to set descriptors. (Input/Output) lengths are filled in by report_writer_, and each is the number of characters needed to contain the column value after conversion from any supported data type to nonvarying, unaligned character format. In the case where the descriptor is completely zero, lengths are set by the caller. The report_writer_ examines the value of this field to determine the length in characters for the column. (Input/Output) indexes are filled in by report_writer_, and each is the index into the row value buffer for a particular column. (Input) There are also three variables defined in this include file to description of these variables follow. row_value variable provides a method to refer to the complete row value. Its declaration is: declare row_value char(row_info.value_length) based (row_info.value_ptr); A PL/I program to set the row value completely blank could use the PL/I statement: row_value = " "; row_value_as_an_array variable provides a method to refer to any single character within the row value. Its declaration is: declare row_value_as_an_array (row_info.value_length) char(1) based (row_info.value_ptr); A PL/I program to set the 15th character within the row_value to a blank could use the PL/I statement: row_value_as_an_array (15) = " "; column_value variable provides a method to refer to a complete column value. Its declaration is: declare column_value char (row_info.column.lengths (row_info.current_column_number)) based (addr (row_value_as_an_array (row_info.column.indexes (row_info.current_column_number)))); A PL/I program to set all of the columns to blanks could use the PL/I code fragment: do row_info.current_column_number = 1 to row_info.number_of_columns; column_value = " "; end; :Entry: destroy_invocation: 09/11/85 report_writer_$destroy_invocation Function: This entry destroys a report_writer_ invocation. Usage: dcl report_writer_$destroy_invocation entry (ptr); call report_writer_$destroy_invocation (report_writer_info_ptr); Arguments: report_writer_info_ptr (Input/Output) is the pointer to the report_writer_ info structure. If this pointer is null, the call is ignored. This pointer is set to null after the invocation is destroyed. :Entry: set_report_writer_info_ptr: 09/11/85 report_writer_$set_report_writer_info_ptr Function: This entry is used by complex subsystems that require more than one report_writer_ invocation to be present in the subsystem invocation. It takes the caller provided report_writer_ info pointer and places it in an internal location associated with the sci_ptr. When the next report_writer_ standard request is invoked, it uses the new report_writer_ info pointer now associated with its sci_ptr parameter. Usage: dcl report_writer_$set_report_writer_info_ptr entry (ptr, ptr, fixed bin(35), char(*) varying)); call report_writer_$set_report_writer_info_ptr (report_writer_info_ptr, sci_ptr, code, message); Arguments: report_writer_ptr (Input) is the pointer to a report_writer_ info structure. This pointer becomes the report_writer_ info pointer that is passed to the report_writer_ standard requests. sci_ptr (Input) is the pointer to the ssu_ info structure returned to the subsystem by the ssu_$create_invocation entrypoint. code (Output) is a standard error code. If this code is non-zero, the current report_writer_ info pointer remains in effect. message (Output) if code is non-zero this parameter contains the reason for the failure. Declaring this argument as "character (128) varying" provides an area large enough to contain any returned error message. Notes: The most common type of subsystem using report_writer_ is one where there is only one report_writer_ invocation present in the one subsystem invocation. If a subsystem requires more than one report_writer_ invocation to be present in the one subsystem invocation, call the report_writer_$create_invocation as many times as required, saving the returned report_writer_ info pointer after each call. This entrypoint is then called with the desired report_writer_ info pointer before any of the report_writer_ standard requests are used. The call to this entrypoint ensures that the correct report_writer_ info pointer is used by the report_writer_ standard requests. :Entry: set_table_manager: 09/11/85 report_writer_$set_table_manager Function: This entry is used by complex subsystems that require more than one table_manager procedure to be used in a report_writer_ invocation. It takes the caller provided table_manager name and creates entry variables to the expected entrypoints. (See the "report_writer_$create_invocation entrypoint" for more information on the table_manager procedure.) After this entrypoint is called, the next invocation of the report_writer_ display request uses this new table_manager procedure. Usage: dcl report_writer_$set_table_manager entry (ptr, char(*), fixed bin(35), char(*) varying); call report_writer_$set_table_manager (report_writer_info_ptr, table_manager_name, code, message); Arguments: report_writer_info_ptr (Input) is the pointer to the report_writer_ info structure returned by the report_writer_$create_invocation entrypoint. table_manager_name (Input) is the name of the new table_manager procedure. code (Output) is a standard error code. If this code is non-zero, the current subsystem table_manager procedure remains in effect. message (Output) if code is non-zero, this parameter contains the reason for the failure. Declaring this argument as "character (128) varying" provides an area large enough to contain any returned error message. Notes: The most common type of subsystem using report_writer_ is one where there is only one table_manager procedure required for the one report_writer_ invocation. If a subsystem wishes to switch between different table_manager procedures within one report_writer_ invocation, this entrypoint should be called with the name of the new table_manager procedure. The call to this entrypoint results in the new table_manager procedure being called the next time the report_writer_ display request is used. ----------------------------------------------------------- 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