MDBS RDL Manual Dec1985 pdf

MDBS REPORT DEFINITION REFERENCE MANUAL

The MDBS RDL MANUAL

Version 3.08

Micro Data Base _{Systems, Inc.} P. _O. Box 248

Lafayette, Indiana 47902 USA

Telex: 209147 _ISE UR

(312) 303-6300 _{(in Illinois)}

December 1985

Copyright Notice

This entire manual _{is provided for the use of the} customer and _the customer ' s

employees . The entire contents have been copyrighted by Micro Data Base Systems,

Inc. , and reproduction by any means is prohibited except as permitted in a written

agreement _{with Micro} Data Base Systems, _Inc.

(C) COPYRIGHT 1983 _Micro Data Base Systems, _Inc. Rev. 85A

NEW RELEASES, VERSIONS, AND A WARNING

Any programming endeavor _of the magnitude _of the MDBS _software

will

necessarily continue to evolve over time. Realizing

this,

Micro Data Base _{Systems, Inc.,} vows to provide

its

users with updates to

this

version for a nominal handling fee.

New _{versions of} MDBS _software

will

be _{considered as separate products.}

However, bona _{fide owners of previous versions are generally}

entitled

to a preferential rate structure.

Finally,

each _{copy of our software is personalized to}

identify

_the

licensee. There _{are several levels of this personalization,} some of

which involve encryption methods _{guaranteed to} be

combinatorially

difficult

to decipher. Our _products have been _{produced with} a _very

substantial

investment of

capital

and _{labor, to say nothing of the}

years of

prior

involvement in the data base management _area by our

principals.

Accordingly, we _are

seriously

concerned about _any

unauthorized copying of our products and

will

take any and

all

available legal action against

illegal

copying _or

distribution

_{of our}

products.

Table

of Contents

I. OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . . .

l

A. _{Organization . . . . . . . . . . . . . . . . . . . . . . .}

l

B. _{Introduction to} ROL.

. . .

I

II. DEFINITIONS . . . 5

A. _Designers and End _Users. . . . 5

B. Reports and Pages. _{. . . . . . . . . . . . . . . . . . . .} 5

C . Report Details . . . 5

D . Prompt Variables . . . 6

E . Computed Variables and Functions . . . _{. . .} 6

F _{. Grouping: Headers and Footers} . . . _{. . . . . .} 7

G. _{sort ing} . . . _{. .} . _{. . .} . _{. .} . _{. . . . .} . . _{. . . . . .} 8

H . Relationships. . . 8

III. MDBS.RDL SPECIFICATIONS _. . . . _{. . . . . . . .} 9

A . Notational Conventions . . . 9

B. RDL _Sections . . . .lO

Identification

Section. . . .12

Prompt _{Section. . . . . . . . . . . . . . . . . . . .} .14

Output _{Control Section.} . _{. . . . . . . . . . . . . .} .17

Function Def

inition

_{Section . . . . . . . . . . . . .} .20

Computed _{Variable Section . . . . . . . .} . _{. . . . .} .26

Report Detail Section . . . _{. . . . . . .} .28

Group _{Section . . . . .} . _. . _{. . .} . _{. . . . . . . .} .34

IV. USING THE MDBS.RDL SOFTWARE . . . . . . . . . . . . .43

A . Overview . . _{. . . . . . . . .} . _{. . . . . . . . . . . .} .43

b. The RDL _Analyzer . . . .43

C . Compiling the Generated Program(s) . . . _{. .} .45

D . Executing the Compiled Program(s) . . . _{. . . .} . _. .46

V. RDL ANALYZER DIAGNOSTICS. _{. .} . . . . _{. .} . . _{. . . . . .} .47

VI. RDL EXAMPLES _{. .} . _. . _{. . . .} . _{. . . .} . _. . _. . _. . _{. .} .53

Example

l.

_{. . . . . . . . . . . . . . . .} . _{. . .} . _{. .} .56

Example 2. _{. . . . . . . . . . . . . .} . _{. . . . . .} . _. .61

Example 3 . . . _{. .} . _{. . .} .70

Example 4 . . . _{. . . . .} . _{. .}8O Example 5. _{. . . . . . . . .} . _. . . . _. . _. . _{. .} . _{. .} . 91

FIGURES Figure

I-l.

The Role _of ROL. . . . . _{. .} . _. . _{. . . . . . . .} 4

Figure

III-I.

Notation . . . _{. . .} .10

Figure

VI-l.

Sample Schema . . . _{. . . . . . . .} .53

Figure VI-2. Sample DDL _{Specification.} . . . _{. . .} .54

APPENDICES

Append _ix A. RDL _Keywords

. . . _{. . .} . . A-l

Append _ix B. The RDL _Syntax

. . . B-l

INDEX _{. . . . . . . . . . . . . . . . .} . _{. . . . . . . . . .} Index-l

MDBS

rdl

MANUAL - " MDBS RDL MANUAL

[. OVERVIEW

A. Organization

%-The MDBS RDL _{Manual describes the optional} RDL module _{of the} MDBS

III

data base management _system.*

It

is

assumed _{that the} reader _is

familiar

with the postrelational, extended-network schemas supported

by MDBS. _{Knowledge of the other} MDBS _{languages for} data base

processing (e.g., DML, QRS, _{IDML) is not required in order to use the}

Report

Definition

Language. However,

familiarity

with QRS

will

facilitate

the process of learning to use RDL, _since ROL _is designed

to be _{consistent with} QRS.

Chapter _{I of}

this

manual concludes _{with an introduction to the}

role of RDL _{in application} development. The RDL _constructs and

features available for designing a _{report are} explained in Chapter

II.

Details of the

rdl

_{syntax are formally presented in} Chapter

III.

Chapter IV _explains how _{to use the} RDL _{Analyzer and the}

final

_chapter

discusses diagnostics that can arise during RDL analysis. B. _{Introduction to} ROL

The Report _Definition Language (RDL) _{is another aid that helps}

magnify the _{productivity of application} system _developers who use

MDBS. A _{developer uses the}

rdl

to formally specify the characteristics of a desired report and the prompting behavior of a

program that generates that report. An RDL _{specification is input to}

the RDL _{Añdlyzer which checks the specification for consistency} and

syntactic correctness.

If

no _errors are detected, the RDL _Analyzer

automatically generates a complete program which behaves in accordance

with the RDL _{specifications. The resultant program contains the} DML

commands needed _to generate the _{desired report.} These are embedded

within the control structures of a C _{host language.}

The _{role of} RDL _{in application system development and usage}

is

illustrated

in Figure

I-l.

RDL _{enables a report designer who knows}

nothing about DML _and C

to produce _{application programs written in} C

and _containing

all

_necessary DML _{logic for extracting and displaying}

desired data from _an MDBS _{data base. a report designer does need to}

know the schema _{of the} data base being used. The generated _program handles

all

_{report formatting as specified with} the RDL _{and can route}

the report to a

printer

(using preprinted forms,

if

_desired), a

console, or a disk

file.

The generated _program

will

also prompt an end _{user for various information as indicated in the} RDL

specification. An end _{user's responses serve to}

initialize

_variables

in the generated program at execution time, thereby allowing the end user to place conditions on the

retrieval

of data for the report and

to control the _appearance of the _report.

* MDBS

III

Version 3.06 _{(or greater).}

MDBS ROL MANUAL

- I.

OVERVIEW

-

MDBS RDL MANUAL

An RDL _{specification can have up to seven}

distinct

sections

for

specifying the behavior of the program that

is

to be _generated:

Identificat:

ion _section

Prompt _section

-Output _{control section}

Function

definition

section

Computed _{variable section} Report

detail

_section Group _section

The _sections must appear in

this

sequence.

All

specifications within

a section _are made _{in a free-form manner. Tite major characteristics}

of each _{section are} summarized _here.

The

identification

_{section is} used _{to declare the} name of the

file

or

files

that

will

hold the generated program.

It

is

also used

to indicate the name of the data base which _{the generated program}

will

utilize,

a _user id for that data base, and _{that user's} password.

A _{prompt variable}

is

_{used to gather information from an end}

user.

For each prompt _{variable declared in the}

rdl

prompt _{section, the} generated _{application program}

will

prompt _{the end user to enter} some

data which

will

be used by the _{program to} determine the _ultimate appearance and _{content of} the _report being produced. For _instance,

the data base _{name, user id,} and password _might be _treated as prompt "

variables. When _{specifying a prompt variable, the report designer}

gives

its

name, type, size, and the prompt message that

is

to be

presented on the console _to an end _user. The designer can also

specify a default value for each prompt _variable. Thus, prompt

variables serve as parameters to the generated _{application program.} The _{output control section is} used _{to speci£y output page depth,}

left

and _{top margins. pauses in output display,} and _{the áevice to} which _{the output report is to} be _routed. These _can be _either

explicitly

declared or they can be _{handled as prompt variables,}

enabling the end user of the generated program to determine these

output

traits.

a _report designer can optionally specify one _or more functions

that are to be used _within the generated _program. These _{are declared}

in the RDL _function

definition

section. A _{function can} have _multiple

input parameters. Within the

definition

_of a function local variables

can be declared. These, together with global variables (e.g., prompt

variables) and data _{items, can be used within} assignment _statements,

if-then-else control structures, and _{test-case control structures}

inside the body _{of the function.} Each _{function is specified so that}

it

returns a single value.

MDBS RDL MANUAL

- I.

OVERVIEW " MDBS ROL MANUAL

Developer-defined functions, together with

built-in statistical

functions (e.g. SUM, AVERAGE), _{can be used to declare computed}

variables. This is accomplished _in the computed _{variable section.} Each computed _{variable is given} a _{name, type} and size. _{In addition,} a

formula is specified, indicating how _{the item's value is to be}

determined. Tlíe _{formula consists of} a function and

its

arguments.

For

built-in

_functions, an optional conditional clause can be

specified. For example, FOR (YTDEARN<1OOOO) SUM (YTDEARN) _{is a}

formula that says the computed _{variable's value}

will

be _the sum of

all

values of the YTDEARN _{data item (in the data base)} which _{are less than} 10000.

The _report

detail

_{section defines the content of the report. In}

this

section the developer indicates which data items _(from the data

dictionary or screen

dictionary),

computed _variables, prompt

variables, and _{expressions involving any of the former three are to} have

their

_{value(s) appear in the report.} The _{physical position of} each _of these _in the _{output report is specified. This section also} has _{an optional} FOR _{clause and a required} THRU _clause

like

those _that appear in a QRS _{statement. Furthermore, an optional} SORT _{clause can}

be _{specified to cause} the _{report details to} be _sorted on various

criteria.

The _{group section allows} a developer to specify _page breaks and

various kinds of groupings of report

details.

Page breaks are stated

in terms _{of data items.} Whenever a data item's value changes, the

next report

detail

is forced to the _{next report page.} Grouping _means

that

all

report details having some specified characteristics in

common _{appear as} a _group in the _{output report.} Headers and footers

automatically accompany each _group,

if

_{desired. Also, automatic}

sorting of groups can be requested.

MDBS RDL MANUAL

- I.

OVERVIEW

-

MDBS RDL MANUAL

(^B:!',","o'::?

)

creates V

RDL

Specificatiorl

y input to

RDL

Analyzer utilizes

'm

autommically Data Base _extracts

generates Control System ¶

Y m Cc"nsults

DML

. . Commands

Apphcation

Program(8)

r responds

to ge nerates _{Y V}

prompts

l /

(

End User )m _presented to Report ) Integral t Postrelational

) )

L_~~

DictionaryData (\ Daca Base

\ \

i

Figure

I-l.

Tlíe Role _of

rdl

MDBS RDL MANUAL MDBS RDL MANUAL

II. DEFINITIONS

A. _Designers and End Users

A _{report desiqner creates an} ROL _{specification} which _{defines the}

-appearance and content of a _report. The RDL _Analyzer

is

a _program

that accepts an RDL _{specification as input} and _generates a _program (or

two programs, in some cases). After a generated _program has been

compiled,

it

can be executed by an

4

ASQtn After prompting the end

user

for

various information, the executing program produces a _report

for the end _{user. In the} event _that two programs were generated by

the RDL _{Analyzer, the}

first

program

will

produce an intermediate

file

which _{is then}

utilized

by _the second _{program to} produce _the

final

report.

Since _the RDL _{Analyzer produces} C

source code programs, a

designer with C _programming

expertise can modify generated programs

if

desired.

B. _Reports and Pages

A _{repoj"t consists of one or more pages.} A Rá9Q _{consists of one}

or more horizontal lines of output. The _{report designer controls the} maximum number _{of lines per report page.} The

left

margin and _top margin _for a report's _{pages are} also determined by the _designer. The area to the

left

of the

left

margin _{on each page is blank. Similarly,}

nothing appears above a page's top margin. On each _page, the

first

line

beneath the _top margin

will

(by _{default) contain} the date and the page number.

If

_{desired, the report designer can suppress}

this

automatic display of date _{and page number.} A _{report can be routed to} a

printer,

console _{screen, and/or disk}

file.

C. _{Report Details}

A _report

typically

_{contains many report aetai1s.}

All

_report

details

within a _report have the same _{structural appearance, but they}

differ

in terms _{of content.} Each _report

detail

_{consists of one or} more lines containing

literals

and/or data _{values. Tfjtera1s} are

titles,

labels, and _{other strings of characters that} do _not change from _{one report}

detail

_{to another.} Data _values can

differ

for

different

report details. Data _{values can be obtained} from a data

base _{and can be obtained} from computations performed by _the generated program. The _positions (both _horizontal and

vertical)

_of

literals

and

data values within a _report

detail

_{are controlled} by _{the report}

designer.

MDBS RDL MANUAL

-

II.

DEFINITIONS

-

MDBS RDL MANUAL

D. Prompt _Variables

The _{designer can declare variables} whose _{values are to} be determined _{by an end user} when _the generated _{program begins executing.}

These _{are called} prmnpt \/a.riah1es. because _{the program} prompts _the end

-user to acquire each _{variable's value.} For each prompt _{variable, the}

designer specifies what the prompt _message

will

be. A _default

response can also be _{declared for} each prompt _variable. E. Computed _Variables and _Functions

Tlie _{simplest kind of report}

detail

_{displays data values that the} generated _{program obtained} from prompt _{variables or} has _{retrieved from}

the data base. Beyond

this,

the _{designer can define} computea ¶/ariah1e5 whose _{values are automatically calculated} (and _displayed) by

the generated program for each report

detail.

a computed _variable

is

defined in terms _of a f11nction and _function arguments. _This can be a

built-in

function _or a special function created by the _report

designer.

The seven

built-in

functions compute _various

statistics:

COUNT,

SUM, _MIN, MAX, AVERAGE, STDDEV, _and PERCENT. When _a

statistical

function

is

used _{to define} a computed variable,

it

_can have _{one or} two arguments. These arguments are data items.

Iii two arguments are used, _{then the} second argument

restricts

_the scope of the

statistic's

computation. F'or instance, AVERAGE

(MOSAL,DNUM) _{is the average of monthly salaries for consecutive report}

details with the same department number. _Normally,

this

_function would be _{included in the footer defined}

for

department _{groups (footers} are described in the next section). When a _report is generated, each

group of

details

for a department number would be followed by a _footer

showing _{the average monthly salary for} the _department's employees.

If

this

function is included instead in the

definition

for report

details,

then a _{department's average}

will

_appear in each of the

details

generated _{for that} department group.

If

only one argument _is used, the _{scope of values} used _in computing _the

statistic

depend _{on whether} the _{computation occurs in} a

report

detail,

a _group footer, a _page footer _or a _report footer. _Iri a

report

detail,

the

statistic

_is computed _with

all

_{values* of the data}

item argument _that have been _{retrieved. In} a _group (page _or report)

footer, the _computation uses only those _{values* retrieved}

for

_that group (page or report). For _{instance, the value of} AVERAGE (MOSAL) _in a _report

detail

is the _average of

all

monthly salaries for employees

that appear in the report. In a _page footer,

it

is the _average of

all

salaries on the page, and so

forth.

*

If

_{no values} have been _retrieved, each

statistic

_{is set to} O.

MDBS RDL MANUAL

-

II.

DEFINITIONS

-

MDBS ROL MANUAL

A _{designer can optionally specify conditions for}

built-in

functions. To _define a computed variable whose value is the _average

department _{salary for} employees _over 30 _{years of age, the designer}

specifies

-.

FOR _(AGE>30) AVERAGE _{(MOSAL,DNUM).}

The _{report designer can}

alternatively

_define computed _variables

in terms _{of special functions.} A _{special function}

is

_created by _the

designer.

It

is

essentially a _program module that computes a value.

Inputs to the function are specified as arguments when the function

is

invoked. Each argument corresponds _to a parameter used within the

function's body. Local _{working variables} can also be declared within

the function's body. _{In addition to} assignment _statements,

if-then-else and _{test-case statements can} be _{used within} a function. A _return

statement is used _to

exit

from a function with the function's value.

F. _Grouping: Headers and _Footers

The _{designer can request that report details} be grouped _in

various ways. a major aspect _{of grouping}

is

_that a header and a

footer can be specified to automatically accompany each group of

report de'tails. A _{header or footer can be designed to consist of one}

or more lines containing

literals

and/or data values. The data values can jje _{values of data items,} prompt _variables, or computed variables.

Thé header _for a _{group appears} immediately before the group's

report

details.

Normally, the header _is designed _{to contain}

descriptive information introducing a _group of

details.

A _{footer for} a _{group appears}

just

_after the group's details.

It

is usually

designed _{to contain information} summarizing a _group of details.

The _{simplest kind of grouping is to group} by _{report. This} causes

all

of a report's _{details to} be _{treated as} a _group. The header and

footer specified for

this

kind of grouping appear at the

start

and

finish

of the report, respectively. Report _details can also be grouped by _page. Since each _{group consists of} a _page of _report

details,

the header and _{footer specified for page grouping} serve as page headers and footers, appearing _{at the}

start

and

finish

_of each page.

Another _{kind of grouping allows report details to} be _separated

into groups based on the values of a specified data item (or computed

variable). As _the generated program _creates each new _report

detail,

a

check _is made _{to see whether the specified data item (or computed}

variable) value has changed _since the

last

_report

detail.

If

it

has changed, then the newly _{created report detail} begins a new _group of

report

details.

As _{with report grouping} and _{page grouping,} each

resulting group can be _{prefaced by a header and followed by a footer.}

The _{designer can specify multiple levels of grouping.} The

grouping of one level occurs within each group produced by the next

higher

(i.e.,

broader) level of grouping. For instance, suppose that

report details consist of employee _information and _{that three levels}

of grouping have been _declared by _{the designer. At the highest level}

MDBS ROL MANUAL

-

II.

DEFINITIONS

-

MDBS RDL MANUAL

there is grouping by company, then grouping by

division,

and

finally

grouping by _department. The _{generated program} produces _{an output}

report having employees grouped by company. within each company group, the employee _{details are} grouped by the

division

_in which _they work. _within each

division,

employees _are grouped by _department.

-G. _Sorting

a _designer can specify two _{types of sortinq: sorting of report}

details

and _{sorting of groups.}

If

a designer has requested sorting of

report

details,

then _the generated program

will

_{output report}

details

in sorted order.

If

grouping (other than by _report or by page) has been _{requested for} the _report, then _{the sorting of report}

details

occurs within each of the lowest level groups. When _specifying a

grouping (other than by _report or by page) _{the designer} can request a

sorting of the resultant groups.

In general sorting can be _{based on the values of one or more data}

items and/or computed _variables. Any _{mixture of} ascending and descending _directions can be _{specified. For instance, the sorting of}

employee _{details (within} each _division) might be based on ascending

job codes and descending monthly _salary. Thé _{sorting of} department groups (within a division) might be based on ascending department code. _within each _{company, division groups could} be _ordered by ascending _{division names.}

Finally,

_{company groups} might be _arranged

in terms _of descending

(i.e.,

_{highest to lowest)} annual _sales.

H. _{Relationships}

just

as important as the data items used in generating a _report,

are the re1&ti,onsh.ips among those data items. Because _{of the inherent}

flexibility

of MDBS'S _{postrelational approach to data structuring,} a

schema _{allows many relationships to exist} among a _group of selected

data items. Set names are used to indicate the semantics _{of various}

relationships. The _{report designer can} choose which _{relationships} are

to jje used by the generated program in producing

its

report.

MDBS RDL MANUAL MDBS ROL MANUAL

III. MDBS.RDLSPECIFICATIONS

A. _Notational Conventions

After the content and _{layout for} a report has been determined,

-the report can be formally specified with the Report

Definition

Language. An RDL _{source specification consists of several sections.}

Each _{section consists of various kinds of clauses;} some of which _are

optional and some of which _are required. These clauses are presented

on a section-by-section basis. Discussion of those clauses that _can

be regarded _{as advanced features are} denoted _{in the}

left

margin by a

vertical

bar. The complete _{syntactic description of}

all

_clauses appears in Appendix B. _Figure

III-I

shows _the meanings _{of the}

notations used.

A _{clause is composed of one or more of the following terIn$:}

keywords,

identifiers,

file

_{names, strings, integers, real} numbers,

formats, user names, passwords. _procedures.

KeYwc)r(ls are denoted _{by upper case}

letters.

All

_other terms in a

clause are in lower case. This upper case _vs. lower case

distinction

is

for documentation _{purposes only.} Upper and lower case can be mixed

in an actual ROL _{source specification.} A _complete

list

_of

rol

keywords _{appears in} Appendix A.

Identi-fiers used _{in describing an} RDL _{section are denoted by}

id-l,

id-2, id-3, etc. Ident:

ifiers

are selected by the report

designer. An

identifier

_{consists of} from _{one to eight} alphanumeric

characters. An RDL _{keyword can} be _{used as an}

identifier

if it

is immediately preceded by the ITEM _keyword.

If

the ITEM _keyword

is

_not

inserted

prior

to an

identifier,

then _that

identifier

should _not be an

RDL _keyword.

EíÁe _{nmnes used in describing an} RDL _{section are denoted by}

file-l,

file-2,

file-3,

etc. File names are chosen by _{the report designer;}

they must be

fully qualified

file

_{names within the host operating} system.

Inteqers used _{in describing an} RDL _{section are} denoted by

int-l,

int-2, int-3,

etc.

RmL numhers used _{in describing an} RDL _{section are denoted by}

real-l,

real-2, real-3, etc.

Forma.ts _are used _{to control the output appearances of} numeric

expressions. Denoted by _fmt, a format is enclosed _in a matching pair

of quotes. Formats are specified in the C _languages

printf

_style.

The manual _that accompanies _the C

compiler should have _{descriptions of}

permissible

printf

formats.

strinq$ of characters are denoted by

string-l,

string-2, etc. Each _{string within an} RDL _{section has a unique number as}

its

suffix.

The _{actual string values are} chosen by _{the report designer.} A _string

value must

fit

_within a pair of matching double quotes _{on one}

line

_of

the RDL _{source specification.}

MDBS RDL MANUAL

-

III.

MDBS.RDL SPECIFICATIONS

-

MDBS RDL MANUAL

IZ=K _namm denoted by _{usr, are one to sixteen character}

(alphanumeric) names.

pass\Ñ/oralqt denoted by _{pass, are one to twelve character}

(alphanumeric) strings.

-proceallres used _{in describing an} RDL _{section are denoted by}

procedure-l, procedure-3, etc. A _procedure

is

a _{program consisting of}

statements of various kinds: assignment,

if-then-else,

_test-case,

break, and _return.

An _{underlined expression must appear.}

:

Zero _or one of the alternatives

within

the _brackets must be used.

i

j

Exactly one of the alternatives within

the braces must appear. *

! )

One _{or more of the alternatives within}

the braces must appear.

Figure

III-I.

Notation

B. RDL _Sections

An RDL _{source specification consists of up to seven kinds of}

sections. These _sections must _{appear in the order given} below. Clauses _within a section _{are stated in} a free format

(i.e.,

column

positioning

is

unimportant for the RDL _{Analyzer). Upper case} and

lower case can be used interchangeably. More than one clause can appear on a

line;

a clause (but not a term) _{can be}

split

_{over more}

than one

line;

unless otherwise indicated, optional clauses within a

section can appear in any order. Clauses are separated by blanks. Comments _can appear between _any two terms _{of clauses within} an RDL

source specification.

The _{kinds of} ROL _{sections and}

their

_{ordering are as follows:}

dentification

Section

Prompt _{Section (optional)}

Output _{Control Section (optional)}

Function

Definition

Section (optional)

Computed _{Variable Section (optional)} Report _{Détail Section}

group Section (optional)

MDBS RDL MANUAL

-

III.

MDBS.RDL SPECIFICATIONS

-

MDBS RDL MANUAL

CQmInents _{in an} RDL _{source specification}

TM characters

/*

located anywhere _{in the} RDL _source

specification indicates that

all text

that follows

is

a comment,

until

the comment _{is terminated} by the _characters

*/

-Comments _{can extend over many}

lines.

Examples:

/*

THIS IS A COMMENT

*/

I*****

*

* RDL SOURCE SPECIFICATION

*

*****/

l*

_{FUNCTION DEFINITIONS}

*/

(C) COPYRIGHT _{1983 Micro Data Base Systems, Inc.}

mdbs

rdl

manual

-iii.

mdbs.rdl SPECIFICATIONS _- MDBS RDL _manual

identificationsect/on

The

identification

_section must be _{present. This section is} used

to

identify

which MDBS _{data base}

will

be accessed by _{the generated}

program. This

will

be _{referred to as the}

target

_{data base. Ie}

addition, the report designer uses

this

section to specify

" _a

user name and _{password, to confirm}

that

_{the designer} does have _{access to} Éhe _{data base,}

" _the

names of

files

that are to hold the generated _program.

The

identification

_{section's clauses should} be _{stated in the}

order shown below.

a) Data base _clause ñ?T4V¶F FILE name _is

"fiP-l"

The _indicated

file-l

must be _{the physical}

file

that

_holds the main _{area of the target data} base. The _{data dictionary in}

this

main _{area is} used by _the RDL _{Analyzer during program}

generation.

File-l

is a

fully

qualified

file

_name

for

the

host operating system.

Examples: DATABASE _FILE NAME _{IS "B: DEB"}

database name _"INVEN/DB:

I"

DATABASE _{"/usr/db/customer.db"}

b) User clause (optional) 9SEE _is

"irir

"} with Fpí¶¶"}

The _{indicated usr} must be a bona

fide

_user

for

the

target

data base and _pass must be

that

_{user's password.}

If

this

clause is omitted, the designer must _{specify the user} and password _{on the operating} system command

line

when _the RDL

Analyzer is invoked. Such _{an omission is desirable in}

security-sensitive

circumstances, because

it

means

that

a

valid

name and password

will

not appear in the RDL

specification.

If

use or pass contains a blank, then quotes

must be used.

If

_{quotes are not} used

for

_{usr or} pass then

all

its

alphabetic characters are converted to upper case. Examples: USER _{IS "Alvin} Wade" WITH SECRET

USER _GCl5 "DJL"

USER KnowledgeMaster WITH MDBS USER _deb WITH _{"nton reve"}

.

MDBS RDL MANUAL

-

III.

MDBS.RDL SPECIFICATIONS

-

MDBS ROL MANUAL

C) _{Program clause (optional)} PROGRAM _{FILE IS}

"f

ir~"

The RDL _Analyzer

will

_{generate one or two} C

source code programs, plus two comnand

f lies.

One command

file will

compile the _source program(s) _. The _other

will

execute the compiled program(s) _.

Thé _indicated

file-2

name _can be _{up to seven} characters long

and _{can be qualified} by a drive/directory.

It

will

be appended

with

l

(and 2) _{to yield the name(s) of the}

file(s)

_{holding the}

generated _source program(s) _. A _{.C extension is} used _for source code

f lies.

The command

f lle

for compilation uses the

f ile-2

name with a C _{prefix. The command}

file

that executes has the

name indicated by

file-2.

If

the _program clause _{is omitted,}

file-2

_is assumed _to be RPG.

Examples : PRCGRAM FILE IS "INV" PROGRAM _{"B: SALES"}

mdbs

rol

manual

-iii.

mdbs.rdl specifications

-

mdbs

rol

manual

prompt section

The prompt _{section is optional.}

It

_is used _{to define} the prompts which the generated _program

will

_{present to an end user.} Ea_{ch pr ompt}

--is defined in terms _of

8

a _{prompt variable which}

will

hold the end _{user's response,}

. the type and size of the prompt variable,

. a prompt message which

will

be presented to the end _user, . a default value for the prompt variable

a) Prompt clause PPMPT VARIABLES ARE

This clause _{is required}

if

_{you intend to define prompts.}

It

is

followed by one _or more prompt

definition

clauses.

Examples: PROMPT _VARIABLES ARE

prompt

b)_

f~:_{ompt defi ^nition clayZ\e}

[iNsTcNFn

real

tntfc'fp

=

<

btnapy _{> iN-1}

Mppc¶fp

"

"stri,nq-?") )

=<

i

>

["strinq-1"]

default

,i,nt-4

J

sTPTbG _{ml -1}

x

=

I

{=MAT}

inr.-'[,int-3]

íllme

m

rue

_J

A _{prompt def}

inition

_{begins wth}

id-l,

_{which is the name of}

the _{pr ompt variable} being _defined.

It

cannot be a data

item. This _{variable is declared to} be _{one of nine types:}

unsigned, _{real, integer, binary, character, string, internal} decimal _{(idec) , time, or date. with} the _{exception of time} and date _variables, a size _{can be} specified. _For a time

prompt _variable, the _{end user}

will

be _{prompted to enter nine}

characters of the form hhh: mm:ss _{to indicate} hours (hhh) _, minutes (min) _{and seconds (ss)}

. For a date type, the end

user is prompted _for ten _{characters of} the form mm/dd/yyyy

to indicate a month (nun), day (dá) and year (yyyy) _. An

internal decimal _{size consists of} two integers. The

first,

int-2 , indicates the number of

digits

accepted for an idec

prompt _variable. The number _of

diqits

_to the _{right of} the decimal _{point is optionally specified} by

int-3.

If

_{int-3 is}

omitted, then O

is assumed. For

all

other types,

int-l

indicates the number _of bytes used _{to hold the pr ompt}

variable's value. E'or a

l

_or 2 byte integer, a _user

will

be

MDBS RDL MANUAL

-

III.

MDBS.RDL SPECIFICATIONS - MDBS RDL MANUAL

allowed to enter up to 7

digits

(including the sign). Up _to

12 can be _entered

for

_{larger integers.} Up _to 25

digits

(including the _sign and _{decimal point) can} be entered _for a

real variable. Minimum and maximum _{sizes were} discussed _in

the _{preceding chapter.}

-If

the optional

string-l

is specified,

it

serves as a prompt message which is output by _{the generated program.} The end

user sees

this

message on the console screen

just prior

to the place where the _variable's value _{is to} be _entered.

As another option, a

default

value _can be declared

for

a

prompt

variable.

This value is an integer

for

unsigned or

integer types, a real number

for

idec or real types, and a

string for

any of the other type.

If

a

default

value has

been _declared

for

a _prompt

variable,

then that value is

displayed in square brackets next _to the prompt _message

(if

any). An _{end user} who _{desires the default value, needs only}

to press the Return _(Enter) key when prompted _for a value.

UFILE, UNAME _and UWORD _{are three special prompt variables.}

If

these _{are defined in the} prompt section, they must appear

in the above _sequence and must _{precede the}

definitions

_of any other prompt

variables.

Types and _{sizes are not}

specified for these special prompt variables. The _values

that an end user supplies for these prompts are immediately used by _{the generated program to attempt to open the data} base.

If

the _{end user} has responded _{with valid values,} then

the data base _is opened _{with the read/write access} codes

assigned to the indicated _user name. The rest of the prompts are then presented.

Iii

an end _user has responded

with invalid values, then _{execution of} the generated _program

is aborted.

Omission of these three special prompt variables from the

rdl specification

means that the

file,

_user name, and password _specified by the _{designer (for} RDL _{analysis) appear}

in the source code _{of the generated program.} As a

result,

the generated _{program opens} the data base _with the

designer-specified

file,

_user name, and password. The end _user

therefore has _the

read/write

_access

privileges

_associated

with the _{designer-specified user name.}

UDATE, UPAGE _{and UTIME are also special prompt variables.}

Types and _{sizes are not}

specified

when _{these prompt}

variables are declared. The value that an end user supplies

for UDATE _{is used as the date that automatically appears at}

the top oÍl each _{report page.}

If

UDATE _{is not declared as a}

prompt _variable, then the generated _{program obtains} the date from the machine _clock. The value _{that an end user supplies}

for UPAGE _{is the page number that automatically appears at}

the top of the

report's

first

_page.

If

UPAGE

is

_not

declared as a prompt

variable,

then

l

is the number of the

report's

first

page. The value that an end _{user supplies}

for

UTIME _is used _{to "time-stamp" the report}

if

UTIME is specified in the PLACE _{clause for a}

detail,

_header

or footer.

MDBS RDL MANUAL

-

III.

MDBS.RDL SPECIFICATIONS - MDBS RDL MANUAL

Examples:

UNAME "USER NAME:

"

BDATE DATE _"BEGINNING DATE: " EDATE DATE "ENDING DATE: "

MAXSAL IDEC _8,2 "MAXIMUM SALARY OF INTEREST _IS " DNAME CHAR ₁₂ "DEPARTMENT NAME?"

CCAP REAL 4 _{"Estimated cost} OF

capital: "

UCOM STR 75

"Enter comments _to be _{included on each report} page:

"

CDATE DATE "TODAY'S DATE " CTIME TIME "CURRENT TIME ="

ODEV CHAR 7 "OUTPUT DEVICE (S _{or P)?"} DEFAULT _"PRINTER"

PSIZ INT

l

"How _{many lines per page?"} DEFAULT 55 UPAGE _{"Starting page?"} DEFAULT 5

UTIME _{"what time is}

it?"

MDBS RDL MANUAL

-

III.

MDBS.RDL SPECIFICATIONS - MDBS RDL MANUAL

OUTPUTCONTROL SECTION

The _output

control section is

used _{to govern the general}

appearance of reports produced by _{the generated program. In}

this

section a report's _{page size,}

left

margin width, and top margin depth _" can be _specified. The _automatic date _{and page numering for} each _page

can be suppressed. There _{are also clauses to indicate} output pauses and _{the device}

(printer,

_{screen, disk}

file)

_{to which output from the}

generated program is to be _sent. The _output

control

_{section and any}

of the _{six clauses in}

this

_{section are optional.} The clauses _in

this

section can be specified in any order.

a) Page _{size clause (optional)} EAGE _SIZE

ím

_LINES

This clause is used _{to specify} the maximum number _{of lines}

that

will

appear on each page of the report.

If

int-l

is

specified,

then that integer is "hard-wired" into the generated _program.

Alternatively,

a previously defined

prompt variable,

id-l,

can be specified. This allows an end

user of the generated program to

alter

the page size as

desired, via a _{response to} the

id-l

prompt.

If

_{the optional} page size clause is omitted, a default of 24 lines _{per page}

is used.

If

the

identification

section's _{screen clause is present,}

then the _{page size clause} has no effect.

Examples: PAGE _{SIZE IS} 20 PAGE 55 _LINES

PAGE PSIZ

b) _Left Margin _{clause (optional)} LEET MARGIN

=ZJ

This clause is used _{to specify the location of the}

left

margin

for

report pages. The number of spaces to the

left

of

this

margin _{is indicated either} by _int-2 (an _integer) or by a

previously

defined _prompt

variable (id-2).

The

placements _{of report details within} a _{page are} made relative

to the

left

margin.

If

the optional

left

margin clause is omitted, a

left

margin of five _spaces is used.

When windows _{or screens are placed on} a _page, the

left

margin _{is ignored.}

Examples: LEFT MARGIN 2 LEFT 8

LEFT LPROMPT

MDBS

rdl

_manual

-

III.

MDBS.RDL SPECIFICATIONS - MDBS RDL MANUAL

c) Top margin clause _(optional) TQ2 MARGIN

í¡n:

"3

Thetopmarginclause

isusedto specifythe location

of the

a—

top margin

for

report pages. The number of blank

lines

above _this margin _{is indicated either} by _int-3 (an _integer)

or by a previously defined _{prompt variable}

(id-3).

The

placementof

lines

withinapage is made

relative

_{to the top}

margin. Omission of

this

optional clause

results

in a top

marain oÍl two blank _lines. Examples: TOP MARGIN O

TOP 4

TOP TPROMPT

d) Device clause _(optional) PPTNTEP

qcFlFFN nF¶/Tc.R

"fjje_j"

=

Reports can be routed to a console _scEeen,

printer,

_or disk

file.

If

PRINTER, SCREEN, _or

file-l

is specified, then _that

choicé is hardwired into

the generated _program. Aiternatively, a previously defined prompt _{variable (id-5)}

having an STR _{type can be specified (the}

variable's

_{size is}

automatically set to be _{IQ). This enables an end-user to} choose _{one or more devices}

for

each _{run of the generated}

program. The end _{user must respond to the prompt by}

entering some combination of the

letters

S, P, F.

If

ptinter

output is desired, a P _{must be entered.} A _response

of S

causes output to be _{routed to the console screen.} For disk

file

output, the end _{user's response} must have _an E. This causes the end _{user to} be _{prompted flor} a

fully

qualified

file

name. IF the device clause is not present,

SCREEN _{is assumed.}

Examples: DEVICE PRINTER DEVICE "El: _REPT.T" DEVICE DEVPRQM

e) pause clause _(optional) EALISE AFTER PAGE

If

this optional

clause is present, output from the generated program

411

pause

after

each _page. The page

depth is controlled by _{the Page depth clause. This pause}

occurs only for screen and

?rinter

Qutput devices. Output

resumes when the ená user presses the Return (Enter) key. Examples: PAUSE

PAUSE

after

PAGE

MDBS RDL MANUAL

-

III.

MDBS.RDL SPECIFICATIONS - MDBS RDL MANUAL

f) Date/page suppression clause _(optional) SUJ212BESS DATE PAGE

The generated _program

will

_{automatically output} a date and

page number on the top

line

of each report page, with the

-exception of the report header _pages

(if

_{any). Either or}

both of these can be suppressed

with

the date/page

suppression clause.

If

neither DATE _nor PAGE _{is specified}

in this clause, both _are suppressed.

If

the

identification

section contains a _{screen clause,} then both date and page

number _{are automatically} suppressed. Examples: SUPPRESS PAGE

SUPPRESS DATE

SUPPRESS DATE PAGE

SUPPRESS

g) Form alignment clause _(optional) ALIGNMENT PAGES

!ízú

This clause causes the generated program to

print

out a

specified number _of empty pages, for purposes of

aligning

preprinted forms (using the _{printer line} feeá _control). The

number _{of pages} can be _stated

explicitly

(int-4)

_{by the}

report designer. Alternatively, the designer _{can indicate}

that the value of the id-6 prompt variable

is

to be _{used to}

control the number _{of alignment pages.} Examples: ALIGNMENT PAGES 3

ALIGNMENT

l

ALIGNMENT ALPGS

MDBS RDL MANUAL

-

III.

MDBS.RDL SPECIFICATIONS - MDBS RDL MANUAL

FUNCTIONDEFINlTIONSECTION

The _function

definition

_{section is optional.}

If

it

_{is present in} an RDL specification,

it

consists of one or more function definitions. Any _{of the functions defined in}

this

_{section can}

later

be _{used when}

defining computed _{variables in the next section.} Each _function

is

defined in terms _{of three clauses: function}

identification,

parameter

typing, and _{function computation.} These _clauses must appear in the

order shown here.

a) _Function

identification

clause

EUNCTIQN _{isizl [L{ig=2,}*L] k¥pQ=L SiZézL}

In

this

clause a function is given a name

(iá-l),

a type and a _size. Because a function has a numeric value, type-l must

be _INT, REAL, IDEC _or UNSIGNED. _{with the exception of IDEC,}

the _{associated size-l is} an integer indicating how may bytes

of storage are used to hold the _{function's value.} For IDEC,

size-l is

an integer

indicating

how may

digits

are in the

function's

value. Optionally, a second integer _can be

specified for the _idec type _{to declare} the number of

digits

to the

right

of the decimal point

(if

this is

omitted, O

is

assumed).

If

desired, a function _can be _{declared to} have _{one or more}

parameters. The _{names (e.g.,}

iá-2)

_{of these}

formal

parameters are separated by commas and enclosed

within

a

pair of parentheses. A _{comma should not} be _used

following

the _last parameter.

Examples: FUNCTION COMPUTAX _(PI) REAL 4

FUNCTION RTRNRATE (XI,X2,X3,X4,X5,I) IDEC 9,7

FUNCTION DATECVRT _INT 4

MDBS RDL MANUAL

-

III.

MDBS.RDL SPECIFICATIONS

-

MDBS RDL MANUAL

b) Parameter _typing clause

/

/

"nNsTgNFn _"

"

> *

REAL

_ LNTEGEB

INT

"

Z:

"

>

'nt·l

Liá=z,r

ceiáeácter

<

<

CHAR

>

>

STElIjjG

wSTE Z

i

ÉÉtÉMAT )

int22[,int-3]

TIME

RATE

X Y. _{7 7}

A _{type and sizemust} be

specifiedfor

_{eachof the parameters}

declared in the function

identification

clause. The _nine

permissible types are unsigned,

real,

integer, binary,

character,

string,

idec, time and _date. No _size

is

specified for time and date parameters. An idec parameter

size can be _{specified in terms of} two _integers:

int-2 is

the

total

number _of

digits

and

int-3 isthe

number _of

digits

to the

right

_of the decimal _point.

If

_{int-3 is omitted,}

its

value

is

assumed _to ije O. _For

all

_{other types,}

int-l

indicates the number _{of bytes} used _{to hold the parameter's}

value. Minimum and maximum _{sizes were discussed in the} preceding _chapter.

Examples: PI IDEC _4,1

I

REAL 4 _Xl,X2,X3,X4 IDEC _7,2 X5 IDEC _10,2

PCODE CHAR 8

c) _Function computation clause L _{prc)cp!l|1re_1}

i

This clause consists of a _{procedure enclosed in} a _matching

pair of braces. The procedure _is composed _{of local variable}

declarations followed by a _sequence of statements. A _local

variable

is

used _only

within

_{the procedure in which}

it

_is

declared. Local

variables for

a procedure _{are not}

mandatory, but _can be _{useful for holáing temporary results.}

Alocal

variable

is

declared in exactly the same manner as a

parameter (see the parameter _typing clause above).

After a procedure's

local

variables have been _declared, a

sequence of statements _{is specified} which _indicates how _to

compute the _{function's value.} Five _{kinds of statements} are

allowed: assignment,

if-then-else,

test-case, break, and

return. Any of these kinds of statements can be _nested

within

an

if-then-else

or test-case statement. A _return

statement must be _present.

If

the procedure _execution does

not

exit

through a return statement, then the

function's

value

is

undefined. Each _statement

within

a _procedure

is

terminated by a semi-colon (;).

.

MDBS RDL MANUAL

-

III.

MDBS.RDL SPECIFICATIONS - MDBS RDL MANUAL

i) Assignment statement

An assignment statement has the _form:

yarLahX ± eYpres¶linn-1'

where _{the variable}

is

a

local

variable which has been

declared

earlier

in the procedure and the _{expression is} an arithmetic expression. The _{permissible arithmetic}

operators in an expression _are +,

-,

*,

/,

%

(modulo),

and _unary-. The _permissible operands _are numbers,

prompt

variables,

local variables,

data

items,

parameters, and _{parenthesized arithmetic expressions.}

When _{an expression}

is

_{evaluated, the following operator}

precedence

is

_observed

within

each _{matching pair of} parentheses

(if

_any):

unary-,

4

/,

%, +,

-Expressions in the innermost parentheses pairs _are evaluated

first.

Examples:

TEM4=3+P1;

VAR=PROMPT3/32+MOSAL;

TAX=BASE+(YRSAL-BASE)*PRCNT;

MDBS RDL MANUAL

-

III.

MDBS.RDL SPECIFICATIONS

-

MDBS RDL MANUAL

ii)

If-then-else statement

An _{if-then-else statement has the form:}

ie (condjtic)n-1) then L _{¶rpar.pmenr¶-1 L else} L _atakmoenks=2

l

If

the _{specified condition is} met, then the _statements

of statements-l are executed. In cases where ELSE

is

used, the statements _{of statements-2} are executed when the _{specified condition is} not _satisfied.

A _{condition is enclosed}

within

_{a matching pair of}

parentheses.

It

_is composed _{of one or more relational}

expressions, each of which _{evaluates to true or false.} Any one of the

following relational

operators can be used _in a relational expression:

t <>p >= f < r > r <

Operands _in a

relational

expression _can be numeric or

character constants, prompt <