MULTICS TECHNICAL BULLETIN MTB-606
To: MTB Distribution
From: Al Dupuis
Date: 01/19/83
Subject: LINUS Report Generation
ABSTRACT
The LINUS report generator produces formatted reports from a
relational data base. Through this facility the user can
control: page width and length; page breaks; headers and
footers; column titles; sorting output on one or more keys; and
totaling/subtotaling across rows and down columns. The report
generator has been designed to serve the needs of the casual and
the experienced user. A casual user can have a default report
layout provided by the system, while more experienced users have
the option of precisely defining the report layout.
Comments on this MTB will be greatly appreciated. Please send
them to:
The System M forum
>udd>Demo>dbmt>continuum>LINUS_development.
or
Dupuis.Multics on System M
or
HVN 357-6632 or 602/862-6632
________________________________________
Multics Project internal working documentation. Not to be
reproduced or distributed outside the Multics Project.
MTB-606
ORGANIZATION
This MTB is made up of several sections. The first is an
introduction and covers the motivation, competition, and goals.
The second section is a system overview and highlights the format
options and LINUS requests. The third section covers the default
report writer operation and functions. The fourth section covers
optional report writer functions, and Attachments A and B are
detailed descriptions of the requests and format options.
MTB-606
1. INTRODUCTION
Motivation
The LINUS built-in report generation capabilities are provided by
the "print" request. The features provided allow only the most
primitive forms of report generation and do not satisfy the needs
of the majority of users. External report generation is provided
through the "report" request interface to MRPG, the "create_list"
request interface to lister, and the "write" request interface to
other Multics formatting tools (i.e. emacs, compose, etc.) For
a number of reasons these external methods of report generation
have been deemed inappropriate for the task of producing
formatted reports from a relational data base, and a PFS item for
providing a more functional Report Generator built into LINUS has
been agreed to.
Competitive Systems
The competitors closest to LINUS are the various implementations
of SQL. SQL is offered by a number of companies and runs on both
minis and mainframes. One of the more popular implementations of
SQL is IBM's SQL/DS, and it has been used frequently for
functionality comparisons during the design of the LINUS report
writer.
Although SQL is almost identical to LINUS in some instances,
there are differences in the user interface and differences in
capabilities. One of the areas of capability differences is
report generation, where SQL provides more functional and flexi-
ble features.
A brief list of some of the SQL report generation capabilities
follows:
o The ability to generate a report with the system providing
all of the defaults.
o The ability to store a report format and later recall it.
o Totaling and subtotaling on columns.
o Suppression of duplicate rows and/or columns.
o User control over column titles, column separators, column
alignment, column display, headers, footers, page width, and
page length.
o Line printing complete or selected portions of the display
image.
MTB-606
o Omitting and then restoring columns from the display image.
o Scrolling forward, backward, left and right through the
displayed image.
System Goals
The two main goals of the report writer are ease-of-use and
functionality. These two goals are in constant conflict with
each other and trade offs must be made, weighing the usefulness
of a given feature against the complexity it would introduce.
Enough specific functionality has been spelled out in the PFS to
make sure that the report writer is more functional than the
existing print request. A comparison against SQL report writers
shows that the implementation of only the stated PFS
functionality would not provide a system that would stand up in
competitive sales situations. There are three ways the goal of
functionality can be stated:
a) provide a system with more functionality than LINUS currently
offers, but significantly less than the competition
b) provide a system with functionality equivalent to the compe-
tition
c) provide a system with functionality greater than the competi-
tion
The report writer described in this MTB aims primarily at (b) and
(c). The competitive SQL implementations are considered
easy-to-use, so a product that meets (b) and has a similiar user
interface seemed like a reasonable choice. When (c) could be
provided and the functionality gained was greater than the
complexity introduced, then it was opted for.
MTB-606
2. SYSTEM OVERVIEW
Basic Operation
The LINUS report writer system retrieves rows (tuples) from a
relational data base and produces a formatted report as output.
The rows to be retrieved are specified via a LILA selection
expression.
Formatting Options
The formatted report is produced under the control of "formatting
options". A formatting option consists of a name to identify it
and a value which it is set to. An example of a formatting
option is "-page_width 80". The name of this option is
"-page_width" and the value associated with the name is "80".
Formatting options which deal with columns require an option
identifier to uniquely identify the column. For example, to set
the width of a column, an identifier is needed to determine which
column the width should be set for. Identifiers can be given as
the number of the column in the LILA selection-expression, the
name of the column as defined in the open model or submodel, or a
star name which is matched against the column names. Examples of
formatting options with identifiers are "-width salary 10",
"-folding 3 fill", and "-alignment ** center".
The formatting options are grouped into three classifications:
general report options; general column options; and specific
column options.
General report options control overall characteristics of a
report, such as the page width. They are given a default value
when linus is first invoked, and can be changed by the user at
any time. They retain their value across a complete linus
session.
General column options control overall characteristics of the
columns, such as watching the value of certain columns to
determine if a page break should be generated. They are given a
default value for every new LILA selection-expression, and can be
changed by the user at any time. They retain their value until
the next new LILA selection-expression.
Specific column options control the characteristics of one
specific column, such as a column's width. They are given a
default value for every new LILA selection-expression, and can be
changed by the user at any time. They retain their value until
the next new LILA selection-expression. These are the only
formatting options which require an identifier to determine which
column the particular option applies to.
MTB-606
The concept of "active" options is employed by the requests to
make the system easier to use for the novice, yet still provide
flexibility for the experienced user. For example, if a novice
user did not use page headers, she would never see any reference
to them unless she specifically mentioned them. If she defined a
page header to use, it would become active and would appear in
the output of the various reporting requests. If she asked for
the page header to disappear, it would revert back to the
"inactive" state.
All specific column options are considered active at all times.
General column options and general report options are considered
active only when their value is different from the default value
they are originally given. For example, if the page_width is
always set to its default value it is not considered active. The
moment that it is changed to a value different from its default
it is considered active.
Requests
There are several requests which can be used in the creation of
reports. (See "ATTACHMENT A" for a complete description of these
requests.) The "set_format_options" request is used to change
the values of format options. The "list_format_options" request
is used to list the names and values of format options. The
"save_format_options" request is used to save the names and
values of one or more options as a report layout; and the
"restore_format_options" request restores these saved report
layouts.
The "display" request deals with retrieving rows from MRDS,
formatting a report from them, and displaying the formatted
report.
MTB-606
3. DEFAULT REPORT ELEMENTS
A page consists of a title line followed by as many rows as will
fit on the remainder of the page. The default title line is made
up of one or more column titles, one column title for each column
on the page. The column title is the column name (attribute
name), as found in the open submodel or model. If the column is
the result of an expression or function invocation, the column
title will be "eN", where N begins at 1 and increases by 1 for
each function invocation or expression encountered in the
selected data. The row is made up of one or more columns, all
concatenated together to form the row.
Separators
There is a separator provided for each column value and each
column title. The default separator is two blanks and is placed
between each pair of column values and each pair of column
titles. The last column title or column value of a row has no
separator.
Folding
When formatting the report, there are times when the report
elements do not fit within their defined width. The action that
must occur to rectify this situation is termed "folding". There
are two different ways in which folding can occur. The first is
"truncation". Truncation means the value is truncated to the
defined width and the last displayable character is replaced by
the truncation character(s) (normally "*"). The second is
"filling". Filling means that portions of the value will be
moved down to the next line(s), allowing the newly formatted
value to appear within its defined width.
A common occurence of folding is within column titles. A column
title has a default width which is the same as the column width.
If the column title cannot fit within this defined width, the
folding action of "filling" is done. Portions of the title are
moved down to the next line(s) until a fit occurs.
The default width for the column value is derived from the open
model or submodel. The width chosen is the exact number of
characters needed to contain the value after it has been
converted from the internal data base data type to character
format via PL/I conversion rules. When the default width is used
the column value always fits, but this width can be reduced by
the user. The reduction of the column width causes folding to
occur. Column folding can be set to "fill" or "truncate" and
proceeds as described above for column title folding. The
default for column values is "fill".
MTB-606
The concatenation of all the column values and separators to come
up with the row value, can cause row folding to occur. This
happens when the resulting row is wider than the defined page
width. If row folding is set to fill and the row is wider than
the page width, columns which appear on or to the right of the
right page boundary are moved down to the next line(s). Their
corresponding titles are moved so that they appear directly over
their columns.
If row folding is set to truncate and the row is wider than the
defined page width, the title line and row value are truncated to
page width and the last displayable character(s) is set to the
truncation character. The default for row folding is "fill".
Alignment
The alignment for column values is derived from the data type of
the column, as defined in the open model or submodel. Character
and bit strings default to left alignment, decimal data defaults
to decimal point alignment, and all other data types default to
right alignment. The user can set the alignment of individual
columns to left, right, center, or decimal point alignment.
The alignment for a column title is left; the title is left
justified within its defined width.
The alignment for a title line or a row is left, which means the
title line or row will be placed against the left page boundary.
MTB-606
4. OPTIONAL REPORT ELEMENTS
For the user with more complex report formatting needs, there are
a number of optional features which may be used to achieve
greater control over the appearance of the report. Their
description follows.
Editing
Editing can be specified for any column value, and is provided by
LINUS active requests and Multics active functions. The column
value is passed to the active function or request and the
returned value is then folded and aligned as described above.
Editing of column values is not provided by default.
Headers and Footers
A header or footer is a character string provided by the user.
The character string can contain active requests, can be made up
of more than one "portion", and can consist of more than one
line. A delimiter character is used to separate the different
portions of a header or footer. This delimiter character
defaults to "!" but can be changed by the user. The
header/footer can consist of a left, right, and center portion.
Evaluation of a header/footer is a two part operation that
proceeds in the following manner: first, the header/footer is
divided into its portions based on the "delimiter" character; and
second, active requests are evaluated. The LINUS active request
"page_number" can be used to obtain the current page number in a
header/footer, and the LINUS active request "column_value" can be
used to obtain the value of a column from the current row.
A header or footer can be made up of a left, right, and center
portion. These portions are determined by the delimiter charac-
ters found. The portions are aligned to the left, right, and
center of the page. Folding on headers/footers proceeds indepen-
dently for each part.
Headers and footers can be defined for a page and a row. The
first row that will appear on the page is available for the page
header. The current row is available for use in the row header
and row footer. The last row that will appear on the page is
available for the page footer.
The major differences between headers/footers and column titles
are: titles are character strings that can't contain active
functions; and they are associated with a column and inherit its
width and always appear directly above their respective column.
MTB-606
Active Requests
Active requests are used in headers/footers to substitute values
into the header/footer at the time the report is being formatted.
For example, the Multics active function "date" could be used to
provide the current date as part of the header or footer.
They are also used to provide editing for column values which
will become part of the row value. For example, the LINUS active
request "picture" could be used to provide editing features like
dollar signs and commas.
LINUS active requests are specified by the user through the
construct "[name STR]", where name is the name of the desired
active request and STR is any argument(s) required by the active
request. Multics active functions are invoked via the LINUS
"execute" active request. They are specified by the user through
the construct "[execute name STR]", where name is the name of the
Multics active function and STR is any argument(s) required by
the active function. The active function/request is evaluated
and its returned value is substituted into the original string,
before folding and alignment takes place.
Page Breaks
Page breaks can be set to occur when the value of one or more
columns changes. The occurence of a new value in the column(s)
being watched causes the current page to be closed out and a new
page started. The new row which caused the page break is not
made available until the start of the next page. This allows the
page footer to access the correct row (the last row on that
page).
Excluding Columns
Columns selected via LILA can be excluded from the row value.
Through the use of the "column_value" active request, the column
value can be obtained for placement elsewhere on the page. For
example, a user could exclude the display of a column that is
being used to determine when to generate page breaks, and place
the value of the column in the page header through
"column_value".
Ordering Of Columns
The columns appear on the page in the order they were selected
through LILA. This order can be changed by the user without
having to go back and change the LILA select.
MTB-606
Outlining
One or more columns can have duplicates values suppressed. If
more than one column is specified the left to right order they
are given in is treated as a major to minor hierarchy. If the
values of all columns are the same as the previous values then
their display will be suppressed. A change in value of any one
column causes all columns lower in the hierarchy to have their
values displayed, in addition to the column that changed. An
exception to this is if it is the first line on a new page, when
duplicate values are never suppressed.
Totals and Subtotals
Totals and subtotals can be specified for columns. The totals
and subtotals are placed directly under their associated columns.
A column subtotal is generated when the value of the column(s)
the subtotal is associated with changes. The subtotal can be
associated with one or more columns. Several subtotals can be
specified, each associated with different columns. Subtotals can
be "reset" or "running". A column total is generated after the
last input row has been processed.
Separators and Delimiters
The separators used to separate column values and column titles
from each other can be set to any string of printable characters
by the user. The delimiter character used to delimit the
different portions of a header/footer can also be set by the
user.
ATTACHMENT A
FORMATTING OPTIONS
01/19/83 Formatting Options (General Information):
Formatting options control the layout of a report. A formatting option
consists of a name to identify it and a value which it is set to.
Examples of formatting options are "-page_width 80" and "-title_line
on". Formatting options which deal with columns require an option
identifier to uniquely identify the column. For example, to set the
width of a column, an identifier is needed to determine which column
the width should be set for. Identifiers can be given as the number of
the column in the LILA selection-expression, the name of the column as
defined in the open model or submodel, or a star name which is matched
against the column names. Examples of formatting options with
identifiers are "-width salary 10", "-folding 3 fill", and "-width **
20".
The values of format options are listed and set through the
"list_format_options" and "set_format_options" requests. These
requests take control arguments which are the names of the format
options. For example, to find out what the current page width is, the
request "list_format_options -page_width" would be given. To change
the page width, the request "set_format_options -page_width 65" would
be used.
Classifications:
The formatting options can be grouped into three classifications: gen-
eral report options; general column options; and specific column
options.
General report options control overall characteristics of a report,
such as the page width. They are given a default value when linus is
first invoked, and can be changed by the user at any time. They retain
their value across a complete linus session.
General column options control overall characteristics of the columns,
such as watching the value of certain columns to determine if a page
break should be generated. They are given a default value for every
new LILA selection-expression, and can be changed by the user at any
time. They retain their value until the next new LILA
selection-expression.
Specific column options control the characteristics of one specific
column, such as a column's width. They are given a default value for
every new LILA selection-expression, and can be changed by the user at
any time. They retain their value until the next new LILA
selection-expression. These are the only formatting options which
require an identifier to determine which column the particular option
ATTACHMENT A
FORMATTING OPTIONS
Active options:
All specific column options are considered active at all times. Gener-
al column options and general report options are considered active only
when their value is different from the default value they are original-
ly given. For example, if the page_width is always set to its default
value it is not considered active. The moment that it is changed to a
value different from its default it is considered active. This, for
example, reduces the number of options listed when a user types the
"list_format_options" request with no control arguments. The
page_width would never be listed if it was set to its default value,
unless it was specifically asked for.
List of options:
General report options:
delimiter page_footer_value page_header_value
page_length page_width title_line
truncation
General column options:
column_order exclude group
outline page_break row_folding
row_footer_value row_header_value subtotal
total
Specific column options:
alignment editing folding
ATTACHMENT B
REQUEST DESCRIPTIONS
01/19/83 column_value, clv
Syntax: [column_value column_id]
Function: returns the value of the specified column for the current
row. This request can only be used as an active request. It is used
within a formatted report produced by the display request to obtain a
column's value from the current row. It is an error to use this
request anywhere except in a header/footer or editing string within a
report produced by the display request.
Arguments:
column_id
specifies which column the value should be returned for. column_id
can be given as the name of the column as defined in the open
model/submodel or the number of the column in the LILA
ATTACHMENT B
REQUEST DESCRIPTIONS
01/19/83 display, di
Syntax: display {-control_args}
Function: retrieves selected data, creates a report, and displays it
on the terminal or saves it to a file.
Control arguments:
-brief, -bf, -long, -lg
specifies that display is to suppress warning messages (-brief), or
print warning messages (-long). Warning messages are printed when a
control argument such as -old_retrieval is used and the data from a
previous retrieval isn't available. -long is the default.
-delete_rows, -dlr, -keep_rows, -kr
specifies that display is to delete or keep the retrieved data on
its termination. Keeping the retrieved data allows its re-use on
subsequent invocations of the display request. Previously retrieved
data that has been sorted retains its sort order. -delete_rows is
the default.
-new_retrieval, -nr, -old_retrieval, -or
specifies that display should begin a new retrieval from the data
base, or, use data retrieved during its previous invocation.
-new_retrieval is the default.
-save path, -sv path
where path is the name of the file which will contain the formatted
report. If this argument is not given the report is displayed on
the terminal.
-sort NAME {-ascending | -descending} ... {NAME {-asc | -dsc}}
where NAME is the name of a column as defined in the open
model/submodel or a number corresponding to the position of the col-
umn in the selection expression. It can be followed by -ascending
or -descending. If -ascending or -descending is not specified, the
default is -ascending.
-temp_dir dir_name, -td dir_name
specifies that the given directory should be used for storing the
retrieved data instead of the process directory. This temp dir will
continue to be used until another new temp dir is requested. A new
temp dir can only be specified when a new retrieval is being
ATTACHMENT B
REQUEST DESCRIPTIONS
01/19/83 format_line, fl
Syntax: [fl control_string {args}]
DOCUMENTATION TO BE SUPPLIED LATER. REFER TO THE COMMANDS AND ACTIVE
ATTACHMENT B
REQUEST DESCRIPTIONS
01/19/83 list_format_options, lsfo
Syntax: lsfo -control_arg
or lsfo -format_option_args
or [lsfo -format_option_arg]
Function: lists the names and values of individual report formatting
options; all report formatting options; or the active report formatting
options. As an active request returns the value of the specified for-
mat option.
Control arguments:
-active, -act
specifies that only the active formatting options are to be listed
(DEFAULT). Type help "formatting_options.gi" for more information
on "active" formatting options. This control arg is incompatible
with "-all" and the format option arguments. If "-active" and
"-all" are both given the last one supplied will be used.
-all, -a
specifies that all formatting options are to be listed. This con-
trol arg is incompatible with "-active" and the format option argu-
ments. If "-all" and "-active" are both given the last one supplied
will be used.
Format Option Arguments (General Report Options):
-delimiter, -dm
the character used to delimit the different portions of a header or
footer.
-page_footer_value, -pfv
the page footer placed at the bottom of each page.
-page_header_value, -phv
the page header placed at the top of each page.
-page_length, -pl
the length of each formatted page given as the number of lines.
-page_width, -pw
the width of each formatted page given as the number of characters.
-title_line, -tl
specifies the printing or suppression of printing of the title line.
-truncation, -tc
ATTACHMENT B
REQUEST DESCRIPTIONS
Format Option Arguments (General Column Options):
-column_order, -co
the order of the display of columns in the detail line.
-exclude, -ex
the columns that will be excluded from display in the detail line.
-group, -gr
the columns used to group a number of rows based on their values.
-outline, -out
the columns which are candidates for duplicate suppression.
-page_break, -pb
the columns which are candidates for a break to a new page.
-row_folding, -rf
the action that occurs when a detail line exceeds the page width.
-row_footer_value, -rfv
the row footer placed after each detail line.
-row_header_value, -rhv
the row header placed before each detail line.
-subtotal, -stt
the columns which will have subtotals taken on them.
-total, -tt
the columns which will have totals taken on them.
Format Option Arguments (Specific Column Options):
"column_id" in the following descriptions means the column name as
defined in the open model/submodel, the number of the column in the
LILA selection-expression, or a star name which is matched against the
column names.
-alignment column_id, -al column_id
the alignment mode within the display width for the specified col-
umn.
-editing column_id, -ed column_id
the editing string for the specified column.
-folding column_id, -fdg column_id
the folding action taken when the column value exceeds the display
width for the specified column.
ATTACHMENT B
REQUEST DESCRIPTIONS
the character string that separates the specified column from the
column in the detail line which immediately follows it.
-title column_id, -ttl column_id
the character string that is placed at the top of the page above the
specified column.
-width column_id, -wi column_id
the display width in the detail line for the specified column.
Notes:
Refer to the description of the set_format_options request for a com-
plete list of the default values for the format options and a discus-
sion of their allowed values.
Examples:
list_format_options
list_format_options -all
list_format_options -width 1 -alignment salary
ATTACHMENT B
REQUEST DESCRIPTIONS
01/19/83 page_number, pn
Syntax: [page_number]
Function: returns the current page number. This request can only be
used as an active request. It is used within a formatted report
produced by the display request to obtain the number of the current
page. It is an error to use this request anywhere except in a
header/footer or editing string within a report produced by the display
ATTACHMENT B
REQUEST DESCRIPTIONS
01/19/83 picture, pic
Syntax: [picture pic_string values -control_arg]
DOCUMENTATION TO BE SUPPLIED LATER. REFER TO THE COMMANDS AND ACTIVE
ATTACHMENT B
REQUEST DESCRIPTIONS
01/19/83 restore_format_options, rsfo
Syntax: rsfo path
Function: restores the saved report layout specified by path. Only
the formatting options found in the saved report layout have their val-
ues changed.
Arguments:
path
the pathname of the saved report format to be restored. If path
does not have a suffix of ".fo.lec", one is assumed.
Notes:
Refer to the save_format_options request for more detail on the content
of the saved report format.
Examples:
restore_format_options sample_display_format
ATTACHMENT B
REQUEST DESCRIPTIONS
01/19/83 save_format_options, svfo
Syntax: svfo path {-format_option_args} {-control_args}
Function: saves the current values of format options as a linus
subsystem exec_com. The saved format can be restored later with the
restore_format_options request. The file is saved with a suffix of
".fo.lec". Individual format options; active format options; or all
the format options can be saved.
Arguments:
path
the pathname of the segment which will contain the saved format.
The suffix ".fo.lec" is appended if not given.
Format Option Arguments:
Refer to the description of the list_format_options request for a com-
plete list of the names of the format option arguments. Each format
option named will have its value saved in the exec_com specified by
path. These arguments are incompatible with the control arguments -all
and -active listed below.
Control arguments:
-active, -act
specifies that only the active formatting options will be saved.
(DEFAULT) Type "help formatting_options.gi" for more information on
"active" formatting options. This control argument is incompatible
with the format option arguments and "-all". If -all and -active
are given the last one supplied is used.
-all, -a
specifies that all formatting options should be saved. This control
argument is incompatible with the format option arguments and
"-active". If -all and -active are given the last one supplied is
used.
-selection_expression, -se
specifies that the current lila selection_expression should also be
saved. A restore_format_options on the saved format will also
restore and process the saved selection expression.
ATTACHMENT B
REQUEST DESCRIPTIONS
-all and -active are incompatible with the format option arguments and
can not be used on the same request line. -all and -active are incom-
patible with each other and if both are supplied on the request line,
the last one given will be used.
Examples:
save_format_options report_layout
save_format_options report_layout -all
save_format_options report_layout -selection_expression
save_format_options report_layout -page_header_value -page_footer_value
save_format_options report_layout -page_header_value -width salary
ATTACHMENT B
REQUEST DESCRIPTIONS
01/19/83 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 of the formatting options to their default
values.
The option value given for any format option argument can be the con-
trol arguments "-default" or "-prompt". If "-default" is given for the
value, LINUS will set the value of the format option to the system
default. If "-prompt" is given for the value, LINUS will prompt for
the value with the prompt string "Enter FORMAT_OPTION_NAME.". A line
consisting of the single character "." will terminate the prompted
input mode. To suppress the printing of the prompt string use the
"-brief" control argument.
Format Option Arguments (General Report Options):
-delimiter CHAR, -dm CHAR
the character used to delimit the different portions of a header or
footer. The default character is "!". This can be set to any
printable character except the special escape character "".
-page_footer_value STR, -pfv STR
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
header are executed unless they are protected by the escape charac-
ter "". Any occurence of the characters "[" or "]" that are meant
as text rather than active request delimiters must be preceded by
the escape character. To place an escape character into the header
as text without its special meaning, precede the escape character
with another escape character. The default value for STR is ""
which means there is no page footer provided by default.
-page_header_value STR, -phv STR
the page header placed at the top of each page. Refer to the
description of "-page_footer_value" for the content of a
header/footer. The default value for STR is "" which means there is
no page header provided by default.
-page_length N, -pl N
the length of each formatted page given as the number of lines. N
can be given as "0" or any positive integer. "0" means that the
report is not to be paginated and it is created as one continous
stream. The default value for N is "66".
ATTACHMENT B
REQUEST DESCRIPTIONS
the width of each formatted page given as the number of characters.
N can be given as "0" or any positive integer. "0" means that the
page_width will always be set by LINUS to be the exact width needed
to contain all of the columns specified in the LILA
selection-expression. The default value is "79" characters.
-title_line STR, -tl STR
the value of title_line is used to determine whether a title line
should be printed. The default value for STR is "on" which means
that a title line is printed at the top of each page. STR can also
be set to "off" to inhibit the printing of the title line.
-truncation STR, -tc STR
the value of truncation is used to determine the character(s) that
should be used to indicate that truncation of some value has
occured. The default value for STR is "*". STR can be set to any
sequence of printable characters.
Format Option Arguments (General Column Options):
-column_order COLUMN_LIST, -co COLUMN_LIST
the value of column_order is used to determine the order that the
columns should appear in the detail line. The default value for
COLUMN_LIST is the list of columns from the LILA
selection-expression in the order supplied. This means that the
columns will appear in the exact same order as they appear in the
LILA selection-expression. COLUMN_LIST can be set to a list of col-
umn names or numbers. Columns missing from this list will be placed
after the columns which appear in the list. That is, if five col-
umns were selected and the column_order value had been given as "3
2", the complete order would be "3 2 1 4 5".
-exclude COLUMN_LIST, -ex COLUMN_LIST
the value of exclude is used to determine if any of the columns
selected via LILA should be excluded from the detail line. The
default value for COLUMN_LIST is "" which means no columns should be
excluded. COLUMN_LIST can be set to a list of column names or num-
bers.
-group COLUMN_LIST, -gr COLUMN_LIST
the value of group is used to group a number of rows based on the
values of one or more columns. The default value for COLUMN_LIST is
"" which means no group of rows has been defined. 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 most major column, and the last column named becomes
the most minor column. The hierarchy of columns can be used with
the "outline", "page_break" and "subtotal" options as described
below under each option's description.
ATTACHMENT B
REQUEST DESCRIPTIONS
the value of outline is used to determine if duplicate values in a
column should be suppressed. The default value for COLUMN_LIST is
"" which means no columns should have duplicate values 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 will be suppressed unless it is the first line of a new page.
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 have outlining done on them. A change in value
of any one column causes all columns lower in the hierarchy to have
their values displayed, in addition to the column that changed. An
exception to this is if it is the first line on a new page, when
duplicate values are never suppressed.
-page_break COLUMN_LIST, -pb COLUMN_LIST
the value of page_break is used to determine when page breaks should
be generated. The default value for COLUMN_LIST is "" which means
that no columns are watched for page breaks. COLUMN_LIST can be set
to a list of column names or numbers. The columns specified in the
list are watched and when their values change, a break to a new page
is generated. If any of the named columns are a member of the group
of rows defined via the "group" option, it and all columns more
major in the group will be watched for page breaks.
-row_folding STR, -rf STR
the action that occurs when a detail line exceeds the page width.
STR can be set to "fill" or "truncate". The default value is "fill"
which means that columns which appear on or to the right of the
right page boundary are moved down to the next line(s) to obtain a
correct fit. Their corresponding column titles are also moved so
that they appear directly above their respective columns. STR can
be set to "truncate" which means that any columns that appear on or
to the right of page_width are truncated and the last displayable
character is replaced with the truncation indicator character.
-row_footer_value STR, -rfv STR
the row footer placed after each detail line. Refer to the descrip-
tion of "-page_footer_value" for the content of a header/footer.
The default value for STR is "" which means there is no row footer
provided by default.
-row_header_value STR, -rhv STR
the row header placed before each detail line. Refer to the
description of "-page_footer_value" for the content of a
header/footer. The default value for STR is "" which means there is
no row header provided by default.
-subtotal SUBTOTAL_SPEC, -stt SUBTOTAL_SPEC
the value of subtotal is used to determine what columns subtotals
should be generated for, when they should be generated, and what
ATTACHMENT B
REQUEST DESCRIPTIONS
SUBTOTAL_SPEC is "" which means no subtotals should be generated for
any columns. SUBTOTAL_SPEC can consists of one or more blank
separated "triplets". The syntax of a triplet is
"column_1,column_2{,reset | running}". "column_1" is the name or
number of the column that a subtotal will be generated for.
"column_2" is the name or number of a column whose value should be
watched to determine when to generate the subtotal. When the value
of this column being watched 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 will be watched
for subtotal generation. "reset" or "running" indicate the type of
subtotal desired. If neither is given then "reset" is the default.
"reset" means the subtotal counter will be reset to zero each time a
subtotal is generated. "running" means the subtotal will not be
reset to zero.
-total COLUMN_LIST, -tt COLUMN_LIST
the value of total is used to determine the columns totals should be
generated for. The default value for COLUMN_LIST is "" which means
no columns should have totals generated. COLUMN_LIST can be set to
a list of column names or numbers. If any column named is a member
of the "group" of rows defined via the "group" option, then it and
the columns more major in this group will have totals generated for
them. Totals are generated after the last detail line. If
subtotals have been requested but totals have not, a total is
generated automatically for each column that has a subtotal.
Format Option Arguments (Specific Column Options):
"column_id" in the following descriptions means the column name as
defined in the open model/submodel, the number of the column in the
LILA selection_expression, or a star name which is used to match column
names.
-alignment column_id STR, -al column_id STR
the value of alignment is used to determine the alignment of a col-
umn value within its display width. "column_id" specifies which
column the alignment applies to. "STR" is the alignment mode and
can be set to "center", "left", "right", or "decimal N". The
default value for STR depends upon the type of column selected via
LILA. Character and bit strings default to left alignment, decimal
data defaults to decimal point alignment, and all other data types
default to right alignment. For decimal alignment, the decimal
alignment position within the display width is given a default val-
ue. This alignment position can be changed by the user by
specifying the value as "decimal N", where N is the character posi-
tion within the display width where the decimal point should be
aligned.
ATTACHMENT B
REQUEST DESCRIPTIONS
the value of editing is used to specify additional editing that
should be done to the column value before it is placed on the page.
"column_id" specifies which column the editing applies to. The
default value for STR is "" which means additional editing should
not be done. Multics active functions and LINUS active requests are
normally used to provide the additional editing. For example, to
place commas and dollar signs in a column called "salary", the
string "[pic $99,999v.99 [column_value salary]]" could be specified
as the editing value. Refer to the description of the
"column_value" request for its usage.
-folding column_id STR, -fdg column_id STR
the value of folding is used to determine what type of action should
occur when a column value exceeds its display width. "column_id"
specifies which column the folding applies to. The default value
for STR is "fill" which means portions of the value which exceed the
display width are moved down to the next line(s) until a correct fit
is obtained. STR can also be set to "truncate" which means the
column's value is truncated to fit in the display width and the
truncation character(s) is placed at the end of the value to indi-
cate truncation has occurred.
-separator column_id STR, -sep column_id STR
the value of separator is used to separate a column from the next
one following it. The last column on a line does not have a separa-
tor. "column_id" specifies which column the separator applies to.
The default value for STR is two blanks. STR can be changed to any
sequence of printable characters.
-title column_id STR, -ttl column_id STR
the value of title is placed above the column at the start of each
page if the option "title_line" is set to "on". "column_id"
specifies which column the title applies to. The default value of
STR is the name of the column taken from the open model or submodel.
STR can be set to any sequence of printable characters. The title
is left justified in the display width for its associated column.
If the value of title is wider than the columns display width it is
filled to obtain a correct fit.
-width column_id N, -wi column_id N
the value of width is used to determine the display width for a col-
umn. "column_id" specifies which column the width applies to. The
default value for N is the width for the column derived from the
open model or submodel. The derived width will be the number of
characters needed to contain the value after conversion from the
data type found in the data base to character format. N can be set
to any positive integer.
Control arguments:
ATTACHMENT B
REQUEST DESCRIPTIONS
print/don't print the prompt string for values when the "-prompt"
control argument is given. The default is -long, which means prompt
with the string "Enter FORMAT_OPTION_NAME". If -brief and -long are
both used on the request line, the last one supplied will be used.
-default
specifies that LINUS should set the value of the format option which
immediately precedes this control argument to the system supplied
default.
-string STR, -str STR
allows STR to be entered as a format option value when STR begins
with a hyphen.
-prompt
specifies that LINUS should prompt for the value of the format
option which immediately precedes this control argument. A prompt
string will be written before the prompting action unless the -brief
control argument is used. A line consisiting of the single charac-
ter "." will terminate the prompted input mode.
-reset, -rs, -no_reset, -nrs
reset/don't reset all formatting options to their system default
values. The default is -no_reset which means only the user
specified options will have their values changed. If -reset is giv-
en, all format options will be reset to their 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 used on the
request line, the last one supplied will be used.
Notes:
At least one format option argument or "-reset" must be specified.
Format option arguments and control arguments can be mixed freely in
the request line, but a control argument cannot be placed in between a
format option name and a format option value. For example, "sfo
-page_width 80 -reset" is a valid request. "sfo -page_width -reset 80"
is not valid. If a value is to be set that begins with a hyphen, the
control argument "-string" must be given before the value to distin-
guish it from control arguments and format option arguments.
Examples:
set_format_options -width 1 25
set_format_options -title emp_name "Employee Name"
set_format_options -reset -page_width 80 -page_length 60
set_format_options -page_footer_value "!!-[page_number]-!!"
set_format_options -page_header_value -prompt
Enter page_header_value.
ATTACHMENT B
REQUEST DESCRIPTIONS
!!!!
!!--Page [page_number]--!!
.
sfo -exclude exchange extension -width area_code 12
sfo -editing area_code "[fl ^a/^a-^a [clv area_code]