MODULE sca$report_format_runoff IDENT "T4.0-3" !************************************************************************* ! * ! © 2000 BY * ! COMPAQ COMPUTER CORPORATION * ! © 2000 BY * ! ELECTRONIC DATA SYSTEMS LIMITED * ! * ! THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED * ! ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE * ! INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER * ! COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY * ! OTHER PERSON. NO TITLE TO OR OWNERSHIP OF THE SOFTWARE IS HEREBY * ! TRANSFERRED. * ! * ! THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE * ! AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY COMPAQ COMPUTER * ! CORPORATION OR EDS. * ! * ! NEITHER COMPAQ NOR EDS ASSUME ANY RESPONSIBILITY FOR THE USE OR * ! RELIABILITY OF THIS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY * ! COMPAQ. * ! * !************************************************************************* !+ ! Facility: ! SCA - Source Code Analyzer ! REPORT - Report Subfacility ! ! Abstract: ! This module contains routines that deal with the formatting of VAX/Digital ! Standard Runoff (.RNO) source files. ! ! All of the dependencies on Runoff are isolated into this module. !- ! Constant values used for formatting strings. ! CONSTANT sca$report_k_formfeed := ASCII(12), sca$report_k_null := ASCII(0), ! Use control characters for specifying bold and underline, so that we don't ! interfere with characters in user text. ! sca$report_k_runoff_bold := ASCII(6), ! bolding sca$report_k_runoff_underline := ASCII(11), ! underlines sca$report_k_runoff_uppercase := ASCII(16), ! Uppercase sca$report_k_runoff_lowercase := ASCII(23), ! Lowercase sca$report_k_runoff_bold_on := sca$report_k_runoff_uppercase + sca$report_k_runoff_bold, sca$report_k_runoff_bold_off := sca$report_k_runoff_lowercase + sca$report_k_runoff_bold, sca$report_k_runoff_underline_on := sca$report_k_runoff_uppercase + sca$report_k_runoff_underline, sca$report_k_runoff_underline_off := sca$report_k_runoff_lowercase + sca$report_k_runoff_underline; PROCEDURE sca$report_add_table_item_runoff (item_name; item_description) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure adds an entry to a table. All of our tables are two columns, ! consisting of an item and the description of the item. ! ! FORMAL PARAMETERS: ! ! item_name ! ! The name of the item to put into the table, as a TPU string. IN ! parameter. ! ! item_description ! ! The description of the item, as a TPU string. Optional IN parameter. !-- LOCAL output_string; ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_ADD_TABLE_ITEM_RUNOFF'); ENDON_ERROR; ! If the item_description is provided, write the item_name in the first ! column and the item description in the second column. ! IF GET_INFO(item_description,'TYPE') = STRING THEN output_string := item_name + ASCII(9) + item_description; ELSE ! No item_description was specified - just write the item_name. ! output_string := item_name; ENDIF; sca$report_append_text('.BREAK;' + output_string, TRUE); RETURN; ENDPROCEDURE PROCEDURE sca$report_appendix_runoff (appendix_title) !++ ! FUNCTIONAL DESCRIPTION: ! ! This routine writes an appendix heading in RNO format. ! ! FORMAL PARAMETERS: ! ! appendix_title ! ! The name of the appendix, as a TPU string value. IN parameter. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_APPENDIX_RUNOFF'); ENDON_ERROR; sca$report_append_text('.APPENDIX ' + appendix_title, TRUE); ENDPROCEDURE PROCEDURE sca$report_chapter_runoff (chapter_title, decl_class) !++ ! FUNCTIONAL DESCRIPTION: ! ! This routine writes a chapter heading in Runoff format. ! ! FORMAL PARAMETERS: ! ! chapter_title ! ! The name of the chapter, as a TPU string value. IN parameter. ! ! decl_class ! ! The declaration class of the object that the chapter describes, as a ! TPU string value. IN parameter. !-- LOCAL full_chapter_title; ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_CHAPTER_RUNOFF'); ENDON_ERROR; ! Construct the chapter title, including declaration class information if ! it is enabled. ! IF sca$report_option_decl_class_modules AND (decl_class <> '') THEN full_chapter_title := chapter_title + ' (' + decl_class + ')'; ELSE full_chapter_title := chapter_title; ENDIF; ! Write the chapter heading and set up the header styles and margins. ! sca$report_append_text('.CHAPTER ' + full_chapter_title, TRUE); sca$report_append_text ('.STYLE HEADERS 7,1,6,6,7,3,1,9,2', TRUE); sca$report_append_text ('.LEFT MARGIN 5.RIGHT MARGIN 75', TRUE); ENDPROCEDURE PROCEDURE sca$report_end_fragment_runoff !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the commands necessary to end a code fragment. ! ! FORMAL PARAMETERS: ! ! None !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_END_FRAGMENT_RUNOFF'); ENDON_ERROR; ! We don't need to turn on FILL mode, because the next .CHAPTER command ! will turn it back on. ! sca$report_blank_line; RETURN; ENDPROCEDURE PROCEDURE sca$report_end_list_runoff !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the formatting commands to end a list. ! ! FORMAL PARAMETERS: ! ! None !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_END_LIST_RUNOFF'); ENDON_ERROR; sca$report_append_text ('.END LIST', TRUE); ENDPROCEDURE PROCEDURE sca$report_end_parameter_section_runoff !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the formatting commands to end the description of the ! parameter list in a routine section. ! ! FORMAL PARAMETERS: ! ! None !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_END_PARAMETER_SECTION_RUNOFF'); ENDON_ERROR; sca$report_append_text ('.LEFT MARGIN -2', TRUE); sca$report_blank_line; ENDPROCEDURE PROCEDURE sca$report_end_routine_section_runoff (;routine_name) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the formatting commands to end a routine section. ! ! FORMAL PARAMETERS: ! ! routine_name ! ! The name of the current routine being processed, as a TPU string. ! IN parameter. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_END_ROUTINE_SECTION_RUNOFF'); ENDON_ERROR; ! Disable the use of headers. ! sca$report_append_text ('.NO HEADERS', TRUE); sca$report_blank_line; ENDPROCEDURE PROCEDURE sca$report_end_routine_subsection_runoff !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the commands to end a subsection of a routine ! section. ! ! FORMAL PARAMETERS: ! ! None !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_END_ROUTINE_SUBSECTION_RUNOFF'); ENDON_ERROR; ! Move the left margin back 2 columns. ! sca$report_append_text ('.LEFT MARGIN -2', TRUE); sca$report_blank_line; ENDPROCEDURE PROCEDURE sca$report_end_section_runoff !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the commands needed to end a section. ! ! FORMAL PARAMETERS: ! ! None !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_END_SECTION_RUNOFF'); ENDON_ERROR; ! Nothing special is required to mark the end of a section. Just ! write a blank line to make the source file easier to read. ! sca$report_blank_line; ENDPROCEDURE PROCEDURE sca$report_end_subsection_runoff !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the commands needed to end a subsection. ! ! FORMAL PARAMETERS: ! ! None !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_END_SUBSECTION_RUNOFF'); ENDON_ERROR; ! Nothing special is required to mark the end of a subsection. Just ! write a blank line to make the source file easier to read. ! sca$report_blank_line; ENDPROCEDURE PROCEDURE sca$report_end_table_runoff !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure terminates a table. ! ! FORMAL PARAMETERS: ! ! None !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_END_TABLE_RUNOFF'); ENDON_ERROR; ! Nothing special is required to end a table. Just write a blank line to ! make the source file easier to read. ! sca$report_blank_line; ENDPROCEDURE PROCEDURE sca$report_include_file_runoff (file_name) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes a .REQUIRE command. ! ! FORMAL PARAMETERS: ! ! file_name ! ! The name of the file to be included. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_INCLUDE_FILE_RUNOFF'); ENDON_ERROR; sca$report_append_text ('.REQUIRE "' + file_name + '"', TRUE); ENDPROCEDURE PROCEDURE sca$report_list_element_runoff(element_text) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes a single list element. ! ! FORMAL PARAMETERS: ! ! element_text ! ! The text of the element. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_LIST_ELEMENT_RUNOFF'); ENDON_ERROR; ! Use the .LIST ELEMENT tag to indicate a list element. ! sca$report_append_text ('.LIST ELEMENT;', TRUE); ! Write the text using sca$report_paragraph_runoff. Suppress the leading ! paragraph character in order to properly format the text. ! sca$report_paragraph_runoff (element_text, FALSE); ENDPROCEDURE PROCEDURE sca$report_paragraph_runoff (text_block; initial_paragraph) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes one or more paragraphs of text. We assume that ! .AUTOPARAGRAPH is in effect, and hence don't bother to separate paragraphs ! with .PARAGRAPH directives. (We use blank lines to separate them.) ! ! FORMAL PARAMETERS: ! ! text_block ! ! The text of the paragraph, as a TPU string or range value. It must ! contain at least one paragraph. IN parameter. ! ! initial_paragraph ! ! A boolean flag to indicate whether to write an initial paragraph. TRUE ! means write ".BLANK 1" command, FALSE means not to write the ".BLANK 1" ! command the initial time through. If omitted, the default is TRUE. ! ! IMPLICIT INPUTS: ! ! sca$report_option_fill !-- LOCAL end_paragraph, end_paragraph_pattern, individual_paragraph_range, local_text_block, local_flag, saved_position, search_range, start_paragraph; ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_PARAGRAPH_RUNOFF'); ENDON_ERROR; local_flag := initial_paragraph; saved_position := MARK(FREE_CURSOR); ! Default to starting a new paragraph for the beginning of the text. ! IF local_flag = tpu$k_unspecified THEN local_flag := TRUE; ENDIF; ! We define the end of a paragraph to be an empty line, as defined by ! the pattern eve$pattern_empty_line. ! end_paragraph_pattern := eve$pattern_empty_line; ! If the text block is a string, convert it into a range by copying it ! into a scratch buffer. ! IF GET_INFO(text_block,'TYPE') = STRING THEN POSITION(sca$report_scratch_buffer); ERASE(sca$report_scratch_buffer); COPY_TEXT(text_block); local_text_block := CREATE_RANGE( BEGINNING_OF(sca$report_scratch_buffer), END_OF(sca$report_scratch_buffer), NONE) ELSE local_text_block := text_block ENDIF; POSITION(BEGINNING_OF(local_text_block)); ! Strip leading blank lines from the text block, by moving the beginning ! point of the range. ! start_paragraph := SEARCH_QUIETLY ( NOTANY(eve$kt_whitespace + ASCII(12) + ASCII(0)), FORWARD, EXACT, local_text_block); IF start_paragraph = 0 THEN ! There is no text associated with this tag. ! IF local_flag = TRUE THEN sca$report_append_text('.BLANK 1', TRUE); ENDIF; POSITION(saved_position); ERASE(sca$report_scratch_buffer); RETURN ELSE ! Start at the line containing the first non-blank character. ! POSITION(BEGINNING_OF(start_paragraph)); POSITION(LINE_BEGIN); start_paragraph := MARK(FREE_CURSOR) ENDIF; local_text_block := CREATE_RANGE (start_paragraph, END_OF(local_text_block), NONE); IF GET_INFO (sca$report_option_fill, 'TYPE') = UNSPECIFIED THEN sca$report_option_fill := sca$report_fill; ENDIF; IF sca$report_option_fill THEN ! /FILL is in effect. Divide the text into individual paragraphs, ! separated by blank lines so that DSR will fill them. ! This algorithm assumes there is always at least one paragraph. ! POSITION(BEGINNING_OF(local_text_block)); LOOP ! Find the paragraph boundaries. ! start_paragraph := MARK(FREE_CURSOR); ! Search for end of paragraph. ! search_range := CREATE_RANGE (start_paragraph, END_OF(local_text_block), NONE); end_paragraph := SEARCH_QUIETLY ( end_paragraph_pattern, FORWARD, NO_EXACT, search_range); IF end_paragraph = 0 THEN end_paragraph := END_OF(local_text_block) ELSE POSITION(BEGINNING_OF(end_paragraph)); end_paragraph := MARK(FREE_CURSOR) ENDIF; individual_paragraph_range := CREATE_RANGE (start_paragraph, end_paragraph, NONE); ! Write the current paragraph. ! IF local_flag = TRUE THEN sca$report_append_text('.BLANK 1', TRUE); ENDIF; local_flag := TRUE; sca$report_append_text (individual_paragraph_range, TRUE); sca$report_blank_line; ! Search for the start of the next paragraph. ! POSITION (end_paragraph); EXITIF MARK(FREE_CURSOR) >= END_OF(local_text_block); search_range := CREATE_RANGE (end_paragraph, END_OF(local_text_block), NONE); start_paragraph := SEARCH_QUIETLY( NOTANY(eve$kt_whitespace + ASCII(12) + ASCII(0)), FORWARD, EXACT, search_range); EXITIF start_paragraph = 0; POSITION (start_paragraph); ENDLOOP; ELSE ! /NOFILL is in effect - write the whole text block as a literal. ! sca$report_append_text ('.LITERAL', TRUE); sca$report_append_text (text_block, TRUE); sca$report_append_text ('.END LITERAL', TRUE); sca$report_blank_line ENDIF; ERASE(sca$report_scratch_buffer); POSITION (saved_position); RETURN; ENDPROCEDURE PROCEDURE sca$report_placeholder_runoff (placeholder_name) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes a placeholder to the output file. It always writes an ! optional placeholder. ! ! Digital does not currently support LSE definitions for DSR. We use the ! square bracket convention for the placeholders, but customers must create ! their own LSE language definitions to exploit them. ! ! FORMAL PARAMETERS: ! ! placeholder_name ! ! The name of the placeholder, as a string. Placeholder brackets should ! not be included in the string. IN parameter. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_PLACEHOLDER_RUNOFF'); ENDON_ERROR; sca$report_append_text ('[' + placeholder_name + ']', FALSE); RETURN; ENDPROCEDURE PROCEDURE sca$report_start_2167a_design_runoff !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure initializes a 2167A detailed design document. It writes ! introductory formatting commands. ! ! FORMAL PARAMETERS: ! ! None !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_START_2167a_DESIGN_RUNOFF'); ENDON_ERROR; ! Write a comment to inform the user of the report type. ! sca$report_append_text ('.!2167A Design Document', TRUE); ! Write a comment indicating how the file was generated and on what date. ! sca$report_append_text ( FAO ('.!!Generated by the LSE/SCA Report Tool, ' + sca$report_2167a_design_module_ident + ', !%D', 0), TRUE); ! Redefine flagging characters and disable detection options which might ! interfere with actual code. ! sca$report_append_text ('.ENABLE BOLDING.FLAGS BOLD _' + sca$report_k_runoff_bold, TRUE); sca$report_append_text ('.ENABLE UNDERLINING.FLAGS UNDERLINE _' + sca$report_k_runoff_underline, TRUE); sca$report_append_text ('.FLAGS UPPERCASE _' + sca$report_k_runoff_uppercase, TRUE); sca$report_append_text ('.FLAGS LOWERCASE _' + sca$report_k_runoff_lowercase, TRUE); sca$report_append_text ('.NO FLAGS ACCEPT', TRUE); sca$report_append_text ('.NO FLAGS BREAK', TRUE); sca$report_append_text ('.NO FLAGS CAPITALIZE', TRUE); sca$report_append_text ('.NO FLAGS HYPHENATE', TRUE); sca$report_append_text ('.NO FLAGS INDEX', TRUE); sca$report_append_text ('.NO FLAGS OVERSTRIKE', TRUE); sca$report_append_text ('.NO FLAGS PERIOD', TRUE); sca$report_append_text ('.NO FLAGS SUBSTITUTE', TRUE); sca$report_chapter_runoff (sca$report_section_detailed_design, ''); ENDPROCEDURE PROCEDURE sca$report_start_fragment_runoff (fragment_number, id_text_size) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the commands needed to start a new code fragment. ! ! FORMAL PARAMETERS: ! ! fragment_number ! ! The number to assign to the fragment, as a TPU integer value. IN ! parameter. ! ! id_text_size ! ! The number of columns required to display the fragment number. OUT ! parameter. !-- LOCAL fragment_string; ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_START_FRAGMENT_RUNOFF'); ENDON_ERROR; ! Set up the margins and disable filling. ! sca$report_append_text ('.LEFT MARGIN 5.RIGHT MARGIN 80', TRUE); sca$report_append_text ('.NOFILL.KEEP', TRUE); ! Write the code fragment identifier. ! fragment_string := STR(fragment_number) + ' '; sca$report_append_text (sca$report_k_runoff_bold_on + fragment_string + sca$report_k_runoff_bold_off, FALSE); id_text_size := LENGTH(fragment_string); RETURN; ENDPROCEDURE PROCEDURE sca$report_start_header_runoff (level, section_title) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the header for a given level. ! ! FORMAL PARAMETERS: ! ! level ! ! The level for the header, as an integer. IN parameter. ! ! section_title ! ! The title to use for the header. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_START_HEADER_RUNOFF'); ENDON_ERROR; ! Set the left margin to 5 columns. ! sca$report_append_text ('.LEFT MARGIN 5', TRUE); ! Write the heading, bolded. ! sca$report_append_text ('.HEADER LEVEL ' + STR(level) + ' ' + sca$report_k_runoff_bold_on + section_title + sca$report_k_runoff_bold_off, TRUE); ! Indent the left margin an additional 4 columns. ! sca$report_append_text ('.LEFT MARGIN +4', TRUE); RETURN; ENDPROCEDURE PROCEDURE sca$report_start_list_runoff (;list_style) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the formatting commands necessary to start a list. ! ! FORMAL PARAMETERS: ! ! list_style ! ! The type of list to be created. The default is ! SCA$REPORT_K_LIST_NUMBERED. The styles supported are: ! ! sca$report_k_list_simple ! sca$report_k_list_unnumbered ! sca$report_k_list_numbered ! sca$report_k_list_lower_alpha ! sca$report_k_list_upper_alpha ! sca$report_k_list_lower_roman ! sca$report_k_list_upper_roman !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_START_LIST_RUNOFF'); ENDON_ERROR; ! Default to using a numbered list. ! IF list_style = tpu$k_unspecified THEN list_style := sca$report_k_list_numbered; ENDIF; ! Depending upon the list style, write the appropriate DSR commands to set ! up the list. ! CASE list_style FROM sca$report_k_first_list_index TO sca$report_k_last_list_index [sca$report_k_list_simple] : sca$report_append_text ('.LIST 0," "', TRUE); [sca$report_k_list_unnumbered] : sca$report_append_text ('.LIST 1, " "', TRUE); [sca$report_k_list_numbered] : sca$report_append_text ('.LIST', TRUE); sca$report_append_text ('.DISPLAY ELEMENTS D, " "', TRUE); [sca$report_k_list_lower_alpha] : sca$report_append_text ('.LIST', TRUE); sca$report_append_text ('.DISPLAY ELEMENTS LL', TRUE); [sca$report_k_list_upper_alpha] : sca$report_append_text ('.LIST', TRUE); sca$report_append_text ('.DISPLAY ELEMENTS LU', TRUE); [sca$report_k_list_lower_roman] : sca$report_append_text ('.LIST', TRUE); sca$report_append_text ('.DISPLAY ELEMENTS RL', TRUE); [sca$report_k_list_upper_roman] : sca$report_append_text ('.LIST', TRUE); sca$report_append_text ('.DISPLAY ELEMENTS RU', TRUE); [INRANGE, OUTRANGE] : sca$report_bad_target (list_style); RETURN; ENDCASE; ENDPROCEDURE PROCEDURE sca$report_start_parameter_runoff (parameter_name) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the formatting information necessary for starting ! the description of a single parameter in the parameter list description of ! a routine section. ! ! FORMAL PARAMETERS: ! ! parameter_name ! ! The name of the parameter, as a TPU string. IN parameter. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_START_PARAMETER_RUNOFF'); ENDON_ERROR; ! Separate parameters with blank lines. Write the parameter name, bolded. ! sca$report_append_text ('.SKIP 1', TRUE); sca$report_append_text ( sca$report_k_runoff_bold_on + parameter_name + sca$report_k_runoff_bold_off, TRUE); ENDPROCEDURE PROCEDURE sca$report_start_parameter_section_runoff !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the formatting information necessary for starting ! the description of the parameter list in a routine section. ! ! FORMAL PARAMETERS: ! ! None !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_START_PARAMETER_SECTION_RUNOFF'); ENDON_ERROR; ! Make sure there are at least 5 lines left on this page. ! sca$report_append_text ('.TEST PAGE 5', TRUE); ! Write the section header (bolded). ! sca$report_append_text ('.SKIP 1.NOFILL', TRUE); sca$report_append_text ( sca$report_k_runoff_bold_on + '____________________________________________________________' + sca$report_k_runoff_bold_off, TRUE); sca$report_append_text ( sca$report_k_runoff_bold_on + 'ARGUMENTS:' + sca$report_k_runoff_bold_off, TRUE); sca$report_append_text ('.SKIP 1.FILL', TRUE); ! Indent the left margin by 2 columns. ! sca$report_append_text ('.LEFT MARGIN +2', TRUE); ENDPROCEDURE PROCEDURE sca$report_start_routine_section_runoff (module_name, routine_name, routine_decl_class) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the commands needed to start a new routine section. A ! routine section is a highly stylized section that describes a given routine, ! such as used by the VMS documentation. ! ! FORMAL PARAMETERS: ! ! module_name ! ! The name of the module which contains this routine, as a TPU string ! value. IN parameter. ! ! routine_name ! ! The name of the routine, as a TPU string value. IN parameter. ! ! routine_decl_class ! ! The declaration class of the routine, as a TPU string. IN parameter. !-- LOCAL full_routine_title; ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_START_ROUTINE_SECTION_RUNOFF'); ENDON_ERROR; ! Construct the routine title, including declaration class information if ! it is enabled. ! IF sca$report_option_decl_class_routines THEN full_routine_title := routine_name + ' (' + routine_decl_class + ')'; ELSE full_routine_title := routine_name; ENDIF; ! Start a new page for each routine. ! sca$report_append_text ('.PAGE', TRUE); ! Reset the left margin to 5 columns from the edge, and enable the ! displaying of headers. ! sca$report_append_text ('.LEFT MARGIN 5', TRUE); sca$report_append_text ('.HEADERS ON', TRUE); ! Set the running title to the module name and the running subtitle to the ! routine name. ! sca$report_append_text ('.TITLE ' + module_name, TRUE); sca$report_append_text ('.SUBTITLE ' + full_routine_title, TRUE); ! Write the section header (bolded). ! sca$report_append_text ('.SKIP 1.NOFILL', TRUE); sca$report_append_text ( sca$report_k_runoff_bold_on + '____________________________________________________________' + sca$report_k_runoff_bold_off, TRUE); sca$report_append_text ( sca$report_k_runoff_bold_on + full_routine_title + sca$report_k_runoff_bold_off, TRUE); sca$report_append_text ('.SKIP 1.FILL', TRUE); ! If the routine name is not blank, write the indexing commands to include ! the routine in the index. ! IF routine_name <> tpu$k_unspecified THEN IF routine_name <> '' THEN sca$report_append_text ('.FLAGS INDEX', TRUE); sca$report_append_text ('.INDEX ' + routine_name, TRUE); sca$report_append_text ('.INDEX ' + module_name + ' > ' + routine_name, TRUE); sca$report_append_text ('.ENTRY ' + routine_name + ' > ' + module_name, TRUE); sca$report_append_text ('.NO FLAGS INDEX', TRUE); ENDIF; ENDIF; ENDPROCEDURE PROCEDURE sca$report_start_routine_subsection_runoff (heading) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the commands needed to start a new subsection of a ! routine section. ! ! FORMAL PARAMETERS: ! ! heading ! ! The heading to use for the subsection, as a TPU string. IN parameter. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_START_ROUTINE_SUBSECTION_RUNOFF'); ENDON_ERROR; ! Check for at least 5 lines left on this page. ! sca$report_append_text ('.TEST PAGE 5', TRUE); ! Write the section header (bolded). ! sca$report_append_text ('.SKIP 1.NOFILL', TRUE); sca$report_append_text ( sca$report_k_runoff_bold_on + '____________________________________________________________' + sca$report_k_runoff_bold_off, TRUE); sca$report_append_text ( sca$report_k_runoff_bold_on + heading + ':' + sca$report_k_runoff_bold_off, TRUE); sca$report_append_text ('.SKIP 1.FILL', TRUE); ! Indent the left margin by 2 columns. ! sca$report_append_text ('.LEFT MARGIN +2', TRUE); ENDPROCEDURE PROCEDURE sca$report_start_section_runoff (section_title) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the commands needed to start a new section. ! ! FORMAL PARAMETERS: ! ! section_title ! ! The name of the section, as a TPU string value. IN parameter. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_START_SECTION_RUNOFF'); ENDON_ERROR; ! Set the left margin at 5 columns. ! sca$report_append_text ('.LEFT MARGIN 5', TRUE); ! Write the header with the heading bolded. ! sca$report_append_text ('.HEADER LEVEL 1 ' + sca$report_k_runoff_bold_on + section_title + sca$report_k_runoff_bold_off, TRUE); ! Indent the left margin an additional 4 columns. ! sca$report_append_text ('.LEFT MARGIN +4', TRUE); ENDPROCEDURE PROCEDURE sca$report_start_subsection_runoff (section_title) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the commands needed to start a new subsection. ! ! FORMAL PARAMETERS: ! ! section_title ! ! The name of the section, as a TPU string value. IN parameter. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_START_SUBSECTION_RUNOFF'); ENDON_ERROR; ! Set the left margin to 5 columns. ! sca$report_append_text ('.LEFT MARGIN 5', TRUE); ! Write the header with the heading bolded. ! sca$report_append_text ('.HEADER LEVEL 2 ' + sca$report_k_runoff_bold_on + section_title + sca$report_k_runoff_bold_off, TRUE); ! Indent the left margin an additional 4 columns. ! sca$report_append_text ('.LEFT MARGIN +4', TRUE); ENDPROCEDURE PROCEDURE sca$report_start_software_specification_runoff !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure initializes a software specification report. It initializes ! TPU variables and writes introductory formatting commands. ! ! FORMAL PARAMETERS: ! ! None !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_START_SOFTWARE_SPECIFICATION_RUNOFF'); ENDON_ERROR; ! Initialize report-dependent global variables. ! sca$report_table_number := 1; ! Write out the initial lines of the report. ! sca$report_append_text ('.!Software Specification', TRUE); ! Include a comment indicating how the file was generated and on what date. ! sca$report_append_text ( FAO ('.!!Generated by the LSE/SCA Report Tool, ' + sca$report_internals_module_ident + ', !%D', 0), TRUE); ! Redefine flagging characters and disable detection options which might ! interfere with actual code. ! sca$report_append_text ( '.ENABLE BOLDING.FLAGS BOLD _' + sca$report_k_runoff_bold, TRUE); sca$report_append_text ( '.ENABLE UNDERLINING.FLAGS UNDERLINE _' + sca$report_k_runoff_underline, TRUE); sca$report_append_text ( '.FLAGS UPPERCASE _' + sca$report_k_runoff_uppercase, TRUE); sca$report_append_text ( '.FLAGS LOWERCASE _' + sca$report_k_runoff_lowercase, TRUE); sca$report_append_text ('.NO FLAGS ACCEPT', TRUE); sca$report_append_text ('.NO FLAGS BREAK', TRUE); sca$report_append_text ('.NO FLAGS CAPITALIZE', TRUE); sca$report_append_text ('.NO FLAGS HYPHENATE', TRUE); sca$report_append_text ('.NO FLAGS INDEX', TRUE); sca$report_append_text ('.NO FLAGS OVERSTRIKE', TRUE); sca$report_append_text ('.NO FLAGS PERIOD', TRUE); sca$report_append_text ('.NO FLAGS SUBSTITUTE', TRUE); ENDPROCEDURE PROCEDURE sca$report_start_table_runoff (heading) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure sets things up for a table. ! ! FORMAL PARAMETERS: ! ! heading ! ! The heading to use for the table, as a TPU string. IN parameter. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_START_TABLE_RUNOFF'); ENDON_ERROR; ! Check for at least 4 lines left on this page. ! sca$report_append_text ('.TEST PAGE 4', TRUE); ! If the heading is not null, set up the table. ! IF heading <> '' THEN sca$report_append_text ( '.CENTER; Table ' + STR(sca$report_table_number) + '. ' + heading, TRUE); sca$report_table_number := sca$report_table_number + 1; ENDIF; sca$report_append_text ('.BLANK 2', TRUE); RETURN; ENDPROCEDURE PROCEDURE sca$report_unnumbered_heading_runoff (heading_text) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes an unnumbered heading. ! ! FORMAL PARAMETERS: ! ! heading_text ! ! The text of the heading. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_UNNUMBERED_HEADING_RUNOFF'); ENDON_ERROR; ! Break in case we are in the middle of a line. ! sca$report_append_text ('.BREAK', TRUE); ! Write the heading text, bolded. ! sca$report_append_text ( sca$report_k_runoff_bold_on + heading_text + sca$report_k_runoff_bold_off, TRUE); ! Perform another break to insure the text which follows is not put on the ! same line as the heading. ! sca$report_append_text ('.BREAK', TRUE); RETURN; ENDPROCEDURE PROCEDURE sca$report_write_cross_reference_runoff (cross_reference) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure adds a cross reference number to a previously written ! overview line in the output buffer. ! ! FORMAL PARAMETERS: ! ! cross_reference ! ! The cross reference number to write, as an integer. IN parameter. ! ! IMPLICIT INPUTS: ! ! The current position is assumed to be the location to add the cross ! reference number. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_WRITE_CROSS_REFERENCE_RUNOFF'); ENDON_ERROR; COPY_TEXT(' ' + sca$report_k_runoff_bold_on + sca$report_k_runoff_underline_on + STR(cross_reference) + sca$report_k_runoff_bold_off + sca$report_k_runoff_underline_off); RETURN; ENDPROCEDURE PROCEDURE sca$report_write_line_break_runoff !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes a line break. ! ! FORMAL PARAMETERS: ! ! None !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_WRITE_LINE_BREAK_RUNOFF'); ENDON_ERROR; ! Write a blank line to make it easier to see the DSR commands. ! sca$report_blank_line; ! Issue a break command to place any text which follows on a separate line. ! sca$report_append_text ('.BREAK', TRUE); sca$report_blank_line; ENDPROCEDURE PROCEDURE sca$report_write_parameter_description_runoff (parameter_description) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the description of a single parameter. ! ! FORMAL PARAMETERS: ! ! parameter_description ! ! The description of the parameter, as a TPU range. IN parameter. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_WRITE_PARAMETER_DESCRIPTION_RUNOFF'); ENDON_ERROR; ! Indent the left margin an additional 4 columns. ! sca$report_append_text ('.LEFT MARGIN +4', TRUE); ! Write the parameter description. ! sca$report_paragraph(parameter_description); ! Restore the left margin. ! sca$report_append_text ('.LEFT MARGIN -4', TRUE); RETURN; ENDPROCEDURE PROCEDURE sca$report_write_return_value_runoff (routine_type,return_value) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the return value portion of the routine section. ! ! FORMAL PARAMETERS: ! ! routine_type ! ! The type of the routine, as a TPU string. IN parameter. ! ! return_value ! ! A description of the return value, as a TPU string. IN parameter. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_WRITE_RETURN_VALUE_RUNOFF'); ENDON_ERROR; ! If there is either a return type or return value description, write the ! RETURNS section. ! IF (routine_type <> '') OR (return_value <> '') THEN ! Check for at least 5 lines remaining on this page ! sca$report_append_text ('.TEST PAGE 5', TRUE); ! Write the section header (bolded). ! sca$report_append_text ('.SKIP 1.NOFILL', TRUE); sca$report_append_text ( sca$report_k_runoff_bold_on + '____________________________________________________________' + sca$report_k_runoff_bold_off, TRUE); sca$report_append_text ( sca$report_k_runoff_bold_on + 'RETURNS:' + sca$report_k_runoff_bold_off, TRUE); sca$report_append_text ('.SKIP 1.FILL', TRUE); ! Indent the left margin by 2 columns. ! sca$report_append_text ('.LEFT MARGIN +2', TRUE); ! If there is a return type, then write the return type. ! IF routine_type <> '' THEN sca$report_append_text ('Type: ' + sca$report_k_runoff_bold_on + routine_type + sca$report_k_runoff_bold_off, TRUE); ! Leave a blank line if we also have a return value description. ! IF return_value <> '' THEN sca$report_append_text('.SKIP 1', TRUE); ENDIF; ENDIF; ! If there is return value description text, write it. ! IF return_value <> '' THEN sca$report_append_text (return_value, TRUE); ENDIF; ! Restore the left margin. ! sca$report_append_text ('.LEFT MARGIN -2', TRUE); sca$report_blank_line; ENDIF; ENDPROCEDURE PROCEDURE sca$report_write_routine_format_runoff (routine_name, routine_type, parameter_names) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the Format section of the routine description. This ! section shows the calling sequence for the routine. ! ! FORMAL PARAMETERS: ! ! routine_name ! ! The name of the routine, as a string. IN parameter. ! ! routine_type ! ! The type of the routine return value (or '' if it has no return value), ! as a string. IN parameter. ! ! parameter_names ! ! The names of the parameters of the routine, as an array of strings, or ! 0 if the routine has no parameters. IN parameter. !-- LOCAL i; ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_WRITE_ROUTINE_FORMAT_RUNOFF'); ENDON_ERROR; ! Check to make sure there are at least 5 lines left on this page. ! sca$report_append_text ('.TEST PAGE 5', TRUE); ! Write the section header (bolded). ! sca$report_append_text ('.SKIP 1.NOFILL', TRUE); sca$report_append_text ( sca$report_k_runoff_bold_on + '____________________________________________________________' + sca$report_k_runoff_bold_off, TRUE); sca$report_append_text ( sca$report_k_runoff_bold_on + 'FORMAT:' + sca$report_k_runoff_bold_off, TRUE); sca$report_append_text ('.SKIP 1.FILL', TRUE); ! Indent the left margin an additional 2 columns. ! sca$report_append_text ('.LEFT MARGIN +2', TRUE); ! If there is a return value, write the routine type followed by the ! routine name. ! IF routine_type <> '' THEN sca$report_append_text (routine_type + ' = ' + sca$report_k_runoff_bold_on + routine_name + sca$report_k_runoff_bold_off, FALSE); ELSE ! There is no return value, so just write the routine name. ! sca$report_append_text ( sca$report_k_runoff_bold_on + routine_name + sca$report_k_runoff_bold_off, FALSE); ENDIF; ! Write the parameters (if any). ! IF parameter_names <> 0 THEN ! Lead off with 2 extra spaces before the first parameter. ! sca$report_append_text ('##', FALSE); i := 1; LOOP EXITIF i > parameter_names{0}; IF i < parameter_names{0} THEN sca$report_append_text ('#' + STR(parameter_names{i}) + ',', TRUE); ELSE ! This is the last parameter - don't follow it with a comma. ! sca$report_append_text ('#' + STR(parameter_names{i}), TRUE); ENDIF; i := i + 1; ENDLOOP; ENDIF; ! Restore the left margin. ! sca$report_blank_line; sca$report_append_text ('.LEFT MARGIN -2', TRUE); sca$report_blank_line; ENDPROCEDURE PROCEDURE sca$report_write_routine_remark_runoff (remark_string) !++ ! FUNCTIONAL DESCRIPTION: ! ! This procedure writes the remark string of a routine to a routine section. ! ! FORMAL PARAMETERS: ! ! remark_string ! ! The remark string to write, as a TPU string. IN parameter. !-- ON_ERROR [OTHERWISE] : sca$report_common_error_cleanup('SCA$REPORT_WRITE_ROUTINE_REMARK_RUNOFF'); ENDON_ERROR; ! Indent left margin an additional 2 columns. ! sca$report_append_text ('.LEFT MARGIN +2', TRUE); ! Write the remark text. ! sca$report_append_text (remark_string, TRUE); ! Restore the left margin. ! sca$report_append_text ('.LEFT MARGIN -2', TRUE); sca$report_blank_line; ENDPROCEDURE ENDMODULE