1168549_B20_Forms_Reference_Jul84 1168549 B20 Forms Reference Jul84

1168549_B20_Forms_Reference_Jul84 1168549_B20_Forms_Reference_Jul84

User Manual: 1168549_B20_Forms_Reference_Jul84

Open the PDF directly: View PDF PDF.
Page Count: 105

Download1168549_B20_Forms_Reference_Jul84 1168549 B20 Forms Reference Jul84
Open PDF In BrowserView PDF
Burroughs

____B_u_r-=r.o~ughs

Reference
Manual

PrIced Item
PrInted In U.S.A
Jul,1984
•

1168549

Burroughs cannot accept any financial or other
responsibilities that may be the result of your use
of this information or software material,
including direct, indirect, special or consequential
damages. There are no warranties extended or
granted by this document or software material.

You should be very careful to ensure that the use of this
software material and/or information complies with the
laws, rules, and regulations of the jurisdictions with
.
respect to which it is used.

The information contained herein is subject to change
without notice. Revisions may be issued to advise of
such changes and/or additions."

Correspondence regarding this publication should be forwarded using the
Remarks form at the back of the manual, or may be addressed directly to
Corporate Documentation-West, Burroughs Corporation, 1300 John Reed
Court, City of Industry, California 91745, U.S.A.

LIST OF EFFECTIVE PAGES
Page

Title
ii
iii
iv
v thru x
1-1 thru
2-1 thru
2-24
3-1 thru
4-1 thru
A-I thru
B-1 thru
B-6
C-l thru
C-12
D-l thru
D-6
1 thru 3
4

1168549

1-6
2-23
3-6
4-22
A-6
B-5
C-ll
D-5

Issue
Original
Original
Original
Blank
Original
Original
Original
Blank
Original
Original
Original
Original
Blank
Original
Blank
Original
Blank
Original
Blank

iii

TABLE OF CONTENTS
Title

Section

Page

INTRODUCTION . .
1

2

1168549

ix

OVERVIEW . . . .
. . . . .
Installing the B 20 Forms Utility . . . .
Creating and Editing Forms (Forms Editor) . . .
Files, Forms, and Fields
......... .
Field Definitions . . . . . . .
Name . . . . . . .
. .. .
Repeating Fields .
........... .
Default . . . . .
. .... .
Highlights . . . . . . . . . .
. .. .
Auto-exit During Program Run . . . . . .
Running a Report on a Form (Forms Reporter) . . . .
Running a Program Using Your Form (Forms Run Time)
Opening a Form . . . . . . .
At Run Time . . . . . . .
At Link Time . . . . . . .
Variable Naming Convention .

1-1
1-1

FORMS EDITOR . . . . . . .
....
....
Accessing the Forms Editor to Create A Form
Accessing the Forms Editor to Modify A Form
Status and Work Areas
. . . . . . .
Moving the- Cursor
. . . .
Cursor Key Plus Shift
. . . . .
Cursor Key Plus Code .
......... .
Cursor Keys in Combination . . . . . .
Selections . . . . . . . . . . . . .
Captions . . . . . . . . . . . . . . . . . . . .
Edit Modes . . . . . . . . .
Delete and Back Space Keys .
Literal Insert . .
. . . . . .....
Commands . . . . .
. . . . .
Reselect (fl) . . . . .
Undo (f2)
Draw (f4)
Drawing Lines
Drawing Boxes

2-1
2-1
2-1
2-3
2-4
2-4
2-4
2-4
2-5
2-6
2-6
2-7
2-7
2-7
2-8
2-8
2-9
2-9
2-9

1-2
1-2
1-3
1-3
1-3
1-4
1-4
1-4
1-4
1-5
1-6
1-6
1-6
1-6

v

TABLE OF CONTENTS (Cont)
Section

Erase (f5) . . . .
. . . . .
. ...
Read Form (f6) . . . . . . . . . .
Write Form (f7)
....... .
Define Field (f8) . . . . . . . .
....
Defining Single Fields .
. . .
Defining Repeating Fields
. . .
Modifying Field Definitions . . . . . . . .
Modifying Field Position and Width .
Test Drive (f9) . . . . . . . . .
Delete Selection (flO)
... .
Copy . . . . . . .
Move . . . . . . . . . . . . . . .
Zoom (Code Z)
View Edit Codes
Next Tag . . . . . . . . . . . . .
Exiting the Forms Editor

vi

Page

Title

.
.
.
.
.
.

2-10
2-10
2-12
2-13
2-13
2-16
2-18
2-18
2-19
2-19
2-20
2-21
2-22
2-22
2-22
2-23

3

FORMS REPORTER

3-1

4

FORMS RUN TIME
........ .
Variable Names .
. . . . .
Prefixes
. . . . . . . . . . .
Roots
. . . .
Suffixes . . . . . . .
..... .
Variable Name Examples . . . . . .
Forms Run Time Services . . . .
Run Time Sequence
DefaultField .
DefaultForm
Disp1ayForm
GetFieldInfo
LockKbd

4-1
4-1
4-2
4-3
4-3
4-4
4-4
4-5
4-5
4-6
4-6
4-7
4-9

TABLE OF CONTENTS (Cont)
Section

A

B
C

D

Title

Page

OpenForm . . . . . . . .
ReadField
SetFieldAttrs
UndisplayForm ..
UserFillField . . . . . . . . . . . .
WriteFie1d . . .
Error Response . .
Type Codes . . . . . . . . . . . . . . .
Configuring the Type System
Forms RUn Time Structure
FmRgtd.asm Source Text.
Defining Types . . . . . .
....
Starter Kit of Types . . . . . . . . .
Adding Types .
. . . . . .
Range Checking and Data Validation

4-9
4-10
4-10
4-11
4-11
4-14
4-14
4-15
4-16
4-16
4-17
4-18
4-18
4-19
4-22

ERROR MESSAGES . . . . . . . . .
Forms Editor Error Messages
Forms Run Time Error Messages . . . . .
SAMPLE BASIC PROGRAM . . .
. . . .
TRAINING EXERCISE: CREATE A FORM
Access the Forms Editor to Create A Form . .
Start With Captions . . . .
Add some Lines and Boxes .
Add Tabular Columns
Define Fields for User Entry . . . . . . . . . . .
Additional Training Activities
GLOSSARY OF TERMS

A-1
A-1
A-4
B-1
C-1
C-1
C-2
C-3
C-6
C-7
C-11
D-1

INDEX

1168549

1

vii

LIST OF ILLUSTRATIONS
Figure

2-1
2-2
2-3
2-4
2-5
3-1
3-2
C-1
C-2
C-3
C-4
C-5
C-6

C-7
C-8

Page

Title

Forms Editor Command Form
.....
Read Form Command Form . .
Define Field Command Form . . . .
Fields Tags (Sample)
Save Form . . . . .
FReport Command Form .
Sample Form Report . .
Selected Caption Box
Captions In A Box . . . .
Selected Horizontal Line
Subdivided Box . . . . . . . . . . . .
Tabular Form . . . . . . . . .
Selection For A Repeating Field . . . . . . . . .
Defined Fields . . . . .
. . . . .
Finished Form . . . . . . . . . . . . . . .

2-2
2-10
2-13
2-15
2-23
3-1
3-3
C-3
C-3
C-4
C-5
C-6
C-8

C-9
C-10

LIST OF TABLES
Table

2-1
2-2
4-1
4-2
4-3
4-4

4-5
4-6
4-7

viii

Page

Title

Forms Editor Commands
....
Character Attributes . . . . . . .
Variable Prefixes
. . . . .
Variable Root Terms . . . . . . . . .
Variable Suffixes
. . . . . . . .
Forms Run-Time Services . . . . . . . .
cbFieldlnfoRet and cbFieldInfoMax Format
pInitState and pExitStateRet Information
Conversion Procedure Module . . . . . .

. . . . .
. . . . .
. .
. . . . .

2-8
2-15
4-2
4-3
4-3

4-5

4-8
4-13
4-18

INTRODUCTION
This manual contains descriptive and procedural information on
the B 20 Forms Utility: Forms Editor, Forms Reporter, and Forms
Run Time.
You should be familiar with standard B 20 Executive commands.
You also need some programming knowledge to run or link a form to
a program (but programming knowledge is not required to create or
design a form).
This manual is organized in sections, as follows:
Section 1, Overview, provides general information on
using the B 20 Forms utility, including
software installation, the FORMS EDITOR, the
Forms Reporter, and Forms Run Time.
Section 2, Forms Editor, contains procedures for
creating, editing, and testing a form, using
the FORMS EDITOR.
Section 3, Forms Reporter, contains procedures for
displaying a report on a form.
Section 4, Forms Run Time, describes Forms Run Time
services, error response, and type codes, and
provides information for structuring a custom
type system.
This manual also contains four appendixes, as follows:
Appendix A lists error and status messages and discusses
possible causes and solutions.
Appendix B contains a BASIC program which uses the Forms
utility.

1168549

ix

Appendix C contains a training exercise with step-bystep instructions for constructing a form and
displaying a report on the form.
Appendix D contains a glossary of terms.
Additional related information is available in the following
manuals (referenced in sections of this manual):
B
B
B
B

x

20
20
20
20

Systems
Systems
Systems
Systems

Custom Installation and Reference Mallual
Linker/Libraria/l Reference Manual
Operating System (BTOS) Referellce Manual
Standard Operations Guide

SECTION 1
OVERVIEW
The B 20 Forms utility consists of:
•

an editor (FORMS EDITOR command) to help you design forms

•

a forms reporter (FREPORT command) to display information
about a form

•

run time modules (Forms Run Time) which you can link to a
program to display forms and accept data supplied by a
user

Throughout this manual, user refers to the operator of a program.

INSTALLING- THE B 20 FORMS UTILITY
If you have a hard disk B 20 system, you install the B 20 Forms
utility software by using the SOFTWARE INSTALLATION command and
the Forms System Disk. The FORMS EDITOR, Forms Reporter, and
Forms Run Time are then available at the Executive. (For more
information on the SOFTWARE INSTALLATION command, refer to the
B 20 Systems Custom Installatioll and Reference Manual.)

If you have a dual floppy B 20 system, each time you use the
FORMS EDITOR, Forms Reporter, or Forms Run Time services you must
insert the Forms System Disk in drive fO (after you sign on).
-Insert the floppy disk for the form you are creating or editing
in drive fl.

1168549

1-1

CREATING AND EDITING FORMS (FORMS EDITOR)
You design or edit forms (draw lines, type captions, and define
user entry fields) using the FORMS EDITOR. Since Forms Run Time
permits a program to refer to fields symbolically, you can often
edit a form without changing the program.
While you are editing or designing the form, the FORMS EDITOR
displays it as it will appear at program run. The FORMS EDITOR
also has a command (TEST DRIVE), that allows you to fill in
fields as a user. When you TEST DRIVE or WRITE your form, the
FORMS EDITOR compacts the form into a set of tables. When you
finish editing the form, you can save the form (or the latest
version of the form) in a file to be called at run time.
Files, Forms, and Fields

Forms are filed in special form files (a B 20 file with a suffix,
.form, automatically added by the FORMS EDITOR). Forms consist
of lined and captioned displays with fields for accepting user
data entries or displaying computed data. A form can contain
many nonoverlapping fields, limited by screen size and byte
availability of your system. You define the fields when you
create or change a form.
Each form has a name, separate from its file name. If the form
is the only form in the file, the form name and file name are
usually the same.
When a form is stored in a library file with other forms, the
form name is used to distinguish the form from the other forms.
These forms are stored in object module format; groups of forms
can therefore be bundled together using the LIBRARIAN utility
(described in the B 20 Systems Linker/Librarian Reference Manual).
Each field also has a distinguishing name; however, you can also
designate repeating fields (many fields with the same name).
Repeating fields are distinguished by their index number.

1-2

Field Definitions

Lines and captions are protected fields; user input at run time
cannot change them. You define unprotected fields by using the
DEFINE FIELD command of the FORMS EDITOR. Defined fields have
field names and, optionally, default values that will or will not
display for the user, indexes (if repeating fields), highlights
when selected or unselected, and automatic exit when the user
enters a last character.
Name

The field name is a text string up to 40 characters in length.
When a program calls Forms Run Time, it specifies the field name
(and index if the field is repeating). Field names must be
unique, unless all fields that share the name are repeating. The
distinction between uppercase and lowercase is ignored for
matching field names.
Repeating Fields

Repeating fields are groups of fields that have the same name.
Tabular forms with columns containing rows of data usually have
repeating fields. Each column contains many fields of the same
name.
The repeating fields are distinguished by their indexes
(location). If the repeating field is vertical, the FORMS EDITOR
automatically assigns index numbers consecutively (starting with
1). However, you can assign index numbers when you define the
repeating field (DEFINE FIELD command of the FORMS EDITOR). No
two fields (locations) can have the same field name and index
number.
You can modify the number of fields for repeating fields without
changing the program that calls it; however, the program must use
the Forms Run Time Service GetFieldInfo (described in section 4)
to determine the number of fields.

1168549

1-3

Default

Each field has a default value that the field is set to when the
form is first displayed. The default is empty (null) unless you
enter a value when you define (or redefine) the field.
Unless you set Show Default? to no when you define a field, the
default displays when the form is used. The default value does
not have to display to be read by the program.
Highlights

You can apply visual highlights (character attributes) to fields
when you define them. These character attributes make the
defined field blink, display in reverse video, display halfbright, and/or display underlined.
Each field can be assigned a selected and an unselected character
attribute. When a user positions the cursor in a field, the
field is selected; when a user positions the cursor outside the
field, the field is unselected.
Auto-Exit During Program Run

Forms Run Time returns control to the program when the user
attempts to exit the field. If you set Auto-exit? to yes when
you define a field, Forms Run Time also returns control to the
program when a text character is typed in the last character cell
of the field.
.

RUNNING A REPORT ON A FORM (FORMS REPORTER)
The Forms Reporter (FREPORT command) displays information on a
form (form name, size, height and width, and number of fields)
and lists each field's defined characteristics (name, size,
single or repeating, index, and options). This report can be
written to a disk file or printer.

1-4

RUNNING A PROGRAM USING YOUR FORM (FORMS RUN TIME)
Forms Run Time is a library of object module procedures. You can
write a program in any B 20 programmming language and use Forms
Run Time services as follows:
1.

The program specifies the form name and, optionally, a
screen location for the display.

2.

Forms Run Time uses the tables stored by the FORMS
EDITOR to display the form.

3.

The user completes fields in a sequence controlled by
the program.

4.

Forms Run Time prompts the user to enter data into each
field and returns the data to the calling program.

5.

Forms Run Time controls user exiting of each field as
follows:
If the user presses a key that moves the cursor within
the field, (such as BACK SPACE, DELETE, Left Arrow and
Right Arrow) Forms Run Time does not return control to
the program.
If the user presses keys that move the cursor from the
field (such as TAB, NEXT, Up Arrow and Down Arrow),
Forms Run Time exits the field and returns control to
the program.
If the user types text (alphanumerics and punctuation)
Forms Run Time does not return control to the program
unless Auto-exit? is turned on (set to yes) and the
text entry is in the last character cell of a field.

6.

Forms Run Time encodes field input values as it returns
them to the program.

1168549

1-5

Opening a Form

The forms for a program that uses Forms Run Time are typically
stored in one or more files and must be opened by a program
before they can be used. Forms can be opened at run time or link
time, but a program is easier to maintain if the form and run
files are separate.
An open form consists of a memory work area that contains all the
information needed to display the form and to access its fields.
The work area required is included in the Forms Reporter (FREPORT
command) report and displays at the top of FORMS EDITOR screen
(unless the form is full screen) so you can monitor form size as
you create a form. A full-screen form requires a work area of
approximately 2K.
At Run Time

The program can open the form at run time if you use OpenForm
(described in section 4).
At Link Time

Since forms are stored as object modules, you can use the LINKER
utility for static inclusion of the forms in the run file. The
program can then refer to the form by its form name (declared as
a public symbol in the form file). The form is conceptually
opened at link time and you do not need OpenForm. (Refer to the
B 20 Systems Linker/Librarian Reference Manila/).

Variable Naming Convention

The variable names used in procedure definitions, fields of
request blocks, and other data structures allow you to infer some
of the variable's characteristics from its name.
Some common variable name prefixes, roots, and suffixes are
listed in section 4.

1-6

SECTION 2
FORMS EDITOR
You can use the FORMS EDITOR to design or modify a form. The
form displays as it will appear during program run. Appendix C
contains a training exercise for creating a form.

ACCESSING THE FORMS EDITOR TO CREATE A FORM
To access the FORMS EDITOR, proceed as follows:
1.

Type

2.'

Press GO. The words Forms Editor appear at the top of
the screen. The area below the double line is work
space for creating a form.

forms editor

at a command prompt (B 20 Executive).

NOTE
You can name your form (and save it) by using the WRITE FORM
command. Your new form is not saved until you use this
command.

ACCESSING THE FORMS EDITOR TO MODIFY A FORM
To access the FORMS EDITOR and modify a form, proceed as follows:
1.

1168549

Type forms editor
at a command prompt (B 20 Executive)
and then press RETURN to display the FORMS EDITOR
command form (as shown in figure 2-1).

2-1

Command forms editor
Forms Editor
File
[Form]

Figure 2-1.

2.

Forms Editor Command Form

Type the file name in the File field.
It is
name,
added
later

not necessary to add the .form suffix to the file
as that is the default. (The .form suffix is
as part of the WRITE FORM command, discussed
in this section.)

The volume and directory default is the current path.
If you want to access a form from a different volume or
directory, you must type in the complete file name
using brackets--[volume]filename.

3.

If the file has more than one form, type the form name
in the [Form] field. The default is the file name.

4.

Press GO; the form appears.
NOTE

You can save the changed version of your form by using the
WRITE FORM command. The changed version is not saved until
you use this command.

2-2

STATUS AND WORK AREAS
A double line divides the FORMS EDITOR screen into two parts:
•

the area above the double line is for status.
The words Forms Editor appear at the top left corner
and messages display in the center. After the form has
been stored (WRITE FORM command), the number of bytes
the form uses appears at the top right corner and the
form name appears in the center.
If you create or access a form that uses the entire
screen area, the work area expands and the status
information no longer displays.

•

the area below the double line is the work area.
When you access the FORMS EDITOR to create a form, the
work area is empty except for the cursor which is in
the center of the screen.
When you access the FORMS EDITOR to modify a form, the
form appears in the work area with the cursor at the
last line edited.
If you create or access a form that uses the entire
screen, the work area covers the status area.

1168549

2-3

Moving the Cursor

You can move the cursor anywhere on the display. You move the
cursor by using the cursor keys (Up Arrow, Down Arrow, Left
Arrow, and Right Arrow). The cursor moves one space in the
corresponding direction (up, down, right, left) for each time the
cursor key is pressed. If you hold the cursor key down, the
cursor moves repeatedly.
Cursor Key Plus Shift

When you press a cursor key and the SHIFT key simultaneously, the
cursor jumps several spaces in the corresponding direction (up,
down, right, or left).
Cursor Key Plus Code

When you press a cursor key and the CODE key simultaneously, the
cursor moves to the corresponding edge of the screen (top,
bottom, right, or left).
Cursor Keys in Combination

You can center the cursor horizontally by simultaneously pressing
the Left Arrow and Right Arrow keys. You can center the cursor
vertically by simultaneously pressing the Up Arrow and Down Arrow
keys.
You can move the cursor diagonally by simultaneously pressing the
Up Arrow or Down Arrow key and the Left Arrow or Right Arrow key
(by also pressing the CODE key, you can quickly move the cursor
to a corner of the screen).

2-4

Selections

A selection is a rectangular area of the screen that you choose
(select) by using the HARK and BOUND keys. After you select an
area, you can use the FORMS EDITOR commands to draw lines or
boxes, erase lines or boxes, move or copy part of the form,
assign character attributes (highlights) to the selected area,
and define fields.
You can select only one area at a time; however, the selection
can be any size and can include fields or only a portion of a
field. If you make a new selection, you automatically remove a
previous selection.
To make a selection, proceed as follows:
1.

Position the cursor at a corner of the rectangular area
you want to select.

2.

Press MARK. The character cell containing the cursor
appears in reverse video. (You have selected this
character cell.)

3.

Move the cursor to another corner of the rectangular
area you want to select.

4.

Press BOUND. A reverse video rectangle appears.
have selected this rectangle.)

(You

You can change the width or height of your selection by
pressing BOUND again at a different screen position.
The marked corner of the selection remains fixed, but
the rectangle changes to reflect the new corner.
If you press MARK again, you remove the previous
selection and only the character cell currently
containing the cursor is selected.
You can set character attributes for the selection by pressing
CODE and a letter for the character attribute. (Refer to Define
Field, later in this section, for a list of character
attributes.)

1168549

2-5

Captions
Captions are protected; they cannot be overwritten by lines
during forms editing or modified by the user at run time.
You can place captions anywhere, but lines and captions cannot
occupy the same character cell. Two or more distinct captions
can occupy the same line of a form, for example:
left caption

right caption

You should separate these same line captions by cursor movement
(empty character cells)--not by spaces. Spaces are characters
and you cannot draw lines through character cells occupied by
spaces.
If you edit one of these same line captions, the position of
other captions is not affected. For example:
left abcde caption

right caption

If you edit one of these same line captions such that the caption
collides with the caption to the right, the system emits an audio
signal. If you try to insert more characters than can fit on
that line, the system emits an audio signal.
A caption overrides a selection. If you start typing a caption
after you have made a selection, the selection disappears. You
can recover the selection after you finish typing the caption by
pressing f1 (RESELECT).
Edit Modes

You can use either insert or overtype to add or modify captions.
In overtype mode, the characters you type replace the characters
at the cursor position. If the OVER TYPE key light (LED) is on,
your B 20 is in over type mode. If the key light is off, press
the OVER TYPE key to enter the over type mode.

2-6

In insert mode, the characters you type are inserted at the
current cursor position (the character at the cursor position and
the cursor move to the right). If the OVER TYPE key light is
off, your B 20 is in insert mode. If the key light is on, press
the OVER TYPE key to enter the insert mode.
NOTE
Text does not wrap. If an insert would cause the text to pass
the edge of the screen or to run into text which ends at the
screen edge, the system beeps and will not accept the entry.
Delete And Back Space Keys

The DELETE and BACK SPACE keys can help you edit captions. When
you press DELETE, you remove one character (at the cursor
position). BACK SPACE functions differently depending on which
edit mode you use, as follows:
•

In overtype, BACK SPACE is equivalent to the Left Arrow
key: it moves the cursor to the left but does not
delete text.

•

In insert, BACK SPACE moves the cursor to the left,
deleting the text to the left of the cursor position as
it moves.

Literal Insert

Press CODE and • (single quote) to literally insert the next key
you press. All characters in the range OOh-FFh are accessible
from the keyboard using this method.

COMMANDS
Access the FORMS EDITOR commands by pressing function keys as
described in table 2-1.

1168549

2-7

Table 2-1.
Key

Forms Editor Commands

Command

Use This Command To:

f1

RESELECT

Select the last selected area

f2

UNDO

Delete the last change

f4

DRAW

Draw a line or box through the
selected area

f5

ERASE

Remove a line or box from the
selected area

f6

READ FORM

Display a stored form

f7

WRITE FORM

Store a form

f8

DEFINE FIELD

Define field characteristics

f9

TEST DRIVE

Fill in fields as a user

flO

DELETE SELECTION

Remove captions, lines, and
fields from the selection

Reselect (tl)

In most cases, when you make a selection and then use a command
on that selection (for example, DRAW), the selection disappears
after the command. If you want to select the same area of the
form again, press fl (RESELECT).
Undo (t2)

You can delete your last command by pressing f2 (UNDO). UNDO
restores deleted text or erased lines, deletes new lines or
insertions or copied portions, and puts moved material back. The
selection and cursor are also returned to the positions they had
occupied. Any uninterrupted sequence of text-entry operations
counts as a single command for UNDO.

2-8

D~aw

(f4)

Using DRAW, you can draw lines or boxes on your form. Any text
in the path of a line (including spaces) is unaffected;
therefore, the resulting line may be broken. To draw lines or
boxes, you select a portion of the screen and then press:
•

f4 to draw a line

•

SHIFT and f4 to draw a thick line

•

CODE and f4 to draw a double line

Drawing Lines

To draw a vertical line, select a rectangle with a width equal to
one character cell. To draw a horizontal line, select a
rectangle with a height equal to one character cell.
Drawing Boxes

To draw a box, select a rectangle with width and height greater
than one character cell. After you press f4, four lines are
drawn through the center of the character cell at each edge of
the selection.
To subdivide this box with lines, make a selection for a vertical
or horizontal line that ends at the box boundaries. The kind of
line (thin, thick, double) does not have to correspond to the box
lines.
Occasionally the correct line character is not available for an
intersection. This happens because it would require 256 line
font characters to do all intersections correctly, leaving no
room in the character set for regular characters. When the
correct line character is unavailable, the FORMS EDITOR supplies
an approximation with the correct shape but the incorrect kind of
line (thin, thick double) for a branch. If you later perform a
DRAW at that intersection such that a correct line character
becomes available, the FORMS EDITOR supplies the correct
character.

1168549

2-9

Erase (f5)

You can use ERASE to remove lines or boxes.
selected area are not removed.

Captions within the

To erase lines or boxes, select the line, box or portion of line
or box to be erased. Press f5 (ERASE). All the lines within the
boundary of your selected area are erased. If the erased line
intersects other lines, the erasure clears the intersections.
Read Form (f6)

You can open a stored form as you access the FORMS EDITOR by
pressing RETURN after you type the command and filling in the
file and/or form name. To recall a stored form while you are in
the FORMS EDITOR, use the READ FORM command (f6) .

• ",,11Q,
When the form displays, it overwrites the screen, erasing
any data on the display. If it overwrites a form that you
have not saved (by using WRITE FORM), the form is lost.
Proceed as follows:
1.

Press f6 (READ FORM). A READ FORM command form
displays as shown in figure 2-2. If you currently have
a form on your display, that file name is in the form.
rr===============READFORM==============~

Flle:

[Form:]

Figure 2-2.

2-10

Read Form Command Form

2.

Type the. file name in the File: field.
It is
name,
added
later

not necessary to add the .form suffix to the file
as that is the default. (The .form suffix is
as part of the WRITE FORM command, discussed
in this section.)

The volume and directory default is the current path.
If you want to access a form from a different volume or
directory, you must type in the complete file name
using brackets--[volume]filename.
3.

If the file has more than one form, press NEXT to move
to the [Form:] field. Type the form name. The default
is the file name.

4.

Press GO. If you have not saved the currently
displayed form, the FORMS EDITOR prompts you to confirm
you wish to erase it. If you want to erase the form
and display the form you requested, press GO.
If you press CANCEL instead of GO, the READ FORM
command is terminated.

You can use the READ FORM command to recall the previous version
of a form you have been editing (if you have not yet stored the
edited form under that form name).

•

If you want to keep your new version and display the
old, press f7 (WRITE FORM) and store your present form
under a new form name. Then use READ FORM to display
the earlier version.

•

If you want to return to the earlier version (deleting
your changes), press f6 (READ FORM) while the form is
displayed. A message displays, requesting you to
confirm that you want to delete the currently displayed
form. Press GO again to proceed with the READ FORM
command or press CANCEL to terminate the command.

1168549

2-11

Write Form (f7)

You can save and name a form while it is displayed by using the
WRITE FORM command. Form files are written as object modules to
enable form bundling using the LIBRARIAN utility and static
inclusion of forms into programs using the LINKER. Like any
object module, a form file has a module name (the form name). If
you are using the LIBRARIAN to package forms into a library, do
not rename form files prior to calling the LIBRARIAN or Forms Run
Time will not function correctly.
NOTE
If you are using a B 21, it is important that you
frequently save (WRITE FORM) your form. If you exceed
the character attribute limitation, the FORMS EDITOR
exits and all changes since the last WRITE FORM are lost.
Proceed as follows:
1.

Press f7 (WRITE FORM). A WRITE FORM command form
displays.

2.

Type the file name in the File field.
The volume and directory default is the current path.
If you want to store the form in a different volume or
directory, you must type in the complete file name
using brackets--[volume]filename.

3.

Press GO; the message Writing ••• appears. The FORMS
EDITOR adds a .form suffix to the file name and
translates the form into the binary format of a form
file. Status information appears in the status area
unless the form is too large.
If you press CANCEL instead of GO, the WRITE FORM
command is terminated.

2-12

Define Field (f8)

You can use the DEFINE FIELD command to add or redefine fields
and display the properties of individual fields.
Defining Single Fields

You can define a single field for any rectangular area that is
exactly one character cell high. Proceed as follows:
1.

Select the area using the cursor and the MARK and BOUND
keys.

2.

Press f8 (DEFINE FIELD). A DEFINE FIELD command form
displays (as shown in figure 2-3).

r.==============

DEFINE FIELD

============~

-

Name:

Index:

Default value:

Options:
:':':':'1
Show default? 1"":'
~i¥~!!
Attributes:

Unse1ec t e:
d tfLJ
rnJ

Figure 2-3.

1168549

Auto-exit? ITIITTIJ
_

Repeating? rI1l"I7I
_

Selected: tEJ
~.:~.::.~:.

Define Field Command Form

2-13

3.

Use the NEXT key to move the cursor to the next field
or use the Up Arrow key to move the cursor to the
previous field. Respond to the fields, as follows:
1)

Field Name. You must type a distinguishing
name for the field (maximum 40 characters).

2)

Index. Leave this field blank. The index is
used to identify repeating field locations.

3)

Default Value. Type a default value (alpha
or numeric) if desired.
The default is an empty field (null). If the
default you enter occupies more character
cells than the field size, the FORMS EDITOR
trims the default value (from the right) to
fit.

4)

Show Default? If you do not want the default
to show during run time, use the DE~ETE key
to remove the Yes and type no.

5)

Auto-exit? If you want the auto exit, use
the DELETE key to remove the No and type yes.

6)

Repeating? Leave repeating set to No since
this is a single field.
If Repeating? is set to yes, your selection
was for more than one field. Press CANCEL to
terminate DEFINE FIELD and then change your
selection, or follow the Repeating Fields
'procedure (later in this section).

7)

Attributes. The defaults are A (no
highlighting) for unselected and E (reverse
video) for selected. If you want to change
the character attribute, use the DELETE key
to remove the letter and type a new entry.
(Table 2-2 lists the available character '
attributes.)
,.0:"

2-14

Table 2-2.

LETTER

Character Attributes

Blinking

CHARACTER ATTRIBUTE
Reverse
Video
Underlining

Halfbright

A

yes

B
C
D
E

yes
yes
yes
yes
yes
yes

F
G

H

I

yes
yes
yes
yes
yes
yes
yes
yes

J
K
L

M
N

0

P
4.

yes
yes

yes
yes

yes
yes

yes
yes
yes
yes
yes
yes

yes
yes

yes
yes

yes

Press GO. The form reappears. A square box appears
for each character cell in the field. These square
boxes are called a tag. If you define two adjacent
fields (with no separating captions or lines), one
field contains filled boxes so you can distinguish
between the two fields. (Tags are illustrated in
figure 2-4.)
If you press CANCEL instead of GO, you terminate the
DEFINE FIELD command. The work area and form
reappears.

Tag For One Field

000000000000000

Tags For Two Adjacent Fields

0 DO • • • • • • • • • • • •

Figure 2-4.

1168549

Field Tags (Sample)

2-15

Defining Repeating Fields

Usually repeating fields are vertically stacked; however, you can
align fields horizontally or distribute them randomly.
You can define vertically stacked repeating fields in one
operation. For horizontal or random fields, you can define the
fields vertically and then use MOVE (discussed later in this
section) to position each field or you can define each repeating
field separately.
Proceed as follows to define a repeating field:
1.

Select the field using the cursor and the MARK and
BOUND keys.
For vertically stacked repeating fields, select all
fields.
For horizontal or random repeating fields, select the
first field.

2.

Press f8 (DEFINE FIELD). A DEFINE FIELD command form
displays (as shown in figure 2-3). Use the NEXT key to
move the cursor to the next field in the form or use
the Up Arrow key to move the cursor to the previous
field.

3.

Respond to the name and index fields, as follows:
1)

Field Name. You must type a distinguishing
name for the field (maximum 40 characters).
The same field name must be used for each
field.

2)

Index.
For vertically stacked fields, leave the
index as is (1) or change it to start index
numbering from a different number.
For horizontal or random fields, enter an
index number as you define each field. Start
with the field in the top left of the form

2-16

and number each field sequentially, moving
right and then down. The index is used to
identify each field's location.
4.

The other field characteristics are optional. For
vertically stacked fields, each field will initially be
given the same characteristics. You can later select
each field and modify these characteristics.
1)

Default Value. Type a default value (alpha
or numeric) if desired.
The default is an empty field (null). If the
default you enter occupies more character
cells than the field size, the FORMS EDITOR
trims the default value (from the right) to
fit.

5.

1168549

2)

Show Default? If you do not want the default
to show during run time, use the DELETE key
to remove the Yes and type no.

3)

Auto-exit? If you want the auto exit, use
the DELETE key to remove the No and type yes.

4)

Repeating? If you selected an area for
vertically stacked repeating fields, the
Repeating? option is set to Yes. If you
selected one field of a repeating field, use
the DELETE key to remove the No and type yes.

5)

Attributes. The defaults are A (no
highlighting) for unselected and E (reverse
video) for selected. If you want to change
the character attribute, use the DELETE key
to remove the letter and type a new entry.
(Table 2-2 lists the available character
attributes.)

Press GO. The form reappears. A square box appears
for each character cell in each defined field. These
square boxes are called a tag. If you define two
adjacent fields (with no separating captions or lines),
one field contains filled boxes. (Tags are illustrated
in figure 2-4.)

2-17

If you press CANCEL instead of GO, you terminate the
DEFINE FIELD command. The form reappears.
6.

If you are creating horizontal or random fields, move
each field to its location (being careful to keep the
indexes sequential, left to right then top to bottom)
or repeat steps 1 through 5 to define each field.

Modify Field Definitions

You
You
the
the

can use the DEFINE FIELD command to modify existing fields.
can select a single square box of a defined field to redefine
field. Your selection is automatically adjusted to include
entire field.- Proceed as follows:
•

Single Fields. Select the field. Press f8 (DEFINE
FIELD). Edit the DEFINE FIELD form. Press GO.

•

Vertically Aligned Repeating Fields. Select the field
(select the entire field height to modify all fields,
for example, to renumber the index). Press f8 (DEFINE
FIELD).
Edit the DEFINE FIELD form. Press GO.

•

Horizontal or Random Repeating Fields. Select each
field. Press f8 (DEFINE FIELD). Edit the DEFINE FIELD
form. . Press GO.

Modify Field Position and Width

You can move the field or change its width by editing the field's
t.ag, as follows:

2-18

•

Insert spaces in front of the tag to move the field to
the right, or backspace in front of the tag to move the
field to the left.
'

•

Delete some of the tag boxes using to shorten the field
(and move it to the left).

•

You can also move or copy fields (MOVE and COpy are
discussed later in this section).

Test Drive (f9)

The TEST DRIVE command simulates the field reponses of a form as
it appears during a program run. Proceed as follows:
1.

Press f9 (TEST DRIVE). The FORMS EDITOR translates the
form into the binary format of a form file (however, no
file is written). The field tags are removed and the
cursor is positioned within the first field. Forms Run
Time controls the form.

2.

You can now tryout your form by typing text and using
NEXT to move the cursor through the fields. As you
exit each field, Forms Run Time reads your entry and
displays the information. You can verify the character
attributes, show default, and auto-exit. If you press
a key that is unknown to Forms Run Time, a message
displays.

3.

Press f9 (TEST DRIVE) again to return control to the
FORMS EDITOR. Field tags reappear.

Delete Selection (f10)

You can use the DELETE SELECTION command to delete (erase) all
captions, lines, and fields from the area you have selected. If
you split the tag in two, the first part of the tag becomes the
field and the second part becomes a caption whose appearance is a
sequence of square boxes. Proceed as follows:

1.

2.

Select the area to be deleted (use the cursor and the

MARK and BOUND keys).

Press flO (DELETE SELECTION). The selected area is
completely replaced with empty spaces.
NOTE

You can also press CODE and DELETE to access the DELETE
SELECTION command. Use f5 (ERASE) to delete only lines, not
text.

1168549

2-19

Copy

You can copy lines, fields, and captions from one part of the
form to another by selecting the area to be copied and using the
COpy key. Proceed as follows:
1.

Select the area to be copied (the source area).

2.

Position the cursor at the top left corner of the area
to receive the copy (the target area).
Source and target areas can overlap.

3.

Press COPY. The selected source area is copied to the
target area you specified. Lines extending across the
edges of the copy are trimmed or joined to the
surrounding lines.
To copy the source area to a target area specified by
placing the cursor at the top right corner of the target
area, use the SHIFT and COpy keys.
To copy the source area to a target area specified by
placing the cursor at the top center of the target area,
use the CODE and COpy keys.

After COpy, the target area remains selected., and the cursor
moves to the same position relative to the new selection as it
had relative to the old. Press COpy a second time to make three
copies of the source area, spaced equally across the screen.

""'(I]~'
If you COpy fields, the field must be repeating or you must
either redefine the field to be repeating or rename one of
the fields. If you TEST DRIVE a form with duplicate single
field names, the FORMS EDITOR assigns the blinking character
attribute to all fields in conflict.

2-20

Move

You can move lines, fields, and captions from one part of the
form to another by selecting the area to be moved and using the
MOVE key. Proceed as follows:
1.

Select the text, lines, or fields to be moved (the
source area).

2.

Position the cursor at the top left corner of the area
to receive the moved text, lines, or fields (the target
area).
Source and target areas can overlap.

3.

Press MOVE. The selected source area is moved to the
target area you specified. Lines extending across the
edges of the areas are trimmed or joined to the
surrounding lines.
To move the source area to a target area specified by
placing the cursor at the top right corner of the target
area, use the SHIFT and MOVE keys.
To move the source area to a target area specified by
placing the cursor at the top center of the target area,
use the CODE and MOVE keys.

After MOVE, the target area remains selected, and the cursor
moves to the same position relative to the new selection as it
had relative to the old. Press MOVE a second time to move the
original source area by twice the distance in the same direction.

W+,u'WQ'
If you move fields, be careful that repeating fields are
still sequential. Edit the index numbers if they are not.
If you TEST DRIVE a form with non-sequential fields, the
FORMS EDITOR assigns the blinking character attribute to all
fields in conflict.

1168549

2-21

Zoom (Code Z)

ZOOM is only available on B 22 systems.
The ZOOM command changes the display from 132 to 80 columns, and
back aga in. Press CODE and Z to swi tch modes. I f the screen·, was
formatted in 132-column mode, it is changed to 80-column mode·:····
and vice versa.
If the form in the Work Frame is more than 80 columns wide, ZOOM
displays the message Form is too wide and does not change the
display.
View Edit Codes

.''''W~I
Literal insert spaces are lost when you use CODE and V
because the command does not distinguish between spaces made
visible with a previous use of the command and space
characters entered via the literal insert command.
This command makes all formatting visible on the screen. Press
CODE and V to view formatting. Space Bar characters show as
dots. Press CODE and V again to exit.
Next Tag

You can press NEXT to select the next field tag, an easy way to
move through a form you are editing. If you press NEXT, your B 20
starts at the current cursor position and scans row by row down
the screen, searching for a tag. If the cursor is currently in a
tag, the search begins just beyond that tag. If no tag is found
between the cursor and the bottom of the screen, the search
resumes at the top of the screen.
When a tag is found, it is selected, and the cursor positioned
under the first square box of that tag. You can edit that tag or
press NEXT again to move on.

2-22

EXITING THE FORMS EDITOR
Press FINISH to end a session with the FORMS EDITOR and return
your B 20 to the Executive. If you have not saved the form you
edited or created (using WRITE FORM), a Save form displays
similar to figure 2-5.

rr================

FINISH

================::;,

. File:

Figure 2-5.

Save Form

The File: field default is the previous file name.
are:

Your options

•

To save the form in the named file, press GO.

•

To save the form in a different file, edit the File
field and press GO.

•

To delete the form, edit the Save? field to No, and
press GO.

•

To terminate FINISH, press CANCEL.
NOTE

If you have a dual floppy system, reinsert a
Disk in drive fO to return to the Executive.

1168549

System

2-23

SECTION 3
FORMS REPORTER
The Forms Reporter (command FREPORT) displays the following form
information: the form name, the size (bytes), the displayed
height and width, and the number of defined fields.
In addition, by default the Forms Reporter displays the following
information for each field of the form: the field name, the row
and column number (the top left corner has the coordinates 0,0),
the width in characters, whether or not the field is repeating,
the field index, the first and last indexes for the field, the
field default value, the setting for show default and auto-exit,
and the field's character attributes when selected and
unselected.
The report can be written to a disk file or printer.
To display a forms report, proceed as follows:
1.

Type

2.

Press GO. The FREPORT command form appears (as shown
in figure 3-1).

j'rcport

Command
FReport

at a command prompt (Executive).

freport

File
[Form]
[Fields?]
[Output]

Figure 3-1.

1168549

FReport Command Form

3-1

3.

You must type the file name in the File field.
It is not necessary to add the .form suffix to the file
name, as that IS the default. (The .form suffix is
added as part of the WRITE FORM command, discussed in
section 2.)
The volume and directory default is the current path.
If you want to access a form from a different volume or
directory, you must type in the complete file name
using brackets--[volume]filename).

4.

The other fields of the FREPORT command form are
optional, as follows:
1)

[Form]. Type a form name if the specified
file is a library file containing more than
one form. The default is the file name.

2)

[Fields?]. If you do not want information
reported for the fields, type no. The
default is yes.

3)

[Output]. Type a device name, if desired.
For example, type [lpt] to print the report.
The default is to only display the report.
If your form has many fields, the report
takes more than one screen to display. For
this reason, you may want to print the form
report or specify a file to store it in.

5.

3-2

Press GO. A forms report displays similar to
figure 3-2. You may have to press the NEXT PAGE or
SCROLL UP keys to display the entire form. When the
last item of the report is displayed, the Forms
Reporter exits to the Executive.

Form name: Tutorial
height: 16
width: 36

size: 904 bytes
number of fields:
22

Field name: Salesman
Row:
0 Column: 12 Width: 23
Repeating? No
Index:
(first:
last:
)
Default:
Show default? Yes Auto-exit? No
Unselected: C Selected: E
Field name: PartNumber
Row:
4 Column:
1 Width: 10
Repeating? Yes Index:
1 (first:
1 last:
5)
Default:
Show default? Yes Auto-exit? No
Unselected: A Selected: E
Field name: Quantity
Row:
4 Column: 12 Width:
7
Repeating? Yes Index:
1 (first:
1 last:
5)
Default: 1
Show default? No
Auto-exit? No
Unselected: A Selected: E
Field name: UnitPrice
Row:
4 Column: 20 Width:
7
Repeating? Yes Index:
1 (first:
1 last:
5)
Default:
Show default? Yes Auto-exit? No
Unselected: A Selected: E
Field name: TotalPrice
Row:
4 Column: 28 Width:
7
Repeating? Yes Index:
1 (first:
1 last:
5)
Default:
Show default? Yes Auto-exit? No
Unselected: A Selected: E
Field name: PartNumber
Row:
6 Column:
1 Width: 10
Repeating? Yes Index:
2 (first:
1 last:
5)
Default:
Show default? Yes Auto-exit? No
Unselected: A Selected: E

Figure 3-2.

1168549

Sample Form Report (Sheet 1 of 4)

3-3

Field name: Quantity
Row:
6 Column: 12 Width:
7
Repeating? Yes Index:
2 (first:
1 last:
5)
Default: 1
Show default? No
Auto-exit? No
Unselected: A Selected: E
Field name: UnitPrice
Row:
6 Column: 2:
7
Repeating? Yes Index:
2 (first:
1 last:
5)
Default:
Show default? Yes Auto-exit? No
Unselected: A Selected: E
Field name: TotalPrice
Row:
6 Column: 28 Width:
7
Repeating? Yes Index:
2 (first:
1 last:
5)
Default:
Show default? Yes Auto-exit? No
Unselected: A Selected: E
Field name: PartNumber
Row:
8 Column:
1 Width: 10
Repeating? Yes Index:
3 (first:
1 last:
5)
Default:
Show default? Yes Auto-exit? No
Unselected: A Selected: E
Field name: Quantity
Row:
8 Column: 12 Width:
7
Repeating? Yes Index:
3 (first:
1 last:
5)
Default: 1
Show default? No
Auto-exit? No
Unselected: A Selected: E
Field name: UnitPrice
Row:
8 Column:. 20 Width:
7
Repeating? Yes Index:
3 (first:
1 last:
5)
Default:
Show default? Yes Auto-exit? No
Unselected: A Selected: E
Field name: TotalPrice
Row:
8 Column: 28 Width:
7
Repeating? Yes Index:
3 (first:
1 last:
5)
Default:
Show default? Yes Auto-exit? No
Unselected: A Selected: E

Figure 3-2.

3-4

Sample Form Report (Sheet 2 of 4)

Field name: PartNumber
Row: 10 Column:
1 Width: 10
1 last:
5)
Repeating? Yes Index:
4 (first:
Default:
Unselected: A Selected: E
Show default? Yes Auto-exit? No
Field name: Quantity
Row: 10 Column: 12 Width:
7
Repeating? Yes Index:
1 last:
5)
4 (first:
Default: 1
Unselected: A Selected: E
Show default? No
Auto-exit? No
Field name: UnitPrice
Row: 10 Column: 20 Width:
7
Repeating? Yes Index:
1 last:
5)
4 (first:
Default:
Show default? Yes Auto-exit? No
Unselected: A Selected: E
Field name: TotalPrice
Row: 10 Column: 28 Width:
7
Repeating? Yes Index:
1 last:
4 (first:
5)
Default:
Show default? Yes Auto-exit? No
Unselected: A Selected:

E

Field name: PartNumber
1 Width: 10
Row: "12 Column:
Repeating? Yes Index:
1 last:
5 (first:
5)
Default:
Show default? Yes Auto-exit? No
Unselected: A Selected: E
Field name: Quantity
Row: 12 Column: 12 Width:
7
Repeating? Yes Index:
1 last:
5 (first:
5)
Default: 1
Unselected: A Selected: E
Show default? No
Auto-exit? No
Field name: UnitPrice
Row: 12 Column: 20 Width:
7
1 last:
5 (first:
5)
ReHeating? Yes Index:
Default:
Show default? Yes Auto-exit? No
Unselected: A Selected: E

Figure 3-2.

1168549

Sample Form Report (Sheet 3 of 4)

3-5

Field name: TotalPrice
Row: 12 Column: 28 Width:
7
Repeating? Yes Index:
5 (first:
1 last':
5)
Default:
Show default? Yes Auto-exit? No
Unselected: A Selected: E
Field name: AmountDue
Row: 14 Column: 28 Width:
7
Repeating? No
Index:
(first:
last:
)
Default:
Show default? Yes Auto-exit? No
Unselected: A Selected: E

Figure 3-2.

Sample Form Report (Sheet 4 of 4)

NOTE
The report shown in figure 3-2 is for the form created
during the tutorial in appendix B.

3-6

SECTION 4

FORMS RUN TIME
Forms Run Time is a library of object module procedures.
Programs written in any Burroughs programming languages can use
Forms Run Time as follows:
•

The program specifies the form name and, optionally, a
screen location for the display.

•

Forms Run Time uses the tables previously constructed
by the FORMS EDITOR to display the form, prompts the
user to enter data, and returns the data to the calling
program.

•

Fields are filled in by the user in a sequence chosen
by the program.

•

Field information is encoded and/or validated and
returned to the program.

Appendix B contains a BASIC program that uses Forms Run Time.

VARIABLE NAMES
The variable names used in Forms Run Time procedure definitions,
fields of request blocks, and other data structures allow you to
infer some of the variable's characteristics from its name.
Each variable name is composed of up to three parts:
root, and suffix.

prefix,

NOTE
Numbers are decimal except when suffixed with "h" (for
hexadecimal). Thus, 10h = 16 and OFFh = 255.

1168549

4-1

Prefixes

The prefix identifies the data type (as shown in table 4-1).
Prefixes can be compound, for example:
cb

count of bytes (the number of bytes in a string of
bytes)

pb

pointer to (logical memory address of) a string of
bytes

rgb

array of bytes.

Table 4-1.

Variable Prefixes

b

byte (8-bit character or unsigned number)

c

count (unsigned number)

f

flag (TRUE

i

index (unsigned number)

n

number (unsigned number) (same as "c")

o

offset from the segment base address (16 bits)

p

logical memory address (pointer) (32 bits
consisting of the offset and the segment base
address)

q

quad (32-bit unsigned integer)

rg

array of ...

s

size in bytes (unsigned number)

=

OFFh or FALSE

0)

t.

4-2

Roots

The root is unique to that variable or a compound of two.
roots are listed in table 4-2.
Table 4-2.

Some

Variable Root Terms

dh

device handle

erc

status (error) code

exch

exchange

feb

file control block

fh

file handle

lfa

logical file address

rq

request block

ucb

user control block

Suffixes

The suffix identifies the use of the variable (as listed in
table 4-3).
Table 4-3.

1168549

Variable Suffixes

Last

the largest allowable index of an array

Max

the maximum length of an array or buffer (one
greater than the largest allowable index)

Ret

the variable's value is to be set by the called
process or procedure (it is not specified by
the calling process)

4-3

Variable Name Examples

Some examples of variable names are:
cbFileSpec

the count of bytes of a file specification

ercRet

the status code to be returned to the
calling process

pbFileSpec

the memory address of a string of bytes
containing a file specification

pDataRet

the memory address of an area into which
data is to be returned to the calling
process

ppDataRet

the memory address of a 4-byte memory area
into which the memory address of a data item
is to be returned to the calling process

pRq

the memory address of a request block

psDataRet

the memory address of a (2-byte) memory area
into which the size of a data item is to be
returned

sData

the size (iri bytes) of a data area

sDataMax

the maximum size (in bytes) of a data area

ssDataRet

the size of the area into which the size of
a data item is to be returned.

FORMS RUN TIME SERVICES
Forms Run Time provides many services, categorized by function in
table 4-4 and described in alphabetical order in this section.

4-4

Table 4-4.

Forms Run-Time Services

Form Services

Field Services

DefaultForm
DisplayForm
OpenForm
UndisplayForm

DefaultField
GetFieldInfo
ReadField
SetFieldAttrs
UserFillField
WriteField

User
Input Control
LockKbd

Run Time Sequence

A typical program proceeds as follows:
1.

The program calls OpenForm.

2.

The program calls DisplayForm.

3.

The program then makes a series of calls to
UserFillField to accept input, ReadField to encode this
input, and WriteField to display decoded data in a
field. This is repeated until the form is complete.

4.

The program calls UndisplayForm to remove the form from
the screen.

The BASIC program in appendix B calls a form per the above
procedure.
Defaultfield

DefaultField restores a field to its default value (as it appears
immediately following DisplayForm). If Show default? is turned
on for the field (specified yes when the field was defined), the
default value appears.

1168549

4-5

The procedural interface is:
DefaultField (pForm, pbFieldName, cbFieldName, index):
ErcType
pForm is a pOinter to the work area of an open form.
pbFieldName and cbFieldName describe a·character string naming
the field to be defaulted. The distinction between uppercase and
lowercase is ignored in matching field names.
Index specifies which field of a repeating field is to be
defaulted. If the named field does not have the repeating
property, index is ignored.
Defaultform

DefaultForm restores a form to its default state (as it appears
immediately following DisplayForm) by applying DefaultField to
each field.
The procedural interface is:
DefaultForm (pForm): ErcType
pForm is a pointer to the work area of an open form.
Dispfayform

DisplayForm displays a form at a specified location. The form
can be centered horizontally and/or vertically within a frame by
specifying 255 for iCol and/or iLine. Each field in the form is
defaulted as described in DefaultField.
The procedural interface is:
DisplayForm (pForm, iFrame, iCol, iLine): ErcType
pForm is a pointer to the work area of an open form.

4-6

iFrame is a frame number in the Video Control Block.
the B 20 Systems Operatillg System (BrOS) Referellce Mallual.)

(Refer to

iCol is a column number within the frame.
iLine is a line number within the frame.
GetFieldlnfo

GetFieldInfo returns information about a field (for example, the
number of repeating fields) . . Only inlormation requested using
cbFieldInfoMax is returned.
The procedural interface is:
GetFieldInfo (pForm, pbFieldName, cbFieldName, index,
pfieldInfoRet, cbFieldInfoMax): ErcType
pForm is a pointer to the work area of an open form.
pbFieldName and cbFieldName describe a character string naming
the field to be interrogated. The distinction between uppercase
and lowercase is ignored in matching field names.
Index specifies which field of a repeating field is to be
interrogated. If the named field does not have the repeating
property, index is ignored.
pFieldInfoRet and cbFieldInfoMax describe the memory work area
into which the field information is returned. The format of this
information is listed in table 4-5.

1168549

4-7

Table 4-5.
Offset

cbFieldlnfoRet and cbFieldlnfoMax Format

FieldL

Size
(bytes)

Description

o

iCol

2

a column number (left edge of
the form is column 0)

2

iLine

2

a line number (the top of the
form is line 0)

4

cCol

2

the Eield"width in columns

6

fShowDefault

2

TRUE if Show-default? is yes

8

fAutoExit

2

TRUE if Auto-exit? is yes

10

fRepeating

2

TRUE if Repeating? is yes

12

attrSel

2

a 4-bit encoding of the
selected character attributes

14

attrUnsel

2

a 4-bit encoding of the
unselected character
attributes

16

indexFirst

2

the lowest index number for a
repeating field

18

indexLast

2

the highest (largest) index
number for a repeating field

20

reserved

30

cchDefault

32

rgchDefault

4-8

10

2
cchDefault

the length of the default
string defined for this field
the default string defined
for this field

LockKbd

LockKbd requires that the user press CANCEL before using the
keyboard. When a program calls LockKbd, the system emits an
audio signal and the keyboard locks; further user input is
refused until the CANCEL key is pressed. Each time a key other
than CANCEL is pressed, the system emits an audio signal and does
not respond.
The procedural interface is:
LockKbd: ErcType
Open Form

OpenForm reads information associated with a form from an open
file into a work area in memory. Once open, the form work area
is self-contained and the file can be closed.
The procedural interface is:
OpenForm (fh, pbFormName, cbFormName, pFormRet, cbMax):
ErcType
fh is an open file handle for the form file (or library file).
pbFormName and cbFormName describe a character string containing
the form name of the form to be read. The distinction between
uppercase and lowercase is ignored in matching form names.
pFormRet and cbMax describe the memory work area into which the
open form is returned. A typical form requires a work area of
approximately 2K. To find out how much work area the form
requires, check the Status Area of the FORMS EDITOR or use the
Forms Reporter (FREPORT command).

1168549

4-9

ReadField

ReadField reads data from a field into program memory, encoding
the currently displayed text according to the type code supplied.
Show default? has no affect on Readfield. ReadField returns the
default value unless a user entry changes the field's value,
whether or not the default is displayed.
The procedural interface is:
ReadField (pForm, pbFieldName, cbFieldName, index, pbRet,
cbMax, pcbRet, pType): ErcType
pForm is a pointer to the work area of an open form.
pbFieldName and cbFieldName describe a character string naming
the field to be read. The distinction between uppercase and
lowercase is ignored in matching field names.
Index specifies which field of a repeating field is to be read.
If the named field is not repeating, index is ignored.
pbRet and cbMax describe the memory work area into which the data
is returned.
pcbRet is the memory address of the word into which the count of
bytes read is returned.
pType is the memory address of a type code used in encoding the
data.
SetFieldAttrs

SetFieldAttrs sets the field character attributes.
The procedural interface is:
SetFieldAttrs (pForm, pbFieldName, cbFieldName, index,
attr): ErcType

4-10

pForm is a pointer to the work area of an open form.
pbFieldName and cbFieldName describe a character string naming
the field to be modified. The distinction between uppercase and
lowercase is ignored in matching field names.
Index specifies the field in a repeating field to be modified. If
the named field is not repeating, the index is ignored.
attr is a word containing any of the following:
•

a binary value in the range 0-15, directly encoding the
desired character attributes

•

an 8-bit character code of a letter in the range A-P
(Refer to the table of character attributes in
section 2.)

•

the letter U for the unselected attributes of the
field, as specified at form definition

•

the letter S for the selected attributes of the field,
as specified at form definition

U ndisplayForm

UndisplayForm removes a form from the screen. The form is
replaced with the null character (code Oh). The contents of any
fields that were not read are lost.
The procedural interface is:
UndisplayForm (pForm): ErcType
pForm is a pointer to the work area of an open form.
U serFiliField

UserFillField allows the user to interactively modify a field's
contents. Usually this means data entry into a blank field.

1168549

4-11

UserFillField highlights the field with the selected character .
attributes and sets the cursor to a specified character position
within the field. UserFillField processes user keystrokes until
an unrecognized key is depressed, at which point the field is
exited and its unselected character attributes are restored. If
auto-exit is turned on for a field, that field is exited when the
last character cell is filled.
The terminating keystroke is passed back to the calling program
in exitState.ch. Usually this program interprets the keystroke
(for example, the user may use NEXT to sequence through fields).
This interpretation is entirely under the control of the program.
A terminating key, such as NEXT or TAB, is not entered into the
field as data. If an auto-exit field is exited becaus~~a
character is typed in its last position, then the character is
entered as data, exitState.ch is set to right arrow (code 12h),
and exitState.fAuto-Exit is set to TRUE.
If the user attempts to move the cursor or enter characters
beyond the field boundaries, the system emits an audio signal.
If the user presses the CODE and Left Arrow keys, the cursor
moves to the left edge of the field; if the user presses the
CODE and Right Arrow keys, the cursor moves to the end of the
field.
The user enters or edits text in either insert or overtype mode
and can press the CODE and DELETE keys or the CODE and BACK SPACE
keys to delete the contents of the entire field.
The procedural interface is:
UserFillField (pForm, pbFieldName, cbFieldName, index,
pInitState, pExitStateRet): ErcType
pForm is a pointer to the work area of an open form.
pbFieldName and cbFieldName describe a character string naming
the field to be filled. The distinction between uppercase and
lowercase is ignored in matching field names.
Index specifies the field that is to be filled in (for a
repeating field). If the field is not repeating, the index is
ignored.

4-12

plnitState points to a descriptor block and pExitStateRet points
to a memory area as described in table 4-6.

Table 4-6.

Offset

pInitState and pExitStateRet Information

Field

Size
(bytes)

Description

plnitState:

o

ich

2

2

reserved

6

the initial cursor position
relative to the start of the
field (where the first
character position is
numbered 0)

pExitStateRet:

o

ich

2

the final cursor position
relative to the start of the
field

2

ch

2

the terminating character
code

4

fAutoExit

2

TRUE if the field was exited
by auto-exit

6

fModified

2

TRUE if the field contents
were changed by the user

8

fEmpty

2

TRUE if the field was empty
(all spaces) on exit

reserved

6

10

1168549

4-13

WriteField

WriteField writes data to a field from the program memory,
decoding the data into text according to the type code supplied.
The procedural interface is:
WriteField (pForm, pbFieldName, cbFieldName, index, pb, cb,
pType): ErcType
pForm is a pointer to the work area of an open form.
pbFieldName and cbFieldName describe a character string naming
the field to be written. The distinction between uppercase and
lowercase is ignored in matching field names.
Index specifies which field of a repeating field is to be
written. If the named field is not repeating, the index is
ignored.
pb and cb describe a memory area containing the data to be
displayed.
pType is the memory address of a type code used in decoding the
data.

ERROR RESPONSE
Users occasionally make errors while filling in forms. Common
errors are alphabetic characters in numeric fields or numeric
values that are out of range.
Forms Run Time supports error handling by the program, but it
does not mandate a particular format for error response. Two
possible ways are:
•

You can set the program to signal an error by emitting
an audio signal and repositioning the cursor in the
field in which invalid data was entered.
The interface to UserFillField permits the

4-14

specification of the character position in the field
where the cursor is initially positioned; you can use
this to respond to an erroneous entry.
This is particularly effective if your program is
intended for a user who is typing slowly and looking at
the display.
•

If the form was designed to contain a special
application status field, you can write the program to
display an appropriate error message in this field,
call LockKbd, and then reset the field to null after
the user presses CANCEL.
LockKbd emits an audio signal for each character typed,
discarding any typing after the erroneous entry until
the user presses the CANCEL key. You can assign the
application status field a character attribute (using
the FORMS EDITOR) to ensure that any error message is
emphasized.
If your program is intended for a user who is doing'
high-speed data entry and who does not usually look at
the screen, this may be necessary to ensure the user
realizes an error occurred.

TVPECODES
A type code is presented to Forms Run Time whenever a field is
read or written; the type code determines how the data is encoded
or 'decoded.
User entry data must be encoded (converted) for use by the
calling program; data written to a field must be decoded for the
display. The encqding and decoding process uses a predefined set
of data types. In Forms Run Time, these types are represented by
text strings called type codes.
A type code ends with a period and can contain a numeric value
(for example, a length). If a type code contains a numeric
value, the final period is preceded by a colon and a string of
decimal digits. Examples of'type codes are Binary and
Character:50.

1168549

4-15

The type system is configurable when Forms Run Time and the
program are linked through the use of program-supplied type codes
and conversion routines.

CONFIGURING THE TYPE SYSTEM
Type codes obtain their semantics through a table lookup strategy
at run time. The table to be searched is determined when you
link the Forms Run Time and the program; its name is rgtdForm and
it is found in the module FmRgtd.asm.
The table is generated by assembly language source code. You can
extend the type system by changing this table; however, you do
not need to use this part of the FORMS utility for most
applications.
Forms Run Time Structure

The components of Forms Run Time are:
•

a master table contained in an assembly language source
file, FmRgtd.asm

•

a set of object module procedures

The result of assembling FmRgtd.asm is an object file:
FmRgtd.obj. The LINKER links this object file with the other
object modules. {Refer to the B 20 Systems Linker/Librarian Reference Manual.}
To configure Forms Run Time, edit FmRgtd.asm and add or delete
object modules. Then reassemble FmRgtd.asm and relink.

4-16

FmRgtd.asm Source Text

The source text of FmRgtd.asm is:
DGroup GROUP CONST ASSUME DS: DGroup
CaNST SEGMENT WORD PUBLIC 'CaNST'
%*DEFINE(DefineType(typecode, EncodeProc,
DecodeProc»
(
DB %LEN(%typecode), '%typecode'
DD %EncodeProc
DD %DecodeProc
CaNST ENDS
EXTRN %EncodeProc:FAR, %DecodeProc:FAR
CONST SEGMENT
)

PUBLIC rgtdForm
rgtdForm LABEL BYTE
·%DefineType(Binary, EncodeBinary,
DecodeBinary)
%DefineType(Character, EncodeChar,
DecodeChar)
DB 0
CONST ENDS
END

1168549

4-17

Defining Types

Each calIon the macro DefineType generates one table entry,
defining one type. The entry for Binary:
%DefineType(Binary, EncodeBinary, DecodeBinary)
is equivalent to the following code:
DB 9, 'Binary'
DD EncodeBinary
DD DecodeBinary
CONST ENDS
EXTRN EncodeBinary:FAR,
DecodeBinary:FAR
CONST SEGMENT
This defines the type code Binary, to be implemented by the
external procedures EncodeBinary and DecodeBinary.
Starter Kit of Types

All of the encode and decode procedures for these types are
implemented by various object modules supplied along with the
FORMS utility. Table 4-7 lists the modules that contain
conversion procedures.
Table 4-7.

Conversion Procedure Modules

Module

4-18

Procedure

FmBnry.obj

DecodeBinary

FmChar.obj

EncodeChar, DecodeChar

This set of types can be used as a starter kit. You can add
additional types to the list or change the definition of existing
types, thereby customizing Forms Run Time to support any
specialized data representation or data validation required in a
set of applications. Types can be removed from the type system,
and the run time thereby made more compact, by deleting the
appropriate definition lines from FmRgtd.asm and reassembling.
The corresponding object module(s) can then be deleted from the
LINKER without error.
For example, to eliminate character strings, the rgtd table
should be edited so that it reads:
rgtdForm LABEL BYTE
%DefineType(Binary, EncodeBinary,
DecodeBinary)
DB 0
and the module FmReal.obj should be excluded from the LINKER.
When you edit the rgtd table, note that the DB 0 at the end of
the table serves as a terminator and must never be deleted.
Adding Types

When type conversion is required by a ReadField or WriteField,
the rgtd table is searched for a type code matching the one
supplied to the ReadField or WriteField in progress. The
distinction between uppercase and lowercase is ignored in
matching type codes, as is the numeric suffix of the type code
(if any). Thus the type Character, defined above, matches all of
the following types codes:
CHARACTER: 50.
Character:100.
cHarAcTer:1.

1168549

4-19

If no match is found for a given type code, the message Bad type
specification is returned from ReadField or WriteField. If a
match is found in the table, the associated EncodeProc (in the
case of ReadField) or DecodeProc (in the case of WriteField) is
then called to perform the conversion.
An EncodeProc (used by ReadField) must have the interface:
EncodeProc (prgch, cch, pb, cb, pcbRet, sType): ErcType
prgch is a pointer to the text read by Forms Run Time from a
field.
cch is the length of the text read from a field.
pb and cb describe the data area passed to ReadField where the
encoding of the text should be placed.
pcbRet is a pointer to a word to be set to the number of encoded
bytes placed by EncodeProc into pb.
sType is the binary value of the type code's numeric suffix (if
any).
EncodeProc converts the string defined by prgch and cch into data
in the area defined by pb and cb and sets the word pointed to by
pcbRet to the number of bytes returned. sType gives specific
information about the data types (needed to conveniently handle
types, such as packed decimal). If encoding is unsuccessful or a
data validation fails (for example, because an alphabetic
character is. entered into a numeric field), the message Invalid
data is returned; otherwise, the message Ok is returned.
DecodeProc (used by WriteField) must have the interface:
DecodeProc (prgch, cch, pb, cb, pcbRet, sType): ErcType
prgch is a pointer to an area in which text to be written. to a
field is placed.

4-20

cch is the length of an area in which text to be written to a
field is placed.
pb and cb describe the existing encoded data.
pcbRet ia a pointer to a word to be set to the number of decoded
bytes.
sType is the binary value of the type code's numeric suffix (if
any).

Example:
To implement a new type called Money, proceed as follows:
1.

Write procedures EncodeMoney and DecodeMoney to perform
the conversions. EncodeMoney accepts $ddd.cc strings,
converts them to cents, and then converts them to 16bit integers equal to the number of cents. If a string
containing other characters or in a different format
were read, EncodeMoney displays the message Invalid
data. DecodeMoney converts a binary number of cents
into a money string with $ and . punctuation.

2.

Edit the FmRgtd.asm file to include a type definition
for Money, by adding an entry of the form:
%DefineType(Money, EncodeMoney, DecodeMoney)

3.

Relink the reassembled FmRgtd.obj to the application
system along with modules containing the procedures
EncodeMoney and DecodeMoney.

The system then recognizes the type code Money and Forms Run Time
calls EncodeMoney and DecodeMoney whenever needed.

1168549

4-21

Range Checking and Data Validation

The program is responsible for range checking and other data
validation of encoded data. In the BASIC program in appendix B,
the PartNumber field is checked for range validity in lines 720740.

4-22

APPENDIX A
ERROR MESSAGES

The FORMS utility has status and error messages to assist you in
creating a form or calling the form from a program.

FORMS EDITOR ERROR MESSAGES
Bad file format
The file typed in a READ FORM command form cannot be found.
Check that you have specified the file correctly and try
again. The volume and directory default is the current
path. If you want to access a form from a different volume
or directory, you must type in the complete file name using
brackets--[volume]filename.
Cannot move partial fields
You can only MOVE or COpy a partial field to a location on
the same line. Adjust your selection to include the entire
field or MOVE or COpy the partial field to a location on the
same line.
Cannot open that file
The file typed in a READ FORM command form cannot be found.
Check your file specification. The volume and directory
default is the current path. If you want to access a form
in a different volume or directory, you must type in the
complete file name using brackets-[volume]filename.

1168549

A-I

Destination out of bounds
You cannot MOVE or COpy a field into an area which overlaps
the edge of the screen. Check the position of your
selection and check the position of the cursor.
Field has nonsequential index
One field of a repeating field has an index that is out of
sequence with the rest of the repeating field. The field is
blinking. Change the index or rename the field.
Form is too complex
Your form cannot be translated into binary format because it
has exceeded the FORMS EDITOR in-memory work area. Try a
TEST DRIVE (the FORMS EDITOR compacts the form as a result
of TEST DRIVE and WRITE FORM commands). If the message
still displays, reduce the length of field names or default
values until the message no longer displays when you TEST
DRIVE the form. This problem is particularly likely to
occur if you moved or copied fields.
Form is too wide
The ZOOM command cannot reformat the display to 80 columns
because the form does not fit. Use the VIEW EDIT CODE
command (press CODE and V) to check for any space characters
that you can remove.
Illegal form name
A form name must consist only of alphanumeric characters
(including the filename). Make sure that your entire form
and file name conforms to this restriction.
Multiple use of same field name
Two or more fields have the same name, but they are not
defined as repeating. The problem fields are blinking.
Either change the field names or specify yes for repeating.

A-2

~o

fields defined
NEXT and TEST DRIVE (f9) cannot be used unless a field has
been defined.

No selection
The command you chose requires a selection.
selection and then try the command.

Make a

No such form
The form you typed in the READ FORM command form does not
exist in that file. If your file name is correct, check
your current path.
Too many attributes (B 21 workstation only)
B 21 systems have a limit of 15 attribute changes per line.
An attribute change occurs once at the beginning of the line
and whenever two adjacent characters have different
attributes. In addition to character attributes discussed
in section 2, B 21 systems consider changes between ASCII
code ranges 0 through 127 (7Fh) and 128 (BOh) through 255
(OFFh) as character attribute changes.
If you exceeded the character attribute limitation on a B 21
because you have 7 or more vertical lines on one line, you
can use CODE • to create the vertical lines (character code
16h).
Too many fields
Your form cannot be translated into binary format because it
has exceeded the FORMS EDITOR in-memory work area. Try a
TEST DRIVE (the FORMS EDITOR compacts the form as a result
of TEST DRIVE and WRITE FORM commands). If the message
still displays, reduce the length of field names or default
values until the message no longer displays when you TEST
DRIVE the form. This problem is particularly likely to
oCGur if you moved or copied fields.

1168549

A-3

FORMS RUN TIME ERROR MESSAGES
Decimal
Value

Hexadecimal
Value

3700

OE74

Name not found.
The form name supplied to OpenForm was not found
in the file. Check that the file name and form
name are correct for the form you want.

3701

OE75

Bad object file.
The file supplied to OpenForm is not a valid
object module. The file could be empty. Check
that the file name is correct for the form you
want.

3702

OE76

Form too big.
The work area supplied to OpenForm is too small
to contain the named form. You can use the
Forms Reporter (FREPORT command) to determine
the required work area.

3703

OE77

Form out of bounds.
The screen coordinates passed to DisplayForm
would result in a part of the form lying outside
the frame. You can use the Forms Reporter
(FREPORT command) to determine the required
height and width.

A-4

Decimal
Value

Hexadecimal
Value

3704

OE78

Form not displayed.
A Forms RUn Time service (DefaultField,
DefaultForm, ReadField, SetFieldAttrs,
UndisplayForm, UserFillField, or WriteField) was
called for a form that was not displayed.
Display the form (use DisplayForm) before
attempting any of these Forms Run Time services.

3705

OE79

No such field.
A Forms RUn Time service (DefaultField,
GetFieldlnfo, ReadField, SetFieldAttrs,
UserFillField, or WriteField) was called for a
field (specified by pbFieldName, cbFieldName)
and index that does not exist. Use the Forms
Reporter (FREPORT command) to determine the
correct name and index.

3706

OE7A

Bad type specification.
A ReadField or WriteField was supplied with a
type code that is not defined in your
configuration. Examine the source text of
FmRgtd.asm for a list of defined type codes.

3707

OE7B

Bad data size.
A ReadField was attempted in which the cbMax
parameter was incorrect for the type of data
being returned (for example, a cbMax of three
for type Binary). Make sure that the size and
type of your data agree.

1168549

A-5

Decimal
Value

Hexadecimal
Value

3708

OE7C

Invalid data.

A ReadField or WriteField was attempted in which
the requested data conversion could not be
performed (for example, reading an alphabetic
string as type Binary)~ For WriteField, make
sure the type of the data you are displaying is
correct. For R~adField, display an error
message and have the user reenter the data.

A-6

APPENDIX B
SAMPLE BASIC PROGRAM
This BASIC program uses OpenForm, DisplayForm, UserFillField,
ReadField, WriteField, and UndisplayForm (Forms Run Time services
discussed in section 4) to run the form created in appendix C.
The program includes range checking and data validation of
encoded data .with the PartNumber field (lines 720-740).
10
11
20
30
40
50
60
70
80
100
110
120
130
140
150
160
170
180
190
200
210
220
230·
240

1168549

'Basic program using Tutorial.form
'Illustrating fixed and repeating fields, user input and
program output
.
OPTION BASE 1
CHNEXT% = &HA: ERCINVALIDDATA% = 3708
'Create part number <=> price data base
DIM PRICES% [20]
FOR 1% = 1 TO 20: READ PRICES%[I%]: NEXT 1%
DATA 1, 5, 17, 20, 3, 4, 7, 6, 2, 3, 3, 12, 15, 19, 6, 8,
4,
, 9, 9, 15
'Open the form
FILE$ = "Tutorial.form"
PSWD$'= ""
FH% = 0
MODE% = &H6D72 ' modeRead
ERC% = OPENFILE(PTR(FH%), PTR(FILE$), LEN(FILE$),
PTR(PSWD$), LEN (PSWD$), MODE%)
IF ERC% <> 0 THEN GOTO 9000
FORM$ = "Tutorial"
DIM FORM% [500] , 500 words = 1000 bytes
ERC% = OPENFORM(FH%, PTR(FORM$), LEN (FORM$),
PTR(FORM%[l]), 1000)
ERC2% = CLOSEFILE(FH%) , close the .file even if OpenForm
got an error
IF ERC% <> 0 THEN GOTO 9000
IF ERC2% <> 0 THEN GOTO 9000
'Now clear the screen and display the form centered
PRINT CHR$(255) + "pf" + CHR$(255) + "vf" + CHR$(&HC);

B-1

250
260
270
300
310
320
330
340
350
360
370
380
390
400
410
500
510
520
530
540
550
560
570
580
590
600
610
620
630
640
650
660
670
680
690
700
710
715

B-2

ERC% = DISPLAYFORM(PTR(FORM%[l]), 0, 255, 255)
IF
, ERC% <> 0 THEN GOTO 9000
'Prompt user to fill in Salesman field
DIM INITSTATE% [4]
DIM EXITSTATE% [8]
FLD$ = "Salesman"
INITSTATE%[l] = 0 'initState.ich: initial cursor
position
ERC% = USERFILLFIELD(PTR(FORMJo[l]), PTR(FLD$), LEN(FLD$),
0, PTR(INITSTATE%[l]), PTR(EXITSTATE%[l]»
IF ERC% <> 0 THEN GOTO 9000
IF EXITSTATE%[2] = CHNEXT% THEN GOTO 500 '
exitState.ch = Next => proper exit
PRINT CHR$(7); , anything else is improper exit: make a
beep (by £rinting ASCII bell)
INITSTATE%[l] '= EXITSTATE%[l] , leave cursor where it was
GOTO
350 ' and try again
,
'

'Now find out how many repetitions there are
DIM INFO% [16]
FLD$ = "PartNumber"
ERC% = GETFIELDINFO(PTR(FORM%[l]), PTR(FLD$), LEN(FLD$),
1, PTR(INFO%[l]), 32)
IF
, ERC% <> 0 THEN GOTO 9000
'Loop through all repetitions
AMOUNTDUE% = 0
FOR INDEX% = INFO%[9] TO INFO%[10] , indexFirst to
indexLast
,
'Prompt user to fill in Part Number
PART% = 0
FLD$ = "PartNumber"
Type$ = "Binary."
INITSTATE%[l] = 0 ' initial cursor position
ERC% = USERFILLFIELD(PTR(FORM%[l]), PTR(FLD$), LEN(FLD$),
INDEX%, PTR(INITSTATE%[l]), PTR(EXITSTATE%[l]»
IF ERC% <> 0 THEN GOTO 9000
IF EXITSTATE%[2] = CHNEXT% THEN GOTO 710 ' proper exit
PRINT CHR$(7); , improper exit: beep
INITSTATE%[l] = EXITSTATE%[l] , leave cursor where it was
GOTO 650 ' and try again
'Find out what the user typed
CBREAD% = 0

720
730
740
750
760
770
780
790
800
810
820
825
830
840
850
860
870
880
890
900
910
920
930
940
950
960
970
980
990
1000
1010
1015
1020
1030
1040
1050
1060
1070

1168549

ERC% = READFIELD(PTR(FORM%[l]), PTR(FLD$), LEN(FLD$),
INDEX%, PTR(PART%), 2, PTR(CBREAD%), PTR(TYPE$»
IF ERC% = 0 AND PART% > 0 AND PART% <= 20 THEN GOTO 800 '
valid £art number
IF ERC70 <> ERCINVALIDDATA% AND ERC <> 0 THEN GOTO 9000 '
random error
'Here if invalid part number: display an error message
MSG$ = "Invalid Part Number"
GOSUB 5000
, And make the user do it allover again
GOTO 600
GOSUB 6000 ' clear the message
'Got a good part number, redisplay to right justify
ERC% = WRITEFIELD(PTR(FORM%[l]), PTR(FLD$), LEN(FLD$),
INDEX%, PTR(PART%), 2, PRT(TYPE$»
IF ERC% <> 0 THEN GOTO 9000
'Now look up unit price and display
UNITPRICE% = PRICES%[PART%]
FLD$ = "UnitPrice"
TYPE$ = "Binary."
ERC% = WRITEFIELD(PTR(FORM%[l]), PTR(FLD$), LEN(FLD$),
INDEX%, PTR(UNITPRICE%), 2, PTR(TYPE$»'
IF
, ERC% <> 0 THEN GOTO 9000
'Prompt user to fill in Quantity
FLD$ = "Quantity"
TYPE$ = "Binary."
QUANTITY% = 0
INITSTATE%[l] = 0 ' initial cursor position
ERC% = USERFILLFIELD(PTR(FORM%[l]), PTR(FLD$), LEN(FLD$),
INDEX%, PTR(INITSTATE%[l]), PTR(EXITSTATE%[l]»
IF ERC% <> 0 THEN GOTO 9000
IF EXITSTATE%[2] = CHNEXT% THEN GOTO 1010 ' proper exit
PRINT CHR$(7); , improper exit: beep
INITSTATE%[l] = EXITSTATE%[l] , leave cursor where it was
GOTO 950 ' and try again
'Find out what the user typed
CBREAD% = 0
ERC% = READFIELD(PTR(FORM%[l]) PTR(FLD$), LEN(FLD$),
INDEX%, PTR(QUANTITY%), 2, PTR(CBREAD%), PTR(TYPE$»
IF ERC% = 0 THEN GOTO 1100 ' valid number
IF ERC% <> ERCINVALIDDATA% THEN GOTO 9000 ' random error
'Here if invalid quantity: display an error message
MSG$ = "Not a number"
GOSUB 5000

B-3

1080
1090
1100
1110
1120
1125
1130
1140
1150
1160
'1170
1180
1190
1200
1210
1220
1230
1240
1250
1400
1410
1420
1500
1510
1520
1530
5000
5010
5020
5030
5040
5050
5060
5070
5080
6000
6010
6020
6030
6040

B-4

'And make the user do it allover again
GOTO 900
GOSUB 6000 ' clear the message
'Redisplay quantity as we did part number
ERC% = WRITEFIELD(PTR(FORM%[l]), PTR(FLD$), LEN(FLD$),
INDEX%, PTR(QUANTITY%), 2, PTR(TYPE$»
IF ERC% <> 0 THEN GOTO 9000
'Compute total price = unit price * quantity, and display
TOTALPRICE% = UNITPRICE% * QUANTITY%
FLD$ = "TotalPrice"
TYPE$ = "Binary."
ERC% = WRITEFIELD(PTR(FORM%[l]), PTR(FLD$), LEN(FLD$),
INDEX%, PTR(TOTALPRICE%), 2, PTR(TYPE$»
IF ERC% <> 0 THEN GOTO 9000
'And update Amount Due
AMOUNTDUE% = AMOUNTDUE% + TOTALPRICE%
FLD$ = "AmountDue"
TYPE$ = "Binary."
ERC% = WRITEFIELD(PTR(FORM%[l]), PTR(FLD$), LEN(FLD$),
INDEX%, PTR(AMOUNTDUE%), 2, PTR(TYPE$»
IF ERC% , <> 0 THEN GOTO 9000
'Finished a row, loop back for next row
NEXT
INDEX%
,
'Last row filled: put cursor back and exit
PRINT CHR$(255) + "pn" + CHR$(255) = "vn";
END
,
'Subroutine to display MSG$ in the form
'Use escape sequence to position cursor and set blinking
attributes
PRINT CHR$(255) + "c" + CHR$(50) + CHR$(25) + CHR$(255) +
"ai";'
'Display message
PRINT MSG$;
'Reset attributes to nlain and beep
PRINT CHR$(255) + "aa t ' + CHR$(7);
RETURN
,
'Subroutine to clear the error message
'Use escape sequence to position cursor
PRINT CHR$(255) + "c" + CHR$(50) + CHR$(25);
'Print 50 spaces
PRINT STRING$(50, " ");

6050
6060
9000
9010
9020

1168549

RETURN
I
I Error exi· t
PRINT "error"

GOTO 1500

ERC%

B-5

ApPENDIX C
TRAINING EXERCISE: CREATE A FORM
This appendix is a training exercise containing step-by-step
instructions for creating a form (with captions, lines and boxes,
and single and repeating fields).
If you are not familiar with overtype and insert modes or cursor
movement on the B 20, you should review those paragraphs in
section 2. Also refer to section, 2 as necessary for additional
information on FORMS EDITOR commands.
NOTE
You can exit any FORMS EDITOR command (TEST DRIVE,
WRITE FORM, etc.) and return to the FORMS EDITOR by
pressing CANCEL. You can exit the FORMS EDITOR and
return to the Executive by pressing FINISH.

ACCESS THE FORMS EDITOR TO CREATE A FORM
To access the FORMS EDITOR, proceed as follows:
1.

Type

2.

Press GO. The words Forms Editor appear at the top of
the screen. The area below the double line is work
space for creating a form. The cursor is in the center
of the screen.

1168549

C-l'

[ormseditor

at a command prompt (B 20 Executive).

START WITH CAPTIONS
1.

Move the cursor approximately 16 spaces to the left.

2.

Type Part No..
times.

3.

Type Quan..

then press the Right Arrow key three times.

4.

Type

then press the Right Arrow key three times.

5.

Type Tota/.
similar to

Price.

then press the Right Arrow key three

The center of your form should now look
Part Ho.

C-2

Quan.

Price

Total

ADD SOME LINES AND BOXES
1.

Surround the captions with a box.
1)

Position the cursor one line above and two
character cells to the left of the Part Ro.
caption. Press MARK.

2)

Position the cursor three lines below and two
character cells to the right of the Total caption.
Press BOUND. You have now selected an area for a
box. Your form should now look similar to
figure C-1.

Figure C-l.

3)

Selected Caption Box

Press the SHIFT and f4 keys (DRAW). The captions
are surrounded by a thick line box. Your form
should now look similar to figure C-2.

Part NO.

Figure C-2.

1168549

Proceed as follows:

Quan.

Price

Total

Captions In A Box

C-3

2.

Subdivide the box horizontally (draw lines to separate
the captions). Proceed as follows:
1)

Position the cursor one line below the captions at
the right box boundary. Press MARK.

2)

Position the cursor on the same line (one line
below the captions) at the left box boundary.
Press BOUND.
Since you have selected an area one character cell
high, your selection is for a line. Your form
should now look similar to figure C-3.

I

Part No.

I':lII

Figure C-3.

3)

C-4

,..

Quan.
<

Price

Total

. " ' < . , .~.:::"

m

Selected Horizontal Line

Press f4 (DRAW).

A thin line appears.

3.

Subdivide the box vertically.
1)

Proceed as follows:

Midway between Part No. and Quan., select a
rectangle one character cell wide which intersects
the top and bottom thick lines.
(Position the cursor one line above the captions,
press MARK. Position the cursor in a direct line
below the selected character cell, intersecting
the bottom line. Press BOUND.)

2)

Press f4 (DRAW).

3)

Add vertical lines between Quan. and Price and
between Price and Total.
(Press fl (RESELECT).) The selection for ·the line
between Part No. and Quan. reappears. Position
the cursor one line above the captions, midway
between Quan. and Price. Press COPY twice. Two
more vertical lines appear. (You can use COpy
because these columns are equal in area.)
Your form should now look similar to figure C-4. -

Part No.

Quan.

Figure C-4.

1168549

Price

Total

Subdivided Box

C-5

ADD TABULAR COLUMNS
To make a tabular form with five rows of data, you COpy the lower
box five times. Proceed as follows:
1.

Select the lower box using HARK and BOUND.
(Position the cursor on the left boundary, one line
below the caption. Press MARK. Position the cursor on
the right boundary, two lines below the marked corner.
Press BOUND.)

2.

Position the cutsor one line below the lower left
corner of the box. The cursor is now in the lower left
corner of the selection.

3.

Press COPY. A copy of the selected box is appended to
the bottom of the box and selected. The cursor is
positioned one line below the lower left corner of the
box (in the lower left corner of the selection).

4.

Press COpy three more times.
similar to figure C-S.

Part NQ.

Quan.

Figure C-S.

C-6

Price

Your form should now look

Total

Tabular Form

DEFINE FIELDS FOR USER ENTRY
1.

Define repeating fields for each column. Figure C-6
illustrates the screen during the define field command
form with the part number repeating field selected.
Proceed as follows:
1)

Select the column labeled Part No. as shown in
figure C-6. (Be careful not to include the
caption line in your selection.)
(Move the cursor to inside the left bottom corner
of the form. Press MARK. Position the cursor one
line below and left of the intersection between
the Part No. and Quan. columns. Press BOUND.)

2)

Press f8 (DEFINE FIELD). The DEFINE FIELD command
form appears. Your screen should now look similar
to figure C-6.
Use NEXT to move the cursor through the DEFINE
FIELD command form fields, as explained in the
following steps. When changing an existing entry
(such as the Yes for Show default?), you must use
DELETE to clear the character cells before before
you can type a new entry.

1168549

3)

Type Par/Number in the Name: field of the DEFINE
FIELD command form.

4)

Press GO. Five fields are defined.
a tag (sequence of square boxes).

5)

Select the Quan. column and define a repeating
field named quantity with a default value of 1,
and set Show Default? to no.

6)

Define the repeating fields UnitPrice and
TotalPrice. Your form should now look similar to
figure C-7.

Each contains

C-7

Forms Editor 4.0

r;:::=============== DEFINE FIELD ================;-t
Name:

•
•
Index:

Defaul t value:

11!1!1!I!lllll!I!!!!IIII!I!IIII!I!!III!!!I!I!!!I!!!!!!!!!!!!I!i!I!!!!!!l!l!l!!!!:!:!!!l!!!I!!!l!l!!!!!!!!I!!!!ll!li!l!!!!!I!!I!!!!:!!!!!;!!!!!I!l!!!!!!!!!!!!!!!!!!!!!!!!!!!!!l!l!IIIII!I!l!!!!1

~~:~~f8Ult? 11~~~I!1
AttribUtes:

Auto-exit?

LJnselected:

II

II~!I!!I

Selected:

Price

Figure C-6.

C-8

Repeating?

I!IJ
Total

Selection For A Repeating Field

Part No.

Quan.

Price

Total

000000000 0000000 0000000 0000000
000000000 0000000 0000000 0000000
000000000 0000000 0000000 0000000
000000000 0000000 0000000 0000000
000000000 0000000 0000000 0000000

Figure C-7.

1168549

Defined Fields

C-9

2.

Define two single fields.

Proceed as follows:

1)

Select an area three lines high at the bottom of
the Total column (intersecting the bottom line and
having the same width as the Total column).

2)

Press the SHIFT and £4 keys (DRAW). A thick line
box appears, joined to the main form.

3)

Select the interior of this box and define a field
named AmountDue. Press GO.

4)

Type the caption·
box.

5)

Move the cursor to the top of the form. Type the
caption Salesman: above the Part No. column.

6)

. Define a field named Salesman to the right of the
caption. Change the unse1ected character
attribute to underline (letter C). Press GO. The
form should now appear similar to figure C-B.
Salesman:
Pa.rt No.

Amoullt Dlle

to the left of the

000000000000000000000000
Quan.

Prioe

Total

000000000 0000000 0000000 0000000
000000000 0000000 0000000 0000000

000000000 0000000 0000000 0000000
000000000 0000000 0000000 0000000

000000000 0000000 0000000 0000000
Amount aue:

Figure C-S.

C-IO

-I 0000000

Finished Form

ADDITIONAL TRAINING ACTIVITIES
Before exiting the FORMS EDITOR:
•

Save the form you created in a file named Tutorial by
using the WRITE FORM command (press f7).

•

Run a TEST DRIVE (press f9) of the form you created.

After exiting the FORMS EDITOR (exit by pressing FINISH):

•

Run a FORMS REPORTER report on the form you created
(command FREPORT at the Executive level).

•

Use the BASIC program in appendix B to run your form.

1168549

C-ll

APPENDIX D

GLOSSARY OF TERMS
CHARACTER ATTRIBUTES
Character attributes are visual highlights which you can apply to
fields when you define them. These highlights make the defined
field blink, display in reverse video, display half-bright,
and/or display underlined.
DEFAULTFIELD
DefaultField is a Forms Run Time service that restores a field's
value to its default.
DEFAULTFORM
DefaultForm is a Forms Run Time service that restores a form to
its default state.
DEFINE FIELD
DEFINE FIELD (f8) is a FORMS EDITOR command that allows you to
set field characteristics (such as field name, default, character
attributes).
DELETE SELECTION
DELETE SELECTION (flO) is a FORMS EDITOR command that removes all
captions, lines, and fields from a selected area.
DISPLAYFORM
DisplayForm is a Forms Run Time service that displays a form on
the screen.

1168549

D-1

DRAW
DRAW (£4) is a FORMS EDITOR command that allows you to draw a
line or box at the selected area of the form.
ERASE
ERASE (£5) is a FORMS EDITOR command that allows you to remove a
line or box from the selected area of the form.
FIELDS
Fields are special areas of a form that are set aside for
accepting user data entries or displaying computed data. A form
can contain many nonoverlapping fields, limited by screen size
and byte availability of the system.
FORMS
Forms are lined and captioned displays with fields for accepting
user data entries or displaying computed data.
FORMS REPORTER
The Forms Reporter (command FREPORT) displays the following form
information: the form name, the size (bytes), the displayed
height and width, and information on the defined fields.
FORMS RUN TIME
Forms Run Time is a library of object module procedures
(services).
GETFIELDINFO
GetFieldlnfo is a Forms Run Time service that returns information
about a field.

D-2

INDEX
Index numbers are used to distinguish locations in a repeating
field.
INSERT MODE
Insert is one of the edit modes available on the B 20. In insert
mode, the characters you type are inserted at the current cursor
position (the character at the cursor position and the cursor
move to the right). If the OVER TYPE key light is not on, your
B 20 is in insert mode. If the light is on, press the OVER TYPE
key to enter the insert mode.
LOCKKBD
LockKbd is a Forms Run Time service that requires the user to
press CANCEL before using the keyboard.
OPENFORM
OpenForm is a Forms Run Time service that reads a form from a
file into a work area in memory.
OVERTYPE MODE
Over type is one of the edit modes available on the B 20. In
over type mode the characters you type replace the characters at
the cursor position. If the OVER TYPE key light is on, your -B20
is in over type mode. If the light is not on, press the OVER TYPE
key to enter the over type mode.
READ FORM
READ FORM (f6) is a FORMS EDITOR command that allows you to
display a stored form.

1168549

D-3

READFIELD
ReadField is a Forms Run Time service that reads data from a
field into program memory.
REPEATING FIELDS
A repeating field is a group of fields that have the same field
name. The repeating fields are distinguished by their indexes
(location).
RES ELECT
RES ELECT (fl) is a FORMS EDITOR command that allows you to select
the same form area again.
SELECTIONS
A selection is a rectangular area of the screen that you choose
by using the MARK and BOUND keys.
SETFIELDATTRS
SetFieldAttrs is a Forms Run Time service that sets the character
attributes of a field on the screen.
TEST DRIVE
TEST DRIVE (f9) is a FORMS EDITOR command that allows you to
display the form as it will appear at run time and fill in fields
as a user.
UNDISPLAYFORM
UndisplayForm is a Forms Run Time service that removes a form
from the screen.

0-4

UNDO
UNDO (£2) is a FORMS EDITOR command that allows you to delete the
previous change to the form.
USERFILLFIELD
UserFillField is a Forms Run Time service that allows user input
to a field.

WRITE FORM
WRITE FORM (£7) is a FORMS EDITOR command that allows you to
store (save) a form.
WRITEFIELD
WriteField is a Forms Run Time service that writes data to a
field from program memory.

1168549

D-5

INDEX
Adding Types 4-19
Auto-exit 1-4
Back Space Key 2-7
Bound 2-5
Captions 2-6
cbFieldlnfoMax 4-8
cbFieldlnfoRet 4-8
Character Attributes 2-15
CO,des J Type 4-15
Configuring the Type System 4-16
Conversion Procedure Modules 4-18
Copy 2-20
Cursor 2-4
Data Validation 4-22
Default 1-4
DefaultField 4-5
DefaultForm 4-6
Define Field (f8) 2-13
Defining Repeating Fields 2-16
Defining Single Fields 2-13
Defining Types 4-18
Delete Key 2-7
Delete Selection (flO) 2-19
DisplayForm 4-6
Draw (f4) 2-9
Edit Modes 2-6
Erase (f5) 2-10
Error Messages
Forms Editor A-I
Forms Run Time A-4
Error Response (Forms Run Time) 4-14
Exiting the Forms Editor 2-23
Field Definitions 1-3
Auto-exit During Program Run 1-4
Default 1-4
Highlights 1-4
Modifying Field Definitions 2-18
Modifying Field Position And Width 2-18
Name 1-3
Repe~ting Fields 1-3

1

INDEX (Cont)

Fields 1-2
Finish 2-23
FmRgtd.asm Source Text 4-17
Forms 1-2
Forms Editor 1-2, 2-1
Forms Editor Commands 2-8
Forms Reporter 1-4, 3-1
Forms Run Time 1-5, 4-1
Forms Run Time Services 4-4
Forms Run Time Structure 4-16
Freport 1-4, 3-1
GetFieldInfo 4-7
Highlights 1-4
Insert 2-7
Installing The B 20 Forms Utility 1-1
Linker/Librarian 1-2, 1-6, 2-12, 4-16, 4-19
Literal Insert 2-7
LockKbd 4-9
Mark 2-5
Move 2-21
Next Tag 2-22
OpenForm 1-6, 4-9
Opening a Form 1-6
Over type 2-6
pExitStateRet 4-13
pInitState 4-13
Prefixes 4-2
Range Checking and Data Validation 4-22
Read Form (f6) 2-10
ReadField 4-10
Repeating Fields 1-3
Reselect (f1) 2-8
Roots 4-3
Run Time Sequence 4-5
Save Form 2-23
Selections 2-5
SetFieldAttrs 4-10
Show Default 1-4, 4-5, 4-10
Software Installation 1-1
Starter Kit of Types 4-18
Status and Work Areas 2-3
Suffixes 4-3
Tag 2-15
Test Drive (f9) 2-19

2

INDEX (Cont)

Tutorial 3-3, C-11
Type Codes 4-15
Adding Types 4-19
Configuring the Type System 4-16
Data Validation 4-22
Defining Types 4-18
FmRgtd.asm Source Text 4-17
Forms Run Time Structure 4-16
Range Checking 4-22
Starter Kit of Types 4-18
UndisplayForm 4-11
Undo (f2) 2-8
UserFillField 4-11
Variable Names 4-1
Variable Prefixes 4-2
Variable Root Terms 4-3
Variable Suffixes 4-3
View Edit Codes 2-22
Work Area 2-3
Write Form (f7) 2-12
WriteField 4-14
Zoom (Code Z) 2-22

3

Documentation Evaluation Form

Title: __
B_20_S
....Y,-s_t_em_s_F_o_r_m_s_R_e_f_er_e_n_c_e_M_a_n_ua_l_ _ __

Form No:
Date:

1168549

July 1984

Burroughs Corporation is interested in receiving your comments
and suggestions, regarding this manual. Comments will be utilized in ensuing revisions to improve this manual.

Please check type of Suggestion:

o

Addition

o

Deletion

o

Revision

o

Error

Comments:

From:
Name

Title
Company
Address
Phone Number _ _ _ _ _ _ _ _ _ _ _ _ _ __
Remove form and mail to:
Burroughs Corporation
Corporate DUClIlIH!lItatillll -- West
1300 John Reed Court
City of Industry. CA 91745
U.S.A.

Date _ _ _ _ _ _ _ _ __



Source Exif Data:
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
XMP Toolkit                     : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37
Producer                        : Adobe Acrobat 9.2 Paper Capture Plug-in
Modify Date                     : 2009:12:26 22:13:35-08:00
Create Date                     : 2009:12:26 22:13:35-08:00
Metadata Date                   : 2009:12:26 22:13:35-08:00
Format                          : application/pdf
Document ID                     : uuid:e1a1acbe-8dd7-432b-8459-db08312eb0e6
Instance ID                     : uuid:09856a04-7502-4bc4-857c-44da9fde1f2e
Page Layout                     : SinglePage
Page Mode                       : UseNone
Page Count                      : 105
EXIF Metadata provided by EXIF.tools

Navigation menu