1 09/10/85 set_format_options, sfo
2
3 Syntax: sfo -format_option_args -control_args
4
5
6 Function: sets individual report format options to user-specified or
7 default values, and/or all formatting options to default values.
8
9 Note: The option value given for any format option argument can be
10 the control arguments -default or -prompt. If -default is given for
11 the value, report writer sets the value of the format option to the
12 system default. If -prompt is given for the value, report writer
13 prompts for the value with the prompt string "Enter
14 FORMAT_OPTION_NAME.". A line consisting of the single character "."
15 terminates the prompted input mode. To suppress display of the
16 prompt string, use the -brief control argument.
17
18
19 Arguments:
20 format_option_args can be one or more of the following:
21
22 GENERAL REPORT OPTIONS
23 -delimiter CHAR, -dm CHAR
24 CHAR is the character used to delimit the different portions of a
25 header or footer and can be set to any printable character.
26 Default value for CHAR is
27 -format_document_controls STR, -fdc STR
28 STR determines if the format_document_ subroutine is to interpret
29 format document control lines when filling overlength text. STR can
30 be set to on, meaning format_document_ interprets control lines in
31 the text and provides special filling actions based on the embedded
32 control lines. Default value for STR is off meaning
33 format_document_ does not check for control lines embedded in text.
34
35
36 -hyphenation STR, -hph STR
37 the value of -hyphenation determines if hyphenation is to be
38 attempted when filling overlength character strings. STR can be set
39 to "on," specifying that hyphenation is to be attempted. Default
40 value for STR is off meaning no hyphenation is attempted.
41
42
43 -page_footer_value STR, -pfv STR
44 STR is the page footer placed at the bottom of each page. The page
45 footer can consist of more than one line, and each line can have a
46 left, right, and center portion. The individual portions of each
47 line are delimited by the delimiter character. Active requests
48 found in the footer are evaluated and their return value is placed
49 into the footer before folding and alignment takes place. Portions
50 of a footer with zero length have their space on the page
51 redistributed to the other portions whose lengths are not zero. For
52 example, if the page footer contained only a center portion:
53
54 !!Sample Center Portion!!
55
56 the text is centered on the page and has the full page width
57 available for the text. Similarly, a left portion or right portion
58 only is aligned to the left or right of the page and has the full
59 page width available for placement of text. Two exceptions to this
60 action are when the footer has a left, right, and center portion,
61 and the left or right portion has a zero length, such as:
62
63 !left part!center part!!
64
65 or
66
67 !!center part!right part!
68
69 in which case the left or right part of the page is unavailable for
70 placement of text i.e. the space is not redistributed to the other
71 two portions. If the redistribution of the available page width is
72 not desired, the placement of a single blank into a portion such as
73 " <SP> Center Part <SP> " prevents the redistribution from taking
74 place because each portion has a length greater than zero. Default
75 value for STR is "" meaning there is no page footer provided by
76 default.
77
78
79 -page_header_value STR, -phv STR
80 STR is the page header placed at the top of each page. Refer to the
81 description of -page_footer_value for the content of a header.
82 Default value for STR is "" meaning there is no page header
83 provided by default.
84 -page_length N, -pl N
85 N is the length of each formatted page given as number of lines. N
86 can be given as "0" or any positive integer. 0 means the report is
87 not to be paginated and is created as one continuous stream.
88 Default value for N is 0
89
90
91 -page_width N, -pw N
92 N is the width of each formatted page given as the number of
93 character positions. N can be given as "0" or any positive integer.
94 0 means the page_width is always set by report writer to be the
95 exact width needed to contain all of the columns specified in the
96 query. If N is greater than zero and the width for any column
97 exceeds N, the width of the column is automatically set to N.
98 Default value for N is 79
99 -title_line STR, -tl STR
100 STR determines if a title line is to be printed. STR can be set to
101 "off" to inhibit the printing of the title line. Default value of
102 STR is on meaning a title line is printed at the top of each page.
103
104
105 -truncation STR, -tc STR
106 STR determines the characters to be used to indicate truncation of
107 some value. STR can be set to any sequence of printable characters.
108 Default value for STR is *
109
110
111 GENERAL COLUMN OPTIONS
112 -column_order column_list, -co column_list
113 column_list determines the order in which columns appear in the
114 detail line. column_list can be set to a list of column names or
115 numbers. Columns missing from this list are placed after the
116 columns which appear in the list. That is, if five columns were
117 selected and the column_order value is given as "3 2", the complete
118 order would be "3 2 1 4 5". Default value for column_list is the
119 list of columns from the query in the order supplied meaning that
120 the columns appear in the exact order as they appear in the query.
121
122
123 -count column_list, -ct column_list
124 column_list determines the columns for which counts are generated.
125 column_list can be set to a list of column names or numbers. Counts
126 are generated after the last detail line. If a count is requested
127 on a column that is excluded, the count is also excluded from the
128 page. An exception to this rule is when all columns are excluded.
129 Counts are provided in this case to allow reports consisting of some
130 combination of counts, subcounts, totals, and subtotals only.
131 Default value for column_list is "" meaning no columns have counts
132 generated.
133 -exclude column_list, -ex column_list
134 column_list determines if any of the columns selected in the query
135 are excluded from the detail line. column_list can be set to a list
136 of column names or numbers. Default value for column_list is ""
137 meaning no columns are excluded.
138
139
140 -group column_list, -gr column_list
141 column_list determines the grouping of a number of rows based on the
142 values of one or more columns. column_list can be set to a list of
143 column names or numbers. The column or columns named in the list
144 become a hierarchy of columns. The first column named is the major
145 column, and the last column named becomes the minor column. The
146 hierarchy of columns can be used with the outline, page_break, and
147 subtotal options described below. Default value for column_list is
148 "" meaning no group of rows is defined.
149
150
151 -group_footer_trigger column_list, -gft column_list
152 column_list determines when to generate the group footer.
153 column_list can be set to a list of column names or numbers. The
154 columns which appear in this list must also appear in the column
155 list associated with the -group option. If the -group option is set
156 to a new value, columns which are eliminated from the column_list
157 are also eliminated from the -group_footer_trigger column_list.
158 When any of the columns specified in the column_list are about to
159 change with the next row, the group footer is evaluated. The group
160 footer is always evaluated after the last row of the report.
161 Default value for column_list is "" meaning no group footer
162 triggers are defined.
163
164
165 -group_footer_value STR, -gfv STR
166 STR is the group footer placed after each group of rows when any of
167 the columns associated with the -group_footer_trigger option
168 changes. Refer to the description of -page_footer_value above for
169 the content of a header/footer. Default value for STR is ""
170 meaning there is no group footer defined.
171
172
173 -group_header_trigger column_list, -ght column_list
174 column_list determines when to generate the group header.
175 column_list can be set to a list of column names or numbers. The
176 columns which appear in this list must also appear in the column
177 list associated with the -group option. If the -group option is set
178 to a new value, columns which are eliminated from the column_list
179 are also eliminated from the -group_header_trigger column_list.
180 When any of the columns specified in the column_list have just
181 changed with the current row, the group header is evaluated. The
182 group header is always evaluated before the first row of the report.
183 Default value for column_list is "" meaning no group header
184 triggers are defined.
185
186
187 -group_header_value STR, -ghv STR
188 STR is the group header placed before each group of rows when any of
189 the columns associated with the -group_header_trigger option
190 changes. Refer to the description of -page_footer_value above for
191 the content of a header/footer. Default value for STR is ""
192 meaning there is no group header defined.
193
194
195 -outline column_list, -out column_list
196 column_list determines if duplicate values in a column are to be
197 suppressed. column_list can be set to a list of column names or
198 numbers. If the value of a named column is the same as its previous
199 value, then the value is suppressed unless it is the first line of a
200 new page. Default value for column_list is "" meaning no columns
201 have duplicate values suppressed.
202
203 If any of the named columns are a member of the "group" of rows
204 defined by the group option, then it, and all of the columns more
205 major in this group, are outlined. A change in value of any one
206 column displays all columns lower in the hierarchy in addition to
207 the column that changed. An exception is the first line on a new
208 page, in which case duplicate values are never suppressed.
209
210
211 -page_break column_list, -pb column_list
212 column_list determines when page breaks are generated. column_list
213 can be set to a list of column names or numbers. The columns
214 specified in the list are examined, and when their values change, a
215 new page break is generated. If any of the named columns are a
216 member of the "group" of rows defined via the group option, then it,
217 and all columns more major in the group, are examined for page
218 breaks. Default value for column_list is "" meaning that no
219 columns are examined for page breaks.
220 -row_footer_value STR, -rfv STR
221 STR is the row footer placed after each detail line. Refer to the
222 description of -page_footer_value above for the content of a
223 footer. Default value for STR is "" meaning that no row footer is
224 provided.
225
226
227 -row_header_value STR, -rhv STR
228 STR is the row header placed before each detail line. Refer to the
229 description of -page_footer_value above for the content of a
230 header. Default value for STR is "" meaning that no row header is
231 provided.
232
233
234 -subcount subcount_spec, -sct subcount_spec
235 subcount_spec determines what columns subcounts to generate, when
236 they should be generated, and what type of subcount is generated.
237 Default value for subcount_spec is "" meaning that no subcounts
238 are generated for any columns.
239
240 subcount_spec can consist of one or more blank-separated "triplets."
241 The syntax of a triplet is:
242
243 column_1,column_2reset | running
244
245 where:
246
247 column_1
248 is the name or number of the column for which a subcount is
249 generated.
250 column_2
251 is the name or number of a column whose value is examined to
252 determine when to generate the subcount. When the value of the
253 column being examined changes, the subcount is generated. If
254 this column is a member of the group of rows defined via the
255 group option, it, and all columns more major in the group, are
256 examined for subcount generation.
257
258
259 reset | running
260 indicates the type of subcount desired. If reset is selected,
261 the subcount counter is reset to 0 each time a subcount is
262 generated. If running is selected, the subcount is not reset to
263 0. If a subcount is requested on a column that is excluded, the
264 subcount is also excluded from the page. An exception to this
265 rule is when all columns are excluded. Subcounts are provided in
266 this case to allow reports consisting of some combination of
267 counts, subcounts, totals, and subtotals only. Default is
268 reset
269
270
271 -subtotal subtotal_spec, -stt subtotal_spec
272 subtotal_spec determines what column subtotals to generate, when
273 they should be generated, and what type of subtotal is generated.
274 Default value for subtotal_spec is "" meaning no subtotals are
275 generated for any columns.
276
277 subtotal_spec can consist of one or more blank-separated triplets.
278 The syntax of a triplet is:
279
280 column_1,column_2reset | running
281
282 where:
283
284 column_1
285 is the name or number of the column for which a subtotal is
286 generated.
287 column_2
288 is the name or number of a column whose value is examined to
289 determine when to generate the subtotal. When the value of the
290 column being examined changes, the subtotal is generated. If
291 this column is a member of the group of rows defined via the
292 group option, it, and all columns more major in the group, are
293 examined for subtotal generation.
294
295
296 reset | running
297 indicates the type of subtotal desired. If reset is selected,
298 the subtotal counter is reset to 0 each time a subtotal is
299 generated. If running is selected, the subtotal is not reset to
300 0. If a subtotal is requested on a column that is excluded, the
301 subtotal is also excluded from the page. An exception to this
302 rule is when all columns are excluded. Subtotals are provided in
303 this case to allow reports consisting of some combination of
304 counts, subcounts, totals, and subtotals only. Default is
305 reset
306
307
308 -total column_list, -tt column_list
309 column_list determines what column totals to generate. Default
310 value for column_list is "" meaning no totals are generated for any
311 columns.
312
313 column_list can be set to a list of column names or numbers. Totals
314 are generated after the last detail line. If a total is requested
315 on a column that is excluded, the total is also excluded from the
316 page. An exception to this rule is when all columns are excluded.
317 Totals are provided in this case to allow reports consisting of some
318 combination of counts, subcounts, totals, and subtotals only.
319
320
321 SPECIFIC COLUMN OPTIONS
322 In the following descriptions, column_id means the column name, the
323 number of the column in the query, or a star name which is used to
324 match column names.
325
326
327 -alignment column_id STR, -al column_id STR
328 column_id specifies which column the alignment applies to and STR is
329 the alignment mode. STR can be set to center, left, right, both, or
330 decimal N. The default value for STR depends upon the type of
331 column selected. Character and bit strings default to
332 left-alignment, decimal data with a non-zero scale defaults to
333 decimal-point-alignment, and all other types default to right
334 alignment. For decimal-point-alignment, the decimal alignment
335 position within the display width is given a default value. This
336 alignment position can be changed by specifying the value as
337 "decimal N", where N is the character position within the display
338 width where the decimal point is aligned. The alignment mode "both"
339 specifies that the column value is aligned to the leftmost and
340 rightmost character positions within its display width. Text is
341 padded by insertion of uniformly distributed whitespace if
342 necessary.
343
344
345 -editing column_id STR, -ed column_id STR
346 STR specifies the additional editing to be done to the column value
347 before it is placed on the page and column_id specifies which column
348 the editing applies to. Multics active functions and subsystem
349 active requests are normally used to provide additional editing.
350 For example, the editing value:
351
352 e pic $99999v.99 column_value salary
353
354 places commas and dollar signs in the salary column. Default value
355 for STR is "" meaning additional editing is not done.
356
357 Refer to the column_value request for a description of usage.
358
359
360 -folding column_id STR, -fold column_id STR
361 STR determines what type of action occurs when a column value
362 exceeds its display width and column_id specifies which column the
363 folding applies to. STR set to truncate means that the value of the
364 column is truncated to fit in the display width and the truncation
365 characters are placed at the end of the value to indicate that
366 truncation occurred. Default value for STR is fill meaning
367 portions of the value which exceed the display width are moved down
368 to the next lines until a correct fit is obtained.
369 -separator column_id STR, -sep column_id STR
370 STR separates a column from the next one following it and column_id
371 specifies which column the separator applies to. The last column on
372 a line does not have a separator. STR can be any sequence of
373 printable characters. Default value for STR is "<SP><SP>"
374
375
376 -title column_id STR, -ttl column_id STR
377 STR is the title placed above the column at the start of each page
378 if the title_line option is set "on" and column_id specifies which
379 column the title applies to. Default value of STR is the name of
380 the column. If the title is not the same number of characters as
381 the display width of the column the title is centered within the
382 display width for its associated column. If the value of title is
383 wider than the display width of the column it is filled or
384 truncated to obtain a correct fit depending on the folding action
385 of the parent column.
386
387
388 -width column_id N, -wid column_id N
389 N determines the display width for a column and column_id specifies
390 which column the width applies to. N can be set to any positive
391 integer. Default value for N is the number of character positions
392 needed to contain the value after conversion from the subsystems
393 data type to character format.
394
395
396 Control arguments:
397 -brief, -bf
398 specifies that the prompt string for values is not to be displayed.
399 If the -brief and -long control arguments are both entered on the
400 request line, the last one supplied is used.
401 -default
402 specifies that report writer set the value of the format option
403 which immediately precedes this control argument to the
404 system-supplied default.
405 -long, -lg
406 displays "Enter FORMAT_OPTION_NAME" prompt string for values when
407 the -prompt control argument is provided. Default If the -brief
408 and -long control arguments are both entered in the request line,
409 the last one supplied is used.
410
411
412 -no_reset, -nrs
413 specifies that formatting options are not to be reset to system
414 default values. Default is that only user-specified options can be
415 changed. If the -reset and -no_reset control argument are both
416 entered in the request line, the last one supplied is used.
417 -prompt
418 specifies that report writer prompts for the value of the format
419 option which immediately precedes this control argument. A prompt
420 string is written before the prompting action unless the -brief
421 control argument is used. A line consisting of the single character
422 "." terminates the prompted input mode.
423
424
425 -reset, -rs
426 specifies that all formatting options are to be reset to system
427 default values before the values are changed for any other format
428 options specified in the request line. If -reset and -no_reset are
429 both entered in the request line, the last one supplied is used.
430 -string STR, -str STR
431 enters STR as a format option value when STR begins with a hyphen.
432
433
434 Notes: At least one format option argument or the -reset control
435 argument must be specified. Format option arguments and control
436 arguments can be mixed freely in the request line, but a control
437 argument cannot be placed between a format option name and a format
438 option value. For example:
439
440 sfo -page_width 80 -reset
441
442 is a valid request, but
443
444 sfo -page_width -reset 80
445
446 is not valid. If a value is to be set that begins with a hyphen, the
447 -string control argument must be given before the value, to distinguish
448 it from control arguments and format option arguments.
449
450
451 Examples:
452 sfo -width 1 25
453 sfo -title emp_name "Employee Name"
454 sfo -reset -page_width 80 -page_length 60
455 sfo -page_footer_value "!!-display_builtins page_number-!!"
456 sfo -page_header_value -prompt
457 Enter page_header_value.
458 !execute date!SAMPLE REPORT!execute time!
459 !!!!
460 !!--Page display_builtins page_number--!!
461 .
462 sfo -exclude exchange extension -width area_code 12
463 sfo -editing area_code "e format_line ^a/^a-^a
464 column_value area_code column_value exchange
465 column_value extension"
466