09/10/85 set_format_options, sfo Syntax: sfo {-format_option_args} {-control_args} Function: sets individual report format options to user-specified or default values, and/or all formatting options to default values. Note: The option value given for any format option argument can be the control arguments -default or -prompt. If -default is given for the value, report writer sets the value of the format option to the system default. If -prompt is given for the value, report writer prompts for the value with the prompt string "Enter FORMAT_OPTION_NAME.". A line consisting of the single character "." terminates the prompted input mode. To suppress display of the prompt string, use the -brief control argument. Arguments: format_option_args can be one or more of the following: GENERAL REPORT OPTIONS -delimiter CHAR, -dm CHAR CHAR is the character used to delimit the different portions of a header or footer and can be set to any printable character. (Default value for CHAR is ) -format_document_controls STR, -fdc STR STR determines if the format_document_ subroutine is to interpret format document control lines when filling overlength text. STR can be set to on, meaning format_document_ interprets control lines in the text and provides special filling actions based on the embedded control lines. (Default value for STR is off, meaning format_document_ does not check for control lines embedded in text.) -hyphenation STR, -hph STR the value of -hyphenation determines if hyphenation is to be attempted when filling overlength character strings. STR can be set to "on," specifying that hyphenation is to be attempted. (Default value for STR is off, meaning no hyphenation is attempted.) -page_footer_value STR, -pfv STR STR is the page footer placed at the bottom of each page. The page footer can consist of more than one line, and each line can have a left, right, and center portion. The individual portions of each line are delimited by the delimiter character. Active requests found in the footer are evaluated and their return value is placed into the footer before folding and alignment takes place. Portions of a footer with zero length have their space on the page redistributed to the other portions whose lengths are not zero. For example, if the page footer contained only a center portion: !!Sample Center Portion!! the text is centered on the page and has the full page width available for the text. Similarly, a left portion or right portion only is aligned to the left or right of the page and has the full page width available for placement of text. Two exceptions to this action are when the footer has a left, right, and center portion, and the left or right portion has a zero length, such as: !left part!center part!! or !!center part!right part! in which case the left or right part of the page is unavailable for placement of text (i.e., the space is not redistributed to the other two portions). If the redistribution of the available page width is not desired, the placement of a single blank into a portion such as " Center Part " prevents the redistribution from taking place because each portion has a length greater than zero. (Default value for STR is "", meaning there is no page footer provided by default.) -page_header_value STR, -phv STR STR is the page header placed at the top of each page. Refer to the description of -page_footer_value for the content of a header. (Default value for STR is "", meaning there is no page header provided by default.) -page_length N, -pl N N is the length of each formatted page given as number of lines. N can be given as "0" or any positive integer. 0 means the report is not to be paginated and is created as one continuous stream. (Default value for N is 0) -page_width N, -pw N N is the width of each formatted page given as the number of character positions. N can be given as "0" or any positive integer. 0 means the page_width is always set by report writer to be the exact width needed to contain all of the columns specified in the query. If N is greater than zero and the width for any column exceeds N, the width of the column is automatically set to N. (Default value for N is 79) -title_line STR, -tl STR STR determines if a title line is to be printed. STR can be set to "off" to inhibit the printing of the title line. (Default value of STR is on, meaning a title line is printed at the top of each page.) -truncation STR, -tc STR STR determines the character(s) to be used to indicate truncation of some value. STR can be set to any sequence of printable characters. (Default value for STR is *) GENERAL COLUMN OPTIONS -column_order column_list, -co column_list column_list determines the order in which columns appear in the detail line. column_list can be set to a list of column names or numbers. Columns missing from this list are placed after the columns which appear in the list. That is, if five columns were selected and the column_order value is given as "3 2", the complete order would be "3 2 1 4 5". (Default value for column_list is the list of columns from the query, in the order supplied, meaning that the columns appear in the exact order as they appear in the query.) -count column_list, -ct column_list column_list determines the columns for which counts are generated. column_list can be set to a list of column names or numbers. Counts are generated after the last detail line. If a count is requested on a column that is excluded, the count is also excluded from the page. An exception to this rule is when all columns are excluded. Counts are provided in this case to allow reports consisting of some combination of counts, subcounts, totals, and subtotals only. (Default value for column_list is "", meaning no columns have counts generated.) -exclude column_list, -ex column_list column_list determines if any of the columns selected in the query are excluded from the detail line. column_list can be set to a list of column names or numbers. (Default value for column_list is "", meaning no columns are excluded.) -group column_list, -gr column_list column_list determines the grouping of a number of rows based on the values of one or more columns. column_list can be set to a list of column names or numbers. The column or columns named in the list become a hierarchy of columns. The first column named is the major column, and the last column named becomes the minor column. The hierarchy of columns can be used with the outline, page_break, and subtotal options described below. (Default value for column_list is "", meaning no group of rows is defined.) -group_footer_trigger column_list, -gft column_list column_list determines when to generate the group footer. column_list can be set to a list of column names or numbers. The columns which appear in this list must also appear in the column list associated with the -group option. If the -group option is set to a new value, columns which are eliminated from the column_list are also eliminated from the -group_footer_trigger column_list. When any of the columns specified in the column_list are about to change with the next row, the group footer is evaluated. The group footer is always evaluated after the last row of the report. (Default value for column_list is "", meaning no group footer triggers are defined.) -group_footer_value STR, -gfv STR STR is the group footer placed after each group of rows when any of the columns associated with the -group_footer_trigger option changes. Refer to the description of -page_footer_value above for the content of a header/footer. (Default value for STR is "", meaning there is no group footer defined.) -group_header_trigger column_list, -ght column_list column_list determines when to generate the group header. column_list can be set to a list of column names or numbers. The columns which appear in this list must also appear in the column list associated with the -group option. If the -group option is set to a new value, columns which are eliminated from the column_list are also eliminated from the -group_header_trigger column_list. When any of the columns specified in the column_list have just changed with the current row, the group header is evaluated. The group header is always evaluated before the first row of the report. (Default value for column_list is "", meaning no group header triggers are defined.) -group_header_value STR, -ghv STR STR is the group header placed before each group of rows when any of the columns associated with the -group_header_trigger option changes. Refer to the description of -page_footer_value above for the content of a header/footer. (Default value for STR is "", meaning there is no group header defined.) -outline column_list, -out column_list column_list determines if duplicate values in a column are to be suppressed. column_list can be set to a list of column names or numbers. If the value of a named column is the same as its previous value, then the value is suppressed unless it is the first line of a new page. (Default value for column_list is "", meaning no columns have duplicate values suppressed.) If any of the named columns are a member of the "group" of rows defined by the group option, then it, and all of the columns more major in this group, are outlined. A change in value of any one column displays all columns lower in the hierarchy in addition to the column that changed. An exception is the first line on a new page, in which case duplicate values are never suppressed. -page_break column_list, -pb column_list column_list determines when page breaks are generated. column_list can be set to a list of column names or numbers. The columns specified in the list are examined, and when their values change, a new page break is generated. If any of the named columns are a member of the "group" of rows defined via the group option, then it, and all columns more major in the group, are examined for page breaks. (Default value for column_list is "", meaning that no columns are examined for page breaks.) -row_footer_value STR, -rfv STR STR is the row footer placed after each detail line. Refer to the description of -page_footer_value (above) for the content of a footer. (Default value for STR is "", meaning that no row footer is provided.) -row_header_value STR, -rhv STR STR is the row header placed before each detail line. Refer to the description of -page_footer_value (above) for the content of a header. (Default value for STR is "", meaning that no row header is provided.) -subcount subcount_spec, -sct subcount_spec subcount_spec determines what columns subcounts to generate, when they should be generated, and what type of subcount is generated. (Default value for subcount_spec is "", meaning that no subcounts are generated for any columns.) subcount_spec can consist of one or more blank-separated "triplets." The syntax of a triplet is: column_1,column_2{reset | running} where: column_1 is the name or number of the column for which a subcount is generated. column_2 is the name or number of a column whose value is examined to determine when to generate the subcount. When the value of the column being examined changes, the subcount is generated. If this column is a member of the group of rows defined via the group option, it, and all columns more major in the group, are examined for subcount generation. reset | running indicates the type of subcount desired. If reset is selected, the subcount counter is reset to 0 each time a subcount is generated. If running is selected, the subcount is not reset to 0. If a subcount is requested on a column that is excluded, the subcount is also excluded from the page. An exception to this rule is when all columns are excluded. Subcounts are provided in this case to allow reports consisting of some combination of counts, subcounts, totals, and subtotals only. (Default is reset) -subtotal subtotal_spec, -stt subtotal_spec subtotal_spec determines what column subtotals to generate, when they should be generated, and what type of subtotal is generated. (Default value for subtotal_spec is "", meaning no subtotals are generated for any columns.) subtotal_spec can consist of one or more blank-separated triplets. The syntax of a triplet is: column_1,column_2{,reset | running} where: column_1 is the name or number of the column for which a subtotal is generated. column_2 is the name or number of a column whose value is examined to determine when to generate the subtotal. When the value of the column being examined changes, the subtotal is generated. If this column is a member of the group of rows defined via the group option, it, and all columns more major in the group, are examined for subtotal generation. reset | running indicates the type of subtotal desired. If reset is selected, the subtotal counter is reset to 0 each time a subtotal is generated. If running is selected, the subtotal is not reset to 0. If a subtotal is requested on a column that is excluded, the subtotal is also excluded from the page. An exception to this rule is when all columns are excluded. Subtotals are provided in this case to allow reports consisting of some combination of counts, subcounts, totals, and subtotals only. (Default is reset) -total column_list, -tt column_list column_list determines what column totals to generate. (Default value for column_list is "", meaning no totals are generated for any columns.) column_list can be set to a list of column names or numbers. Totals are generated after the last detail line. If a total is requested on a column that is excluded, the total is also excluded from the page. An exception to this rule is when all columns are excluded. Totals are provided in this case to allow reports consisting of some combination of counts, subcounts, totals, and subtotals only. SPECIFIC COLUMN OPTIONS In the following descriptions, column_id means the column name, the number of the column in the query, or a star name which is used to match column names. -alignment column_id STR, -al column_id STR column_id specifies which column the alignment applies to and STR is the alignment mode. STR can be set to center, left, right, both, or decimal N. The default value for STR depends upon the type of column selected. Character and bit strings default to left-alignment, decimal data with a non-zero scale defaults to decimal-point-alignment, and all other types default to right alignment. For decimal-point-alignment, the decimal alignment position within the display width is given a default value. This alignment position can be changed by specifying the value as "decimal N", where N is the character position within the display width where the decimal point is aligned. The alignment mode "both" specifies that the column value is aligned to the leftmost and rightmost character positions within its display width. Text is padded by insertion of uniformly distributed whitespace if necessary. -editing column_id STR, -ed column_id STR STR specifies the additional editing to be done to the column value before it is placed on the page and column_id specifies which column the editing applies to. Multics active functions and subsystem active requests are normally used to provide additional editing. For example, the editing value: [e pic $99,999v.99 [column_value salary]] places commas and dollar signs in the salary column. (Default value for STR is "", meaning additional editing is not done.) Refer to the column_value request for a description of usage. -folding column_id STR, -fold column_id STR STR determines what type of action occurs when a column value exceeds its display width and column_id specifies which column the folding applies to. STR set to truncate means that the value of the column is truncated to fit in the display width and the truncation character(s) are placed at the end of the value to indicate that truncation occurred. (Default value for STR is fill, meaning portions of the value which exceed the display width are moved down to the next line(s) until a correct fit is obtained.) -separator column_id STR, -sep column_id STR STR separates a column from the next one following it and column_id specifies which column the separator applies to. The last column on a line does not have a separator. STR can be any sequence of printable characters. (Default value for STR is "") -title column_id STR, -ttl column_id STR STR is the title placed above the column at the start of each page if the title_line option is set "on" and column_id specifies which column the title applies to. (Default value of STR is the name of the column. If the title is not the same number of characters as the display width of the column, the title is centered within the display width for its associated column. If the value of title is wider than the display width of the column, it is filled or truncated to obtain a correct fit, depending on the folding action of the parent column.) -width column_id N, -wid column_id N N determines the display width for a column and column_id specifies which column the width applies to. N can be set to any positive integer. (Default value for N is the number of character positions needed to contain the value, after conversion from the subsystems data type, to character format.) Control arguments: -brief, -bf specifies that the prompt string for values is not to be displayed. If the -brief and -long control arguments are both entered on the request line, the last one supplied is used. -default specifies that report writer set the value of the format option which immediately precedes this control argument to the system-supplied default. -long, -lg displays "Enter FORMAT_OPTION_NAME" prompt string for values when the -prompt control argument is provided. (Default) If the -brief and -long control arguments are both entered in the request line, the last one supplied is used. -no_reset, -nrs specifies that formatting options are not to be reset to system default values. (Default is that only user-specified options can be changed.) If the -reset and -no_reset control argument are both entered in the request line, the last one supplied is used. -prompt specifies that report writer prompts for the value of the format option which immediately precedes this control argument. A prompt string is written before the prompting action unless the -brief control argument is used. A line consisting of the single character "." terminates the prompted input mode. -reset, -rs specifies that all formatting options are to be reset to system default values before the values are changed for any other format options specified in the request line. If -reset and -no_reset are both entered in the request line, the last one supplied is used. -string STR, -str STR enters STR as a format option value when STR begins with a hyphen. Notes: At least one format option argument or the -reset control argument must be specified. Format option arguments and control arguments can be mixed freely in the request line, but a control argument cannot be placed between a format option name and a format option value. For example: sfo -page_width 80 -reset is a valid request, but sfo -page_width -reset 80 is not valid. If a value is to be set that begins with a hyphen, the -string control argument must be given before the value, to distinguish it from control arguments and format option arguments. Examples: sfo -width 1 25 sfo -title emp_name "Employee Name" sfo -reset -page_width 80 -page_length 60 sfo -page_footer_value "!!-[display_builtins page_number]-!!" sfo -page_header_value -prompt Enter page_header_value. ![execute date]!SAMPLE REPORT![execute time]! !!!! !!--Page [display_builtins page_number]--!! . sfo -exclude exchange extension -width area_code 12 sfo -editing area_code "[e format_line ^a/^a-^a [column_value area_code] [column_value exchange] [column_value extension]]" ----------------------------------------------------------- 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