Digital PDFs

AA-EU61A-TH

December 1986

292 pages

Original

29MB

Document:	Synergy Programmer’s Manual
Order Number:	AA-EU61A-TH
Revision:	0
Pages:	292
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/pro3xx/POS/AA-EU61A-TH_Synergy_Programmers_Manual_198612.pdf

OCR Text

Synergy Programmer's
Manual
Order No. AA-EU61A-TH
Order No. AD-EU61A-T1

December 1985

This manual describes the tools and procedures that you
use to build an application that can be installed and run
in the Synergy environment.

REQUIRED SOFTWARE:

Professional Host Tool Kit V3.0.
PRO/Tool Kit, 3.0 or later.
Synergy V2.0 or later

OPERATING SYSTEM:

P/OS V3.0 or later

DIGITAL EQUIPMENT CORPORATION
Maynard. Massachusetts 01754-2571

First Printing, February, 1985
Updated, December, 1985

The information in this document is subject to change without
notice and should not be construed as a commitment by Digital
Equipment Corporation. Digital Equipment Corporation assumes· no
responsibility for any errors that may appear in this document.
The software described in this document is furnished under a
license and may only be used or copied in accordance with the
terms of such license.
No responsibility is assumed
software on equipment that
affiliated companies.

for the use or reliability of
is not supplied by DIGITAL or its

The specifications and drawings, herein, are the property of
Digital Equipment Corporation and shall not be reproduced or
copied or used in whole or in part as the basis for the
manufacture or sale of items without written permission.
Copyright © 1985 by Digital Equipment Corporation
All Rights Reserved
The following are trademarks of Digital Equipment Corporation:
CTI BUS
DEC
DECmate
DECsystem-l0
DECSYSTEM-20
DECUS
DECwriter
DIBOL

mamaDmu™

MASSBUS
PDP
P/OS
PRO/BASIC
PRO/Communications
Professional
PRO/FMS
PRO/RMS
PROSE
PROSE PLUS

Rainbow
RSTS
RSX
Tool Kit
UNIBUS
VAX
VMS
VT
Work Processor

CONTENTS
PREFACE

CHAPTER 1

SYNERGY OVERVIEW

1.1
INTRODUCTION TO SYNERGY
1.2
APPLICATION CONTROL
1. 2.1
The Active Application
1. 2.2
Installing and Removing Applications .
1. 2.3
Starting and Exiting the Application.
1. 2.4
Task Control Services Overview
1.3
WINDOWS IN SYNERGY
1. 3.1
Window Description
1. 3.2
Window Attributes
1. 3.3
Video Protocols
1. 3.4
Resources . . . . .
1. 3.5
Changing the Window Size
1. 3.6
Coordinate Systems .
1.3.6.1
GIDIS Coordinates
1.3.6.2
Window Dimensions
1. 3.7
Window Positions . .
1. 3.8
Window Services Overview
1.4
MENUS . . . . . . . . . .
1. 4.1
High-level Menu Services
1. 4.2
Primitive Menu Services

CHAPTER 2

DESIGNING A NEW APPLICATION

2.1
THINKING ABOUT THE HUMAN INTERFACE
The Type of Interaction
2.1.1
2.1. 2
The Screen Contents
2.1. 3
The Keyboard . . . . .
The Format of HELP . .
2.1. 4
The Handling of Errors
2.1. 5
2.1.5.1
User Errors
Programming Errors
2.1.5.2
Resource Errors
2.1.5.3
2.1.5.4
Application Abort
FITTING INTO THE SYNERGY MODEL
2.2
BUILDING THE APPLICATION
2.3

2.3.1
2.3.2
2.4
2.4.1
2.4.2
2.4 . 3

1-1
1-2
1-2
1-3
1-3
1-4
1-4
1-4
1-7
1-9
1-10
1-11
1-12
1-12
1-13
1-15
1-15
1-16
1-16
1-17

Task Names . . . . . .
The Synergy Interface Library
INSTALLING THE APPLICATION . . . .
Synergy Install File (.INS)
SYNERGY INSTALL FILE (.INB) FOR SHARED
APPLICATIONS . . . . . . . . . . . . .
Installing a standard PIOS application
iii

2-1
2-3
2-3

2-4
2-5
2-5

2-5
2-6
2-6
2-6
2-7
2-7
2-8
2-9
2-9
2-9
2-12
2-13

2.5

CHAPTER 3
3.1

3.2
3.3
3.3.1
3.4
3.4.1

3.4.2
3.5

CHAPTER 4
4.1
4.1.1
4.1. 2
4.1. 3
4.1. 4

4.2
4.2.1

4.2.2
4.2.3
4.3
4. 3 . 1
4.3.2
4.3. 3
4. 3 . 4
4.3.5
4.3.6
4.4
4.5
4.5.1
4.5.2

4.6
4.6.1
4.6.2
4.7
4.7.1

4.8
4.9
4.10
CHAPTER 5
5.1

RUNNING FROM THE TOOL KIT AND OTHER
APPLICATIONS

. .

. 2 -14

ADAPTING A P/OS APPLICATION
KEYBOARD USE . . . . . . .
SUSPENDING THE APPLICATION
SCREEN USE . .
Retaining the VT Window Type
MODIFICATIONS TO OTHER FILES
Task Build Files .
Install File . . .
USING THE CLIPBOARD

3-1

3-2
3-2

3-3
3-4

3-4
3-4
3-4

THE SYNERGY INTERFACE
INITIAL STATE · · · ·
At Synergy Start-up
At Window Creation ·
On Return from Suspend
After Other Window Operations
COLOR MAP
· · · · · · ·
WIZPSC - Zap Primary/Secondary Colors
WIZCMP - Zap Color Map Entry
WIRCMP - Reload Color Map
FONTS AND ALPHABETS
User-Defined Fonts · ·
WIRFNT - Restore Fonts
Special Font · · · ·
Text Fonts
· · · ·
Printing the Synergy Character set
Boxed Font ·
· · ·
IMPOSED DEVICE SPACE
· · · · ·
INTERTASK COMMUNICATION METHOD
Synergy Task Communication ·
Receiving Data Packets · · ·
CALL INTERFACE TO SYNERGY SERVICES
Parameters ·
· · · · · · · · ·
WICAL - - Call Window Service · ·
PASSING TYPE-AHEAD TO SYNERGY ROUTINES
MGTCB - Expand Call-Back Code
FILE USAGE
·
SPECIFYING KEY CODES
RESTRICTIONS

· ·
·

4-1

4-1
4-2

4-2
4-2
4-3
4-4
4-4
4-5
4-5

4-6
4-7
4-7
4-7
4-8
4-8
4-12
4-12
4-12
4-13
4-14
4-15
4-15
4-19
4-22
4-22
4-23
4-25

TASK CONTROL SERVICES
TASK CONTROL SERVICES

· · ·

. . . .

5-1

5.1.1
5.1. 2
5.1. 3
5.1.4
5.2
5.2.1
5.2.2
CHAPTER 6
6.1
6.1.1
6.1. 2
6.1. 3
6.1. 4
6.1. 5
6.1.6
6.1. 7
6.1. 8
6.1. 9
6.1.10
6.1.11
6.1.12
6.1.13
6.1.14
6.1.15
6.1.16
6.1.17
6.1.18
CHAPTER 7

WIDON - Application Done
· · · · ·
WIINI - Application Ini tialization
WIINT - Suspend the Application
WISYP - Get System Parameters
SYNERGY MESSAGE BOARD

. . · · · · ·

MGMSG - Send Message to Synergy Message
Board . . . . . . . . .
· · · · . . .
MGDMS - Delete Message from Message Board

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

WINDOW SERVICES
WINDOW SERVICES

Window Descriptor Block
Specifying Window Coordinates
Specifying Window IDs . . . .
WICHW - Change the Size and Position of a
Window . . . . . . . . . .
WICRW - Create a window
WIDSW - Destroy a Window
WIERW - Display Error Window
WIEWT - End wait Message . .
WIGEW - Get Window Parameters
WIHDW - Hide a Window . . . .
WIlDA - ID of a Window at a Point
WIPOW - Change position of a Window
WIPSW - Push a Window . . . .
WISLW - Select a Window . . . .
WISWP - Set Window Parameters
WISWT - Start Wait Message . .
WITTL - Change Title of Front Window
WIXSWT - Start wait with Message Frame. .

6-1
6-1
6-2
6-4
6-5
6-5
6-6
6-7
6-7
6-8
6-8
6-9
6-9
6-9
6-10
6-10
6-11
6-11
6-12

MENU SERVICES

FRAME FILE SERVICES . . . .
7.1
OPENME - Open Frame File .
7.1.1
CLOSEM - Close Frame File
7.1. 2
WIRMS - Read Message Frame
7.1. 3
HIGH-LEVEL MENU SERVICES
7.2
Menu Renditions
7.2.1
Key Usage . . . . . .
7.2.2
Termination Key List
7.2.2.1
Single-Choice Menus
7.2.3
EXSING - Static Single-Choice Menu .
7.2.4
DSINGL - Dynamic Single-Choice Menu
7.2.5
..
HELP Menu . . . . . . . .
7.2.6
EXHELP - Static HELP Menu
7.2.7
Multiple-Choice Menus
....
7.2.8
.
EXMULT - Static Multiple-Choice Menu
7.2.9

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

7.2.10
7.2.11
7.2.12
7.2.13
7.2.14
7.2.15

7.2.16
7.2.17
7.2.18
7.2.19
7.3
7.3.1
7.3.2
7.4

7.4.1
7.4.2
7.4.3
7. 4. 4
7.4.5
7.4.6
7.4.7
7.4.8

7.4.9
7.5
7.5.1
7.5.2
7.6
7.6.1
7.6.2
7.6.3
7.6.4
7.6.5
7.6.6
7.6.7
7.6.8
7.6.9
7.6.10
7.6.11
7.6.12
7.6.13
7.6.14
7.6.15
7.6.16
CHAPTER 8
8.1
8.2
8.2.1
8.2.2

DMULTI c Multiple-Choice Menu
7-10
Flow control Menus . . . . .
. 7-11
EXFLOW - Static Flow Control Menu
7-12
DFLOW - Dynamic Flow Control Menu
. . 7-12
Set-up Menu
. . . .
7-12
WIXPS - Static Set-up Menu
7-13
WIPS - Dynamic Set
Menu
7-14
Messages
. . . . . .
. 7-16
EXMESS - Static Message Frame
7-16
DMESSA - Dynamic Message Frame
. 7-17
STRING EDITING. . . . . . . . .
7-17
WIXSTR - Alphanumeric String Editing
. 7-17
WIXNUM - Numeric String Editing
7-18
FILENAME SERVICES . . . . .
. 7-18
Old File . . . . . . . . .
7-19
WIXOLD - Static Old File .
7-21
OLDFLE - Dynamic Old File
7-21
WICOLD - Get Selected Filename
. 7-21
New File . . . . . . . . .
7-22
WIXNEW - Static New File .
7-23
NEWFLE - Dynamic New File
7-23
File . . . . . . . .
. 7-23
WIXANY - Static Any File .
7-24
DIRECTORY NAME SERVICES
7-24
WIXCHD - Get Directory Name
7-25
WIXSHD - Show Directory Names
7-25
PRIMITIVE MENU AND EDITING SERVICES
. 7-25
String Editing Primitives
. . . .
7-26
WICRS - Create String Editing Window
7-26
WIDES - Destroy String Editing Window
7-28
WIEr - Edit string Field. . . . . . . .
7-28
WIGKS - Get
from String Editing Window 7-29
WIHDR - Change header
. . 7-30
Menu Primitives
. . . . . .
. 7-30
WICRM - Create Menu Window .
7-30
WIDEM - Destroy Menu Window
7-32
WIENM - Change Option in a Menu
7-33
WIGKM - Get Key from a Menu
7-33
WIHDR - Change Header Line .
7-34
WIPOF - Turn Cursor Bar Off
7-34
WIPON - Turn Cursor Bar On .
7-34
WIPPS - Change Cursor Bar position
7-34
WISCM - Scroll Menu Options
7-35

THE FRAME COMPILER, FCT
INTRODUCTION TO FCT
FCT LANGUAGE
.TABLE
.FRAME Command Line

8-1
8-2

8-4
8-4

8.2.3
8.2.4
8.2.5
8.2.6
8.2.7
8.2.8
8.3
8.4
8.4.1
8.4.2
8.4.3
8.4.4
8.4.5
8.4.6
8.4.7
8.4.8
8.5
8.5.1
8.5.2
CHAPTER 9
9.1
9.1.1
9.1. 2
9.2
9.3
9.4
CHAPTER 10
10.1
10.2
10.3
10.3.1
10.3.2
10.4
CHAPTER 11
11.1
11.1.1
11.1. 2
11.1. 3
11.2
11. 2.1
11. 2.2
11. 2.3

.HOME Command Line . . .
.OPTIONS Command Line . . . .
.KEYS Command Line .
. ... .
Blank Line.
Text Line
·
A Binary Message Line
FCT LIMITATIONS
FRAME FORMATION RULES
Flow Control Menu
Single-Choice and Multiple-Choice Menus
Set-up Menu
. . . .
HELP Frame . . . . . .
Message Frame
. . . .
·
Binary Message Frame .
·
Alphastring and Numericstring Menu
VECTOR TABLE . . . . . . .
FCT OPERATING INSTRUCTIONS
FCT on VMS . . . . . .
FCT on PRO/Tool Kit

.
·
·
·
·
·
·
.
•
·
·
·

8-6
8-8
8-9
8-9
8-10
8-13
8-15
8-15
8-15
8-17
8-18
8-20
8 -21
8 -22
8-23
8-24
8-26
8-26
8-26

DEBUGGING THE APPLICATION'S WINDOWS
9-1
9-2
9-2
9-3
9-4
9-4

VUE APPLICATION
Installing VUE .
. . . .
Using VUE
. . . ..
....
MAKE SCREEN WHITE APPLICATION
PRINTING THE SYNERGY SCREEN
FDT TO FCT CONVERSION . . . . .
THE CLIPBOARD
INTRODUCTION TO THE CLIPBOARD
THE TEXT FILE
THE TABLE FILE . . . . .
Special Record Format
Data Record Format . . . . .
TABLE FILE EXAMPLES

· 10-1
10-2
· 10-2
10-3
10-4
· . 10 - 5

SYNERGY CONVENTIONS
WINDOW CONVENTIONS .
Titles . . . . . .
Cursor Use . . .
Size and Location
MENU CONVENTIONS . . .
placement
. . . .
Spelling and Capitalization
Structure and Wording

vii

11-2
11-2
. 11- 3
11-4
11-5
11-5
11-6
. 11-7

11. 3
11. 3.1
11. 3.2
11.3.3
11. 4
11. 4.1
11. 4.2
11.5
11. 5.1
11. 5.2
11.6
11.6.1
11. 6.2
11. 7
11. 7 .1
11. 7 .2
APPENDIX A
A.l
A.2
A.3

A.4
A.5
A.6
A.7

A.8
A.9
A. 9.1
A.l0
APPENDIX B

HELP CONVENTIONS . . . .
placement
. . . . .
Types of HELP Users
Structure of HELP
. . . . .
KEY USAGE CONVENTIONS
The Auxiliary Keypad
Individual Keys . . . . . . .
FILE CONVENTIONS
File Access
Filenames
ALTERNATE CONVENTIONS . . . .
Graph
. . . . . . .
Calculator . . . . . .
DOCUMENTATION CONVENTIONS
Terminology
Organization . . . . . .

. 11-9
. . . . 11-9
11-10
11-10
11-13
11-13
11-13
11-16
11-16
11-18
11-19
11-19
11-20
11-21

11-21
11-22

BATON TWIRLER
INTRODUCTION TO BATON TWIRLER
THE BATON.PAS FILE . .
THE GIDISOPS.PAS FILE
THE SYNERGY.PAS FILE .
THE GIDIS.PAS FILE . .
THE BATONFRMS.SFF FILE
THE BATON.CMD FILE .
THE BATON.ODL FILE .
THE BATON. INS FILE .
The BATON.INB File
THE BUILD.CMD FILE .

A-l
A-3

· A-41
A-45
A-50
A-62

A-69
A-70
A-71
· A-71
· A-72

TABLE OF SYNERGY SERVICES
GLOSSARY

INDEX
EXAMPLES

8-1
8-2

8-3
8-4
8-5
8-6
8-7

8-8

Comments in a Frame File
A Flow Control Menu
A Single-Choice Menu .
A Multiple-Choice Menu
A Set-Up Menu
A HELP Frame . . . .
A Message Frame
An Alphastring Menu
viii

8-3
· 8-16
8-17
8-18
8-19

8-21
8-22
8-23

8-9

A Numericstring Menu . .

1-1
1-2
1-3
1-4
1-5
2-1
2-2
7-1
7-2
7-3
7-4

Windows on the Screen
The Display Process
A Titled Window . . . .
Logical Pixel Mapping (GOS Units)
Window Dimensions in GOS Units .
Sample Install File
Sample (.INB) Install File
Old File Menu . . . . .
New File Menu . . . .
String Editing Window
Single-Choice Menu . . . .

4-1
4-2
4-3
6-1
6-2
B-1

Synergy Character Set
Returned Status Values
Key Encodings . . . .
Window Descriptor Block
Window Coordinates . . .
Table of Synergy Services

. .

. 8-23

FIGURES

. . . .
·
·
·
·

1- 5
1-6
1-8
1-13
1-14
2-12
2-13
7-20
7-23
7-27
7-32

TABLES

4-10
· 4-16
4-24
6-2
• • • 6- 3
B-1

PREFACE

MANUAL OBJECTIVES

This manual tells you how to build an application that
installed and executed in the Synergy environment.
software tools are also described.

can be
Synergy

INTENDED AUDIENCE

You should have some experience developing applications for the
Professional under P/OS. In particular, you should be familiar
with the Tool Kit, P/OS, PRO/GIDIS, and Synergy software for the
Professional.
SYSTEM REQUIREMENTS

You should have the following software:
•

Professional Host Tool Kit V2.0, or later,
or PRO/Tool Kit V2.0, or later

•

P/OS V2.O, or later

•

Synergy Vi.O, or later

STRUCTURE OF THIS DOCUMENT

The manual has eleven chapters, two appendices, and a glossary:
•

Synergy Overview introduces the Synergy environment, as seen
by an application developer.

•

Designing a New Application describes all aspects of
application design specific to the Synergy environment.

•

Adapting a P/OS Application describes the modifications
needed to move an application into the Synergy environment.

•

The Synergy Interface provides a general description of the
call interface between the application and Synergy services.

PREFACE
•

Task Control Services describes each of the Synergy services
that are used to control the execution of the application.

•

Window Services describes each of the Synergy services that
are used to create and manipulate the application windows.

•

Menu Services describes each of the Synergy services that are
used to display menus and solicit input from the end user.

•

The Frame Compiler describes the software tool that is used
to prepare menu, HELP and message frames.

•

Debugging the Application's Windows describes additional
software tools that are used to check the output of the Frame
Compiler and to take screen dumps on a printer.

•

The Clipboard describes the clipboard files and the rules for
their use.

•

Synergy Conventions describes the conventions that are used
in Synergy applications.

•

Baton Twirler provides listings of the files needed to build
a sample window application.

•

Table of Synergy Services is an alphabetized list of all
Synergy Services.

•

Glossary defines special terms used in the Synergy context.

ASSOCIATED DOCUMENTS

•

Tool Kit User's Guide

•

Tool Kit Reference Manual

•

PIOS System Reference Manual

•

PROIGIDIS Manual

•

Synergy User's Guide

xii

PREFACE

CONVENTIONS USED IN THIS MANUAL
Convention or Term

Meaning

[optional]

In
an
FCT command line format,
square
brackets indicate that the enclosed item is
optional. In a file specification,
square
brackets are part of the required syntax.

UPPERCASE

Uppercase words
and
letters,
used
in
examples,
indicate that you should type the
word or letter exactly as shown.

Mixedcase words in angle brackets, used in
FCT command line formats, indicate that you
should substitute a word or value of your
own. Usually the mixedcase word identifies
the type of substitution required.
A horizontal ellipsis indicates that you can
repeat the preceding item one or more times.
For example:
parameter [,parameter ... ]

Tool Kit

This general term refers to the software you
use to develop applications to run on a
Professional computer.

Host Tool Kit

The Host Tool Kit is Tool Kit software that
runs on a host computer, rather than on the
Professional itself.

PRO/Tool Kit

The PRO/Tool Kit is the Tool Kit software
that runs on the Professional computer.

User

The word "user" always refers to the person
utilizing the Synergy application that you
are building. You,
as
the
application
builder, are never referred to as the user.

Synergy services are described in a standard format:
ABCD - Sample Service Call
2 words (output)
word
(input)
n bytes (input)

Status
StringLength
InputString ( )
The uppercase

symbol

ABCD

the
xiii

global

symbol

defined

PREFACE

Synergy.
The call shown above expects three parameters called
Status, StringLength, and InputString.
Parameter names are
chosen
only
for
their
mnemonic content.
An additional
explanation is provided if the intention of the parameter is not
clear from its name. An array parameter is shown with a () after
the name.
The parameter's data type is shown to the right of each parameter
name. The use of the parameter as input or output is indicated.
The parameters must be supplied in the listed order.

xiv

CHAPTER 1

CHAPTER 1
SYNERGY OVERVIEW

1.1

INTRODUCTION TO SYNERGY

Synergy is an application that runs under the PIOS hard disk
operating system.
Synergy provides an environment for the
execution of applications. An application that is built to run
in the Synergy environment can use Synergy services to:
•

Create and manipulate windows on the screen

•

Solicit user input through fields in its windows

•

Solicit user input through menus in special windows

•

Provide message and HELP information in special windows

•

Suspend its execution, enabling other Synergy applications
and PIOS applications to run

•

Exchange data with other Synergy applications through a
common data exchange file called a "clipboard"

An application that is built to run in the Synergy environment is
designed and implemented with the Tool Kit, using any of the Tool
Kit languages and run-time support
facilities.
(Existing
applications that run under the PIOS hard disk operating system
can run in the Synergy environment, with some changes.)
Applications that take
management techniques
in this manual.

full advantage of the Synergy screen
will use most of the facilities described

1-1

APPLICATION CONTROL

1.2

APPLICATION CONTROL

Synergy consists of a collection of tasks
environment for
the Synergy applications.
thought of as providing two major functions:

that provide the
These tasks can be

•

The window manager presents the Synergy Main Menu and
provides the user interface for controlling windows and
tasks.
In the Synergy User's Guide all the functions that
are not performed by applications are discussed as though
they were being performed by the window manager, in order to
simplify the terminology and present Synergy as a single
entity.

•

The window server does the actual work involved in moving
windows and provides menu and HELP services.
Almost all
service calls from the application go to the window server.
(Even the window manager calls the window server to do its
screen manipulation.)

In this manual, we will speak of all the Synergy
provided by the window server.

1.2,1

services

being

The Active Application

Several Synergy applications can be running at the same time, but
only one application can alter information on the screen.
This
is the active application.
The front window is the only window for which a GIDIS viewport is
defined, and thus it is the only window whose display can change.
The active application owns the front window and is the only
application that should write in this window.
The active application also receives all keyboard input.
An application may consist of one task or several
tasks.
The
application can run with the terminal attached and can use an AST
routine to read the keyboard.
When an application gives up
control to the window server by calling the Suspend service, it
must detach the terminal and must ensure that none of its tasks
that continue to run do any I/O through the terminal.
The window server can service only one application and one
request at a
time.
You must ensure that
requests appear
serially, which means that any two tasks of your application must
not request a window service at the same time, and all tasks must
ensure that requests are sent in the proper order.

1-2

APPLICATION CONTROL

1.2.2

Installing and Removing Applications

Synergy applications are installed on both P/OS and Synergy
application menus, using the "Install application" option of the
P/OS Disk/Diskette Services Menu. After the user completes the
Application/Group Name Change Form,
a window appears near the
bottom of the screen, requesting that the user take an additional
action to select a Synergy group in which the application name is
to appear.
This request for a Synergy application group is necessary to
insert the application's name on the Synergy Main Menu.
You must
place a special command in your application's install file to
trigger this action during installation.
The user removes a Synergy application with
the
"Remove
application" option of the P/OS Disk/Diskette Services Menu. A
special command that you place in your application's install file
causes the application's name to be removed from the Synergy Main
Menu. No additional action is required by the user during
removal of a Synergy application.

1.2.3

Starting and Exiting the Application

The user starts the Synergy application from either the P/OS
Application Menu or the Synergy Main Menu. When the application
is suspended, control returns to the Synergy Main Menu.
If the user suspends the application and then suspends the
Synergy Window Manager
(in order to do some work at the P/OS
level), he can resume the application by simply starting it
again. Again, he has the choice of starting from either the P/OS
Application Menu or the Synergy Main Menu.
If the application exits without ever having been suspended,
it
returns to the point from which it was started.
Thus, an
application that is started from a P/OS Application Group menu
will return to that menu on exit,
provided it has not been
suspended. However, once an application has been suspended and
resumed, it returns to the Synergy Main Menu on exit.

1-3

APPLICATION CONTROL

1.2.4

Task Control Services Overview

There are three major services that control the
Synergy application:

execution

•

Initialize - This service is called when the application
starts.
It establishes a handshake with the Synergy system
and retrieves any application-specific data that was saved
the last time the application was run.

•

Suspend - This service is called when the application is
suspending its execution, usually in response to a press of
the FS key. Control is returned to the application when the
user tells the window manager to resume execution of the
application.

•

Done - This service is called when the application is about
to exit.
It passes application-specific data back to Synergy
so that it can be saved on behalf of the application.

1.3

WINDOWS IN SYNERGY

1.3.1

Window Description

A window is a rectangular area of the screen which serves to
focus the user's attention.
It usually has a dark border, called
the windowframe, and a light background.
It contains dark
letters or graphic images.
NOTE
A special window type is available, called a VT
window, to ease migration of an application from
the PIOS hard disk environ~ent to the Synergy
environment.
A VT window always occupies the
full screen, with no windowframe.
It usually
displays light letters and graphic images against
a dark background. VT windows are discussed only
in
Chapter 3.
Applications that take full
advantage of Synergy window facilities do not use
VT windows.

1-4

WINDOWS IN SYNERGY

A window is a rectangular area of
focus the end user's attention.
9f'OlJ'ld and a dark border, called
dirk letters of fraphic illagK.

POSfET

lEJ!!!J[!J[[]

~ application creates ore or .are
than writes to Rach window as
«?UtPut ~reen. All write
I7"lf"""ilrg-lr:-1
mstnJctUJn!S. The c\rSOr
L....:...JL...:..JL-.:..JL....-J
the ~p.,. left Corn&r' of the
the window is posi ti oned on the

Figure 1-1:

Windows on the Screen

An application creates one or more windows on the screen and then
writes to each window as though it were a separate output screen.
All write operations are done with GIDIS instructions.
The
cursor coordinates are given relative to the upper left corner of
the window, regardless of where the window is positioned on the
screen.
GIDIS automatically translates the window-relative
coordinates to screen-relative coordinates,
so the application
can be unaware of where the window actually is on the screen.
Windows are often smaller than a full screen.
Window positions
may intersect,
so that windows may obscure part or all of other
windows.
Each window exists at some level, exactly analogous to
pieces of paper lying on a desk: The top paper covers the parts
of all papers it overlaps; the bottom paper is covered by the
parts of all other papers that overlap it.
We use the terms "top" and "bottom" to describe the stacked
pieces of paper on the desk. We use the terms "front" and "rear"
to describe the stacked windows on the screen.
Each window is independent of all other windows,
so that the
application need not be concerned with whether the windows
overlap. There is no need to "tile" the windows on the screen.
The user may want to refer to two or more windows simultaneously
and thus may want to change the position of the windows in order

1-5

WINDOWS IN SYNERGY
to tile them. However, most applications can ignore this window
positioning activity.
Even when an application has more than one window, it can write
only to its front window. The application calls a Select Window
service to select any of its windows as the front window before
writing to it.
The Select Window service moves the window in
front of all other windows.
In order to guarantee that an application writes only to its own
windows,
the application is required to create the windows
through calls on the Synergy interface and then restrict its
writing to GIDIS instructions.
Synergy adjusts the GrDIS state
so that the application is always addressing the front window.
The application avoids doing text-mode QIOs to the screen in
order to guarantee that the cursor position stays within the
front window and to guarantee that the entire screen will not
scroll.
Creation and display of special windows for menus and HELP are
These
handled entirely through the Synergy window server.
require
windows, which usually have a short life on the screen,
very little development effort and very little space within the
application's address space.

WINDOW
SERVER

APPLICATION
SOFTWARE

GIDIS

1-6

WINDOWS IN SYNERGY

1.3.2

Window Attributes

All windows have a position and a size.
Windows may be
positioned anywhere on the screen, as long as they fit entirely
within the screen. They may be as large as the screen, or as
small
as one character.
The initial size,
position,
and
attributes of a window are defined when the window is created
with the Create Window service.
Windows consist of two parts: a windowframe and a writable area.
The windowframe is a black border surrounding the writable area
of the window. The position of the windowframe is defined by the
X and Y coordinates of its upper left hand corner. The writable
area of the window is specified by a width and height.
There are nine window attributes:
color,
white border,
clear on
three-plane.

stackable,
titled,
hidden,
change, VT,
invisible, and

Giving a window the stackable attribute
means
that
the
application promises to abide by some restrictions and that the
window server can take advantage of those restrictions and gain
some efficiencies in managing the window.
Stackable windows are
treated as a stack, that is, on a first-in,
last-out basis.
A
stackable window can be created in front of a nonstackable
window, but once a stackable window exists on the screen, only
stackable windows can be created in front of it.
Furthermore,
the stackable windows are destroyed in reverse order of their
creation.
The creation and destruction of these windows is not
interrupted by any other window operations, such as changes in
window size or reordering of the stack of windows. The stackable
attribute is used largely by the· window server when it is
creating menu and HELP windows in response to calls from the
application.
It can be used by applications,
provided the
applications abide by the same rules.
A maximum of four
stackable windows can exist on the screen at one time.
Certain
menu services can create up to three stackable windows, so you
should exercise care in calling menu services when you have
created more than one stackable window.
In a titled window the top of the windowframe is thicker and
contains title text. When the titled window is the front window,
its title is highlighted (light letters on a dark background).

1-7

WINDOWS IN SYNERGY

This is a titled window.

\
\

That's the title up there.

Figure 1-3:

A Titled Window

A hidden window is not visible at all on the screen, unless it is
the front window.
(Windows that are not hidden are always
visible unless they are totally obscured by the windows in front
of them.)
A color window can display color graphics.
A noncolor window
displays only black-and-white,
i.e., monochrome.
Because the
window server must manipulate three times as much information
when dealing with a color window, manipulation of a color window
is slower than manipulation of a monochrome window.
Normal
drawing speed is the same in monochrome and color windows,
however.
A window may have a white border between the windowframe and the
writable portion of the window. The white border attribute is
optional, since some applications may need to write to the edge
of the window.
A window with the clear on change attribute is blanked by the
window server after the user has changed the window size.
If
clear on change is not requested, the window contents are redrawn
after the change. Redrawing can take several seconds for large
color windows. An application that refreshs the entire window
following any size change should request the clear on change
attribute, so that time is not wasted.

1-8

WINDOWS IN SYNERGY
A VT window is a special, full-screen window that permits the
full range of terminal subsystem instructions, both text mode and
graphics mode. See Chapter 3.

I
I
I
I
I
I
I
I
I
t

An invisible window is one for which Synergy does not do any of
the normal video drawing operations. That is, ordinarily when a
window is created, Synergy fills it in with white, and draws the
windowframe
around
it.
For a window with the invisible
attribute, this is NOT done (no drawing whatsoever is done when
an
invisible
window is created
the video display is
unaffected). Also, ordinarily when a Synergy window is deleted,
the portion of the display "underneath" the window (other
windows, etc.) is restored automatically.
When an invisible
window is deleted,
this is not done.
The video display is
unaffected so that whatever was drawn into the invisible window
REMAINS after the invisible window is deleted. Note that this is
a dangerous thing to do, in that you can affect the contents of
other windows, or even of the gray Synergy background.
There are situations where it is advantageous to use an invisible
window.
You might want to use an invisible window to guarantee
that a certain sequence of PRO/GIDIS drawing instructions will be
restricted to a portion of the application's normal drawing
window, especially when the application does not have full
control over what that sequence of PRO/GIDIS instructions is (for
example .GID files that reset global addressing parameters). You
could create a normal window and display the contents in it, but
deleting the window will make the drawing disappear
(which you
may not want). Using an invisible window, you can do the above,
with the result that the drawing will appear in the portion of
the main window and will remain until that main window itself is
deleted.
The three-plane attribute is similar to the COLOR attribute,
except that a three-plane window requires that only EBO hardware
be present.
(Unlike the color attribute which requires a color
monitor and end-user authorization using the Synergy setup
feature).
For example,
the three-plane attribute makes gray
scale windows possible on a monochrome display.

1.3.3

Video Protocols

Synergy supports both text and graphics in non-VT windows by
requlrlng the use of the GIDIS protocol. Notice that GIDIS,
is quite
although designed primarily as a graphics protocol,
capable of displaying text as well.

1-9

WINDOWS IN SYNERGY
In order to avoid interference between windows, Synergy maintains
a private copy of the state of GIOIS for each window.
If an
application creates more than one window,
it switches between
them by selecting the desired window with a calIon the Select
Window service. Synergy saves the GIOIS state of the old window
and establishes the GIOIS state of the new window.
There is no "virtual window" larger than the actual window. Data
scrolled off a window is lost, just as data scrolled off the top
or bottom of a VT102 screen is lost. An attempt to write with
coordinates that are outside the actual size of the current
window results in clipping and loss of the data that is outside
the writable area of the window.
GIOIS provides the following character renditions:
italic (both
forward and backward) and reverse video. Oim, bold and underline
renditions can each be emulated by defining a font;
Synergy
defines special fonts that provide these character renditions.
Blink is the only VT102 rendition that is not available, although
the GIOIS block cursor can be used to blink a single rectangle of
any size.
Nearly all GIOIS operations are available, but applications
observe certain restrictions (see Section 4.10).

1.3.4

must

Resources

Synergy copies a window's part of the video bitmap to disk in
order to save the contents of the window for later restoration.
Each full-screen monochrome window requires 64 blocks (32 KB) of
disk memory to hold the bitmap, plus approximately two blocks to
hold the GIOIS state information.
A color window has three
planes of bitmap memory, so the requirements for storing the
color window's bitmap memory are tripled.
(The user must have a
color monitor, and must choose the color option on the Synergy
Set-up Menu, before the application can create a color window.)
Synergy allocates a raster file on the hard disk for use as a
storage area for application windows.
Demands on the raster file
increase as the user suspends applications and starts additional
applications.
If a peak demand exceeds the available raster
spacei Synergy extends the raster file.
The raster file shrinks
back to a minimum size when Synergy exits.
(Notice that Synergy
can exit only when all the Synergy applications have exited.
Suspending an application and suspending Synergy in order to
return to PIOS level does not constitute an exit.)

1-10

WINDOWS IN SYNERGY
If disk space is exhausted it may be impossible to extend the
raster file.
This condition can arise when the Synergy window
server is creating a new window in response to a service call
from your application. The "Raster error" condition is returned
to your application. The application must detect this error
return and alert the user. The procedure is outlined in Section
2.1. 5.

When an application starts, it usually creates at least one
window.
Although applications can create additional windows,
they should destroy any windows that are no longer needed.
This
frees space in the raster file and also keeps the screen from
being cluttered.
(All application
windows
are
destroyed
automatically when the application exits.)
There is a limit of 16 simultaneous windows.
Since most
suspended applications have only one or two windows on the screen
at the time of suspension, this limit is rarely reached.
When a window is created (or removed) in front of a color window,
the color window is saved (or restored). The time required to
save or restore the color window is three times the time for an
eqeivalent monochrome window. This tripling of time applies only
to the operadions on the color window, however. The time to save
or restore a monochrome window i3000t affected.
Copy time is approximately one second per full plana copied.
Therefore, changing from one full-screen color window to another
full-screen color window requires about six seconds.
NOTE

A window with the VT attribute is always treated
as a full-screen color window. All three planes
of video bitmap are saved and restored.

1.3.5

Changing the Window Size

An application can change its window size by calling a window
service.
In addition, the user can change an application
window's size while the application is suspended.
The user
changes the window size by using a Synergy Main Menu option.
Applications must therefore be able to adjust to a new window
size when control is returned from the Suspend call (WIINT). The
window server returns a signal that the window size has changed
and also returns the new width and height. The application may
or may not need to repaint the window to conform to the new size
(depending on what is being shown).
1-11

WINDOWS IN SYNERGY
Applications can restrict size changes by setting upper and lower
bounds on the window dimensions, and can create windows whose
size may not be changed at all.
The application never receives notification that the user has
moved the window to a new location on the screen, and there is no
way for the application to restrict
such
movement.
An
application that is sensitive to the screen position of its
windows can call the Get Window Parameters service, after each
Suspend call to determine the window position.

1.3.6

Coordinate Systems

The video hardware consists of an array of pixels, 1008 wide and
240 high.
(The video hardware is 1024 pixels wide, but Synergy
uses only the leftmost 1008 pixels.) Hardware coordinates are not
used to specify screen positions, however.

1.3.6.1 GIDIS Coordinates - GIDIS requires
that
coordinate
systems be isotropic.
A horizontal movement of N units must
cover the same physical distance on the screen as a vertical
movement of N units, so that geometric figures (such as circles)
have the correct proportions (e.g., round circles, not ovals).
A coordinate system based on hardware pixels is not isotropic
because the pixels on a Professional screen are not square -they have an aspect ratio of 2:5. They are two and a half times
higher than they are wide.
Synergy defines a matrix of "logical" pixels that is mapped to
the hardware pixels.
The logical pixels are isotropic and
smaller than hardware pixels. Specifically, a logical pixel is
half as wide and one fifth as high as a hardware pixel.
This gives Synergy a coordinate system with horizontal positions
ranging from 0 on the left to 2015 on the right, and vertical
positions ranging from 0 at the top to 1199 at the bottom.
This
defines a screen which is 2016 logical pixels horizontally by
1200 logical pixels vertically.
Notice that since the standard character cell is 12 hardware
pixels wide
(24 logical pixels),
the Synergy screen holds
2016/24, or 84 full characters,
rather than the usual 80
characters.
In a window that has a windowframe and a white
border, the writable area is reduced to 2000 GOS units, or 83 1/3
characters.

1-12

WINDOWS IN SYNERGY

5 GOS UNITS

1 HARDWARE PIXEL

2 GOS UNITS

Figure 1-4:

Logical Pixel Mapping (GOS Units)

Logical pixels are defined by Synergy and are known as GOS units
(GIDIS Output Space units).
(An application can define its own
GOS units since they are part of the state information that is
saved and restored for each of the application's windows.)
Further discussions of coordinates in this document refer to the
Synergy-defined GOS units.

1.3.6.2 Window Dimensions - Synergy defines the windowframe to
be 2 GOS units wide on the left, 6 units on the right, and 10
units on the bottom.
If there is a title,
the top of the
1-13

WINDOWS IN SYNERGY

windowframe is 65 units high.
If there is no title, the top of
the windowframe is 5 units high.

WINDOWFRAME

...- - 6

•

2 - _ ......

OVERALL
WINDOW
HEIGHT
WINDOW WIDTH

Figure 1-5:

Window Dimensions in GOS Units

The windowframe is thicker on the right and at the bottom to give
a shadow effect.

1-14

WINDOWS IN SYNERGY
The optional white border between the windowframe and the
writable area is 5 GOS units above and below the writable area,
and 4 GOS units to the left and right of the writable area. Most
applications request the white border so that the information
that they place in the writable area
cannot
touch
the
windowframe.
The outside dimensions of the windowframe must be a multiple of
32 GOS units in width and a multiple of 5 GOS units in height.
You request the window size by specifying the dimensions of the
writable area, however.
The window server will scale your
requested size upward, if necessary, to guarantee that when the
optional white border and windowframe are added, the total window
size satisfies these multiples.
Normally an application is not concerned with exactly how large
the window is, although there is a window service (WIGEW) that
returns all of the exact sizes to your application.
An attempt to create a window with a writable area greater than
the width or height of the screen returns an error. If the width
and height for the writable area can be accommodated, but the
frame and white border cannot, the window server reduces the
writable area to accommodate the full window.
Thus, a request
for a window with a writable area that is 2010 units wide and
1190 units high would create a window with a writable area that
is 2000 units wide and 1170 units high.
Creating a window of width and height equal to zero results in
full screen window with no white border or window frame.

1.3.7

Window Positions

You can request that a window be placed at any horizontal or
vertical position, but the window server always adjusts the
coordinates that you supply by rounding them down to the nearest
positioning unit. Synergy positions every window horizontally on
units of 16 hardware pixels, or 32 GOS units. Synergy positions
every window vertically on a hardware pixel, or 5 GOS units.
This means that if you specify a window position that is anywhere
between 0,0 and 31,4, the window server adjusts the position down
to 0,0. Likewise a requested position that is between 32,5 and
63,9 is adjusted to 32,5.

1.3.8

Window Services Overview

There are numerous window services, but the
1-15

primary

service

WINDOWS IN SYNERGY

the call to create a window. This service must be called to
create the application's window.
If the application
uses
additional windows,
the call is repeated to create each such
window.
The remaining window services are used to modify the window's
size,
position, or title.
There is a service that requests an
update of the window information from the window server, in case
the user has modified the window'S size or position while the
application is suspended.

1.4

MENUS

A menu is a special window that is used to solicit input from the
user.
The input can be in the form of a selection from the menu
choices, or entry of a string of characters or numbers.
It is important that menu operations be
applications,
so that the user need not
interface for each application.

uniform for
all
learn a new human

Menu services are defined at two levels:
•

The high-level services typically create a window, display
information in it, solicit a response from the user, destroy
the window, and return the response to the application, all
in a single call.

•

The low-level services, called primitives, can be used to
perform the same action over a sequence of calls.
You can
use primitives when you want to alter the system's behavior
in its interaction with the user.

1.4.1

High-level Menu Services

High-level services are provided for your convenience and to
foster a consistent human interface among different applications.
(All high-level menu functions are actually implemented within
the window server by calls on primitives.)
Services are provided for single and multiple choice menus,
message frames, HELP frames and HELP menus, and set-up menus.

1-16

MENUS
Many services are available in two forms, static or dynamic.
A
static call passes a frame ID and relies on the window server to
fetch most of the window description from a frame file.
A
dynamic call passes all window data directly from the application
at run time.
A frame file is a file that accompanies the application's task
image (or images). It contains frame descriptions, which can be
specified using a frame ID. Each frame description includes a
frame type, positioning information, and text that is to appear
in the frame. The application can have only one frame file open
at anyone time.
The frame file contains all types of frames
(menu, HELP, etc.).

1.4.2

Primitive Menu Services

The primitive menu services provide a means for creating a menu
or an editing window with one call, then manipulating the
contents of the window with additional calls. The window must be
destroyed with yet another call when interaction with the user is
completed.
This requires more work on the part
of
the
application developer, but lends flexibility and control to the
behavior of the menu.

1-17

CHAPTER 2

CHAPTER 2
DESIGNING A NEW APPLICATION

This chapter presents guidelines for designing a new application.
Perhaps no application can truly be called a new application,
since most embody some aspects of an existing application, if not
the actual source code.
"New" in this context simply means that
the developer has the inclination (and the time!) to consider the
visible,
interactive part of the application and to design or
redesign it so that it is consistent with the existing Synergy
models of the human interface.

2.1

THINKING ABOUT THE HUMAN INTERFACE

An excellent discussion of the human interface appears in the
Digital Press Book, The Human Factor, by Richard Rubinstein and
Harry Hersh.
This book develops over 80 guidelines for good
human interface design.
Although the Synergy tools and services make it convenient to
build an application that has a well-designed human interface,
good design does not happen automatically.
There are a
large
number of decisions that must be made at every level of design to
ensure a consistently good human interface.

The Human Factor urges the reader to test an application with
representative users before committing it to distribution.
The
experience of the Synergy developers enforces this message.
Even
a small amount of such testing can reveal important flaws in the
design.
Often, design is based on assumptions about the user's
experience or ability to cope with mistakes.
Testing can reveal
whether these assumptions are true and can suggest minor changes
that may make a large difference in the user's success with the
application.

2-1

THINKING ABOUT THE HUMAN INTERFACE
The Synergy applications are "integrated."
two things:

Integration

•

The movement of data between applications

•

The human interface of the applications

involves

The clipboard method of moving data between applications employs
an easy-to-use data file.
The clipboard uses no new programming
technique.
It is simply a standardized file
format and file
naming convention.
The clipboard provides the user with a
conceptual model of the data flow between applications that
parallels
the
passing
of a clipboard containing written
information between two people.
Furthermore,
each application
that uses the clipboard names it, discusses it, and displays the
options for using it, in the same way.
The utility of the
clipboard
relies on adherence by all applications to the
conventions that create it as a model.
Nothing prevents the design of Synergy applications that can
share data using techniques other than the clipboard.
The user's
expectation, however, is that the clipboard is the medium for
data sharing; and users will expect to see a Synergy application
use the clipboard. Alternate methods of data sharing may puzzle
users and require additional learning on their part.
The remainder of Synergy's integration
window and menu interface and the
through the keyboard.
Each application appears to the user
on the screen.
Each application
through standard pop-up windows that
use of the keyboard to
respond
uniform across all the applications.

relies entirely on the
user's manipulation of it

through one or more windows
solicits input from the user
contain menus or forms.
The
to these menus and forms is

The Synergy system provides a large number of service calls that
make it convenient for you to present this human interface in
your application.
Although the text in your menus arld forms
is
unique to your application, the user is already familiar with the
look and feel of this interface, since all Synergy applications
use it.
Chapter 11 presents the conventions that are
recommended for
designing a fully integrated Synergy application.
You may
encounter a conflict between the model established by the Synergy
applications and an alternative model that may be suggested by
your application.
You must decide on the tradeoffs between
conflicting models.
within the applications that make up the
Version 1.0 Synergy system, there is evidence of these tradeoffs.
In certain cases,
the developer either felt that the Synergy

2-2

THINKING ABOUT THE HUMAN INTERFACE
conventions were too restrictive or that an alternative model was
already
established
in the user's mind and so chose an
alternative to the Synergy model.
Chapter 11 contains
a
discussion of some tradeoffs that were made in the Version 1.0
Synergy applications.

2.1.1

The Type of Interaction

The Synergy conceptual model is to put information on the screen
in such a way that the user sees as much as possible of his
immediate memory portrayed in front of him. The intention is to
reduce the need for the user to remember things, over either the
short term or the long term.
This is the point of a menu-driven system versus a command-driven
system.
Instead of remembering the syntax and spelling of a
command line, the user sees the relevant information on the
screen and chooses from it.
The menu of relevant choices is
portrayed in a window that is just big enough to contain it.
This tends to focus the user's attention to the smallest amount
of information required for the next action and also leaves the
most recent events in view, represented by other windows behind
the menu.
If the user asks for HELP, the HELP text appears in another
window, which again focuses attention and leaves the recent
context in view behind the window.
The same type of interaction can
carryover
into
the
application's use of windows. The application can show the user
what the current information is, and can invite the user to
interact directly with that information in the window. The
application can switch between two or more windows,
if the
information takes different shapes (the Graph application puts
data in one window and the picture of the data in another
window), or if the information comes from different locations
that must be shown each in its own context.

2.1.2

The Screen Contents

The Synergy screen consists of overlapping windows. One of the
windows is always the front window, the window that commands the
user's most immediate attention. The windows behind the front
window present a context for the user. They can be ignored if
they are not needed in order to deal with the front window, or
they can be consulted. The user is given a standard interface
for moving the application windows about on the screen, so that
2-3

THINKING ABOUT THE HUMAN INTERFACE

windows that are moderate in size can be located so that they
remain in view while the front window is addressed.
In planning your application's use of windows, keep in mind that
the windows behind the front window may be useful to the user,
either because he actually wants to consult them for their
information, or because they provide a
reminder of the most
recent actions.
The front window automatically provides an area of greatest
attention, but within the window there should always be a point
of attention. This is usually a blinking cursor or cursor bar.
The movement of this point of attention provides clues to the
user concerning the action of the program. Confirmation of the
user's actions is often shown by a simple change in the shape or
location of the cursor.

2.1.3

The Keyboard

Synergy uses the keyboard in essentially the same way as PIOS,
but adds specific meaning to more of the function keys. All
Synergy applications assign the same meaning to the F5 key,
and
most Synergy applications assign a common meaning to the Fil,
F12, F13, and ADDTNL OPTIONS keys, which is to display the
application's top level menu, called the flow control menu.
Synergy provides a menu and HELP interface similar to the PIOS
menu and HELP interface. Users can make menu choices by using
the ARROW keys to move the cursor or by typing the leading
characters of the menu option. The DO, RETURN, and HELP keys are
used in the same way.
The Synergy interface presents a model in which the keyboard is
attached only to the front window.
When menus appear on the
screen, keyboard actions are taken as responses to the menu
window. When the menu is removed, the keyboard actions are taken
as responses to the new front window.
In addition,
the Synergy
Window Manager permits the user to define certain keys as strings
of keystrokes. When the user presses one of these user-defined
keys
(UDK), the Synergy Window Manager substitutes the string of
keystrokes.
This model of keyboard use requires that all Synergy applications
buffer their keyboard input through a character-passing buffer.
The character-passing buffer is an implied parameter of many
Synergy service calls.
A detailed description of the characterpassing buffer and its use is given in Section 4.7.

2-4

THINKING ABOUT THE HUMAN INTERFACE

2.1.4

The Format of HELP

Synergy HELP is always invoked by the HELP key and always appears
in a window.
Each HELP window contains a HELP message and menu
options that lead to more HELP.
Since the HELP window is in front of the most recent window,
the
context in which the user requested the HELP is usually visible.
The HELP services that are provided and the conventions that are
recommended in Chapter 11 make it possible to provide extensive
on-line HELP that most users can use without feeling lost.

2.1.5

The Handling of Errors

Error conditions are detected
execution of your application:
•

User errors

•

Programming errors

•

Resource errors

•

Application abort

The methods for handling
following sections.

these

various

errors

are

levels

during

discussed

the

2.1.5.1 User Errors - When the user makes an error responding to
your application, you may want to inform the user by displaying a
message in your application window or by displaying a message in
a special message window.
If you choose to show the message in a
special window, the Synergy convention is to request that the
user press the RESUME key in order to proceed.
You may want to keep the message window short, assuming that the
user's mistake is one of carelessness rather than ignorance. The
Synergy service that displays your message frame has an option
for linking a HELP frame to the message frame.
If the user
presses the HELP key while the short message frame
is on the
screen, he sees another window with the HELP message in it.
You
can place the longer explanation of the error condition (and how
to correct or avoid it) in the HELP window. The HELP window can
even lead into a tree of additional HELP information.
You can
design and program much of this user assistance in a way that
keeps it outside your application task.
Thus,
the application
code merely detects the error condition and makes a single call

2-5

THINKING ABOUT THE HUMAN INTERFACE

on the Synergy service to start the user assistance.

2.1.5.2 Programming Errors - These are the errors that you
expect will never happen,
such as hardware faults or bounds
checks on array accessing.
Many of the Tool Kit languages supply run-time systems that
attempt to report these kinds of errors on the terminal, either
by writing error messages directly to the screen (in text mode),
or by calling a service in the POSRES cluster library.
You must
short-circuit these potential text-mode outputs to the screen,
since such a message would likely be written outside your
application window.
You should request that all error conditions
be returned to your application code, so that you can report the
error without affecting the remaining application windows.
(You
may be able to sever the requirement that the language run-time
system makes on the POSRES cluster library, and remove the POSRES
library name from the command file that you use to build the
application task.)
When your application reports this type of error to the user,
it
should tell the user that the error is not his error.
It should
also give the user some information that will help you to
pinpoint the problem when the error is reported.

2.1.5.3 Resource Errors - When you create a window or execute a
menu service that creates a window, the window server may need to
extend the raster file.
If the disk is full the extend request
fails and the service returns an error status.
You may encounter
the resource problem again if you try to display an error message
in a normal message window, since this will also try to create a
new window.
Synergy always reserves the resources necessary to
display a special window called the error window.
If your
application detects the status return that signals a
resource
error,
you should call the Error Window service, then exit the
application.

2.1.5.4 Application Abort - The user can press INTERRUPT DO
(or
CTRL/C) while your application is running.
If you have requested
that the Signal be returned to your application, it is returned.
If your application does not make this request, the Synergy
window manager gets the signal and terminates your application,
with a message to the user.

2-6

FITTING INTO THE SYNERGY MODEL

2.2

FITTING INTO THE SYNERGY MODEL

Most Synergy applications have a sequence
the user that follow this pattern:

interactions

with

On starting, the application creates its titled window on the
screen.

If the application normally deals with data in a file, the
application puts a file selection or file creation window on
the screen in front of its application window.
(The
application can supply copyright information or welcoming
information in the application window or in the header area
of the file selection window.)

The user indicates what file is desired.

The application begins its work in the application window.

The user reacts with data in the application window and calls
up menus by pressing any of the Fll, F12, F13 or ADDTNL
OPTIONS keys.

The user asks for HELP at any time by pressing the HELP key.

The user suspends the application to do work in other
applications, or to manipulate windows on the screen, by
pressing the F5 key.
The user resumes the application by
selecting the application again.

The user leaves the application by pressing the MAIN SCREEN
key or the EXIT key.
MAIN SCREEN causes the application to
save any work that has been done.
EXIT causes the
application to give the user a choice of saving new work or
quitting without saving it.
Both keys return the user to the
Synergy Main Menu.

2.3

BUILDING THE APPLICATION

Your application consists of one or more task images and an
install file
that tells PIOS how to install and remove the
application and how to start it when the user selects it from a
PIOS Application Group Menu.
An application task image is constructed with the Professional
Application Builder
(PAB),
using your object modules and the
object library supplied with the assembler or compiler that 'you
are using.
The files and procedures to be followed are described

2-7

BUILDING THE APPLICATION
in the Tool Kit User's Guide and the Tool
Kit
and in the documentation that accompanies
compiler that you are using.

Reference Manual
the assembler or

A Synergy application uses Synergy services to manipulate windows
and to display menu and HELP frames.
The Synergy services are
supplied in separate task images and an object library.
Your
application task interfaces to these Synergy services through
routines that are linked as part of your task image.
The
interface routines are drawn from the Synergy Interface Library,
which you supply during task build.
In addition to the
install file and the task images,
your
application contains an object frame file.
The object frame file
contains the menus, HELP frames and message frames
that are
displayed by the tasks during their execution.
You create the
source frame file by writing it in a frame language.
The source
frame
file
is then compiled into an object frame file by the
Frame CQmpiler Tool, FCT.

2.3.1

Task Names

All Synergy applications run as spawned tasks from the- Synergy
window manager task.
Hence all Synergy tasks must have unique
task names.
The following names are already in use
tasks:
CETSK - PROSE PLUS
CHESS - Chess
GEDFOl - PROSE PLUS
GEDSYN - PROSE PLUS
MXPRO - Communications
PRSSK - PROSE PLUS
PVUSYN - File Services
SPLCHK - PROSE PLUS
SPSHEE - Spreadsheet

SPSRES
WIAG
WICAF
WICAT
WICNV
WIFSV
WIRG
WIRS

Synergy

Version

1.0

- Spreadsheet
- Graph
- Calculator
- Calculator
- Datamanager Convert
- File Services
- Datamanager
- Datamanager

All task names used in future releases of Synergy will have the
WI prefix,
so you can avoid conflicts by not using the above
names or any names beginning with WI.

2-8

BUILDING THE APPLICATION

2.3.2

The Synergy Interface Library

The name of the Synergy Interface Library is LB:[1,5]WINLIB.OLB.
The application in Appendix A makes reference to this library
(see page A-70).

2.4

INSTALLING THE APPLICATION

A Synergy application is installed on a
P/OS Application Group
menu and also on the Synergy Main Menu.
The Synergy application
can be started from either menu.

I
I
I

I
I
I
I
I
I
I
I
I
I
I
I
I

I
I
I

I
I

I
I
I

I
I

Some special commands are required in the
install
file
of a
Synergy application.
There are additional rules for the install
file if you wish to create a "shared" application to be run from
P/OS V3.0.
Shared applications in P/OS V3.0 require an .INB file
in addition to the
.INS file
required for
P/OS V2.0
(see
PRO/Toolkit
Manual).
The
following
sections
describe
modifications needed for both the .INB file and the .INS file.

2.4.1

SYNERGY INSTALL FILE (.INS)

The application installation file
a special comment line:

(the .INS file) must begin with

lSYNERGY/I2
Do not insert a space between the exclamation point and the
following S.
This line indicates to Synergy that this is a valid
Synergy application install file.
There are additional
switches
that can be applied to this line and these will be described
later.
The next modification to the .INS file is immediately after the
'Name'
command line.
Insert these three lines after the 'Name'
command line:
FILE [ZZPROVUEjSYNCHK2.TSK/DELETE
FILE [ZZPROVUEjSYNERR.HLP/KEEP
EXECUTE [ZZPROVUE]SYNCHK2.TSK/INS

I
I
I
I

These commands copy two files to the hard disk upon installation
and execute the SYNCHK2 task.
The purpose of the SYNCHK2 task is
to verify that correct version of the Synergy Window Manager
(V2.0) is already installed on the user's system.
If the correct
version of the Synergy Window Manager is not on the user's system

2-9

INSTALLING THE APPLICATION
an appropriate error message will be displayed.
The two file lines imply that you must have these two files
(SYNCHK2.TSK and SYNERR.HLP)
on your application diskette in
directory [ZZPROVUEj.
Therefore,
before
completing
your
application diskette you must copy these files from the Synergy
Tool Kit diskette (SYNTK1) to your first application diskette in
directory [ZZPROVUEj.
The next modifications to your .INS file allows Synergy to update
its Main Menu whenever the application is installed or removed
from the P/OS application menus.
•

Application installation:
EXECUTE [ZZPROVUEjINSAPP.TSK/INS
This command is placed in the install file immediately before
the first "Install" command line. When the user installs the
application, INSAPP.TSK ensures that the application name is
added to the Synergy Main Menu .

•

Application removal:
EXECUTE [ZZPROVUEjREMEXE.TSK/REM
This command is placed in the install file immediately before
the first "File" command line.
If the user removes the
application, REMEXE.TSK ensures that the application name is
also removed from the Synergy Main Menu.

After installation, the Synergy application can be started from
either the P/OS Application Menu or the Synergy Main Menu.
(If
the application is suspended with the F5 key, control returns to
the Synergy Main Menu.)
In order to ensure that the Synergy
Window Manager is in control when the application is started from
the P/OS menu, the install file does not call for the running of
the application, but instead directs P/OS to run the Synergy
Window Manager.
The commands that would normally be in the
install file for running the application are made into comment
lines by placing an exclamation mark in front of the command.
When the window manager begins to run, it reads the install file
and executes the commented commands;
and then it starts the
application by spawning it.
If the application were not a Synergy application, its .INS file
might have the following commands:
(Assume the application task
name is APLNAM in the file APPLFILE.TSK.)

2-10

INSTALLING THE APPLICATION

INSTALL [ZZSYSjPBFSML.TSK/LIBRARY
INSTALL APPLFILE.TSK/TASK
RUN
APLNAM
As a Synergy application, the INSTALL and RUN commands are made
into comments and two new commands are inserted, causing the
Synergy Window Manager to be started. The result is:
lINSTALL [ZZSYSJPBFSML.TSK/LIBRARY
!INSTALL APPLFILE.TSK
!RUN
APLNAM
INSTALL [ZZPROVUE]SYNRUN.TSK/TASK
RUN
WI$MGR
If the .INS file contains ASSIGN commands, these too must be made
into comments.
Thus,
an ASSIGN MENU MYMENU.MNU line becomes
!ASSIGN MENU MYMENU.MNU.
Figure 2-1 shows a side-by-side comparison of an application's
.INS file as it would be for a non-Synergy application and as it
is after Synergy modifications.
Assume that the
original
application uses the P/OS menu and HELP services available
through the POSRES cluster library. Assume that the application
is rewritten to include some Synergy menu services that use a
Synergy frame file, but that it continues to use the P/OS menu
and HELP services as well.
AFTER

BEFORE

NAME "Sample"

FILE SAMPLEVl.TSK/DELETE
ASSIGN MENU MYMENU.MNU
ASSIGN HELP MYHELP.HLP
INSTALL [ZZSYS]PBFSML.TSK/LIBRARY
INSTALL SAMPLEVl.TSK/TASK
RUN SAMPLE

Figure 2-1:

!SYNERGY/I2
NAME "Sample"
FILE [ZZPROVUE]SYNCHK2.TSK/DELETE
FILE [ZZPROVUE)SYNERR.HLP/KEEP
EXECUTE [ZZPROVUE]SYNCHK2.TSK/INS
EXECUTE [ZZPROVUE]REMEXE.TSK/REM
FILE SAMPLEFRM.OFF/DELETE
FILE SAMPLEVl.TSK/DELETE
!ASSIGN MENU MYMENU.MNU
!ASSIGN HELP MYHELP.HLP
EXECUTE [ZZPROVUE]INSAPP.TSK/INS
!INSTALL [ZZSYS]PBFSML.TSK/LIBRARY
!INSTALL SAMPLEVl.TSK/TASK
!RUN SAMPLE
INSTALL [ZZPROVUE]SYNRUN.TSK/TASK
RUN WI$MGR

Sample (.INS) Install File

2-11

INSTALLING THE APPLICATION

2.4.2

SYNERGY INSTALL FILE (.INS) FOR SHARED APP

As mentioned in a previous seC~lon,
the
.INB file allows an
application
to
be
shared
on the PjOS v3.0
ication
environment.
The .INS file is similar to the
.INS file axe
that it contains additional information on the specific
acement
of the application files.
Refer to the Tool Kit Reference Manual
for more information on shared applications.
To create a shared application, you will need both a
.INS file
and a .INS file on your application diskette.
If you do not wish
to create a shared application you will not need the
.INS file
which is described in this section.

NOTE
The .INS file can only be tested on a
system.

PjOS

V3.0

As with the .INS file, the shared application installation
(the .INS file) must begin with a special comment line:

file

lSYNERGYjI2
The next modification to the .INS file is immediately after the
'Name'
command line.
Insert these four lines after the 'Name'
command line:
FILE [ZZPROVUEjSYNCHK2.TSKjDELETE
FILE [ZZPROVUEjSYNERR.HLPjKEEP
EXECUTE [ZZPROVUEjSYNCHK2.TSKjINSjUSR
EXECUTE [ZZPROVUEjSYNCHK2.TSKjINS
The next modifications to your .INE file allows Synergy to update
its Main Menu whenever the application is installed or removed
from the PjOS application menus.
Insert the following two command lines before the first "Install"
command line:
EXECUTE [ZZPROVUEjINSAPP.TSKjINSjUSR
EXECUTE [ZZPROVUEjINSAPP.TSKjINS
Then insert the following two
"File" command line:

command

lines

before

the

first

started

from

EXECUTE [ZZPROVUEjREMEXE.TSKjINSjUSR
EXECUTE [ZZPROVUEJREMEXE.TSKjINS
After installation, the Synergy application can be

2-12

INSTALLING THE APPLICATION
either the P/OS Application Menu or the Synergy Main Menu.
If
the shared application were not a Synergy application,
its
.INB
file might have the following commands:
INSTALL [ZZSYSjPBFSML.TSK/LIBRARY/CLUSTER
INSTALL APPLFILE.TSK/TASK/NETWORK
RUN APPLNAM
As a Synergy application, the INSTALL and RUN commands are made
into comments and two new commands are inserted causing the
Synergy Window Manager to be started. The result is:
!INSTALL [ZZSYSjPBFSML.TSK/LIBRARY/CLUSTER
!INSTALL APPLFILE.TSK/TASK/NETWORK
!RUN APLNAM
INSTALL [ZZPROVUEjSYNRUN.TSK/TASK/CLUSTER
RUN WI$MGR
If the .INB file contains ASSIGN commands, these too must be made
into comments.
For example,
an ASSIGN MENU MYMENU.MNU line
becomes !ASSIGN MENU MYMENU.MNU.
Figure 2-2 shows a side-by-side comparison of an applications's
.INB file as it would be for a non-Synergy application and as it
is after Synergy modifications.
AFTER

BEFORE

NAME 'Sample"

FILE SAMPLEVl.TSK/DELETE/NETWORK
ASS I GN MENU MYMENU. MNU
ASSIGN HELP MYHELP.HLP
INSTALL [ZZSYS]PBFSML.TSK/LIBRARY/CLUSTER
INSTALL SAMPLEV1.TSK/TASK/NETWORK
RUN SAMPLE

Figure 2-2:
2.4.3

ISYNERGY/12
NAME 'Sample"
FILE [ZZPROVUE]SYNCHK2.TSK/DELETE
FILE [ZZPROVUE]SYNERR.HLP/KEEP
EXECUTE [ZZPROVUE]SYNCHK2.TSK/INS/USR
EXECUTE [ZZPROVUE]SYNCHK2.TSK/INS
EXECUTE [ZZPROVUE]REMEXE.TSK/REM/USR
EXECUTE [ZZPROVUE]REMEXE.TSK/REM
FILE SAMPLEFRM.OFF/DELETE
FILE SAMPLEV1.TSK/DELETE/NETWORK
!ASSIGN MENU MYMENU.MNU
!ASSIGN HELP MYHELP.HLP
EXECUTE [ZZPROVUE]INSAPP.TSK/INS/USR
EXECUTE [ZZPROVUE]INSAPP.TSK/INS
I INSTALL [ZZSYS)PBFSML.TSK/LIBRARY/CLUSTER
!INSTALL SAMPLEVl.TSK/TASK/NETWORK
IRUN SAMPLE
INSTALL [ZZPROVUE]SYNRUN.TSK/TASK/CLUSTER
RUN WI$MGR

Sample (.INS) Install File

installing a standard P/OS application

It is possible to install a standard (non-Synergy)
application
into the Synergy environment. The main advantage of this is to
allow a non-Synergy application to be .run from the Synergy Main
Menu as well as the P/OS application menus.

2-13

INSTALLING THE APPLICATION

To install a non-Synergy application,
modify the non-Synergy
application's install file as specified in the previous sections
(2.4.1 and 2.4.2).
Then place a "VT" switch on the "!Synergy/I2"
command line.
The Synergy command line should appear as follows
in your. install file:

!SYNERGY/I2jVT
Once you have made these modifications to your non-Synergy
application's install file and have installed the application, it
will appear
in both the Synergy Main Menu and the
P/OS
Application Menu.
You can now run this appliction from the Synergy Main Menu.
The
"VT"
switch that appears
in the install file tells Synergy to
create a
full
screen VT style window before starting the
application.
This preserves the rest of the Synergy environment
while you are running in Synergy.
When you exit the application
the VT style window is deleted and the Synergy environment is
restored.

NOTE
This modification does not provide any additional
functionality to the application.
It simply
allows you to run a non-Synergy application from
the Synergy environment.
If you wish additional
'Synergy-type' functionality in the application
(such as Suspend or Window menus) the application
itself must be modified.

2.5

RUNNiNG FROM THE TOOL KIT AND OTHER APPLICATIONS

When you are developing an application from the PRO/Tool Kit,
it
is convenient to be able to start the application from the Tool
Kit, rather than from P/OS Main Menu level.
In addition, it may
,be desirable to start a Synergy application by spawning it from a
non-Synergy application.

NOTE
The execution of a Synergy application from
the
Tool Kit may place a heavy demand on system
resources.
The Synergy Window Manager accepts a command line at start-up and
uses the command line to determine the context under which it is
being started.

2-14

RUNNING FROM THE TOOL KIT AND OTHER APPLICATIONS

•

The
ication can be started by selecting it from either
the
ication Group menu or the Synergy Main Menu.
i
method of starting uses the application's install file.
The commands in the install file call for installation of the
SYNRUN.TSK file and execution of the window manager task, as
described in the preceding section.
In this case, there is
no c
line being passed to the window manager.

•
fall

window manager can be started from DCL by executing the
ng
ree commands:

$ INSTALL L8:[ZZPROVUEjSYNRUN.TSK
$~\fI $MGR/COMMAND==" MANAGER"
:;> REMOVE WI $MGR
Th s
thod of starting passes the command "MANAGER" to the
wi
ow manager.
The window manager displays the Synergy Main
Me u.
You can then select any application that has been
installed on the Synergy Main Menu.
This is equivalent to
starting the
rgy Window Manager from a P/OS Application
Group menu.
rgy application can be started directly from DCL
ing the following three commands:

$ INSTALL L8:[ZZPROVUE1SYNRUN.TSK
RUN ~n$MGR/COMMAND="START [appldir]"
REIVlOVE WI $MGR
You e a e "appldir" with the directory name that contains
the
ication's installation file.
If the application
under development is called Faa and it has been
fa t installed from the directory [FOO], the DCL line would
tJe

$ HUN WI$MGR/COMMAND="START [FOO]"
If the application has been installed with P/OS Disk/Diskette
5e
ices and installation placed it in [ZZAP00143j, the
command would be
$ RUN WI$r1GR/COMMAND="START [ZZAP00143j"
Notice that the application must have a properly constructed
rgy) INS file (see Section 2.4.1).
•

Eithe of the command lines may be passed to the PROTSK
routine with the install/run/remove option.
This enables a
running application to start the Synergy window manager at
its Main Menu level, or to start a Synergy application.
(See
the PROTSK routine, described in the P/OS System Reference

2-15

RUNNING FROM THE TOOL KIT AND OTHER APPLICATIONS

Manual.)
In either case, the Synergy application's exit status is not
returned by the PROTSK routine until the Synergy window
manager exits.
The window manager exits with either success
(1) or failure (greater than 1), which it derives from the
application's exit status.
When a Synergy application is started using the "START [J"
command, the application is considered to belong to the
application that calls the PROTSK routine.
As long as the
Synergy application does not suspend itself (using the
Suspend service), the window manager remembers its owner, so
that when the Synergy application exits, the window manager
exits as well, returning status as described above.
The
application that called the PROTSK routine then receives
control.
However, if the Synergy application suspends itself (in
response to the F5 key), the window manager displays the
Synergy Main Menu.
At this point, the user can start other
Synergy applications and can even suspend the Synergy
environment.
Since all these possibilities exist, the window
manager assumes ownership of the application.
If the user
suspends the window manager, the window manager exits by
issuing success status to the task that called the PROTSK
routine.
Notice that the Synergy application (the callee)
may still be executing.
If the task that called the PROTSK
routine (the caller) requires that the Synergy application
complete its execution before the caller can proceed, the
caller and cal lee must establish some other method of
communicating exit status.

2-16

CHAPTER 3
ADAPTING A P/OS APPLICATION

This chapter supplies guidelines for the developer who is
modifying a PIOS hard disk application so that it will run in the
Synergy environment. All necessary modifications are described
in general terms. The details are provided in other chapters.
Use this chapter to determine the scope
organize and plan the modifications.

your

work

and

The application's source code must be modified so that it
communicates with the Synergy services. There are three areas in
which the source code must be modified:
•

Reading the keyboard and using the character-passing buffer

•

Suspending the application

•

Using the screen

The files that control the application's
installation must be modified also.

task

build

and

You should also consider whether the application can profit from
use of the clipboard as an input or an output medium, or both.

3.1

KEYBOARD USE

Synergy provides a buffer for keyboard input
called
the
character-passing buffer. The character-passing buffer is passed
to an application when Synergy starts or resumes the application.
The application must use any bytes in the character-passing
buffer before doing any QIOs to read the keyboard directly.
Likewise, when the application calls a Synergy service, all
keystrokes that have been read (but not used) must be placed in
the character-passing buffer for use by the Synergy service. The
character-passing buffer gets passed back and forth between the
3-1

KEYBOARD USE
application and Synergy.
In effect, all keyboard input flows through the character-passing
buffer.
A detailed description of the character-passing buffer
and its use is given in Section 4.7.
Since all Synergy applications use the Synergy character-passing
buffer, they are all required to read the auxiliary keypad in the
same mode;
namely,
8-bit, application keypad
mode.
This
distinguishes the numeric and punctuation keys on the keypad from
the same keys on the main array of the keyboard.
You can assign the same meaning to these keys as to their
counterparts on the main array of the keyboard, so that the user
is not aware of the distinction in the way that they are read.
However,
in order to unambiguously pass any type-ahead on to
other applications, all applications must read the keys in the
mode that distinguishes the actual key that has been pressed.

3.2

SUSPENDING THE APPLICATION

All Synergy applications recognize the F5 key in their keyboard
input and call a task control service which suspends the
application.
The F5 key should be recognized at all
times,
and
the task should never require additional keystrokes before it
suspends its execution.
If the application spawns additional tasks,
the developer need
not stop all the tasks before calling the Suspend service, but
must ensure that any tasks that continue to run execute no input
or output to the terminal while the calling task is suspended.

3.3

SCREEN USE

You have three choices of how to use the screen.
Each of the
choices involves the creation of a window, but two of the choices
mean fewer changes to the application code.
•

You create the window with the VT attribute, and you do all
remaining screen operations exactly as in the P/OS hard disk
environment, including using the menu and HELP services of
P/OS available in the POSRES cluster library.

•

You create the window with the VT attribute so that you can
continue to do the same terminal output that you did in the
P/OS environment, but you replace the calls on POSRES by
calls on the Synergy menu and HELP services.
This means

3-2

SCREEN USE
creating a Synergy frame file from the frame files produced
with the Frame Development Tool (FDT).
•

3.3.1

You create the window without the VT attribute -- as a
standard Synergy window, probably smaller than the full
screen. This means you must do all screen output with GIDIS
QIOs and that you must not use the menu and HELP services of
P/OS.

Retaining the VT Window Type

A Synergy application must avoid any screen output until it calls
a service that creates a window.
The window may be created with
a special attribute called the VT attribute.
This creates a
full-screen window.
It is possible to use either the PIOS menu and HELP services
(in
POSRES) or the Synergy menu and HELP services, or even a mixture
of the two.
The application can suspend itself by calling the Suspend
service,
since Synergy saves the screen contents and the GIDIS
state of the terminal subsystem.
When the application is
restarted after the Suspend service, Synergy guarantees that the
screen is correctly .restored and that the GIDIS state is
restored.
The application must restore the text-mode state of
the terminal subsystem; and if it has altered the color map,
it
must repeat the color map set-up~
Notice that Synergy restores the video bitmap so that the screen
looks right to the user.
However,
the terminal subsystem
maintains additional screen information, which is not restored by
Synergy.
If the user presses the PRINT SCREEN key after the
application resumes, the printed result might not be an accurate
representation of the screen.
To guarantee that PRINT SCREEN
will work correctly after suspending and resuming,
you must
repaint the entire text-mode contents of your VT window (with any
character attributes that were used initially).
Keep in mind that the window server always saves three planes of
video bitmap for a VT window (if they are present), regardless of
whether the user has asked the Synergy Window Manager to allow
the
use of color windows,
and regardless of whether the
application requests that the window be created with the color
attribute.

3-3

MODIFICATIONS TO OTHER FILES

3.4
3.4.1

MODIFICATIONS TO OTHER FILES
Task Build Files

You must modify any ODL file that you submit to the Professional
Application Builder to build a task that references a Synergy
service. The GOL file must include a reference to the Synergy
Interface Library.
The library routines add about 2000 (decimal)
bytes to your task image.
If you are replacing calls on the
POSRES cluster library, you may be able to remove the reference
to the POSRES library in the command file and regain an
equivalent amount of space.

3.4.2

Install File

In addition to telling Disk/Diskette services how to install and
remove your application, the install file tells PIGS how to start
your application when the user selects it from a P/OS application
menu.
When your application becomes a Synergy application, its
main task image is no longer started by P/OS.
You must modify
the install file in such a way that the install file tells PIGS
to start the Synergy Window Manager.
The Synergy Window Manager
then reads the install file and spawns your application's main
task image as a subtask.

3.5

USING THE CUPBOARD

The clipboard consists of two files that are used to pass user
data between Synergy applications. The files have fixed names
and are always stored in a system directory. Applications follow
a set of simple rules in writing and reading these files.
The advantage to the user is that he need not name the
remember where they are.

files

If you decide to modify your application to read from or write to
the clipboard,
you should follow these rules.
You should also
follow the conventions for describing the clipboard actions in
menus and in your user documentation.
For example, it would be a
mistake to tell the user that your application uses
the
clipboard,
and then require him to type the directory name and
filename of the clipboard file every time that he wants your
application to use it!

3-4

CHAPTER 4

CHAPTER 4
THE SYNERGY iNTERFACE

4.1

INITIAL STATE

Your application calls Synergy services to perform various
actions on its behalf. Many of the services read the keyboard or
alter the screen contents. One of the services,
Suspend,
even
gives the user a chance to start another application.
These actions that take place outside the application's code may
alter the states of the terminal.
Synergy sets the terminal back
to a known state on return from each call. These initial states
are described in the following sections.

4.1.1

At Synergy Start-Up

At Synergy start-up, the server performs the following actions:
Text mode set-up:
Text cursor home
Text cursor off
Keyboard set-up:
Set ANSI cursor key mode
Set application keypad mode
Set 8-bit codes only (CSI, not ESC [)
GIDIS set-up:
Initialize (-1 - Everything)
Load Synergy alphabets
Set output cursor (NO cursor)
Set writing mode (6 - Replace)
Set alphabet (0)
Set cell display size (24,50)
Set cell unit size (24,50)
Set Synergy colors in the color map
Create gray background

4-1

INITIAL STATE

4.1.2

At Window Creation

When a window is created, the following actions occur:
GIDIS set-up:
Set IDS to size of writable are~
Initialize (2!4!8 -Reset Global attributes,
Text, and Cursor)
Set output cursor (No cursor)
Set writing mode (6 - Replace)
Set alphabet (0)
Set cell display size (24,50)
Set cell unit size (24,50)
If it's a color window then
Set plane access (7)
else if this system has EBO then
Set plane access (4)
else
Set plane access (1)
Set primary color (0)
Set secondary color (4)
Fill window with white
(GIDIS active position is at 0,0 in the window)

4.1.3

On Return from Suspend

After a Suspend, which may include a change in window size:
GIDIS set-up:
Set Synergy colors in the color map
Set IDS to size of writable area
Set alphabet (0)
Set cell display size (24,50)
Set cell unit size (24,50)

4.1.4

After Other Window Operations

After other window operations:
GIDIS set-up:
Set IDS to size of writable area
Set alphabet (0)
Set cell display size (24,50)
Set cell unit size (24,50)

4-2

INITIAL STATE
The keyboard is in application keypad mode: The keypad keys do
not return the characters "1", "2", etc., but return CSI
sequences. The keyboard is in a-bit mode. Function keys return
a-bit sequences instead of the longer 7-bit sequences.
For VT windows, no GIDIS set-up is done, except for
color map (see Section 4.2).

4.2

setting

the

COLOR MAP

Synergy establishes the settings of the color map during start-up
with the following values:
Color
Index

% of
Red

% of
Green

% of
Blue

a
a
a
100
a

a
a
100
a

a
a
a

100
100

100

1
2

3
4
5

6
7

100

100
100
100
100

Result
black
red
green
blue
white
cyan
magenta
yellow

You can change these settings by altering percentages, but you
should be aware of the effect of your changes and the rules that
must be followed:
•

Changes that you make to the color map will be applied to all
windows on the screen, since there is no way to restrict the
effect of the color map to your window only.

•

When you call a Synergy menu service, the menu will be
displayed using your color map settings. Since menus are
displayed wit~ color index a providing the primary color and
color index 4 providing the secondary color, you could make a
menu very hard to read by setting these color indices to
noncontrasting colors. Try to avoid modifying the 0 and 4
settings. If you must modify them, you may have to precede
each calIon menu services with an adjustment that makes the
menu readable.

•

When your application suspends itself or exits, Synergy
resets the color map to the Synergy settings. Thus, whenever
your application resumes after a suspend, you must reset the
color map to your own settings.

The application in Appendix A alters the
4-3

color

map

(see

Pages

COLOR MAP

A-5, A-7, A-14, A-1S, and A-17).

4.2,"1

WIZPSC

Zap Primary/Secondary Colors

status
PrimaryColor
SecondaryColor

2 words (output)
1 word (input)
1 word (input)

This call alters the color indices that the server uses when
drawing window frames and such things.
The new color values
should be in the range 0-7.
The server simply passes these
values on to PRO/GIDIS, in SetPrimaryColor and SetSecondaryColor
instructions.
Once zapped, the specified indices will be used
for
ALL
future
window
operations
(even
other Synergy
applications).
The primary and secondary colors are not
reset
until
the entire Synergy environment is exited (not suspended -exited).
In other words, the NEXT TIME Synergy is
run,
the
primary/secondary colors will be back to 0 and 4.
If you want
the new primary/secondary colors to be in effect only until your
application exits, the application must zap them back to a and 4
when it exits.
Note that zapping either the primary or secondary to be values
other than a or 4 forces all futUre windows to become color
windows
(because all
three
planes
of
bitmap
must
be
saved/restored).
This includes stackable windows, and further
includes stackable windows that Menu Services creates.
In fact, you should not issue this call if there are ANY windows
that
have
already been created
(even windows
from other
applications).
Synergy will not crash or become corrupted if you
do so,
but the on-screen appearance of the old windows (and the
old gray background) can be wrong.

4.2.2

WIZCMP - Zap Color Map Entry
Status
Map
Index
Red
Green
Blue
Mono

2 words (output)
1 word (input)
1 word

(input)

1 word (input)
1 word

(input)

1 word (input)
1 word (input)

4-4

COLOR MAP
This call zaps the color map entries that Synergy enforces.
The
six input parameters are the same parameters that the PRO/GIDIS
SetColorMapEntry instruction takes.
Similar to the WIZPSC call, any changes to the color map made
using this call
remain in effect until the entire Synergy
environment is exited.
Note that if all you want is to change the on-screen colors while
your application is running,
you should not use this call.
Instead you
should
simply
issue
GIDIS
SetColorMapEntry
instructions from your application; then Synergy will reset the
color map to the Synergy defaults when the application exits or
suspends.
The WIZCMP call
is provided to change the defaults
that Synergy uses, so they are permanent for the duration of the
Synergy environment.

4.2.3

WIRCMP - Reload Color Map

The following call causes Synergy to reset
map back to the default Synergy colors.
status

the

PRO/GIDIS

color

2 words (output)

This call is useful if your application changes the color map
using the PRO/GIDIS SetColorMapEntry instruction, and you wish to
return to the standard Synergy color map settings.
Synergy implicitly calls this
routine
exits (WIDON) or suspends (WIINT).

whenever

application

If the Zap Color Map (WIZCMP) routine has been used to change the
default Synergy color map, WIRCMP reloads the color map with
those changed default values -- not the original power-up color
pallete.

4.3

FONTS AND ALPHABETS

GIDIS defines alphabet 0 as the DEC Multinational Character Set.
The font style (character shape) is essentially the same as the
font style defined by the text mode of the terminal subsystem.
Synergy defines additional fonts for displaying characters in
menus, and for some special effects that it requires. At Synergy
start-up, the fonts are installed in common regions and then
loaded by name into GIDIS alphabets as follows:

4-5

FONTS AND ALPHABETS

Alphabet
Index

Font
Name

Font
Description

WI$FO

cial
(reserved)
Dim
Normal
Bold
(reserved)
Normal underlined
Bold unde rl ined
Boxed

8
9
10
11
12
13
14
15

WI$F1
WI$F2
WI$F3
WI$F5
WI$F6
WI$FS

To display characters from one of the Synergy fonts
in your
application window, you must use a GIDIS SET_ALPHABET instruction
to select the desired alphabet before issuing any DRAW_CHARACTERS
or DRAW_PACKED_CHARACTERS instructions.
All Synergy fonts except
the Special font use the standard cell unit size and cell display
size of 24 wide by 50 high (GaS units), which is the same as the
terminal subsystem's text-mode character that is 12 hardware
pixels wide and 10 hardware pixels high.
The application in Appendix A uses these fonts (see Page A-45).
Synergy defines these special fonts for various reasons:
•

Synergy needs to provide various renditions of the standard
characters.
The renditions provided are dim, bold, and
underlined versions of the normal character.

•

Synergy needs to draw ~ box around certain text to make it
look like a key caption.

•

Synergy needs to combine some of the characters from the DEC
Special Graphics character set with the characters that form
the DEC Multinational character set.

•

Synergy needs a few special characters that are not available
elsewhere.

4.3.1

User-Defined Fonts

You can load fonts that you design into any of the alphabets 1 to
6.
However,
when you call a Synergy window or menu service, or
when you suspend your application,
you lose all your
font
definitions.
Thus, you must reload your fonts on return from the
Synergy services.
Notice that this means
that
fonts must be

4-6

FONTS AND ALPHABETS

loaded after a window is created, not before.
If you create two
windows, your fonts must be loaded each time you select a new
front window.
You should avoid loading your own font into any of the alphabets
used or reserved by Synergy.
If you must load your font into an
alphabet that is used or reserved by Synergy, you must use the
Restore Fonts service (see below) that requests Synergy to reload
its font into that alphabet.
This prevents the display of menus,
HELP,
etc., using your fonts instead of the Synergy fonts.
This
request must be made prior to any calIon Synergy menu services,
prior to a calIon the Suspend service, and prior to exiting your
application.
Synergy reloads its own fonts before returning
application after a suspend.

4.3.2

control

your

WIRFNT - Restore Fonts
Status
BitMask

2 words (output)
1 word
(input)

Bits in the BitMask correspond to alphabet numbers that Synergy
should restore.
Thus,
to instruct Synergy to reload its font
into alphabet 7, you would supply a BitMask with the value 128
(2

7).

Synergy ignores bits 0 to 6 of the BitMask,
so that you can
supply a mask of -1, which causes Synergy to reload all of its
fonts.

4.3.3

Special Font

The Special font uses a larger cell display size
(16 by 16
hardware pixels)
and has only two characters defined in it.
These are the arrow that the window manager uses to choose a new
front window,
and a pattern that is used to create the gray
background.

4.3.4

Text Fonts

The Dim, Normal and Bold fonts, and the underlined versions of
Normal and Bold, all have exactly the same character shapes, with
the variation being in the number of pixels that are turned on
and whether or not the bottom row of pixels is turned on for

4-7

FONTS AND ALPHABETS
underlining.
This is a
full
256-character alphabet,
which
contains
the DEC Multinational printing characters and is
augmented with additional characters from the DEC
Special
Graphics character set that are placed in the nonprinting
positions of the DEC Multinational set.
This is the Synergy
Character Set, shown in Table 4-1.
Notice that characters 134 and 135 (decimal) when placed together
form the clock icon that is used in the wait message of the title
line of windows.
Characters 136 and 137 (decimal) are
reserved.
Characters 156 to 159
(decimal)
are the multiplication and
division signs, the centered dot and the checkmark.
Character
160 (decimal) is the ellipsis used in various ways by PROSE PLUS,
Graph, and Spreadsheet.
The remaining special characters in the
128 to 155
(decimal) positions are various characters from the
DEC Special Graphics character set,
including the characters
known as the line-drawing characters.
Notice that these characters can be placed in a
frame
file,
providing that you edit the frame
file with an editor that
handles nonprinting 8-bit characters.
To use the text fonts in a
menu,
HELP or message frame,
see Section 7.2.1.
Be sure to
observe the conventions that are established for these text fonts
(see Chapter 11).

4.3.5

Printing the Synergy Character Set

If these fonts are displayed in your application window, and the
window is printed on a dot-matrix printer such as the LA50 with
the PRINT SCREEN key, they will be printed correctly on the
paper.
This is because the PRINT SCREEN key sends the actual
video bitmap to the printer (as sixels).
However, if your application tries to store these characters in a
file,
and the user prints the file using Print Services, the
characters will be sent to the printer for interpretation as DEC
Multinational
characters.
Thus,
all
the
special Synergy
characters will print as blanks or reserved symbols,
since they
are placed into the nonprinting area of the DEC Multinational
Character Set.

4.3.6

Boxed Font

The Boxed font is the same as the Synergy Character Set, with the
addition of a dim line above each character (the top of the box)
and a normal line below each character (the bottom of the box),
All the characters of the Synergy Character Set are available

4-8

FONTS AND ALPHABETS
except the following:
•

The ASCII codes for curly braces (decimal 123 and 125) are
used to select the character shapes that form the left and
right ends of the box.

•

The ASCII codes for the lowercase letters, u, d, 1, and r
(decimal 117, 100, 108, and 114) are used to select the
character shapes for the up arrow, down arrow, left arrow and
right arrow, respectively.

The boxed font is intended solely for displaying key captions,
and all key captions are displayed in uppercase, by convention
(see Chapter 11). To use the boxed font in a menu, HELP, or
message frame, see Section 7.2.1.

4-9

FONTS AND ALPHABETS

Table 4-1:

COLUMN

BITS

Synergy Character Set

ROW

b5
b4 b3 b2 bl

o 0

0
0

1
1

0
0
0

20
16
10

40
32
20

60
48
30

100
64
40

120
80
50

1
1
1

21
17
11

41
33
21

61
49
31

101
65
41

121
81
51

2
2
2

22
18
12

42
34
22

62
50
32

102
66
42

122
82
52

3
3
3

23
19
13

43
35
23

63
51
33

103
67
43

4
4
4
5
5
5

24
20
14

44
36
24

64
52
34

104
68
44

25
21
15

45
37
25

65
53
35

105
69
45

66
54
36

67
55
37

70
56
38

71
57
39

52
42
2A

72
58
3A

141
97
61

161
113
71

142
98
62

143
99
63

163
115
73

144
100
64

164
116
74

125
85
55

145
101
65

165
117
75

126
86
56

146
102
66

166
118
76

127
87
57

147
103
67

130
88
58

150
104
68

111
73
49

131
89
59

151
105
69

112
74
4A

132
90
5A

152
106
6A

133
91
58

153
107
68

{

173
123
78

174
124
7C

}

175
125
7D

6
6
6

26
22
16

7
7
7

27
23
17

1 0

10
8
8

30
24
18

(

11
9
9

31
25
19

)

12
10
A

32
26
lA

13
11
8

33
27
18

53
43
28

;

73
59
38

113
75
48

[

14
12
C

34
28
lC

54
44
2C

74
60
3C

114
76
4C

1 1

15
13
D

35
29

55
45
2D

75
61
3D

115
77
4D

]

36
30
1E

56
46
2E

76
62
3E

116
78
4E

37
31
1F

57
47
2F

77
63
3F

117
79
4F

16
14
E

17
15
F

KEY
CHARACTERc:J]P
40
OCTAL
32
DECIMAL
20

HEX

4-10

,
a

1
160
112
70

50
40
28
51
41
29

1
0

140
96
60

46
38
26
47
39
27

0
0

1
1

0
0

106
70
46
107
71
47
110
48

123
83
53
124
84
54

134
92
5C
135
93
5D

1
m

154
108
6C
155
109
6D

136
94
5E

156
110
6E

137
95
5F

157
111
6F

162
114
72

167
119
77
170
120
78
171
121
79
172
122
7A

176
126
7E
177
127
7F

FONTS AND ALPHABETS

Table 4-1 (continued)

0
0

I
~

140
96
60
141
97
61
142
9S
62

160
112
70

~ 240

... ~

SCAN 5'

161
113
71

241
161
Al

242
162
A2

SCAN 7

162
114
72

243
163
A3

160
AO

143
99
63

SCAN 9

163
115
73

144
100
64

164
116
74

145
101
65

165
117
75

146
102
66

166
118
76

147
103
67

167
119
77

247
167
A7

150
104
68

170
120
78

::n

250
168
A8

151
105
69

251
169
A9

252
170
AA

152

,
r
L

106
6A
153
107
6B
154
108
6C
155
109
6D

156
110
6E

SCAN 1

157
111
6F

171
121
79
172

122
7A

173
123
7B

··

-:t

261
177
Bl

262
178
B2
263
179
B3
264
180
B4

244
164
A4

300
192
CO

320
208
DO

363
243
F3

A
0

364
244
F4

365
245
F5

366
246
F6

345
229
E5

326
214
D6

I:e

346
230
E6
347
231
E7

367
247
F7

350
232
E8

370
248
F8

371
249
F9

372
250
FA

373
251
FB

374
252
FC

375
253
FD

376
254
FE

1 1

••

311
201
C9

312
202
CA

313
203
CB

271
185
B9

272
186
BA

••

,
I

276
190
BE

277
191
BF

••

332
21B
DA

314
204
CC

••

334
220
DC

315
205
CD

••

335
221
DD

316
206
CE
317
207
CF

CHARACTER~06 OCTAL

4-11

336
222
DE

333
219
DB

331
217
D9

KEY

DECIMAL

362
242
F2

325
213
D5

HEX

..a

330
216
D8

324
212
D4

198

310
200
C8

343
227
E3

257
175
AF

337
223
DF

341
225
El

270
184
B8

177
127
7F

304
196
C4

323
211
D3

-J

361
241
Fl

••

327
215
D7

256
174
AE

303
195
C3

307
199
C7

176
126
7E

275
189
BD

342
226
E2

267
183
B7

1/2

306
198
C6

255
173
AD

ROW

322
210
D2

IE.

175
125
7D

360
240
FO

266
182
B6

274
188
BC

340
224
EO

302
194
C2

1f4

I--

246
166
A6

254
172
AC

b6
b5
b4 b3 b2 bl

321
209
Dl

305
197
C5

174
124
7C

BITS

273
187
BB

b7
1

301
193
Cl

265
181
B5

bS
1

f.l

IE.

245
165
A5

253
171
AB

260
176
BO

COLUMN

1
1

0
1

1
1

SCAN 3

0
0

•

1
0

..e
,
I

,
I

A
I

..
I

344
228
E4

351
233
E9
352
234
EA
353
235
EB
354
236
EC
355
237
ED

,
U

..
..Y
U

356
238
EE
357
239
EF

377
255

IMPOSED DEVICE SPACE

4.4

IMPOSED DEVICE SPACE

When your application receives control from Synergy,
the GIDIS
Imposed Device Space has been set to the writable area of your
front window.
This prevents you from writing outside your
window, since the clipping region is the same as the IDS.
You can issue the GIDIS SET_CLIPPING_REGION instruction, however,
in order to modify the clipping region.
You should be careful to
keep the new clipping region within your window's writable area.
GIDIS does not prevent you from setting the clipping region
beyond the IDS boundaries.
If you do this, it is then possible
to issue GIDIS instructions that write outside your window's
writable area.

4.5

INTERTASK COMMUNICATION METHOD

If your application consists of more than one task, you should be
aware of the task operations that occur within Synergy.
You
should not interfere with these operations.
If your application desires to receive data through
will need to use a special interface described below.

4.5.1

ASTs,

you

Synergy Task Communication

The applications and the window manager communicate only with the
window server.
Communication is totally synchronous and can be
likened to an interprocess coroutine call. This is implemented
through a VARIABLE SEND DATA/VARIABLE RECEIVE DATA OR STOP pair
of directives in each direction,
to the window server
(input
parameters), and from the window server (output parameters).
Before the packet is sent, the window server is stopped (a state
in PIOS in which a task does not execute, and does not compete
for memory).
Once the packet is sent, the caller will stop,
and
the window server is allowed to execute. On the return path, the
roles are reversed.
VARIABLE SEND DATA restricts data packets to be smaller than 512
bytes.
This is too small for many of the parameter packets.
Therefore, multiple VARIABLE SEND DATA directives are used to
implement
packets
of up to 2048 bytes.
Additional SEND
directives are used only if the packet is larger than 512 bytes.

4-12

INTERTASK COMMUNICATION METHOD
The interprocess calls are accomplished by subroutines in the
Synergy Interface Library that are linked into each application
task that uses Synergy services.
These modules, including a
512-byte buffer and the Synergy character-passing buffer, occupy
about 2000 decimal bytes of your task's address space.
You can overlay all or part of this area, by calling the modules
out explicitly in the ODL file that is used to link your task.
The module name is the same as the global symbol name for each
service.
When an application receives the F5 key as input, it calls the
Suspend service (WIINT). The interprocess call that follows does
not return until some later time. Instead of returning to the
calling task, the server "returns" to the window manager. The
window manager eventually calls the TRANSFER CONTROL service in
the window server, passing the task that is to be activated.
Instead of the window server returning control directly to the
window manager, it "returns" to the task that is to be activated.
NOTE

When you call a Synergy service, the interface
routine stops the task while it waits to receive
the data packet that is returned by the window
server.
A stop is not a legal operation if the
task is at AST state. Therefore, you must not
call Synergy services from AST state.

4.5.2

Receiving Data Packets

If your application task executes Receive Data directives in
order to communicate with other tasks, your use of this facility
can conflict with Synergy's use.
No conflict arises if you execute your Receive Data directives
from user state (as opposed to AST state). Since Synergy's use
of the Send and Receive Data directives is strictly synchronous,
the Synergy interface routine stops your task until the window
server sends back the result of the service call.
Furthermore,
the interface routine specifies that it should receive only those
packets that are sent by the Synergy window server.
However,
if
your
task
is
using
ASTs
(perhaps
an
unsolicited-input-character AST), and you execute a Receive Data
directive while at AST state, you could potentially receive a
data packet that is intended for the Synergy interface routine.
You can guard against this by always specifying the sender task
4-13

INTERTASK COMMUNICATION METHOD
name from which you are expecting
directive done from AST state.

4.6

data

in any Receive Data

CALL INTERFACE TO SYNERGY SERVICES

The Synergy services are implemented as interface routines in the
Synergy Interface Library. The library is referenced in the .ODL
file used to build the Synergy application.
In the following sections, each service is described individually
with the global symbol that is defined in the Synergy Interface
Library. The parameters that are passed on the call are listed
in the expected order, with an. indication of the data type and
whether the parameter's value is supplied as input to the call or
output from the call, or both input and output. Examples are
given for most calls.
Synergy interface routines conform to the calling conventions for
other PIOS library routines (the PDP-11 R5 sequence), with the
additional feature that no registers are modified by the call.
Notice that the interface routines lie between your application
code and the window server task. The interface routines pack
your input parameters into a data packet. If you supply a null
entry (-1 in the pointer of the parameter list) for an input
parameter, the interface routine supplies a 0 or null string in
the packet. This means the window server does not see a missing
integer parameter; it sees a O-valued parameter.
The window server task sendG back all the output parameters in a
data packet.
The interface routine unpacks the returned values
into the output parameters that you requested. If you supply a
null entry for an output parameter, the interface routine just
ignores the value returned in the data packet.
The interface routines and the window server do very little
checking on the validity of input parameters. It is possible to
pass faulty input, or no input, and get back a status value that
indicates the call was successful.
If your application is
calculating parameter values dynamically, you may want to build
in your own checking code to ensure that the calculated values
are acceptable before using them in the service call. Such code
could be made conditional, so that it can be easily removed when
debugging is completed.
The interface routines pass the call to the window
and wait for its return (see Section 4.5.1).

4-14

server

task,

CALL INTERFACE TO SYNERGY SERVICES

4.6.1

Parameters

Words are 16-bit integers, unless otherwise noted.
Boolean values are stored as one-word integers. The value "true"
is represented by the integer -1, and the value "false" is
represented by the integer O. No other values should be used.
Strings are sequences of bytes whose values may include any
graphic character,
including multinational characters. Unless
specifically stated, string parameters should not include control
characters
(less than ASCII space) or escape sequences.
Most
strings are straight text, and include no formatting information.
In particular, horizontal tab has no meaning in a window.
Make sure that paramters which are unused or
reserved are passed zero values in the call.

are

documented

All services pass back a status code in the first parameter. The
status parameter is a two-word integer array that indicates the
results of the requested operation. The first word indicates the
general result, while the second word may contain additional
information.
See Table 4-2.

I
I

I
I 4.6.2 WICAL -- Call Window Service
I
I Unlike all other Synergy calls, the following routine does not
I use the PDP-ll R5 Calling Sequence format. Rather, it expects
I its two parameters to be pushed onto the stack by the caller
I (followed by the normal JSR PC, WICAL).
I
1 word
(input)
Routine address
I
(input)
1
word
Parameter block address
I
I
I This call is an optional means of indirectly calling Synergy
This routine saves R5, then loads R5 with the second
I services.
parameter
(parameter
block address). Then WICAL (JSR)
calls to
I
the
routine
specified
by
the
routine
address.
Upon
return
from
I
the
called
routine,
WICAL
restores
the
original
value
of
R5,
I
cleans
the
two
parameters
off
of
the
stack,
and
then
returns
to
I
I

I
I
I
I
I

I
I
I

the application.
(In fact WICAL may be used to call
R5 sequence routine, not just Synergy services.)

any

PDP-11

WICAL is useful in two cases:
•

When the parameter block is constructed at run-time
(rather than statically at compile-time by the language
compiler) so that you cannot call the routine directly
from the source code using a normal CALL type statement.
4-15

CALL INTERFACE TO SYNERGY SERVICES

For example, you can allocate the parameter block as an
array
of integers
(do not forget to include the
parameter count word,
as defined by the R5 Calling
Sequence
Standard);
assign
the addresses of the
individual parameters into elements of the array;
then
pass the routine you want to call and the address of the
array to WICAL.
When calling Synergy routines with static argument lists
from PRO/Pascal, you may find that large parameter lists
exceed the limits of the compiler.
In this case,
you
can allocate and construct the parameter block yourself
in Pascal, and then use WICAL.
For example:

•

PROCEDURE DFLOWi SEQ11;

Routine with lots of params }

PROCEDURE WICAL( PROCEDURE SEQ11Procedure;
VAR ParamBlock: [Unsafe] Integer )i EXTERNAL;
PROCEDURE ThisCallsDFLOWi
CONST
ParamCount = 100;
VAR
FlowPB: ARRAY [ O.. ParamCount 1 OF Integer;
StatusBlock: ARRAY [ 1 .. 2 1 OF Integer;
BEGIN { of procedure ThisCallsDFLOW }
FlowPB[ a 1 .- ParamCount;
FlowPB[ 1 1 := IAddress( StatusBlock);

WICAL( DFLOW, FlowPB );
END;

Table 4-2:

{1st parameter}

{ Call the Synergy routine }

{of procedure ThisCallsDFLOW }

Returned Status Values
WORD 1 MEANING

WORD 2 MEANING

Success

Not speci fied

-1

Directive error
(in window server)

DSW
(Directive Status Word)

-2

RMS error
(in window server)

RMS I/O error

WORD 1
VALUE
1

4-16

CALL INTERFACE TO SYNERGY SERVICES
WORD 1
VALUE

WORD 1 MEANING

WORD 2 MEANING

-3

Bad value
(in application)

Parameter number in error

-4

Receive error
(in application)

DSW
(Directive Status Word)

-5

Send error
(in application)

DSW
(Directive Status Word)

-6

Interpreter error

0 - Unknown
1 - Invalid function
2 - Not implemented

-7

Protocol error

0 - Unknown
1 - Invalid function
2 - Not implemented

-8

Bad CurrentValue for
class 2 option in
set-up menu call

undefined

-9

Frame type incompatible
with menu call

Frame found

-10

Network error

DECnet error codes

-11

No more names to return
from Old File
selections

Undefined

-12

Mismatch of option
classes in set-up menu
call

Undefined

-13

String size too large
in set-up menu call

undefined

-14

Wrong number of options
in set-up menu call

Undefined

-16

WIRMS message too big

Undefined

4-17

CALL INTERFACE TO SYNERGY SERVICES
WORD 1
VALUE

WORD 1 HEANING

WORD 2 HEANING

-17

Window error

Too many windows
Invalid position
Invalid size
No active window
Window has no title
Window must be front
window
7. Invalid window ID
8. Invalid operation

-18

Block I/O error

1.
2.
3.
4.
5.

1.
2.
3.
4.
5.
6.

6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
-19

Cannot create file
End of file
Device full
No such file
File not open on
specif~ed channel
Memory unavailable
No channel is available
Invalid file
specification
Invalid channel number
System directive error
File is locked
Illegal operation
Not at end of file
Privilege violation
Line too long
File already exists
Not a sequential file
Invalid record address
Invalid record format
System I/O error

1. No menu or string
editing window exists
2. Front window is not a
menu window
3. Front window is not a
string editing window
4. Too many menus and
string editing windows
5. Too many headers
6. Header too wide
7. Window too wide
8. Too many entries
9. Entry too wide
10. Nonprinting character
11. Invalid entry position

Menu primitive error

4-18

CALL INTERFACE TO SYNERGY SERVICES
WORD 1
VALUE

WORD 1 HEANING

-20

Terminal error

1. Buffer length invalid
2. Initial length invalid
3. Initial position
invalid
4. Directive failure

-21

Raster error

1. Bad parameter value
2. No rasters available
3. Insufficient file space

-22

Internal error

1.
2.
3.
4.
5.

Stack pointer corrupted
Packet protocol
Directive failed
Bad packet type
New task interrupted
packet stream
6. New function
interrupted packet
stream
7. Invalid length for task
context block

-23

Memory error

1. Internal error
2. Attempt to DISPOSE with
an invalid pointer
3. NEW received a negative
size
4. Zero or negative size
block
5. Memory not available
6. Free memory list has
invalid pointer
7. Memory block larger
than 1024
8. Free memory list has
loop
9. Memory block overruns
end of pool

4.7

WORD 2 HEANING

PASSING TYPE-AHEAD TO SYNERGY ROUTINES

The terminal subsystem automatically collects keyboard input in a
type-ahead buffer.
Characters are released from this buffer in
response to QIOs that are executed by the application code.

4-19

PASSING TYPE-AHEAD TO SYNERGY ROUTINES
4.1.1

MGTCB - Expand Call-Back Code

status

2 words (output)

Before the service is called, the application must ensure that
the
character-passing
buffer
is
in the correct format.
Specifically, the call-back code must be removed from the buffer,
any additional characters left-justified, and the buffer length
field set to the correct value.
NOTE

Do not assume that the character-passing buffer
is empty beyond the call-back code. There is
always at least one character in the buffer
beyond the call-back code, and if there are
applications running that use an AST routine to
read
the
keyboard,
they may be appending
characters to the end of the character-passing
buffer while the call-back code is in the buffer.
The application in Appendix A uses the
(see pages A-i0 and A-47).

4.8

character-passing

buffer

FilE USAGE

Your application can be suspended by the user while other
applications are run.
This puts a demand on system resources.
The following suggestions are offered:
•

Before you call the Suspend service, you should free as many
system resources as possible. One way to do this is to close
data files. You can close the data file before the WIINT
call and reopen it on return from the WIINT call.
(Notice
that the window server automatically closes the frame file
for you and then reopens it before returning control to your
application. )

•

If you close files before suspending, you may want to do a
fast reopen of the file using the device and file identifier
in the NAM block that was supplied on the first open, rather
than doing a reopen with the file specification. However,
you should be aware that if the file is on another node of a
network, the device and file identifiers are meaningless and
the open will fail.

4-22

FILE USAGE
•

Your application is more susceptible to an abnormal
termination while it is suspended, since the user may forget
that your application is running and may turn off the
computer. If you leave a file open during the suspend, your
application should anticipate a locked file error return when
it"tries to open the file on start-up. Alternatively, you
may want to open the file with a request that RMS not lock
the file if it is closed abnormally.

•

Open your data files with the minimum required access in
order to reduce the resource requirements.

•

When opening data files in the user's default directory,
address them with the pseudo device name, SY:[], rather than
making explicit reference to a device name.

4.9

SPECIFYING KEY CODES

Many of the menu service routines read the keyboard (through the
character-passing buffer, of course) and return the keystroke
that terminates the service (often the DO
key)
to
the
application.
Many of the terminating keystrokes are multi-byte
CSI sequences, which would require returning a variable-length
string of bytes as the terminating code. Instead, the window
server returns a key code as a 16-bit integer.
Normal keys, like "A" or space or Hi", are represented by their
ASCII codes.
For example, "A" is represented by decimal 65.
Multinational keys are represented by the appropriate values
the copyright key is represented by decimal 169. Any key value
less than decimal 255 is a printable, or graphic, character.
Control keys (normally represented by decimal 0 to 31) are
specified by decimal 256 plus their normal value. For example,
the normal value of CTRLjC is 3, but CTRLjC is represented in
this scheme by 256 + 3, or decimal 259.
Invalid keys (invalid escape sequences) are specified by
1024.
Remember that the HOLD SCREEN and PRINT
accessible to applications in PjOS.

SCREEN

keys

are

decimal
never

The other keys -- function keys, ARROW keys, keypad keys
are
represented by values between 512 and 1024 (see Table 4-3). For
a discussion of the use of the keys in termination key lists, see
Section 8.2.5.

4-23

SPECIFYING KEY CODES
The application in Appendix A defines the
A-45).

Table 4-3:

key

codes

(see

page

Key Encodings

KEY CAPTION

ENCODING

KEY CAPTION

ENCODING

BREAK
SETUP

512 + 13 = 525
512 + 14 = 526

512 + 15 = 527

INTERRUPT
RESUME
CANCEL

512 + 17
529
512 + 18 = 530
512 + 19
531

MAIN SCREEN
EXIT

512 + 20
532
512 + 21 = 533

F11
F12

512 + 23 = 535
512 + 24
536

F13
512 + 25
ADDTNL OPTIONS 512 + 26

HELP

512 + 28

540

512 + 29 = 541

F17
F18

512 + 31
512 + 32

543
544

F19
F20

512 + 33 = 545
512 + 34
546

PF1
PF2

512 + 35
512 + 36

547
548

PF3
PF4

512 + 37
549
512 + 38 = 550

FIND
INSERT
REMOVE

512 + 1 = 513
512 + 2
514
512 + 3 = 515

SELECT
PREV SCREEN
NEXT SCREEN

512 + 4
512 + 5
512 + 6

UP ARROW
DOWN ARROW

551
512 + 39
512 + 40 = 552

RIGHT ARROW
LEFT ARROW

512 + 41 = 553
512 + 42 = 554

Keypad
Keypad
Keypad
Keypad
Keypad
Keypad
Keypad

512
512
512
512
512
512
512

Keypad
Keypad
Keypad
Keypad
Keypad
Keypad
Keypad

512
512
512
Enter 512
512
0
512
1
2
512

+
+
+
+
+
+
+

43
555
44
556
45
557
46
558
47 = 559
48
560
49
561

<xl (delete) 512 + 57

569

4-24

3
4
5
6
7
8
9

+
+
+
+
+
+
+

50
51
52
53
54
55
56

537
538

516
517
518

562
563
564
565
566
567
568

RESTRICTIONS
4.10

RESTRICTIONS

Synergy does not fully protect applications from one another, and
cannot protect itself from abuse by applications. In order for
Synergy and its applications to all work
properly,
each
application must abide by certain restrictions.
•

An application must not use text-mode QIOs to the terminal
for screen output, and it must be careful not to use any
system service that would issue such output QIOs (such as
standard PIOS menu services). The only exception is the use
of instructions that change keyboard characteristics. These
may be used, but the application must reset their state on
return from each Suspend (WIINT) call, since the keyboard
state will have been reset by the window server. If the
application is using a VT window, this reset does not occur.

•

An application may change terminal driver characteristics (by
sending a SF.SMC QIO to the terminal susbsystem), but it must
reestablish the desired characteristics on return from each
WIINT call, since the terminal driver state will have been
reset by the window server.

•

An application may attach the terminal (to do unsolicited
input character ASTs), but must detach the terminal before
calling any window service.

•

An application must check all keyboard input and call the
Suspend service, whenever the F5 key is pressed. The
application mayor may not choose to process any characters
that precede the F5 key, but should not wait for more
characters before suspending. An application in the middle
of some noninteractive operation, such as a database update,
may choose to complete the operation before suspending, or
may choose to abort the operation. Since the user's next
action is not predictable, application files and other
context should be in known states before suspending.

•

An application should be able to refresh its window after a
Suspend service if it allows the window size to be changed by
the user and if the display would not look right in the newly
sized window.

•

All stackable windows are destroyed by the Suspend service.

•

Exercise care in changing the color map, since that action
changes the colors in other windows as well. Since the color
map is not saved, and is reset whenever the application is
suspended, it remains the application's responsibility to
reestablish its own color map when the application resumes
after each such suspension.
4-25

RESTRICTIONS

An application should not change the GIDIS imposed device
space.
The clipping region and the GOS units can be
The window server always sets these for a newly created
window, and after a return from a suspension, the window
server reestablishes these values for the front window .

•

An application may use GIDIS named fonts, and may define
additional named fonts beyond those provided by
rgy.
An
application can define implicitly named fonts (those defined
at run time, one character at a time), but they will have to
be reestablished after a call to any Synergy service.

4-26

CHAPTER 5

CHAPTER 5
TASK CONTROL SERVICES

5.1

TASK CONTROL SERVICES

These operations are used to initialize the interface between the
application task and the Synergy services, and to pass control
and information back to the services. They are described here in
alphabetical order.

5.1.1

WIDON - Application Done
status
ContextBlockLength
contextBlock()

2 words (output)
word
(input)
n bytes (input)

This service is called when the application is about to- exit.
The application can pass up to 32 bytes of context data, which
the window server saves on its behalf.
The context block is
returned by the Initialize service (WIINI) the next time the
application runs. The window server does not attempt to apply
any meaning to the context block. Each application can use the
context block in its own way.
(Do not confuse this data with the
window descriptor block.) The application in Appendix A uses the
context block (see pages A-6, A-14, and A-15).
Like all other services, this service returns to the application.
It does not cause the application to exit.
Once the Done service has been called, the application must not
make any additional calls on the window server and must not do
any more terminal I/O.
The application in Appendix A uses the WIDON service
A-15 and A-48).

5-1

(see

Pages

TASK CONTROL SERVICES

5.1.2

WIINI - Application Initialization
Status
ExpectVersion
ActualVersion
ContextBlockLength
ContextBlock()
Screenwidth
ScreenHeight
Characterwidth
CharacterHeight
Pixelwidth
PixelHeight
Color

2 words
word
word
word
n bytes
word
word
word
word
word
word
word

(output)
(input)
(output)
(input and output)
(output)
(output)
(output)
(output)
(output)
(output)
(output)
(output)

This service initiates communication between the application
Synergy.

and

NOTE
This service can be called only
once
per
execution of the application, and must be called
before any other service or any terminal I/O.
ExpectVersion is the version of the window server expected by the
application;
it
should
be set to 2 with this release.
ActualVersion is the actual version of the window server.
ContextBlock is a block of up to 32 bytes. An application uses
this area to retrieve information stored by the Done service the
last time the application executed. The length of the context
block is both input and output.
As input it specifies the
maximum number of bytes to be returned. As output it specifies
the number of bytes actually returned.
If the returned length is
0, it signifies that this is the first time the application was
run.
(It is recommended that this area be used to save the X and
Y coordinates of the windowframe and the width and height of the
writable area of the window. This information can then be used
to create a window of the position and size the user last
wanted. )
The widths and heights are the sizes of the screen,
of the
default character,
and of the actual hardware pixel in the
Synergy coordinate system (GOS units).
The values can be used as
a basis for graphics calculation if you want to write an
application that is independent of the current hardware.
The Color parameter is boolean; it is true if color (monitor and
three planes of video bitmap) is being used; it is false if color
is not being used (only one plane in use).
The user selects the
use of color from the Synergy Set-up Menu.
This output parameter
5-2

TASK CONTROL SERVICES
is not simply an indication of whether the hardware is present to
do color images on the screen; it indicates that the hardware is
present and that the user wants to use it.
(To find out whether
the color hardware is present, see the EBO parameter to the WISYP
call.) Applications should not create windows-that use color (see
Section 6.1.5) unless the Color parameter returned by the
Initialize service is true, or unless the application is creating
a window with the VT attribute.
The application in Appendix A uses the WIINI service
A-14 and A-48).

5.1.3

(see

Pages

WIINT - Suspend the Application
status
WhyReturn
WindowID
width of writable area
Height of writable area

2 words
word
word
word
word

(output)
(output)
(output)
(output)
(output)

This service suspends execution of the application and gives
control to the window manager. This service must be called when
the application sees the F5 key in its own keyboard input,
and
when the application sees the F5 key returned by any service
call.
If the application has created any stackable windows,
be destroyed before this service is called.

they

must

The window manager can return control from the Suspend service to
the application under two different conditions:
•

When the user tells the window manager to resume execution of
the application, the window manager returns from the Suspend
service with the WhyReturn parameter set to O.
This tells
the application to continue its execution.
If the
application has created only one window, it can ignore the
WindowID, Width and Height parameters.
If the application
has created more than one window, it can use the WindowID
parameter that is returned to learn which of its windows is
in front.

•

If the application has allowed its window(s) to be changed in
size, and the user has requested a size change, the window
manager returns immediately after completing the size change
action with the WhyReturn parameter set to 1.
This tells the
application to adjust the window whose size has been changed,
but does not give the application permission to continue
execution. The application is required to adjust the window

5-3

TASK CONTROL SERVICES
and immediately call the Suspend service again, since the
user still thinks he is manipulating the windows with the
window manager.
The application is told which window was changed (WindowID)
and the new dimensions (Width and Height).
When a window
size changes, the contents of the window depend on the window
attribute "clear on change." If this attribute is true, the
window manager blanks the entire writable area of the window,
and the application must refresh it.
If "clear on change" is
false, the window manager merely retains whatever was in the
writable area before the size changed. When a window is made
larger, the new portion (bottom or right side) is cleared
(with white).
When a window is made smaller, the writable
area is restored with the previous contents (upper left
corner).
Data outside the new writable area is lost.
When the user moves the front window to a new location on the
screen,
no indication is given to the application.
Therefore,
your application should not assume that the screen position of
any window is unchanged over a Suspend service call.
If the
application depends on the screen position of its window,
you
must call the Get Window Parameters service (WIGEW) on return
from WIINT to update the window descriptor block with the current
screen location.
The application in Appendix A uses the WIINT service
A-20 and A-48).

5.1.4

(see

Pages

WISVP - Get System Parameters
status
ExpectVersion
ActualVersion
Screenwidth
ScreenHeight
CharacterWidth
CharacterHeight
Pixelwidth
PixelHeight
Color
EBO
GuideMode

2 words
word
word
word
word
word
word
word
word
word
word
word

(output)
(input)
(output)
(output)
(output)
(output)
(output)
(output)
(output)
(output)
(output)
(output)

This service supplies the information normally returned by the
Initialize service (WIINI), but without the implication that the
application is just starting.
(See Section 5.1.2.) In addition,
two optional extra parameters exist that are not available with
the WIINI call.
5-4

TASK CONTROL SERVICES

I
I
I

The EBO parameter is boolean; it is true if the Extended Bitmap
Option Module
(three planes of video bitmap) is present in the
system.

The GuideMode parameter is boolean; it is true if the Guide Mode
setting on the Synergy Setup Menu is true.
If you wanted your
application to have facilities for doing things differently for
new users than for experienced users, you might use this flag to
determine whether to treat the user as new or experienced.

I
I
I

I
I
I
I
I
I
I

5.2

I
I
I

I
I
I
I
I

SYNERGY MESSAGE BOARD

The Synergy Message Board calls are intended for applications
that wish to send messages to the Synergy Message Board.
For
example, you might want a mail program to use the Message Board
services to notify users when they have new mail messages.
To
view any messages, users must return to the Synergy Main Menu.

The Synergy Message Board is a very limited resource and should
be used with restraint.
The message board can contain a maximum
of 5 (five) messages at one time.
Each message can be up to 40
characters in length.

I
I
I

If the message board receives more than five messages
time, the oldest message is automatically deleted.

I
I
I
I

5.2.1

I
I
I
I
I
I
I
I
I
I
I

I
I
I
I

one

MGMSG - Send Message to Synergy Message Board
2 words (output)
word (input)
word (input)
n bytes (input)

status
GroupIO
MessageLength
MessageText

The MGMSG call sends one message to the Synergy Message Board.
Message length must be less than 40 characters.
The Group 10 is
a 16-bit integer choosen by the caller to indicate a group or
category for the message.
In praGtice, each application should use the same group 10 for
all of its messages.
The caller should also make sure that the
group 10 is significantly random so that it does not conflict
with a group 10 of another application.

5-5

SYNERGY MESSAGE BOARD

5.2.2

MGDMS - Delete Message from Message Board
status
GroupID

2 words (output)
word

The MGDMS call deletes all messages with the same ID as the one
specified in the Group ID parameter.
This call allows an
application to delete all of its messages (or specific group of
messages) with a single call.

5-6

CHAPTER 6

WINDOW SERVICES

Table 6-1:
WORD

1
2
3
4
5
6

7
8
9
10
11
12
13
14
15
16

6.1.2

Window Descriptor Block
MEANING

Window ID
X coordinate of upper left corner of windowframe
Y coordinate of upper left corner of windowframe
width of the writable area of the window
Height of the writable area of the window
Flag Word (1 = true, 0 = false)
Bit 0 Stackable
Bit 1 Titled
Bit 2 Hidden
Bit 3 Color
Bit 4 White border
Bit 5 Clear on change size
Bit 6 (Reserved, must be 0)
Bit 7 VT
Bit 8 Invisible
Bit 9 (Reserved, must be 0)
Bit 10 3 planes
Bit 11 to 15 (Reserved, must be 0)
Minimum width of writable area of the window
Minimum height of writable area of the window
Maximum width of writable area of the window
Maximum height of the writable area of the window
X offset from windowframe to writable area of window
Y offset from windowframe to writable area of window
Overall width of the window
Overall height of the window
Owner task, word 1 of RAD50 name
Owner task, word 2 of RAD50 name

Specifying Window Coordinates

When a window is created,
its position can be specified in
coordinates expressed in GOS units.
The position can also be
specified with pseudo coordinates,
that indicate a general
location on the screen. The window server interprets the pseudo
coordinates and determines the exact positioning.
By using
pseudo coordinates, you can avoid a great deal of computation in
your application.
positions in both X (horizontal)
and Y (vertical)
specified using the coordinates shown in Table 6-2.

6-2

may

WINDOW SERVICES

Table 6-2:

Window Coordinates

VALUE

MEANING

-32767
-32766
-32765
-32764
-32763
-32762
-32761
-32760
-4095 .. -1

Don't care
Off window
Screen minimum
Screen maximum
Screen centered
Window minimum
Window maximum
Window centered
Window-relative position
(The upper left-hand corner of a window can be
positioned to the left or right of the upper left
corner of an existing window. When positioning to
the left of the existing window, negative
coordinates are used, so a position 300 pixels to
the left is -300. In order to encode
window-relative positions, subtract 2048 from the
relative coordinate. Therefore -300 pixels to the
left is encoded as -2348, and 2047 pixels to the
right is encoded as -1. -2048 is the upper left
corner of the window.)
Screen (or absolute) horizontal position
(1008 is middle of screen)
Screen (or absolute) vertical position
(600 is middle of screen)

O•• 2015

O.. 1199

Any value not specified in Table 6-2 is an invalid position.
When there is no window on the screen,
the window-oriented
positions are handled as though a window existed that is exactly
the size of the screen.
When a window is created or moved and its position is specified
in such a way as to make part of the window falloff the screen,
the window server adjusts the coordinates automatically to bring
all of the window onto the screen.
The coordinates that you
specify and the size of the window must be valid before this
adjustment can take place,
however.
The window server never
shrinks or truncates an oversized window, and it never corrects
an invalid coordinate.
For example, a horizontal position of 2016 is not a valid
starting position.
However,
a horizontal position of 2015 is
valid and is equivalent to specifying -32764.
Either 2015 or
-32764 guarantees that the window will be on the far right of the
screen.

6-3

WINDOW SERVICES

(Notice that video hardware may have larger screens
in the
future.
On a wider screen, -32764 will still mean "right side,"
but 2015 may not have that meaning.)

6.1.3

Specifying Window IDs

Each window has a unique ID that is assigned by the window server
when the window is created, and is returned to the application.
The application uses the window ID to identify the window when an
operation is
requested.
Four special IDs can be used as input
parameters to some of the operations.
An ID with the value -1 can be used in the Select operation
(WISLW) to get access to the entire screen.
This is not strictly
a window; the technique is used primarily by the window manager.
Any
application using this pseudo window must
"undo"
its
modifications to the screen and thus restore the
screen to its
state before the application used the pseudo window.
(The window
manager uses this technique when it draws window corners and
blinking bars during window operations.
It draws them in
complement mode, then draws them again in complement mode to
e rase them.)
An ID with a value of -2 can be used as input to any of the
window operations as a
reference to the
front window.
An
application can always refer to its front window with an ID of
-2, instead of using the window ID that is returned in the window
descriptor block. An application that creates more
than one
window must be certain that it knows which window is the front
window, however.
On return from a suspension, it can check the
WindowID parameter that is returned to see that it matches the
desired window'S ID.
If it does not match, the application can
call the Select Window service (WISLW) using the desired window'S
ID to bring that window to the front.
An ID with a value of -3 is used to indicate the next window.
This is accepted as input by the Select (WISLW) operation.
This
is a window server operation,
and should not be used by
applications,
lest they obtain a window belonging to another
application.
An ID of -4 is used to indicate
accepted as
input by the Select
window server operation, and should
lest they obtain a window belonging

6-4

the
rear window.
This
is
(WISLW) operation.
This is a
not be used by applications,
to another application.

WINDOW SERVICES
6.1.4

WICHW - Change the Size and Position of a Window

Status
DescriptorLength
WindowDescriptor()

2 words (output)
word
(input)
n bytes (input)

This service is used to change the size and position of the front
window.
It is an error to attempt to change a stackable window
or a window that is not the front window. When a window changes
size, any text in the title is centered in the new title area,
and is truncated if necessary (on the right side only).
The input from the window descriptor block is the window ID, X
and Y coordinates of the windowframe, and the width and height of
the writable part of the window.

6.1.5

WICRW - Create a Window

Status
DescriptorLength
WindowDescriptor( )

2 words (output)
word
(input)
n bytes (input and output)

This service saves the front window (if any), and creates a new
window. The new window becomes the front window. It is an error
to create a nonstackable window when the front window is
stackable.
The input from the window descriptor block is the X and Y
coordinates of the windowframe, of the window, and the window
attributes: stackable, ti tled, color, white border, clear on
change, VT, invisible, and three-plane. The output is the window
ID.
Creating a window of width and height equal to zero results in
full screen window with no white border or windowframe.

If you request a color window but the user has not told the
Synergy Window Manager to permit color windows, your request for
This
a color window is ignored and you get a monochrome window.
means that the window server will save only one plane of the
video bitmap.
You must be certain that the window server returned a TRUE
setting for the Color parameter on the Initialize (WIINI) call
before you assume that your request for a color window was
granted. Do not write to planes two or three of the video bitmap
unless all three planes are being saved.

6-5

WINDOW SERVICES
This caution does not apply to windows with the VT attribute,
since these windows are always considered to be three-plane
windows.
Also, the three-plane attribute will always
give
you
a
three-plane window, so long as the EBO option is present on the
system.
Notice that you cannot specify the hidden attribute in the WICRW
call.
You must first create the window and then ask that it be
hidden by calling the WIHDW service.
Notice also that only the window 10 field of the window
descriptor block is returned by this service. To update the
other entries of the window descriptor block, you must call the
Get Window Parameters (WIGEW) service.
When a window is created, the maximum and mininum sizes default
to the actual window size, so the size of the newly created
window cannot be changed by the user.
You must call the Set
Window Parameters (WISWP) service to change the maximum and
minimum sizes ii. you want to allow the user to modify the
window's size.
If you request a title, but the window's writable area is too
large to permit a title line on the screen, the title is omitted.
The application in Appendix A uses the WICRW service
A-16, A-26, A-29, A-33, and A-48).

6.1.6

(see

Pages

WIDSW - Destroy a Window

Status
WindowID

2 words (output)
word (input)

When a window is no longer needed, it must be destroyed.
Destroying a window removes it from the screen, uncovering any
windows occluded by it. All storage allocated to the window is
freed.
The window being destroyed must be the front window.
The next
window. becomes the front window, whether or not it is owned by
the same application. If the application has another window, it
must call the Select Window (WISLW) service to ensure that its
next GIDIS output actually goes to its own window.
The application in Appendix A uses the WIDSW service
A-1S, A-28, A-31, A-36, and A-48).

6-6

(see

Pages

wINDOW SERVICES

6.1.7

WIERW - Display Error Window
Status
Up to 5 strings:
TextLength
Text ( )

2 words (output)
word
(input)
n bytes (input)

The window server maintains a hidden window,
called the error
window.
It is used only when an application calls the WIERW
service (typically, when the application cannot create a window
of its own due to a lack of resources). The Display Error Window
service allows the application to display information to the
user.
Since the error window is created at Synergy start-up, it
is always available, even when the raster file is full.
The application supplies up to five lines of text.
The maximum
length of each text line is 40 printing characters, although you
can include additional characters to control renditions
(see
Section 7.2.1).
The window server selects the error window and
displays the text in it. Control returns to the application only
when the user presses RESUME.
NOTE
The WIERW service can be called at any time, even
after the failure of a WIINI call, or before the
WIINI call is attempted.
The WIERW service
destroys any windows that the application has
already created.
The WIERW service can
be
followed only by a WIDON call, and then an exit
from the application.
The application in Appendix A uses the WIERW service
A-9 and A-50).

6.1.8

(see

Pages

WIEWT - End Wait Message
status

2 words (output)

This service erases the message and clock icon created by the
WISWT or WIXSWT service.
The window manager redisplays the
previous title -- centered or right-truncated
in the title
line of the front window.

6-7

WINDOW SERVICES

6.1.9

WIGEW - Get Window Parameters
Status
DescriptorLength
WindowDescriptor()

2 words (output)
word
(input)
n bytes (input and output)

This service is used to retrieve a full description of a window.
The input from the window descriptor block is the window ID. The
window ID may be set to -2, in which case the descriptor block is
filled with information about the front window.
The entire
descriptor block is output, including the actual window ID of the
window being described.
Notice that five services use the window descriptor block as a
parameter,
and may return output information in the window
descriptor block. Only the Get Window Parameters service updates
all fields of the window descriptor block, however.
Before using
values in the window descriptor block
(such as location or
dimension) your application may need to call the WIGEW service.
The application in Appendix A uses the WIGEW service
A-1S, A-20, and A-48).

6.1.10

(see

Pages

WIHDW - Hide a Window
status
WindowID

2 words (output)
word
(input)

This service is used to remove a window from the display.
It is
not destroyed
Select a window (WISLW) will bring it back
but it is not visible. A hidden window is not in the stack of
windows; thus it cannot be selected by the user.
The specified window must be the front window. The next window
becomes the front window, whether or not it belongs to your
application.
An error occurs when an attempt
window.

6-8

made

hide

stackable

WINDOW SERVICES

6.1.11

WilDA - 10 of a Window at a Point
Status
X
Y

Present
WindowID

2 words
word
word
word
word

(output)
(input)
( input)
(output)
(output)

This service is used to determine whether a visible window exists
at point X,Y on the screen.
If it does, Present is returned as
true and WindowIO contains the window 10 of the visible window at
that point.
If no visible window exists there, Present is
returned as false.

6.1.12

WIPOW - Change Position of a Window
Status
OescriptorLength
windowoescriptor()

2 words (output)
word
(input)
n bytes (input and output)

This service is used to move a window to
window must be the front window.

new

location.

The

The input from the window descriptor block is the window 10, and
the X and Y coordinates of the windowframe.
The X and Y
coordinates may be pseudo values (such as -32763 for screen
center).
Be sure to call the Get Window Parameters (WIGEW)
service if you want the window descriptor block updated after the
WIPOW call.

6.1.1 ~

WIPSW - Push a Window
status
WindowIO

2 'Nords (output)
word
(input)

This service moves the specified window
display (behind all other windows).

the

rear

the

When the specified window is the front window,
the next window
becomes the front window, whether or not it belongs to your
application. The highlighting of titles on the former f~ont
window and the new front window is adjusted automatically.
An error occurs when an attempt is made to push a
window, since stackable windows cannot be reordered.

6-9

stackable

WINDOW SERVICES

6.1.14

WISLW - Select a Window
status
WindowID

2 words (output)
word
(input and output)

This service is used to bring a specified window to the front of
the display, whether or not it is a hidden window.
The current
front window is saved (as the second window in the stack) and the
specified window becomes the front window.
GIDIS output is directed only to the front window.
If your
application uses more than one window, use this service to ensure
that the correct window is in front before you issue GIDIS
instructions.
An error occurs when an attempt is made to select a window when
the current front window is stackable, since stackable windows
cannot be reordered or covered by a nonstackable window.
This routine accepts two special pseudo values in WindowID.
Value -3 refers to the second window, the window immediately
behind the front window. Value -4 refers to the rear window.
If
two windows exist on the screen, both -3 and -4 select the rear
one.
If only one window exists, both -3 and -4 select it.
If no
window exists,
both -3 and -4 select the pseudo-window that is
the entire screen.
The highlighting of titles on the former front window and the new
front window is adjusted automatically.

6.1.15

WISWP - Set Window Parameters
Status
DescriptorLength
WindowDescriptor( )

2 words (output)
word
(input)
n bytes (input)

This service sets the maximum and minimum width and height of the
window.
These values control how much the user may change the
size of a window. When a window is created (with WICRW)
these
values are defaulted to the actual window size.
So, call the Set
Window Parameters service if you want to allow the user to be
able to modify the window size.
This routine will not set a limit that is more restrictive than
the current size.
An attempt to do so will set the appropriate
limit to the current size.

6-10

WINDOW SERVICES
The input from the descriptor block is the window ID, minimum and
maximum widths,
minimum and maximum heights and the window
attribute, "clear on change" and "invisible." There is no output
from this service.
The application in Appendix A uses a window descriptor block (see
Pages A-16 and A-48).

6.1.16

WISWT - Start Wait Message
Status
MessageLength
MessageText( )

2 words (output)
word
(input)
n bytes (input)

This service displays a clock icon and a message in the title
area of the front window.
The current title is temporarily
erased. An error occurs if the front window does not have a
title.
This service is used to inform the user that a
time-consuming operation is in progress.
The clock icon is
automatically added to the front of the message, so you should
not include it in the message text.
You must call the End Wait Message (WIEWT) service to restore the
original title of the window when the time-consuming operation is
completed.
If you permit the user to adjust the window size, plan your wait
message so that it makes sense in the narrowest window that you
allow.
See Section 6.1.18 for a variation on this service.

6.1.17

WITTL - Change Title of Front Window
Status
TitleLength
TitleText( )

2 words (output)
word
(input)
n bytes (input)

This service erases the current ti tle of the front window and
Do not call this
in its place.
displays the specified ti tle
displaying the
that
is
window
service to change the ti tle of a
WIEWT.
service,
wait message; use the End Wait Message
The application in Appendix A uses the WITTL service
A-16 and A-48).

6-11

(see

Pages

WINDOW SERVICES

6.1.18

WIXSWT - Start Wait with Message Frame
Status
FrameID

2 words (output)
word
(input)

This service combines the action of two other services, WIRMS
(Read Message Frame) and WISWT (Start Wait Message). The message
frame specified by FrameID is read into the window server's
buffer,
and its first line is taken as the wait message. The
wait message is displayed with the clock icon in the title area
of the front window. The message text is not made available to
the application. The clock icon is added automatically to the
front of the message, so you should not include it in the message
frame.

6-12

CHAPTER 7

CHAPTER 7
MENU SERVICES

This chapter includes descriptions of
referred to generally as menu services.

all services that
This includes:

•

Frame file services

•

High-level menu services

•

Filename services

•

Directory name services

•

Primitive menu and string editing services

7.1

FRAME FilE SERVICES

are

Many of the services described in this chapter use a FrameID
parameter to refer to a menu in the application's frame file.
Before the frame file can be referenced, it must be explicitly
opened.
The frame file should be closed before the application
exits. When cooperating tasks use different frame files, each
task must close its frame file before relinquishing control to
the other task.

7-1

FRAME FILE SERVICES

7.1.1

OPENME - Open Frame File
Status
FrameFileSynchNumber ($FCTV$)
FilenameLength
FilenameText()

2 words
word
word
n bytes

(output)
(input)
(input)
( input)

Opens the frame file for use by the application.
The FrameFileSynchNumber is the number that the Frame Compiler
Tool equates to the global symbol, $FCTV$. The OPENME service
checks the number against a number stored in the frame file that
it opens.
If the numbers match, the application was built with
the global symbols that FCT defined for the actual frame file
that is being opened.
If the numbers do not match, an error
message is displayed by the OPENME service, although execution is
allowed to proceed.
(This is a debugging error and should never
occur in a production application.)
Only one frame file can be open at any point during the
application's execution. Notice, however, that there is no error
return if you try to open a second frame file.
The OPENME
service assumes that you are trying to open the same file that is
already open and simply ignores the call.
The window server closes the frame file when the application
calls the Suspend service and then automatically reopens the
correct frame file before it reactivates the application and
returns to it from the Suspend call.
There is no restriction against using two or more frame files in
an application, but since each frame file defines the $FCTV$
symbol, you will get a multiple-symbol definition error during
the task build if two files are used by the same task.
You must
alter the MACRO file produced by FCT for the second frame file by
changing the $FCTV$ symbol to, say, $FCT2$. Thus, if you wanted
two frame files in the same task, you could open the first file
using the symbol $FCTV$. Then after closing it, you could open
the second frame file u~ing the $FCT2$ symbol.
There doesn't seem to be any advantage to using two frame files
in one task, unless you want to try to put the majority of your
HELP frames in a second frame file and locate it on a separate
diskette. Then the user who wants HELP would insert the diskette
while running your application. Notice that it is not possible
to read menus from one frame file and have menu services
automatically read HELP frames from the other frame file.
Switching between two frame files must be done by calling CLOSEM
and OPENME services from the application code.

7-2

FRAME FILE SERVICES
The default file specification is APPL$DIR:. Therefore,
if you
omit the device and directory name from the file specification
for the frame file, it will automatically be opened from the
[ZZAPnnnnn] directory.
The application in Appendix A uses the OPENME service (see
A-iS and A-50).

7.1.2

Pages

ClOSEM - Close Frame File
Status

2 words (output)

Closes the frame file.

7.1.3

WIRMS - Read Message Frame
Status
CountOfLinesReturned
Offsets()
MessageBuffer ( )
Fl'ameID
MaxBufferLength

2 words
word
n words
n bytes
word
word

(output)
(output)
(output)
(output)
(input)
( input)

Reads a message frame from the frame file and returns it
application.

the

The message text is returned in the MessageBuffer as a single
string of characters (no separators, no CRLFS). The Offsets
array contains byte offsets into the MessageBuffer for each line
of the message.
(The first offset is always 0.) The Offsets
array must have at least one more entry than the number of lines
expected in the message, since the last offset points to the byte
beyond the last line. The length of each line can be computed by
subtracting the line's offset from the offset of the next line.
An error is returned if the message frame's text exceeds the
Notice
that
buffer
size
declared
by
MaxBufferLength.
CountOfLinesReturned is not an input parameter; there is no
bounds check on the Offsets array.
A message frame can also be displayed directly on the screen in a
message window by calling a menu service (see Section 7.2.17).
The application in Appendix A uses the WIRMS service
A-8 and A-50).

7-3

(see

pages

HIGH-LEVEL MENU SERVICES

7.2

HIGH-LEVEL MENU SERVICES

High-level menu services display menus, solicit input from the
user, and return the user's input to the application.
High-level
menu services are provided as a convenience to the application
developer, and to foster consistency in the user interface.
An application requests a high-level menu service through a call
on the window server.
Many of the services offer a static or
dynamic form of call. The static call retrieves the text of the
menu from a frame file using a frame 10 which is passed as a
parameter. The dynamic call passes all the text directly from
the application.
A high-level menu service creates a window for the menu,
determining the window size automatically. The window's position
on the screen is controlled by parameters that have been stored
in the frame file or that are passed on the call. The service
then reads the keyboard (through the character-passing buffer),
and responds to the user's actions. When an appropriate action
has been taken by the user -- that signals the end of the menu
interaction
the menu service destroys the menu window and
returns appropriate values to the application.
A menu consist~ of headers and options. Headers are displayed at
the top of the menu.
The text of each header is left-justified.
Options are displayed on lines below the last header.
Options
may be stacked in a single column, spread across a single row, or
arranged in a matrix of rows and columns.
The number of options
supplied must be equal to the row count times the column count.
(One or more options may be blank, however.
See the SKIP and
NOCHOOSE attributes, described below.)
One of the actions that the user can take is to press the HELP
key.
Menu services recognize the HELP key and automatically
retrieve a HELP frame from the frame file using the appropriate
frame 10 which either was passed from the application or was
stored in the menu frame in the frame file.
The HELP frame is
displayed in another window,
and the menu service permits the
user to move around a HELP tree if one has been provided in the
frame file.
Eventually, the user presses the RESUME key to leave
HELP. The menu service then resumes menu processing.
This
processing of the HELP key is totally automatic. When the menu
service eventually returns the user's response to the menu,
it
gives no notification to the application that HELP was used.
Each option on a menu can have an associated HELPframeIO.
The
HELPframeIO contains the frame 10 of the HELP frame to be used,
should the user ask for HELP when the cursor bar is positioned on
the option.
If the user asks for HELP on an option that has a 0
HELPframeIO, the window server displays a window that informs him
7-4

HIGH-LEVEL MENU SERVICES
that no HELP is available. The user must then press RESUME to
continue without HELP.
This is annoying to
most
users,
especially in the Synergy environment, where HELP always seems to
be present. On the rare occasion when you do not want to supply
HELP for a user, it may be less annoying to him if you code the
HELPframeID with a -1 value (NOHELP). When the window server is
asked to provide HELP on an option whose HELPframeID is -1, it
simply beeps. The same message is conveyed to the user, but he
need not read a new window, and he need not press a key to
continue.
Each option can have an associated optionValue. The Optionvalue
is a number that identifies the option. Rather than return the
text of the option that was chosen by the user, menu services
return the Optionvalue.
Optionvalues must range between 0 and 255.
255 have a special meaning:

Optionvalues 254

and

•

OptionValues 254 (NOCHOOSE) are displayed in dim rendition
and cannot be chosen by the user. NOCHOOSE options are
useful on menus which are displayed often, but have options
which are sometimes invalid. The user always sees the menu
in a familiar form -- with the same options -- and moves the
cursor bar the same way. Options in dim rendition signal to
the user that they will simply beep when selected.

•

OptionValues 255 (SKIP) are displayed in bold rendition, and
the cursor bar never stops on them. SKIP options can be used
to provide blank lines or extra text on the menu.

When options are arranged in a matrix and blank options are used
to group the options into logical subgroups, you should use the
NOCHOOSE attribute rather than the SKIP attribute. A blank line
with the NOCHOOSE attribute lets the cursor move smoothly over
it, whereas the SKIP attribute preverits the cursor bar from
moving sideways onto it.
Single-choice and flow control menus also associate a nextframeID
with each option, in addition to the HELPframeID and the
OptionValue. The nextframeID points to another frame in the
frame file. When an option is chosen by the user, the associated
nextframeID is not used by the menu service; it is merely
returned
to the application as an output parameter.
The
application can use it to select the menu to be displayed on the
next call to menu services.
NextframeIDs provide a mechanism for storing the structure of a
menu tree in the frame file. Their use is not required, although
the actual frameID is always present in the frame file or in the
dynamic call, probably set to o.
7-5

HIGH-LEVEL MENU SERVICES
The rendition of options is controlled by menu services. Options
are usually displayed in normal rendition. When selections are
being made on multiple-choice menus,
the currently selected
options are redisplayed in dim italics.

7.2.1

Menu Renditions

A rendition is a variation in the way a character is displayed on
the screen.
For example, a character -- sayan "A" -- might be
displayed at one of three different levels of brightness; dim,
normal or bold.
Each of these brightness levels is considered a
rendition. Giving the character a slant
(italic rendition)
or
drawing a line under it (underline rendition) are other examples.
Text in menus is generally in normal rendition, but you can vary
the
rendition
by
inserting special nonprinting character
sequences within the headers and the options in menus and string
editing windows,
and in the prompt strings in string editing
windows.
The nonprinting sequence starts with a character with the value
28 decimal.
One, two, or three digits follow, and the sequence
ends with either a "+" or a "_H. The digits are characters "0"
through "9".
FCT will accept character 28 in the source frame
file, but it will also translate the two-character sequence "'$"
into character 28 in headers and options (see Section 8.2.6).
•

The digits form numbers in the range 0 to 999.

•

These numbers represent a binary value whose bits stand for
individual attributes.

•

The last character determines whether these values are set or
cleared; "+" sets attributes (i.e., the value is ORed with
the current rendition), "-" clears attributes (i.e., the
value is NOT ANDed with the current rendition).
Bit

Value

Attribute

1
2
4
8
16
32

Intensity
Intensity
Italic
underline
Reverse
Boxed

1
2
3
4
5

Intensities are determined by using bits 1 and 0 in combination.
There are three levels of intensity -- dim, normal, and bold.

7-6

HIGH-LEVEL MENU SERVICES

Bits 1 and 0

Intensity

00
01
11

Dim
Normal
Bold

The combination of dim and
default renditions are:
Headers:
Options:
Prompt string:
SKIP option:
NOCHOOSE option:

underline

not

supported.

The

Normal
Normal
Normal
Bold
Dim

To underline the word ABC in a line, you must precede it with the
special character, 28, followed by "8+" and then follow the word
with the special character 28 and "8-". In a text line for FCT,
the sequence would be:
Here is the \$8+ABC\$8- word, underlined.
The string "Press \$32+{RESUME}\$32- to leave HELP." will set the
font to be the boxed font at the start of the string "{RESUME}"
and set it back after it (see Section 4.3.6).
The application in Appendix A displays strings in its own window
and does its own interpretation of the embedded control sequences
(see pages A-11 through A-13).

7.2.2

KEY USAGE

Each high-level menu service predefines a set of function keys.
For all menus except HELP menus, the MAIN SCREEN, EXIT, and F5
keys are returned to the application with success status, with
all other output parameters returned as zeros.
User selections
for the set-up menu are ignored. You should always check the
KeyPressed parameter on a success return to see if the user has
pressed one of these keys.
The CANCEL key undoes all selections, returns the cursor bar to
the first item on a menu, and waits for further input from the
user.

7-7

HIGH-LEVEL MENU SERVICES
The SELECT key is recognized on multiple-choice menus.
It
changes the rendition of an option, updates the count of selected
options, and waits for further input from the user.
The D9 and RETURN keys mean an action is to be performed.
On
single-choice,
flow control,
and multiple-choice menus,
the
option the cursor bar is on is selected, the menu is destroyed,
and control returns to the application with successful status and
all output parameters.
Set-up menus do not return to the
application when these keys are pressed. These
are used to
perform the operation for the option and the menu remains
displayed with the cursor bar moved to the next set-up option.
A
set-up menu is successfully terminated only when the user presses
EXIT.
See Chapter 11 for the conventions used to display set-up
menus.
The HELP key displays the HELP frame associated with the option
the cursor bar is on.
During the display of HELP frames, the
NEXT SCREEN and PREV SCREEN keys are used to move forward and
bac~ward
within the HELP tree.
The RESUME key terminates the
display of HELP frames, and returns to the menu.
If a HELP frame has options, a cursor bar is displayed on one of
the options, and the DO and RETURN keys are also enabled.
If the
user presses DO, RETURN, or NEXT SCREEN, the current HELP frame
is destroyed, a new HELP frame is read from the frame file using
the NextFrameID of the current option, and the user's response to
the new HELP frame is solicited.

1.2.2.1 Termination Key List - You can enhance the definition of
keys by supplying a termination key list.
If a key that is in
the termination key list is pressed, the menu service treats it
as a success, destroys the window, and returns all selections.
For example, you may want to treat the ADDTNL OPTIONS key as a
special key on one of your menus.
You put the ADDTNL OPTIONS key
on the termination key list.
When the menu service detects an
ADDTNL OPTIONS key while displaying that menu, it returns the key
to your application instead of just beeping.
Menu services consults the termination key list before it
responds with the usual processing of the key.
Thus, if you put
the SELECT or CANCEL keys on the termination key list,
you are
telling menu services that it should not process that key but
should return it to the application as a "success" response.

7-8

HIGH-LEVEL MENU SERVICES

7.2.3

Single-Choice Menus

A single-choice menu allows the user to make
control returns to the application.

7.2.4

choice

EXSING - Static Single-Choice Menu

Status
KeyPressed
NextFrameIDChosen
OptionValueChosen
FrameID

7.2.5

one

2 words
word
word
word
word

(output)
(output)
(output)
(output)
(input)

DSINGL - Dynamic Single-Choice Menu

Status
KeyPressed
NextFrameIDChosen
OptionValueChosen
TerminationKeyCount
TerminationKeyList()
X
y

HeaderCount
For each header:
HeaderLength
HeaderText()
RowCount
ColumnCount
For each option:
OptionHelpFrameID
OptionNextFrameID
optionLength
OptionText()
OptionValue

7-9

2 words
word
word
word
word
n words
word
word
word

(output)
(output)
(output)
(output)
(input)
(input)
(input)
(input)
(input)

word
n bytes
word
word

( input)
( input)
(input)
(input)

word
word
word
n bytes
word

(input)
(input)
(input)
( input)
( input)

before

HIGH-LEVEL MENU SERVICES

7.2.6

HELP Menu

The application can call the window server to display a HELP
frame from the frame file.
There is no dynamic version of this
call.
See the description of HELP key processing in Section 7.2 and the
discussion of HELP frames in Chapter 11.

7.2.7

EXHELP - Static HELP Menu
status
FrameID

2 words (output)
word
(input)

The application in Appendix A uses the EXHELP service (see
A-38 and A-50).

7.2.8

Pages

Multiple-Choice Menus

Multiple-choice menus allow the user to make multiple selections
before returning to the application. The menu service inserts a
header just above the options that indicates the maximum number
of selections allowed and the number of selections that have been
made. This header is updated automatically by the menu service
as the user moves around the menu, making and cancelling
selections with the SELECT key. The last selection is made and
the menu is terminated when the user presses the DO or RETURN
key.

7.2.9

EXMULT - Static Multiple-Choice Menu
2 word
word
word
n bytes
word

Status
KeyPressed
CountOfOptionsChosen
OptionValuesChosen( )
FrameID

7.2.10

(output)
(output)
(output)
(output)
(input)

DMULTI - Dynamic Multiple-Choice Menu
2 words
word
word
n bytes

Status
KeyPressed
CoutOfOptionsChosen
OptionValuesChosen()
7-10

(output)
(output)
(output)
(output)

HIGH-LEVEL MENU SERVICES
TerminationKeyCount
TerminationKeyList()
X
y

MaxChoices
HeaderCount
For each header:
HeaderLength
HeaderText()
RowCount
ColumnCount
For each option:
OptionHelpFrameID
OptionLength
OptionText ( )
OptionValue

7.2.11

word
n words
word
word
word
word

(input)
(input)
(input)
(input)
(input)
( input)

word
n bytes
word
word

(input)
(input)
(input)
(input)

word
word
n bytes
word

(input)
(input)
(input)
(input)

Flow Control Menus

The flow control menu services display a two-level menu,
get a
choice from the user, and return the choice to the application.
A flow control menu provides an easy way to compress two levels
of a menu hierarchy.
A flow control menu is a list of titles across the top of the
screen, with a single-choice,
single-column submenu "hanging"
from one of the titles. The call specifies the InitialSubmenu to
be displayed (numbered from 0, left-to-right). As the left and
right ARROW keys are pressed, the original submenu disappears and
a different submenu appears below the title to the left or right.
The function keys Fll, F12, F13 and ADDTNL OPTIONS correspond to
the first four submenus.
NOTE
Although more than four submenus are permitted,
you should restrict your flow control menu to
four submenus since there is a convention that
maps these four function keys onto these four
submenus.
Once the flow control menu is displayed by a flow control menu
call,
these keys are recognized by menu services; and they cause
the corresponding submenu to be displayed, without displaying the
submenus in between.
If there are less then four submenus, the
rightmost of these function keys display the rightmost menu.

7-11

HIGH-LEVEL MENU SERVICES

DO or RETURN signifies selection and
application.

successful

return

the

A flow control menu must have at least one title; each title must
have a submenu with at least one option.

7.2.12

EXFLOW - Static Flow Control Menu
status
KeyPressed
NextFrameIDChosen
OptionValueChosen
FrameID
Ini tialSubMenu

2 words
word
word
word
word
word

(output)
(output)
(output)
(output)
(input)
(input)

The application in Appendix A uses the EXFLOW service (see
A-37 and A-50).

7.2.13

DFLOW - Dynamic Flow Control Menu
status
KeyPressed
NextFrameIDChosen
OptionValueChosen
TerminationKeyCount
TerminationKeyList()
InitialSubMenu
X
y

TitleCount
For each title:
TitleLength
TitleText()
SubmenuOptionCount
For each submenu option:
OptionHelpFrameID
OptionNextFrameID
OptionLength
OptionText()
Optionvalue

7.2.14

Pages

2 words
word
word
word
word
n words
word
word
word
word

(output)
(output)
(output)
(output)
(input)
(input)
( input)
(input)
( input.>
(input)

word
(input)
n bytes (input)
word
(input)
word
word
word
n bytes
word

(input)
(input)
(input)
(input)
(input)

Set-Up Menu

set-up menus are special-purpose menus that display
settings for a number of diverse characteristics.
7-12

the current
The user can

HIGH-LEVEL MENU SERVICES
confirm the current setting by not changing it, or can change the
setting to a new value. Control returns to the application when
the user presses the EXIT key or any other key in the termination
key list. There is no validation of new values by menu services.
Each option has a class associated
classes, numbered as follows:

with

it.

There

are

six

A Binary class option has two text strings associated with
it, supplied by the application. The user toggles between
them, by pressing the DO key.

A Menu class option has a single-choice menu associated with
it that supplies the text string appropriate to the
characteristic. The user chooses a value for the
characteristic by pressing the DO key to see the menu, then
making a selection on the menu.

An Alphastring class option has a text string as a value.
The user changes it by editing the text string.

A Numericstr:ing class option has a number string as a value.
The user changes it by editing the number string. Numbers
are unsigned integers that range between 0 and 65535.

An Alphastring/NOECHO class option has a text string as a
value. The user changes it by editing the text string. The
string is not echoed to the screen, except as a checkerboard
character in each character position. This option class is
used to permit users to enter text strings, such as
passwords, without echoing the text on the screen.

A Numericstring/NOECHO class option has a number string as a
value. The user changes it by editing the number string.
Numbers are unsigned integers that range between 0 and 65535.
The digits are not echoed to the sCreen, except as a
checkerboard character in each character position. This
option class is used to permit users to enter numbers without
echoing them on the screen.

7.2.15

WIXPS - Static Set-Up Menu

2 words
word
word
n bytes
word
word

Status
KeyPressed
CountOfOptionschanged
OptionValuesChanged()
FrameID
RowCount
7-13

(output)
(output)
(output)
(output)
(input)
(input)

HIGH-LEVEL MENU SERVICES
For each option:
OptionClass
word
(input)
If Binary (1):
CurrentFlag (O=iirst,
1=second) word
(input & output)
If Menu (2):
CurrentValue
word
(input & output)
If Alphastring (3) or Alphastring/NOECHO (5):
MaxStringLength
word
(input)
CurrentStringLength
word
(input & output)
CurrentStringText()
n bytes (input & output)
If Numericstring (4) or Numericstring/NOECHO ( 6 ) :
CurrentNumber
word
(input & output)
The set-up menu in the frame file supplies the position, headers,
termination key list, and options. The input parameters supply
the initial setting of each option.
You supply the initial
setting for each option in the order that the options appear in
the frame file.
The window server checks that the OptionClass
parameter matches the class that FCT provided when it compiled
the frame.
The set-up menu in the frame file may have options with the SKIP
attribute.
These have an option class that tells menu services
to ignore them.
Do not include parameters for these options.
See the description of output parameters under Section 7.2.16.
The application in Appendix A uses the WIXPS service
A-21 and A-50).

7.2.16

(see

WIPS - Dynamic Set-Up Menu
2 words
word
word
n bytes
word
n words
word
word
word

Status
KeyPressed
CountOfOptionsChanged
OptionValuesChanged()
TerminationKeyCount
TerminationKeyList()
X
Y

HeaderCount
For each header line:
HeaderLength
HeaderText()
OptionCount
For each option:
OptionHelpFrameID
OptionLength

(output)
(output)
(output)
(output)
(input)
(input)
(input)
(input)
(input)

word
(input)
n bytes (input)
word
(input)
word
word
7-14

(input)
(input)

Pages

HIGH-LEVEL MENU SERVICES
OptionText ( )
n bytes (input)
OptionValue
word
(input)
OptionClass
word
(input)
If SKIP (0): nothing else
If Binary (1):
CurrentFlag
(O=first, l=second)
word
(input & output)
FirstTextLength
word
(input)
FirstText()
n bytes (input)
SecondTextLength
word
( input)
SecondText()
n bytes ( input)
If Menu (2):
NextFrameID
word
(input)
CurrentValue
word
(input & output)
If Alphastring (3) or Alphastring/NOECHO (5):
MaxStringLength
word
(input)
CurrentStringLength
word
(input & output)
CurrentStringText()
n bytes (input & output)
If Numericstring (4) or Numericstring/NOECHO (6):
CurrentNumber
word
(input & output)
The output
follows:

parameters

from

WIXPS

and

WIPS

services

are

•

CountOfOptionsChanged - This is 0 if the user has not changed
any of the set-up options. If the user changes one or more
set-up options, the count is returned in this field.

•

OptionValuesChanged - Notice that this is a byte array.
These bytes have unspecified values if CountOfOptionsChanged
is O. Otherwise, the first n bytes in this string supply the
optionValue of the n options that have been changed. An
OptionValue is a number less than 254, so it fits in a byte.
Be sure there are as many bytes in this string as there are
options on the set-up menu. The OptionValues of the changed
options are not returned in any order.

•

CurrentFlag - For each Binary class option, you supply the
initial setting of the option in this field on input, and you
receive the final setting of the option in this field on
output.

•

CurrentValue - For each Menu class option, you supply the
Optionvalue of the option on the pop-up menu that should be
used as the initial setting. The OptionValue of the final
option chosen from the pop-up menu is returned in this
parameter.

7-15

HIGH-LEVEL MENU SERVICES
•

CurrentStringLength and CurrentStringText - For each
Alphastring and Alphastring/NOECHO class option, you supply
the initial string's length and text in these fields on
input, and you receive the final string's length and text in
these fields on output.

•

CurrentNumber - For each Numericstring and
Numericstring/NOECHO class, you supply the initial number in
this field on input, and you receive the final number in this
field on output.

There is some redundancy in the output parameters. You can,
if
you
want,
simply ignore the CountOfoptionsChanged and the
OptionValuesChanged.
In this case, you would look at each of the
set-up options to see what values were returned.
You can use CountOfOptionsChanged to bypass this scan of all the
set-up options.
If the CountOfOptionsChanged shows that no
options were changed, you need not check the other outputs.
If
the CountOfOptionsChanged shows that some options were changed,
the first byte in OptionvaluesChanged identifies the OptionValue
of the first option that was changed, the second byte identifies
the OptionValue of the second option that was changed, etc.

7.2.17

Messages

Message menus are menus without any options. They consist only
of headers.
The menu service displays the headers and waits
until the user presses a termination key. The EXIT, MAIN SCREEN,
and F5 keys are always recognized as terminators by the service.
You should supply other keys as termination keys.
Be sure to
check the KeyPressed parameter on return from the service, to see
what action to take (see Section 11.2.3).
Message frames are also used to store text strings in the frame
file.
You can read the text of the message frame into memory
without putting it on the screen by calling the WIRMS service
(see Section 7.1.3).

7.2.18

EXMESS - Static Message Frame
2 words (output)
word
(output)
word
(input)

Status
KeyPressed
FrameID

7-16

HIGH-LEVEL MENU SERVICES

The
ieation in Appendix A uses the EXMESS service (see
Ac-37 and A-50).

Pages

- Dynamic Message Frame

"19

stat.us
ressed
TerminationKeyCount
TerminationKeyList()

2 words
word
word
n words
word
word
word
word

Hel
rameID
HeaderCount
Fo r' each heade r :
HeaderLength
Heade rTex t ( )

(output)
(output)
(input)
(input)
(input)
(input)
(input)
(input)

word
(input)
n bytes (input)

EDITING
The string editing menu services provide all the functionality of
the
tring editing primitives in a single call.
They create a
string editing window, read and echo the user's keystrokes,
and
then destroy the window.
The string editing services require a
frame I
supply the header and prompt.
There are no dynamic
version
of these calls. To vary the interactive behavior, you
must use the primitives.
Notic

that there is a

string

editing

primitive,

Edit

String

Field (WIEF), that allows you to create a string editing field in
your applicat.ion window, without creating a special
Section 7.6.4).

window

(see

When reading keystrokes into a string field,
control characters
are accepted and echo in the dim font.
Also, the ENTER key on
the numeric keypad inserts a control-M
(carriage
return)
character into the string.

7,3.1

phanumeric String Editing
status
ressed
ReturnstringLength
Returnstring ( )
FrameID
InitialStringLength

2 words
word
word
n bytes
word
word
7-17

(output)
(output)
(output)
(output)
(input)
(input)

STRING EDITING
InitialString()
The frame-type of
"Alphastring."

the

n bytes (input)
frame

specified

the

call

must

The frame file supplies two options.
The text of the first
option is taken as the prompt; the text of the second option as
the initial value of the string to be edited.
If InitialStringLength is 0,
InitialString is ignored.
If
InitialStringLength is nonzero, the InitialString overrides the
default string stored in the frame file.
The frame file's default string (second option) gives the maximum
length of the field,
however.
Be sure to allocate this many
bytes for the ReturnString parameter.
The two options in the frame file are displayed on a single line
in the window,
so their combined length cannot exceed the
allowable window width of 78 characters.

7.3.2

WIXNUM - Numeric String Editing
Status
KeyPressed
ReturnNumber
FrameID
InitialNumber

The frame-type of
"NumericString."

the

frame

2 words
word
word
word
word

(output)
(output)
(output)
(input)
(input)

specified

the

call

must

The frame file supplies two options. The text of the first is
taken as the prompt,
the second is ignored.
You supply the
starting number in the InitialNumber parameter.
A five-byte
field in the window is provided for the number.
The user can edit or enter an integer value from 0 to 65535.
The
number is converted to binary and returned in ReturnNumber.
The
user cannot enter a plus or minus sign, or a decimal point.
You
must call the Alphanumeric String Editing service (WIXSTR) and do
your own parsing of the input if you want to allow signed numbers
or decimal points.

7.4

FILENAME SERVICES

These services are used to retrieve the names of files.

7-18

full

FILENAME SERVICES

file specification is returned to the application.
specification has the usual format:

The full file

NODE::DEVICE:[DIRECTORY]FILENAME.TYP;VERSION
In a DECnet or cluster environment the file specification can be
up to 70 characters long.
You should plan ahead for these
environments and reserve 70 bytes in your parameters so that
these longer file specifications can be returned.

7.4.1

Old File

This service displays a list of existing files
in one
directories and allows the user to make selections.

Your application supplies a wildcard specification as the last
header.
The service prepares a menu window using all the headers
and a matrix of options that is always six rows by three columns.
The initial display of options contains all filenames that match
the wildcard specification.
If more than 18 filenames match the
wildcard specification, the service displays a down arrow on the
menu to indicate that the user can scroll the menu window down
onto additional matching filenames.
As soon as scrolling is
started,
an up arrow is displayed to show the user that he can
scroll back up over the filenames.
Up to 256
filenames may be
presented at a time.
If the user's directory contains more than 256 files, or if the
user wants to look at multiple directories and the combined
number of filenames exceeds 256, then the user must extract some
subset of files by using a new wildcard specification.
The user
modifies the wildcard specification by pressing the FIND key and
entering a new specification.
The current and new specifications
are then merged and redisplayed in the last header.
The matrix
of options is updated with files matching the new wildcard
specification.
The service permits the user
to enter a node
name, in case the system is tied into OECnet.
If the user presses FIND,
then supplies a
new
wildcard
specification,
then presses SELECT instead of DO, all filenames
that match the new specification (up to the maximum allowed)
are
selected automatically and redisplayed in dim italic.
If the user presses ADOTNL OPTIONS, the window server displays a
second menu showing a matrix of options that contains volume and
user directory names.
(System directories are not displayed.)
The matrix
is four rows by three columns, and it also scrolls.
If the user chooses a new directory name,
the new volume and

7-19

FILENAME SERVICES

directory name replace the volume/directory names in the wildcard
specification, and the Old File menu is updated with a new
wildcard specification and a new matrix of filenames.
The matrix of filenames shows the filename,
type and version
number for each file.
Only the highest version number is shown
for each file, unless the wildcard specification has an asterisk
in the version number field.
If the wildcard specification has an asterisk in the directory
name field, then all directories on the volume are shown, and the
filenames are grouped by directory name.
Applications that use a particular file
type should probably
supply that file type in the wildcard specification, which will
serve to reduce the number of files that the user has
to view.
(See Section 11.5.)
The service interprets the SELECT, DO, and CANCEL keys in the
same manner as they are interpreted on the multiple-choice menu.
On return from OLDFLE or WIXOLD, the first filename
is
returned
to the application with a count of the number of filenames
(options) selected. To retrieve the remaining filenames,
WICOLD
must be called, before calling any other services.

r------- Wildcard Specification

Headers

PROSE PlUS Version 1.0

OOCI..I9ff file !'\alII selectioo. Choose the docl.Rel"lt to l'dit,
Press
!'ERE I to create a T'ift docl.lM!l1t.

mmt

BICVOl~:[USERFlLESl*.OOC

CPLCPRINT.DOC;6
FOO.DOC;3
tE\lFllE.DOC;1
REPCRT.OOC;1

Figure 7-1:

DICKS.OOC;!
FOI:FRINT.OOC;2
tEWPRINT .OOC~2

Old File Menu

7-20

FILENAME SERVICES
7.4.2

WIXOLD - Static Old File

Status
KeyPressed
CountOfNamesChosen
FilenameLength
FilenameText()
FrameID
MaxChoices

2 words
word
word
word
n bytes
word
word

(output)
(output)
(output)
(output)
(output)
(input)
(input)

FrameID must select a message frame. The message frame supplies
the positioning information for the window, the termination key
list, the HELPframeID, and the headers including the wildcard
specification.
The wildcard specification is supplied by the
last header in the message frame.
(See Section 8.4.5 for a
description of message frames.)

7.4.3

OLDFLE - Dynamic Old File

2 words
word
word
word
n bytes
word
n words
word
word
word
word
word

Status
KeyPressed
CountOfNamesChosen
FilenameLength
FilenameText( )
TerminationKeyCount
TerminationKeyList()
MaxChoices
X

HelpFrameID
HeaderCount
For each header:
HeaderLength
HeaderText()
The last line of
speci fication.

7.4.4

header

(output)
(output)
(output)
(output)
(output)
(input)
(input)
(input)
(input)
(input)
(input)
(input)

word
(input)
n bytes (input)
text

supplies

the

initial

WICOLD - Get Selected Filename

2 words (output)
word
(output)
n bytes (output)

Status
FilenameLength
FilenameText ( )

7-21

wildcard

FILENAME SERVICES

You use WI COLD when more than one filename was selected by a call
to OLDFLE or WIXOLD.
Each time WI COLD is called, one more
filename is returned to the application.
An error is
returned
after all filenames have been retrieved.
Be sure to retrieve all
the filenames before calling any other services.

7.4.5

New File

These services display a string editing window
specifications as input.

and

file

The application supplies an initial file
specification
in
InitialString which is merged with system defaults and displayed
as the default file specification.
The user can edit any portion
of the default file specification.
The final string is returned
to the application in FilenameText.
The user can press the ADDTNL OPTIONS key to display a second
menu showing a matrix of options containing volume and directory
names.
The matrix is four rows by three columns, and it scrolls.
If the user chooses a new directory name, the new volume and
directory name replace the volume/directory names in the file
specification, but editing continues.
The last header line is used as a prompt.
If a prompt is not
desired,
the last header should have length zero.
The maximum
string size is 78 bytes.
The prompt
and
default
file
spe:ifications are displayed on a single line in the window, so
their combined length cannot exceed the allowable window width of
78 characters.
See Section 11.5 for conventions to be followed
when using these Filename services.

~_Head_er

L I

______________

Enter the I'lf!'W drocl.lllel'lt MIlE! and Pf'HS I][].

L-lI'E:nSERFlLESJ.OOC

~
Figure 7-2:

initial File Specification

New File Menu

7-22

FILENAME SERVICES

7.4.6

WIXNEW - Static New File
Status
KeyPressed
FilenameLength
FilenameText()
FrameID
InitialStringLength
InitialString()

2 words
word
word
n bytes
word
word
n bytes

(output)
(output)
(output)
(output)
(input)
( input)
(input)

FrameID must select a message frame.
The message frame supplies
the positioning information for the window, the termination key
list, the HELPframeID, the headers, and the prompt as the last
header (See Section 8.4.5 for a description of message frames.)

7.4.7

NEWFLE - Dynamic New File
Status
KeyPressed
FilenameLength
FilenameText ( )
TerminationKeyCount
TerminationKeyList()
InitialstringLength
InitialString()
X
Y
HelpFrameID
HeaderCount
For each header:
HeaderLength
HeaderText()

7.4.8

2 words
word
word
n bytes
word
n words
word
n bytes
word
word
word
word

(output)
(output)
(output)
(output)
(input)
(input)
(input)
(input)
(input)
(input)
(input)
(input)

word
(input)
n bytes (input)

Any File

An application can combine the actions of the static services
WIXOLD and WIXNEW by calling the Static Any File service, WIXANY.
Two message frames must be supplied, one for the Old File part
and one for the New File part of WIXANY.
The window server
starts by displaying the Old File menu, but reacts to the INSERT
HERE key.
If the user presses INSERT HERE, the window server
destroys the Old File menu and automatically displays the New
File menu.
(Be sure to avoid putting the INSERT HERE key on
either menu's termination list!)

7-23

FILENAME SERVICES
7.4.9

WIXANY - Static Any File

Status
KeyPressed
CountOfNamesChosen
FilenameLength
FilenameText()
OldfileFrameID
MaxChoices
NewfileFrameID
InitialFilenameLength
InitialFilenameText()

2 words
word
word
word
n bytes
word
word
word
word
n bytes

(output)
(output)
(output)
(output)
(output)
(input)
(input)
(input)
(input)
(input)

OldfileFrameID and NewfileFrameID must select message frames.
The message frames supply the positioning information for the
windows, the termination key lists, the HELPframeIDs, and the
headers -- including the wildcard specifications in the Old File
menu and the prompt in the New File menu.
(See Section 8.4.5 for
a description of message frames.)
Your application determines whether the Old File menu or the New
File menu supplied the filename by examining both the Status and
the CountOfNamesChosen parameters after return from the service:
•

If Status shows success and CountOfNamesChosen is nonzero,
the Old File menu was used to select one or more filenames.
The first filename is in FilenameText. Use WI COLD to
retrieve the additional filenames.

•

If Status shows success, CountOfNamesChosen is zero, and
KeyPressed is the DO key, then the New File menu was used to
supply a name, which is in FilenameText.

•

If Status shows success, CountOfNamesChosen is zero, and
Keypressed is other than the DO key, the user terminated the
menu without supplying any filename. Check for MAIN SCREEN,
EXIT, F5 or a key on one of your termination lists.

7.5

DIRECTORY NAME SERVICES

These services are used to show a list of directories to the user
and to permit the user to choose a directory name from the list.
Only directories that are on the local network node are shown.
You pass the frame ID of a message frame.
The message frame
supplies positioning information for the window, the HELPframeID,
and headers.

7-24

DIRECTORY NAME SERVICES
7.5.1

WIXCHD - Get Directory Name

Status
KeyPressed
DirectoryNameLength
DirectoryNameText()
FrameID

2 words
word
word
n bytes
word

(output)
(output)
(output)
(output)
(input)

The user's choice of directory name is returned
in
the
DirectoryNameLength and DirectoryNameText parameters. Be sure to
examine the KeyPressed parameter to determine if any selection
was made. Interpret the EXIT key to mean "no selection," rather
than "exit from application."

7.5.2

WIXSHD - Show Directory Names

Status
KeyPressed
FrameID

2 words (output)
word
(output)
word
(input)

The user can press RESUME or EXIT to terminate the display of the
directory names.

7.6

PRIMITIVE MENU AND EDITING SERVICES

The primitive services that are described in this section are
used by the Synergy high-level menu services to manipulate the
screen and keyboard. These primitive services are available for
application use in situations where the high-level services do
not provide the desired effect.
These primitive services provide a fine degree of control over
the appearance of menus and the interactions between the user and
the system. However, for most situations the high-level services
may be more than adequate. You should gain a good understanding
of the capabilities of the high-level menu services before
deciding that you must use these primitive services.
The primitive services are generally used in a sequence:
1.

Create the window by calling a Create service.

Execute a loop, reading keys by calling a Get Key service and
examining the output of the call until a satisfactory
termination key is pressed.

7-25

PRIMITIVE MENU AND EDITING SERVICES
3.

Destroy the window by calling a Destroy service.

Notice that the high-level menu services automatically do certain
user-friendly operations that are not performed by the primitive
services, although you can program them yourself.
Specifically,
the high-level services look at the type-ahead buffer before
creating the window.
If the type-ahead buffer supplies an
acceptable response, the display of the window is completely
bypassed. Also, the high-level menu services match the user's
typed
responses against the menu options as a method of
positioning the cursor bar, as well as responding to the ARROW
keys.
There are two categories of primitive services:
•

String editing (soliciting typed input from the user)

•

Menus (soliciting menu choices from the user)

7.6.1

String Editing Primitives

String editing primitives solicit typed input from the user and
return it as a string to the application. You can create and use
a special window to do the editing, or you can request that the
editing be done in the application window.
When reading keystrokes into a string field, control characters
are accepted and echo in the dim font. Also, the ENTER key on
the numeric keypad inserts a control-M
(carriage
return)
character into the string.

7.6.2

WICRS - Create String Editing Window

Status
X

Y
HeaderCount
For each header:
HeaderLength
HeaderText( )
PromptLength
PromptText()
DefaultLength
DefaultText( )
CursorPosition
InputType

2 words
word
word
word

(output)
(input)
(input)
(input)

word
n bytes
word
n bytes
word
n bytes
word
word

(input)
(input)
(input)
(input)
(input)
(input)
(input)
(input)

7-26

PRIMITIVE MENU AND EDITING SERVICES
Max Length
This service creates a string
windows are stackable.

word

(input)

editing

window.

String

editing

The X and Y coordinates position the upper left-hand corner of
the windowframe.
From 0 to 20 headers may be supplied, and are
displayed at the top of the window, left-justified. HeaderLength
must not exceed 78. The prompt text is displayed to the left and
on the same line as the default text.
PromptLength and/or
DefaultLength may be O. DefaultLength must not exceed MaxLength.
The sum of PromptLength and MaxLength must not exceed 78.
CursorPositlon specifies the initial setting of the editing
cursor in the type-in area. It is customary to place it at the
right end of the default text; just set CursorPosition equal to
DefaultLength. If there is no default text, a setting of 0 or 1
positions the cursor on the leftmost character.
InputType specifies either Alpha (0) or Numeric (1).
Numeric
string editing windows permit only the numeric keystrokes and are
thus limited to positive integers. If you want to permit the
user to type signed or fractional numbers, you must use the Alpha
setting and do your own check of the keystrokes for correctness.

r------- Header

PI .... .,w t.tw dail~ c~ins .HIt.:

ROU'KI trip .ileage: 0

Prompt

Figure 7-3:

Initial Value

String Editing Window

Remember that text displayed in a string editing window may
appear in different renditions. (See Sections 7.2.1 and 8.2.7.)
Notice that this service is limited to creation of the string
editing window and display of its initial contents. The actual
editing does not begin until you call the Get Key from String
Editing Window service (WIGKS).

7-27

PRIMITIVE MENU AND EDITING SERVICES

7.6.3

WIDES - Destroy String Editing Window
Status

2 words (output)

This se.rvice is used to destroy the string editing window.
string
editing window is a stackable window and must
explicitly destroyed before a nonstackable window is created
the Suspend service is called.

7.6.4

be
or

WIEF - Edit String Field
Status
KeyPressed
CursorPosition
InputType
Max Length
StringLength
StringText()

2 words
word
word
word
word
word
n bytes

(output)
(output)
(input and output)
(input)
(input)
(input and output)
(input and output)

This service provides the string editing features of a string
editing window,
without creating a special window.
The service
is used to provide string editing directly in the application's
front window.
You must position the GIDIS cursor at the point in
the front window where you want the user's keystrokes to be
echoed.
You then call the WIEF service,
and on return you
retrieve the data from the StringText parameter.
The WIEF
service provides string editing in insert mode with use of the
left and right ARROW keys and the delete key.
Since there are no X and Y parameters, this primitive relies on
the current GIDIS cursor position as the leftmost character
position of the editing area.
MaxLength specifies how long the
editing area is; 78 is the maximum value, assuming you have put
the GIDIS cursor on the left edge of a screen-wide window.
You
must be sure that the StringText parameter has the same number of
bytes as the Max Length value.
You can supply default text for
the string by passing the default text in the StringText
parameter and setting the StringLength parameter to the length of
your default text.
Set StringLength to 0 if you have no default
text.
The WIEF service displays the default text, left-justified
and space filled, in the type-in area.
It then places an editing
(blinking)
cursor on the character position
specified
by
CursorPosition
(use 0 or 1 for
the leftmost character), and
begins to read the keyboard through the character-passing buffer.
InputType specifies the type of keystroke that is accepted, as in
the WICRS servic~ (see Section 7.6.2).

7-28

PRIMITIVE MENU AND EDITING SERVICES
When the user presses a function key other than a left or right
ARROW key, or the delete key, the editing is terminated and WIEF
returns to the application.
You get back in the StringText
parameter all characters as they appear on the screen, that is,
as the user sees them.
StringLength counts the rightmost
character that the user sees, even though the user may have moved
the cursor (with left arrow) back to the beginning of the string
at the time of termination. StringLength includes any spaces
that the user explicitly entered on the end of the string, but
does not include spaces that were supplied by WIEF during the
expansion of the default text. The final position of the editing
cursor is returned in CursorPosition. The terminating key is
returned in KeyPressed.

7.6.5

WIGKS - Get Key from String Editing Window

Status
InitialCursorPosition
KeyPressed
FinalCursorPosition
St ri ngLeng th
StringText()

2 words
word
word
word
word
n bytes

(output)
(lnput)
(output)
(output)
(input and output)
(input and output)

This service begins editing the field in the string editing
window created by WICRS. Keystrokes are echoed in insert mode in
the editing area, and the cursor is moved appropriately.
Left
and right ARROW keys are recognized, and the delete key deletes
the character to the left of the cursor. Control returns to the
application when any other key is pressed.
Although the WICRS call can supply a default string and a
starting position for the cursor, the WIGKS call can also supply
these values.
This allows the WIGKS service to be
used
repeatedly in the same string editing window. For example, the
application may determine that the string supplied by the user in
the first WIGKS call is in error. The application may offer the
user an error message in a new window.
When the user presses
RESUME and the error window is removed, the application may call
the WIGKS service again with a corrected version of the string as
the new default value, and allow the user to continue to edit the
string.
The application supplies an ini tial string using the Strin'gLength
and StringText parameters, and locates the cursor within the
editing area using the InitialCursorPosition parameter (0 or 1
for the leftmost character). The cursor position must be between
zero and MaxLength (set on the WICRS call).
WIGKS returns the
KeyPressed,
the
FinalCursorPosition,
and
the
resultant
StringLength and StringText. Notice that the initial string and
7-29

PRIMITIVE MENU AND EDITING SERVICES

the resultant string share the same application buffer.
An error occurs if the active window
window.

7.6.6

not

string

editing

WIHDR - Change header

This service changes the text of a header line in a
string
editing window.
It is described in Section 7.6.12, since it also
can be applied to a menu.

7.6.7

Menu Primitives

Menu primitives create and manipulate the contents of menus,
and
in so doing solicit menu choices from the user.
The Synergy
window server does most of the work of formatting the menu from
the text that you supply and then moving the blinking cursor bar
in response to the user's keystrokes.
The user generally makes a
menu choice by pressing the DO or RETURN key when the cursor bar
is on the desired option.
The actual text of a menu option is never returned;
rather an
OptiQnValue associated with the option is returned.
OptionValues
are integers in the range 0 to 255.
OptionValues 254 and 255 are
used for options that appear on the menu but are not selectable
by the user.
Options that have OptionValue 254 are called
NOCHOOSE
options
and
are automatically displayed in dim
rendition.
The cursor bar can be moved onto these options; but
if the user attempts to select them the window manager beeps the
keyboard.
Options that have OptionValue 255 are displayed in
bold font and are called SKIP options because the cursor bar
skips over them.
Options with OptionValue 254 or 255 may have
blank text.
Option parameters are listed column by column.

7.6.8

WICRM - Create Menu Window
status
X
y

HeaderCount
For each header:
HeaderLength
HeaderText( )

2 words
word
word
word

(output)
(input)
(input)
(input)

word
(input)
n bytes (input)
7-30

PRIMITIVE MENU AND EDITING SERVICES
RowCount
ColumnCount
For each option:
OptionLength
OptionText()
Rendition
OptionValue

word
word

(input)
(input)

word
n bytes
word
word

(input)
(input)
(input)
(input)

This service creates a menu as a stackable window. The X and y
coordinates position the upper left corner of the windowframe.
The lines of header text are displayed at the top of the window,
and the options are displayed below them. The width of the
window is determined by the longest header line, or by the
longest line containing options.
The height of the window is
determined by the number of headers and the number of rows of
options.
There are 20 text lines available and each line can be
up to 78 bytes long. When more than one option is placed on a
line, each option requires enough bytes to contain the longest
option plus 2. Thus, each column has the same width.
If two
columns of options are intended, no OptionLength can exceed 37
bytes.
The product of the RowCount and ColumnCount parameters determines
the total number of options that must be present. Options may be
arranged in as many rows and columns as desired, subject to the
maximum of 20 text lines and 78 bytes per line. A menu with no
options is allowed (and is used to implement the high-level HELP
service).
Each option is a text string with an integer OptionValue that
will be returned when the option is selected.
If there is more
than one column of options, the parameters supply all options for
the first column, then all options for the second column, etc.

7-31

PRIMITIVE MENU AND EDITING SERVICES

[-{---Pn- ~~:~~iOO ~ .si~le
~

....----.-l

two-collM'l, s.ingle-dlOiu MnJ,
Choice i
Cholce 2
Choice 3

........
111----- Cursor Position

' - - - - - - - - - Options

Figure 7-4:

Single-Choice Menu

Notice that this service only creates the menu window and
displays the text in it. The actual solicitation of the menu
choice must be done by calling the Get Key from a Menu service

7-32

PRIMITIVE MENU AND EDITING SERVICES
(WIGKM).
The cursor bar is initially positioned on the first menu option
(row 0, column 0), even if this option has an Optionvalue of 255
(SKIP).
If necessary, you should call the NIPPS service to
position the cursor bar onto a non-SKIP option. The cursor bar
is automatically turned on.

7.6.9

WIDEM - Destroy Menu Window
Status

2 words (output)

This service destroys the menu window.
It must be called after
WICRM and before a nonstackable window is created or the Suspend
service is called.

7.6.10

WIENM - Change Option in a Menu
Status
OptionRow
OptionColumn
OptionLength
OptionText( )
Rendi tion
Optionvalue

2 words
word
word
word
n bytes
word
word

(output)
(input)
(input)
(input)
(input)
(input)
(input)

This service changes the OptionText and/or OptionValue for a menu
option.
The old text and value are discarded and replaced with
the new ones.
OptionRow and OptionColumn are counted from zero.
An error occurs if the menu is not the front window.

7.6.11

WIGKM - Get Key from a Menu
status
OptionValueChosen
RowChosen
ColumnChosen
KeyPressed

2 words
word
word
word
word

7-33

(output)
(output)
(output)
(output)
(output)

CHAPTER 8
THE FRAME COMPILER, FCT

8.1

INTRODUCTION TO FCT

FCT is a program that converts a source frame file into an object
frame file.
A source frame file is an ASCII text file, created with EDT or a
similar editor, that contains menu frames, HELP frames, and
messages that have been described with the FCT language.
An object frame file is an RMS sequential file that contains menu
frames, HELP frames, and messages in a format that is optimized
for use by the window server.
FCT compiles the source frame file, producing the object frame
file, optionally a listing file, and some symbol definition
files.
FCT diagnoses various errors in the source file with a message to
the terminal.
The message shows the offending line from the
source file, the line number of the offending line, and an error
message stating the nature of the error.
FCT continues to
compile by recovering either on the next token of the source
line, or on the next line of the source file.
FCT produces a listing file that shows all lines of the source
file (numbered) and a cross reference listing that shows all
frame names and the reference's to them from wi thin the frame
file. Diagnostic messages are also embedded in the listing file.
FCT produces a MACRO source file that defines each frame name
from the source frame file as a global symbol, equated to a frame
identifier (16-bit integer). This MACRO file must be assembled
and linked with the application code that expects to refer to
these frames in calls on menu services. The task builder (PAB)
resolves references to the global symbols, replacing them with
the frame identifiers.

8-1

INTRODUCTION TO FCT
For PASCAL programmers, FCT produces a PASCAL source file that
defines the frame names as named constants. This file may be
included in any PASCAL source that expects to refer to the
frames.
FCT recognizes references to frame names from within the source
frame file itself, and resolves these references automatically.
Unresolved references are diagnosed as missing frames.

8.2

Fer LANGUAGE

The purpose of the language is to define frames, that is, blocks
of text and the attributes that are needed to use them as menus,
HELP, and messages in Synergy applications.
Most of what appears in a source frame file is the text of the
frame.
The language is designed to make that text easy to edit
and easy to visualize in a window.
The first character of each line designates what that line
contains. Since all commands begin with a period (.), lines that
begin with a period are called command lines. Lines that do not
begin with a period are either blank lines or text lines. ,A line
that begins with two adjacent periods is treated as a text line;
one of the periods is removed by FCT.
Command lines contain tokens such as
keywords,
integers,
punctuation characters, or quoted strings. The tokens may be
separated by any combination of spaces, commas, and horizontal
tabs.
Any command line may end with a comment; the comment is
introduced by an exclamation mark. FCT ignores all text to the
right of the exclamation mark.
Command lines are short.
on a second line.

There is no need to continue a

command

All keywords must be spelled out in full, or abbreviated to the
first three characters.
No other abbreviations are allowed.
Keywords and their abbreviations are not reserved words, hence
they can be used as frame names. Keywords are case-insensitive.
A command line may have no command, which is useful for inserting
long comments.

8-2

FeT LANGUAGE

*****
***

***

.!
NOTE TO INTERNATIONALIZERS
.! The text lines of this fr~. must not exce.d
.f 30 ch.r.cters.
•!
1

Here is • h.ndy ruler •
2

.!34~678901234~678901234~67890

Example 8-1:

Comments in a Frame File

Integers may be signed plus or minus.
The default is plus, if no
sign character is supplied. An integer may be followed by a "b"
(or "B"), which indicates that the integer value must be stored
in a single byte in the object frame file.
The byte-sized
integer is needed only within binary message frames (see Section
8.4.6).
Quoted strings use double~quote characters as delimiters.
You
can embed a double-quote character in the string by using two
adjacent double-quote characters. Thus "A""B" forms the string
A"B.
Quoted strings must not contain control characters such as
TAB.
In the following line formats, the brackets ( [ and ] )
indicate
optional portions of the line. The <xyz> format indicates the
metasymbol xyz, which must be replaced according
to
the
explanatory text that follows the format.
The ellipsis, ... ,
indicates repetition of the preceding construct. There are eight
line types:
.TABLE
.FRAME command line
.HOME command line
.OPTIONS command line
.KEYS command line
Text line
Binary message line
Blank line
Formats for the eight line types are described below,
then
rules for constructing frames are given in Section 8.4.

8-3

the

FCT LANGUAGE

8.2.1

.TABLE
.TABLE

This line must be the FIRST non-blank and non-comment line in the
source frame file (i.e.
before any .FRAME lines).
The .TABLE line starts the definition of a vector table that
creates an index of the frames in the frame file.
This vectored
index is used by Synergy at run-time to locate frames
in the
object frame file, given a Frame 10.

8.2.2

.FRAME Command Line
.FRAME <FrameName> <FrameType>

This line terminates any previous
frame.

frame

and

introduces

new

A FrameName is required and must be from one to six characters
long, consisting of RA050 characters (A to Z, 0 to 9, dollar sign
and period). The leading character must not be numeric.
The
FrameName becomes a global symbol for the newly introduced frame.
It is the name by which the frame may be referenced from within
other frames, and from the application code.
Keywords and their
abbreviations are acceptable as FrameNames.
The FrameType is
required and must be one of the following:
FLOW
SINGLE
MULTI [ <MaxChoices>
HELP
MESSAGE [ BINARY
ALPHASTRING
NUMERICSTRING
SETUP
For the frame type MULTI, MaxChoices can be supplied.
This is an
integer that indicates the maximum number of choices that the
application is prepared to receive on a multiple-choice menu.
If
MaxChoices is omitted, it defaults to the number of options that
are supplied in the frame.
If MaxChoices is supplied,
it must
not be greater than the number of options supplied.
For the frame type MESSAGE, the attribute BINARY can be supplied.
This frame type,
known as a binary message frame, is distinct
from the standard MESSAGE frame type (see Section 8.4.6).

8-4

FCT LANGUAGE
Notice that the frame type SETUP is not spelled with a hyphen.
The word PROPERTY can be used in place of the word SETUP.

8.2.3

.HOME Command Line

.HOME

[<HorizontalSpec>] [<VerticalSpec>]

This line provides screen positioning information for the frame.
The frame may be positioned along the vertical axis and along the
horizontal axis, independently. Furthermore, either positioning
is either relative to the screen or relative to the application's
current window (the front window). The positioning information
is approximate; that is, the window server may adjust any
coordinates so that the frame can be properly displayed.
Although the format shows the HorizontalSpec first, the order of
the two specs does not matter. There are two formats for the
horizontal spec:

COLUMN

SCREEN
WINDOW

LEFT
1
CENTER )
[ RIGHT
]
[<Integer»

COLUMN : OFF
For either the SCREEN or the WINDOW, LEFT specifies that the
frame should be located farthest left; CENTER specifies that the
frame should be centered horizontally; RIGHT specifies that the
frame should be located farthest right. An integer value may be
supplied as an approximation of the horizontal coordinate of the
left edge of the windowframe. If the SCREEN keyword has been
used, the integer relates to the coordinates of the screen.
If
the WINDOW keyword has been used, the integer is relative to the
left edge of the window. In this case a negative horizontal
coordinate may be given, which means that the frame is to be
positioned n units to the left of the front window (see section
6.1.2).

OFF means that the frame should be located so as not to overlap
the front window, if possible. This means that the frame may be
placed to the left or right of the window, as determined by the
window server.

8-5

FCT LANGUAGE

There are two formats for the vertical spec:

ROW

SCREEN
WINDOW

TOP
CENTER
BOTTOM
[<Integer>]

ROW : OFF
For either the SCREEN or the WINDOW, TOP specifies that the frame
should be located farthest toward the top; CENTER specifies that
the frame should be centered vertically;
BOTTOM specifies that
the frame should be located farthest
toward the bottom.
An
integer value may be supplied as an approximation of the vertical
coordinate of the
top edge of the windowframe.
If the SCREEN
keyword has been used, the integer relates to the coordinates of
the screen.
If the WINDOW keyword has been used, the integer is
relative to the top edge of the front window.
In this case a
negative vertical coordinate may be given, which means that the
frame is to be positioned n units above the front window
(see
Section 6.1.2).
OFF means that the frame should be located so as not to overlap
the front window, if possible.
This means that the frame may be
placed above or below the window, as determined by the window
server.
Either the VerticalSpec or the HorizontalSpec may be omitted from
the
.HOME command line.
If the spec is not present, that
specification is determined by the window server at run time.
It
can be regarded as a "don't care" specification.
If the entire .HOME command line is omitted,
both vertical
horizontal positioning fall into the "don't care" category_

and

Some examples follow .
. HOME COLUMN:WINDOW:LEFT ROW:WINDOW:TOP
This puts the frame in the upper left corner of the front window .
. HOME COLUMN:OFF ROW:WINDOW:CENTER
This puts the center of the frame on the same vertical center as
the front window, but moves the frame horizontally, to the left
or right of the front window, so as to obscure it as little as
possible .
. HOME ROW:SCREEN:BOTTOM

8-6

FCT LANGUAGE
This puts the frame at the bottom of the screen, and
horizontal placement up to the window server .

leaves

its

with

the

. HOME COLUMN:SCREEN:LEFT
This puts the frame along the left edge of the screen,
vertical placement determined by the window server .
. HOME COLUMN:WINDOW:20 ROW:WINDOW:20
This puts the upper left corner of the windowframe about 20
coordinates in and down from the upper left corner of the front
window.
Although the .HOME command line is generally placed immediately
after the .FRAME command line, it can occur anywhere within the
frame definition.

8.2.4

.OPTIONS Command Line

.OPTIONS [ COLUMNS:<ColumnCount> ] [ ROWS:<RowCount>
This line introduces a set of options for the frame and
determines how they are to be displayed within the frame. To
display a single column of options, the line should read,
.OPTIONS COLUMNS:l
that is, the ROWS parameter may be omitted.
row of options, the line should read,

To display a

single

.OPTIONS ROWS:l
that is, the COLUMNS parameter may be omitted.
To display a
matrix of options, both the COLUMNS and ROWS parameters must be
supplied. Note that if both parameters are omitted, that is,
only the command itself is given, a default of COL:l is assumed.
The text of the options appears on lines that follow the .OPTIONS
command line.
They are text lines; the text of each option
appears on a separate line. The option lines are entered in
column-major order, that is, top-to-bottom, left-to-right order.
Thus, twelve options arranged in a three-column grid would
require twelve lines, representing the twelve options in the grid
as shown below.

8-7

FCT LANGUAGE

1
2
3
4

10
11
12

7
8

If fewer than twelve options are supplied, FCT supplies any blank
options (called SKIP lines) that are needed to complete the grid.
If more than twelve options are supplied,
FCT produces a
diagnostic message.

8.2.5

.KEYS Command Line
.KEYS <KeyCode> [ <KeyCode> ] •..

This line introduces one or more termination keys for the frame.
(Termination keys tell the window server to terminate menu
processing when the key is pressed and to return the key value to
the application.) The KeyCode is any of:
•
•
•

An integer in the range 1 to 569
A quoted character, such as "a"
A keyword, such as RESUME (or its abbreviation, RES)

The integer values and keywords used for key codes
in Table 4-2. When the key caption is two words,
word should be used. Thus, MAIN is sufficient for
Keys on the auxiliary keypad must be coded as
values. Thus, Keypad Enter is coded as 558.

are supplied
only the left
MAIN SCREEN.
their numeric

A maximum of 30 keys may be supplied via .KEYS command lines.
Although the
.KEYS command lines are usually placed immediately
after the the .HOME or . FRAME command lines,
they can occur
anywhere in the frame definition.

8.2.6

Blank Line.

A blank line with no characters at all, or only space characters
is totally ignored by FCT.
It may be used to make the source
frame file easier to read. A blank line does not produce a blank
header or blank option line in the frame.
See the next section for a method of specifying blank
option lines.

8-8

header

FCT LANGUAGE
8.2.7

Text line

<Textstring> [\ [ <attribute list> 1 1
The text line is used to supply a text string that appears in the
frame.
If the leading character of Textstring is a period, two adjacent
periods must be supplied. FCT removes .one period and treats the
remainder of Textstring as a normal text line. A double period
is equated to a single period only in the leading character
position of Textstring.
Leading or trailing space characters within Textstring are not
removed.
Textstring must not contain control characters less
than ASCII 28, such as a TAB character.
Textstring is terminated by a backslash if there are attributes
to follow.
In order to embed a backslash in Textstring, two
adjacent backslashes are required. Thus,
ABC\\DEF

yields a ten-character string of text, that looks like
ABC\DEFbbb
where b's represent spaces.
The ASCII 28 character is used to introduce a special control
sequence used by the window server. The ASCII 28 may be inserted
in Textstring with an editor, but since it is a nonprinting
character it is difficult to deal with.
FCT provides an
alternative method of embedding ASCII 28 in Textstring.
The
2-byte sequence "\$" (backslash and dollar sign) can be used in
place of the ASCII 28. This 2-byte sequence is converted into a
single ASCII 28 character in the object frame file. The \$
sequence may appear anywhere in the Textstring.
The control
sequences are described in Section 7.2.1.
The attribute list, if present, consists of one or
more
attributes, supplied in any order. Attributes are tokens, and
follow the same separation rules as tokens on a command line;
namely, spaces, commas, and tabs in any combination.
Attributes generally accompany the text lines that serve as
options on menus.
When the window server displays a menu, it
uses the attributes associated with each option line to control
the action that takes place if the user chooses that option.

8-9

FCT LANGUAGE
The attributes are:
<OptionValue>
? <HelpName>
> <NextName>
< <PrevName>
SKIP
BINARY <O-String> <i-String>
ALPHASTRING [ NOECHO ]
NUMERICSTRING [ NOECHO
An OptionValue, if present, is a numeric quantity in the range 0
to 255.
The OptionValue defaults to 0 if it is omitted. The
Optionvalue is returned to the application by the window server
when the user chooses this option.
A HelpName is signaled by the question mark that precedes it.
If
present,
it is the name of a HELP frame that is associated with
this text.
FCT converts the HelpName into a HELPframeID.
(The
window server uses the HELPframeID to display the HELP frame if
the user presses HELP while the cursor bar is on this option.)
The word NOHELP is reserved (in this context only) to mean that
the HELPframeID should be coded as -1 for interpretation by the
window server.
Normally, the window server provides a "no HELP
available" message if it finds a O-valued HELPframeID when the
user presses HELP.
There are times when even this message should
be suppressed, and ?NOHELP achieves that effect. When the window
server finds a -1 for a HELPframeID, it simply beeps and takes no
other action.
A NextName is signaled by the right angle bracket that precedes
it.
If present,
it is the name of a frame that is to be
associated with this text.
FCT converts the NextName into a
nextframeID.
(This is the name of the next frame that should be
used if the user presses DO while the cursor bar is on this
option.
In the case of a HELP frame, the window server acts on
this name when the NEXT SCREEN key is pressed, and automatically
displays the next HELP frame.
In other instances the window
server merely returns the nextframeID to the application.)
The
NOHELP name may be used in this context with the same meaning
that it has as a HELP name (see above).
A PrevName is signaled by the left angle bracket that precedes
it.
If present,
it is the name of a HELP frame that is to be
associated with this frame.
A PrevName can be supplied only on a
HELP frame; it is used to provide a backward link to another HELP
frame.
The window server acts on this name when the PREV SCREEN
key is pressed,
and automatically displays the previous HELP
frame.
The NOHELP name may be used in this context with the same
meaning that it has as a HELP name (see above).

8-10

FCT LANGUAGE
The SKIP keyword signals that the line is to be skipped by the
cursor bar as it moves over the options of a menu.
The
Textstring of such a line need not be null. The SKIP att~ibute
is
always
mutually
exclusive with the other attributes.
(Although FCT translates a SKIP attribute into an OptionValue of
255, you should not supply an OptionValue of 255. Use the SKIP
keyword instead.)
The BINARY attribute supplies two strings that are used in a
special case of an option on a set-up menu. The O-string and the
1-string are coded as quoted strings.
They are the
two
"settings" of a set-up characteristic that can be toggled.
For
example, the entire option line might be coded as
Scroll:

4 BINARY "Smooth" "Jump" ? HELPXY

The ALPHASTRING and NUMERICSTRING attributes appear orily within
set-up menus.
The optional word NOECHO tells the window server
that the characters that the user enters are not to be echoed to
the screen.
Instead, the window server echoes the checkerboard
character to the screen. Use NOECHO when coding a set-up option
that requests private information such as a password.

The use of attributes is dependent on where the text line
appears.
A text line that appears ahead of the .OPTIONS command
line is a header line and, except for certain HELP frames,
does
not have any attributes. A text line appearing after an .OPTIONS
command line is an "option" and
generally
does
require
attributes.
The rules for use of attributes depend on the frame
type (see Section 8.4).
There are instances in which the text of a header line or an
For example, the message of a HELP
option line is to be blank.
frame consists of header lines that might be grouped into
Also,
the "rest
paragraphs and separated by blank lines.
position" of the cursor bar on a menu may be a blank option.
In no case should blank text be coded as a totally blank line
the source frame file, since blank lines are ignored by FCT.

A blank header or option is coded as a line with a backs lash as
If this is a
the first character (thus the Textstring is null).
header line, it contains only the backslash:
\
If this is an option line and the line is to be skipped by the
cursor bar,
the attribute "SKIP" appears in lieu of any other
attributes.
The line appears as:
\SKIP
8-11

FRAME FORMATION RULES

•

Each option can have a HelpName attribute.

•

No option can have the BINARY, ALPHASTRING, or NUMERICSTRING
attribute.

•

.KEYS command lines can appear anywhere in the frame
definition .

Two-column, single-choice menu
.r • • bbreyi.t.d.
• F"RA F"RAME2 SIN
. HOM ROWISCR.CEN COLISCRICEN
An illu_tr.tion of • _impl.
two-column, Singl.-choic. m.nu.
.OPT COLI2 ROWl3
Choic. l ' 1 ?HLPSI1
Choice 2' 2 ?HLPSI2
Choice 3' 3 ?HLPSI3
Choic. 4' 4 ?HLPSI4
Choice 5' 5 ?HLPSI5
•!

.! All keywords

Example 8-3:

~ illustraUan of a 5i..,le
tMrcol..." single-choice 1M!f1.I •

Choice 1
Choice 2

Choice 3

A Single-Choice Menu

8-16

Choice 4
Choice 5

FRAME FORMATION RULES

.! A multipllll'-choice menu, thilt
.! allow~ three choice~.
Thill' program must
.! ch.ck thilt th.y ar. iI l.gill combiniltion •

. FRAME MULTI3 MULTI 3
.Hll'1E

ROW:~INDOWI100

COL:~INDOW:100

.KEYS NEXT
Pleas. choose on • • ntry in .ach column.
Press '.32+{NEXT SCREEN}'.32- if you do not wilnt
ice cream at thi~ tim •.
• ! (Thill' menu sltrvic. ins.rts a lin. h.r •• )
.OPTIONS COLUMNS:3 ROWS:'
Typ.'SKIP
,SKIP
Sugar con.' 11 ?HLPM11
Plain con.'12 ?HLPM12
Dish,
13 ?HLPM13

Flavor'SKIP
'SKIP
Chocolat.' 21 ?HLPM21
Van i 11 a'
22 ?HLPM22
Strawb.rry' 23 ?HLPM23

Choose .. to 3 i taM, 0 chosen

Scoops'SKIP
'SKIP
Tripl.'
33 ?HLPM33
Daubl.,
32 ?HLPM32
Singl.'
31 ?HLPM31

Example 8-4:
8.4.3

Please choose one ~ in each col~.
Press ItEXT SCREEN I j f' you do not want
ice ere. at this ti •.

Type

fliMr

ScDClp9

Sugar cone
Plain cone
Dish

Chocolate

Triple
Doc.ble
Single

Vanilla

Str~

A Multiple-Choice Menu

Set-Up Menu

(Set-up menus were previously called property sheets.)
•

Text lines that precede the first .OPTIONS command line are
regarded as header lines for the frame.
They cannot have
attributes.

•

There can be only one .OPTIONS command line, which is
followed by the text lines that supply the text of the
options.

•

The .OPTIONS command line must implicitly or explicitly
specify that the options are to be arranged in a single
column, that is, .OPTIONS COL:1.

8-17

FRAME FORMATION RULES
•

Each option must have one of the attributes, BINARY,
ALPHASTRING, NUMERICSTRING, SKIP, or NextName. If NextName
is given, the name must be the name of a single-choice menu.
The window server uses the NextName attribute to display the
single-choice menu for setting the characteristic. The
window server ignores the .HOME command line in this menu,
and attempts to position it to the right of the set-up menu
option. )

•

Each option can have a HelpName attribute.

•

.KEYS command lines can appear anywhere in the frame
definition. Do not put the EXIT key ort the termination key
list. You can put RIGHT ARROW or LEFT ARROW on the
termination key list. The window server then recognizes
these keys as terminators, but only when the cursor is on
options with the BINARY, Nextname or SKIP attribute. When
the cursor is on an option with the Alphastring or
Numericstring attribute, the window server responds to the
ARROW key by moving the cursor within the string being
edited.

Setup menu
.FRAME SETUPl PRO
.HOME COL:WINDClI.hCENTER ROW:WINDOW:CENTER
Indicate your choice. for
the doorbell ~itch •
• OPTIa-lS COL:l
Lighted: ' 1 BINARY ·YES· • NO· ?HLPSUl
Style:
, 2 )STYLEH
?HLPSU2
Name:
, 3 ALPHASTRING
?HLPSU3
Quantity: , 4 NUHERICSTRING
?HLPSU4
'SKIP
Pre •• '.32+<EXIT}'.32- to accept value •• 'SKIP
•!

Indicate yair choices for
the docrbc! 11 sw i tch •
YES
Colanj~l

.FRAME STYLEH SINGLE
.OPTIa-lS COL:l
Ranch'
1 ?HLPSMl
Colonial' 2 ?HLPSM2
Revival' 3 ?HLPSM3
Modern'
4 ?HLPSM4

Example 8-5:
8.4.4

A Set-Up Menu

HELP Frame

A HELP frame can consist of a block of text; it may also have
options like a single-choice menu.
If it has options, the
options are introduced by a .OPTIONS command line, and the
options have a NextName that points to another HELP frame.
If
8-18

FRAME FORMATION RULES
there are no options -- that is, no .OPTIONS command line
a
NextName may be given on the first text line of the frame. This
NextName points to another HELP frame that is displayed when the
user presses the NEXT SCREEN key.
All HELP frames, regardless of whether they have a .OPTIONS
command line, can specify a PrevName on the first text line. The
PrevName, if present, must point to another HELP frame, which is
the frame displayed when the user presses the PREV SCREEN key.

•

Text lines that precede the .OPTIONS command line are
regarded as header lines for the frame. These lines provide
the HELP text for the frame. These lines cannot have
attributes, except for the first text line, which can have a
PrevName and a NextName.

•

There can be only one .OPTIONS command line, which is
followed by the text lines that supply the text of the
options. The .OPTIONS command line can be omitted if there
are no options.

•

Option lines cannot have OptionValue, HelpName, BINARY,
ALPHASTRING, or NUMERICSTRING attributes.

•

Option lines that have text of nonzero length must have
either a SKIP or NextName attribute. The NextName attribute
must reference a HELP frame.

•

Option lines that have no text can have either a SKIP
attribute or no attribute at all. When no attribute is
present, the line is assumed to be a "rest line."

•

.KEYS command lines are not allowed.

8-19

FRAME FORMATION RULES

.! A context-sensitive help frame .
• ! PREV SCREEN takes user to the HELP Index •
• FRAME HLPMSG HELP
.HOME COL:WIN:CEN ROW:OFF
Your selections have been combined with the information that you' <HLPIDX
supplied about the system to determine the requirements regarding
cables and connectors required for a completed confi9uration.

If you want to change the order in any way, just press 'S32+<F17}'S32-.
You will be 9iven an opportunity to add or drop individual items
from the l i st.

Press 'S32+<RESUME}'S32- to leave HELP •
. OPTIONS ROWS:2
How cables are chosen\
)HLPMSl
)HLPMS2
How connectors are chosen'
)HLPIDX
HELP indltx'

YCU' selectiOl'l5 have been cClllbirwd with ttw inf'Clf"'Ution that IfOU
~plied abaut. the systea to det.erlline the requiraents resarding
cables and comectars required for a ca.pleted conf'iglration.

If' yau ....,t to chinge the order in q w.." just press rn11.
You will be given an opport.ulity to add or chip indiYickil11ta,
fro. the list.

Press IREm I to I eave I£LP.
How cab 1es are chosen
How ccnwc~ are choRn

Example 8-6:
8.4.5

I£lP index

A HELP Frame

Message Frame

•

All text lines are regarded as header lines for the frame.
These lines cannot have attributes, except for the first text
line, which can have a HelpName.

•

.OPTIONS command lines are not allowed .

or more . KEYS command lines are required to specify the
• One
termination keys that can be used by the user to proceed from
this menu. The order of the .KEYS command lines is not
significant.

8-20

FRAME FORMATION RULES

Sample message frame
.FRAME FINALl MESSAGE
.HOME COL:WIN:CEN ROW:WIN:80T
.KEYS CANCEL, F17, DO

*** ~$10+FlNAL~.10- ORDER CONFIRMATION ***~ ?~LPMSG
This is a final listing of the products that you have
selected and the cables/connectors that are needed.
~

Your confirmation at this point completes the ordering
process and begins scheduling for shipment and billing_
You will have additional opportunities to cancel this
order, but this is your last opportunity to ~$8+change~$8- it
short of a complete cancellation.
~

Press:

~.32+{DO}~$32-

to confirm it.
make any changes.
to start over.

~$32+{F17}~$32- to
~.32+{CANCEL}~$32-

This is a final listing of the products that you have
selected and the cables/ct:lrl'lecUrs that iII"@ ~.

YCU' confiraation at this point cOilpletes the ordering
process and begins scheduling for shipllE!nt and bj 11 ing.
You will ha~ add.itional opportu'lities to cancel th.is
order, but this is yCU' last opportt.rIity to ~ it
short of' a cOilplete cancellation.
P~s: ~Confj,.. it.
to uk e iP,j chirlges •

to start over.

Example 8-7:
8.4.6
•

Binary Message Frame

Only binary message lines, blank lines, and comment lines may
appear in a binary message frame.
Blank lines and comment
lines do not terminate a continued binary message line.

8.4.7
•

A Message Frame

Alphastring and Numericstring Menu

Any text lines that precede the .OPTIONS command line are
regarded as header lines.
These lines cannot have
attributes.

8-21

FRAME FORMATION RULES

One . OPTIONS ROWS: 1 command 1 ine is requi red, foLLowed
options (text lines).

•

The first option line supplies the prompt text.
Null pr
text ~s coded as a line that begins with a backslash.
The
line cannot have attributes.

The second option line supplies the default text for the
string; the length of its Textstring supplies the Max
th
of the allowed string.
Be sure to pad it with spaces to the
length of the longest string that the user is allowed to
enter.
This line can have a HelpName attribute, but other
attributes are ~ot allowed.

•

.KEYS command lines are not allowed .

two

• ! AlphastTing menu

.FRAME ASTRGF ALPHASTRING
Ent~r

Enter the 1"1
The li!!lit is

th@ ring's inscription,

Th9 limit i~ 30 char.cters .
• OPT IONS R().o,Ill

" ?HLPALF

Example

8~8:

.! Numeric

~trin9

An Alphastring Menu

m.nu

.FRAME NSTRGF NUMERICSTRING
Pl.ase ent~r the daily commuting mileag.:
• OPT I (X\lS RQ4.l: 1
Round trip mileagel "
"

?HLPNUH

Example 8-9:
8.4,8

A Numericstl'ing Menu

VECTOR TABLE

On lines following the .TABLE line
(which must be
the
first
source line
in the
frame
file), list the names of all of the
Frame IDs that are ever referenced in the
source code of your
application.
For example, suppose you have a
frame
file
that contains
ten
frames.
Of those ten, six are referenced by the source code of
the application (passed as FrameID parameters in some static Menu
Service call
such as EXFLOW).
Assume the names of these six
frames are FLOW1, SINGLX, DIALUP,
CANTGO,
ADDOPT,
and NOTYET.
The remaining four frames in the file are not directly referenced

8-22

FRAME FORMATION RULES

I
I

I
I
I
I
I
I
I

I
I
I

I
I

I
I
I
I

I
I

I
I
I

I
I

I
I
I
I
I
I
I
I
I
I

I
I

I'
I
I
I

I
I

I
I
I
I

from the source, but are referenced from other frames
in the
frame
file
(for example, help frames).
Assume their names are
HELPAD, HELPX, HLPFLO, and STRNG5.
In this example, the sequence
of lines for the vector table would look like:
.! Table of frame IDs used from the application source code.
.TABLE
FLOW
SINGLX
NOTYET
DIALUP
C~TOO

ADDOPT
The order of the frames is arbitrary, but there are some cautions
relating to changing the order.
The order of the frame IDs in
the table has no correspondence with the order of the
frames
themselves in the frame file.
The above example creates a table
(which is stored at the
beginning of the object frame
file created by FCT) with six
entries in it.
These six frames are the only ones which your
application source code can refer to.
(You can also include
frames in the table which are never passed at
run-time
to
Synergy, but those frames simply take up unnecessary space in the
object frame file's vector table.)
Each frame 10 in the vector table is assigned an ordinal number;
succeeding table entries are assigned increasing numbers.
Thus,
the frame's number depends on its position in the table
(frames
not included in the table are not assigned numbers and thus
cannot be passed in Menu Service calls).
If you change the order
of the frames
in the table, the numbers assigned to the frames
will change, which will require re-task-building the application
(and for PRO/pascal sources, recompilation).
At run-time, the application passes a FrameID to Synergy.
The
actual binary number that is passed is the frame's ordinal
number.
Synergy uses this ordinal as an index into the vector
table.
The indexed entries in the table contain sufficient
information (internal to Synergy) to allow Synergy to find and
retrieve the actual contents of the specified frame in the object
frame file.
The application does not have to explicitly know what ordinal
number is assigned to what frame 10.
FeT produces a .MAC file
that contains global definitions equating FrameID symbol names to
their ordinal values.
Once you assemble this WHATEVER.MAC file
(using the command "$ MACRO WHATEVER")
and link the
resulting
WHATEVER.OBJ
module
in with your application task(s),
the
relationship between FrameID symbol and ordinal value will be
taken care- of bv the linker.
For PRO/Pascal programs, FCT also
produces a .PAS flle which you can include in your source files

8-23

FRAME FORMATION RULES
using %INCLUDE.
The include file contains CONST defini tions
equating FrameID identifiers with their ordinal numbers.
Once the frame file is set up with the frames in the table, you
can make changes to the bulk of the frame file, without ever
having to
recompile
or
relink
the
application
again.
Specifically, you can add or delete information in the frames,
and you can even move the frames around in the frame file.
(For
example, if the frame file is translated into a different
language, the application tasks do not need to be changed.)
If you ever change the table itself, then the application will
need to be relinked. In addition, for Pascal the sources need to
be recompiled so that the new .PAS include file is used.
But
note that as long as you simply add new frames to the end of the
table, then only those modules that refer to those new frames
need to be recompiled, since the ordinal numbers for the original
frames are unaffected by subsequent table entries.

8.5

FCT OPERATING INSTRUCTIONS

FCT operates as a
program.

8.5.1

native

VMS

program

level

with

PRO/Tool

Kit

FCT on VMS

FCT is started from VMS command
addressing the FCT.EXE file.

RUN

command

FCT prompts for a source filename. You enter the name, and press
RETURN.
Append /LIST to the source filename if you want a
listing file.
If the source file is not in your default directory, you can give
a logical name as part of the file specification. Use the VMS
ASSIGN command to equate the logical name to a desired device and
directory.
If you supply a file type, FCT removes it and substitutes "SFF"
as the file type, so be sure to name source files with the .SFF
file type.
All output files go into the default
filenames match the input filename,
their file types:

8-24

directory.
All output
and are distinguished by

FCT OPERATING INSTRUCTIONS
OFF is the object frame file.
LST is the listing file.
MAC is the MACRO symbol file.
PAS is the PASCAL symbol file.

8.5.2

FCT on PRO/Tool Kit

To run FCT in the PRO/Tool. Kit, enter the Tool Kit and type
RUN $FCT
In order to run, FCT requires that the BASIC-PLUS-2 Resident
Library be installed. If it is not installed, type the following
command:
INSTALL LB:[ZZSYS]BP2RES
FCT prompts for a source filename. You enter the name, and press
RETURN.
Append /LIST to the source filename if you want a
listing file. The source file ·must be in the current user
directory. All output files go to the same directory.

8-25

CHAPTER 9

CHAPTER 9
DEBUGGING THE APPLICATION'S WINDOW

This chapter describes additional tools that may be useful during
application development.

9.1

VUE APPLICATION

VUE is a Synergy application that can be used during development
to look at the frames
in a frame file without executing the
application that owns the frame file.
Suppose you are working on a
source frame
file
for
the XYZ
application.
You are trying to imagine what the frames will look
like when displayed by the application. VUE lets you see most
frames on the screen.
In the case of frames that contain
references to other frames, such as a HELP tree,
you can walk
around the tree
just as you would when the XYZ application is
running.
You should use VUE to examine every frame in a frame file before
releasing the application.
It is possible to create a frame,
such as a HELP frame, that is too large to be displayed on the
screen.
Normal quali ty assurance procedures applied to your
application may not discover
this
problem.
A
thorough
file,
examination of every frame
in the frame
using VUE,
can be displayed.
You will also
guarantees that all frames
discover that viewing a frame on the screen is a far better way
to evaluate it for correctness and effectiveness than looking at
it in a listing.
set-up menus cannot be examined with
provide all the parameters
required
display a set-up menu.

9-1

VUE,
since VUE cannot
for
the service call to

VUE APPLICATION
Also, only those frames included in the frame file's vector table
may be examined (you can add any frames you want to the table).

9.1.1

Installing VUE

VUE is installed
like
any
Synergy
application.
After
installation is complete, you must find the ZZAPnnnnn directory
in which VUE was installed. Copy down the number nnnnn.
If you are using a Professional Host Tool Kit,
copy the file
named VUE.COM to the directory on your host machine where you
expect to work on the frame file.
(If you are using the PRO/Tool
Kit, this step is unnecessary.)
You are now ready to use VUE.

9.1.2

Using VUE

When you are
following:

ready

view

your

source

frame

file

the

Run FCT on the source frame file to obtain an object frame
file.
Assuming this operation is error-free, continue
below.

FCT produces a .MAC file that has the same name as the
source frame file.
Print this on your local printer.

If you are using a Professional Host Tool Kit, execute the
VUE.COM file with two additional parameters as follows:
@VUE nnnnn fffffff
"nnnnn" is the ZZAPnnnnn directory number where you
installed VUE.
"ffffff" is the filename of your frame file
(no file type).
Example:
@VUE 78 MYFRAMES

If you are using the PRO/Tool Kit, copy the object frame
file produced by FCT to the VUE application directory,
renaming it VUE. OFF.
If the object frame file is named
MYFRAMES.OFF, this copy command might resemble:
$ COpy MYFRAMES.OFF [ZZAP00078jVUE.OFF

9-2

VUE APPLICATION

start the VUE application.

VUE requests that you supply the synchronization number
placed in the frame file by Synergy. This is the symbol
$FCTV$ which is defined on the eighth line of the MAC file
that you printed out.
Just enter the number that you see
there.
(The number may be negative.) Assuming that you do
not get an error message from the window server, continue
below.

VUE requests a frame ID.
Frame IDs are the numbers to which
the frame names are equated in the MAC file.
Type any of
those numbers in order to see the corresponding frame.
If
you have a frame called HLPDIR, you will find its name
equated to a number, such as HLPDIR=732.
Enter 732 and a
RETURN in order to see the HLPDIR frame.
If the frame is a HELP frame or a menu frame that references
HELP frames in its options, you can use the keyboard to
travel around the HELP tree, just as you would when the
application is running.
various error conditions are shown on the screen, so if you
have created a frame that is too big, etc., you will see the
error message instead of the frame.
Consult the list of
error codes in Table 4-2.

To stop viewing a frame, do the following:
•
•

If it is a HELP frame, press RESUME.
If it is some other kind of frame, press EXIT.

VUE prompts you for a new frame ID.
9.

To leave the VUE application, press EXIT when you are being
prompted for a frame ID.
(VUE cannot be suspended; it
ignores F5.)

9.2

MAKE SCREEN WHITE APPLICATION

This application provides a white background on which your
(The normal background
application's windows can be displayed.
background
may be useful when
for Synergy is gray.) A white
with
the
PRINT
SCREEN key.
making printouts of the screen

9-3

MAKE SCREEN WHITE APPLICATION

The application is installed like any Synergy application.
When run, the application creates a full-screen window and then
automatically suspends itself. When you tell the window manager
to resume its execution, it exits.

9.3

PRINTING THE SYNERGY SCREEN

The action of the PRINT SCREEN key reverses the black and white
areas of the screen.
The assumption is that you are running the
Professional in a mode that displays light lettering on a dark
background, and that the printout is more useful if it shows dark
lettering on a white background.
However, the normal window in Synergy displays dark lettering on
a light background. When this is reversed by the action of the
PRINT SCREEN key, the printout is not very useful.
A patch command file, SYNREVERS, is included in the Tool Kit,
to
enable you to reverse the Synergy displays.
Once the patch has
been made, Synergy will display dark windows
(with a light
windowframe),
and the lettering within the window will be light.
When the windows are displayed in this manner, the PRINT SCREEN
key produces a printout that looks like the normal Synergy
screen.
Screen prints can be very useful when documenting your
application for end users.
The patch can be applied from DCL by running the ZAP program and
supplying
an
indirect
reference
to
the
command file,
SYNREVERS.CMD.
The patch should be applied when Synergy is not
running,
since it will not take effect until Synergy is
started-up.
After you have obtained the desired screen prints,
you can
reverse the action of the SYNREVERS patch by running the ZAP
program again and supplying an indirect reference to the command
file, SYNNORMAL.CMD.
Again,
the
started-up.

9.4

patch

does

not

take

effect

until

Synergy

FOT TO FCT CONVERSION

The Frame Development Tool, FDT, has been augmented with a WINDOW
command.
This command converts a frame file produced with FDT
into a source frame file for
FCT use.
Additional editing is
required,
but the major portion of the text is converted.
The
9-4

FDT TO FCT CONVERSION

details of the conversion are described in the
Guide.

9-5

Tool

Kit

User's

CHAPTER 10
THE CLIPBOARD

The clipboard is a method of moving data between Synergy
applications.
The clipboard relieves the user of the need to
supply a filename when the data is written and then select a
filename when it is read back.

10.1

INTRODUCTION TO THE CLIPBOARD

The clipboard consists of two
following names and locations:

files.

The

files

•

SYSDISK:[ZZPROVUE]CLIPBOARD.TAB

•

SYSDISK:[ZZPROVUE]CLIPBOARD.DOC -- a text file

have

the

a table file

When your application receives a request to "Write to clipboard,"
the application should delete all existing clipboard files. The
application
should
then
create
CLIPBOARD. TAB
and/or
CLIPBOARD.DOC.
When an application writes data to the clipboard, it is not known
where that data will be read.
For example, Spreadsheet data may
be included as text in a PROSE PLUS document and as input to
Graph.
In the first case only ASCII text is needed, but for the
graph a table file is required. Thus, Spreadsheet creates both
CLIPBOARD. DOC and CLIPBOARD.TAB,
in order to permit both paths
for the data.
If your application can write data in its tabular
format as well as a report or text format, it should write both
formats.
There are some applications that do not understand table files
(such as editors). These need not create CLIPBOARD.TAB when they
create CLIPBOARD.DOC, but they should ensure that any existing
CLIPBOARD. TAB files are deleted,
so that if both files of the
clipboard exist, they are synchronized.

10-1

INTRODUCTION TO THE CLIPBOARD
When an application receives a request to ~Read from clipboard,"
the appropriate clipboard file should be retrieved.
If the file
is not there, the application should inform the user that it
cannot use the data in the clipboard.
NOTE
It is possible for
there to be data in the
clipboard,
even if the desired file does not
exist, so the application should NOT say "no data
exists" unless it has verified that neither
CLIPBOARD.DOC nor CLIPBOARD. TAB exist.
DO not delete the clipboard files after a read
they may be read into another application.

10.2

operation,

since

THE TEXT FILE

CLIPBOARD. DOC contains only ASCII text.
When a GIDIS file
is
being copied to the clipboard,
CLIPBOARD.DOC is created and
should contain a VDM reference to the GIDIS
file.
The
application should use the file
service NEWFLE or WIXNEW to
request a name for the GIDIS file.
The actual GIDIS file is not
considered part of the clipboard and should be stored in the
SY:[] directory,
if the user does not supply a device or
directory with the filename.
If the clipboard file is present,
but the
.GID file
that it
refers to is not in the user's directory, you should inform the
user that the graphics file
cannot be found in the local
directory.
A good example of the technique, with suggested
wording of the message and HELP frames, can be found in the PROSE
To see it, rename the EXAMPLECV.GID file that
PLUS application.
comes with PROSE PLUS to some other name, start up PROSE PLUS and
try to edit picture EXAMPLECV.GID.
The file specification in the VDM reference has only the filename
and file type.

10.3

THE TABLE FILE

The table file represents an array of string and numeric values,
along with some information about the values, and possibly,
private information.
The array consists of rows and columns;
each intersection holds a single value or element.
'rhe elements
are stored in row order; all the elements of row 1 are stored
before the elements of row 2, etc.
The elements in a column or

10-2

THE TABLE FILE
row may be all numeric, all string, or a combination of both.
Tables are stored in an RMS variable-length record file.
Each
record contains ASCII text -- up to 256 bytes. There need not be
a regular mapping from a
row of table elements to a single
record, or an integral number of records. At least one table
element exists in each record, and there may be as many table
elements in a record as can fit within the record size of 256
bytes. This limit is set so that applications can allocate a
reasonably small record buffer.

10.3.1

Special Record Format

Special records contain information outside of the actual values
in the array.
There are four kinds of special records -version, source, size and private.
Version, source, and size records precede the array, while
private records follow the array.
Each special record starts
with an exclamation point character (!) in the first byte, and
has a keyword in uppercase letters.
The syntax is strictly
defined.
In the explanations below, the underscore character (_)
is used to indicate a required space. No leading spaces or extra
embedded spaces are allowed.
All table files have a version number record which is always the
first record in the file. This record has the following form:

Table files may have a source record immediately following the
version record.
The source record identifies the application
that created the table file.
This record has the following form:
! SOURCE_' <name>'

where <name> indicates a name string up to 16 nonblank characters
in length.
The single quotes are required; the angle brackets
are part of the notation, and are not entered.
All table files have a table size record immediately preceding
the records that contain the elements of the array. The table
size record describes the size of the array.
The table size
record has the following form:

where the <n>s are decimal integers indicating the number of rows
and the number of columns in the array. The angle brackets are
10-3

THE TABLE FILE
part of the notation, and are not entered. A table of 20 rows by
8 columns would have the following table size record:

Tables may have private data.
If so,
the data is stored in
separate records after a special record that follows the array
and introduces the private data.
The private data introducer
record has the following form:
!PRIVATE

10.3.2

Data Record Format

Each data record consists of a list of data values
commas.

separated

Spaces and tabs between data items are ignored.
example shows two typical data records:

The

following

'Goods', 'Canned', 'January 12th', 11.43
'Shipments (in thousands)', 57.6,58.2,58.2,59
Synergy Version 2 table files include four types of data
unformatted number, formatted number, string, and date.
(Version
1 table files included only two types of data
unformatted
number and string. Table files are upward compatible.)

•

Unformatted numeric data items may be whole numbers, or

real
numbers in either floating point or exponential (scientific)
notation. Dollar signs and commas are not allowed.
Numbers
may be signed.
Numbers must be convertible to 64-bit
double-precision quantities.
Exponential (E) notation may be
used.
Examples:
1

123.456
.0000001

•

-2.3
0.0
.123456789123E+23
+100.000E-8

Formatted numeric data items may contain

commas and dollar
signs.
If commas or a dollar sign are included in a number,
the number must be bracketed with the # character.
Commas
may be used to punctuate the integer portion of the number at
thousands intervals. The limitation on the range of the
number and the manner in which the number is expressed is the
same as unformatted numeric data items. Examples:

10-4

THE TABLE FILE

#$1.00#
*-123.456*
#123,456.0000001*

•

*$2.30#
*-.123456789123E+23*
*$123,456,789.88#

String data items are bracketed with single-quote

characters
(').
If the string contains embedded single-quotes, each
embedded quote must appear twice ("). The length of string
data items must be less than or equal to 132. Examples:
, abcdef'
'123'
"'What,"
she asked, "is that?'"
'Double-quotes (") are not treated specially.'

•

Date data items are represented in two ways:
&MM/DD/YY&

&MM/DD/YYYY&

MM is the one- or two-digit month, DD is the day, and YY or
YYYY is the year.
When YY is used for the year, it is
interpreted as the 20th century, but only if YY is greater
than or equal to 50; and as the 21st century if YY is less
then 50. A date is bracketed by the & character, as in this
example:
&04/09/52&
A table entry may be omitted.
It's position in the table is said
to hold a null data item.
For example, a pair of unseparated
commas, or a comma in the first or last position in a record,
represents a null data item. Also, a zero-length record (a blank
line) in a table represents a null data item.
Null data items represent missing data, and have no data type. A
spreadsheet may have cells that have no value, for example.
Applications reading in a table should treat null data items in
some reasonable way, perhaps as null strings or zero-valued
numbers. However, applications should not output null data items
as
an abbreviation for zero-length strings or zero-valued
numbers.

10.4

TABLE FILE EXAMPLES

The following are examples of table files showing
data types:
!VERSION 2
10-5

all

supported

TABLE FILE EXAMPLES
!SOURCE 'YOURPROGRAM'
!SIZE 4,5
,&7/1/84&,&8/1/84&,&9/1/84&,&10/1/84&
'Bill' ,24.8,24.7,25.2,25.3
'Kate',23.4,22.5,21,22.1
'Totals:' ,#$48.20#,#$47.20#,#$46.20#,#$47.40#
!PRIVATE
B4=B2+B3
C4=C2+C3
04=02+03
E4=E2+E3
The same table in a different format:
!VERSION 2
!SOURCE 'YOURPROGRAM'
!SIZE 4,5
&7/1/84&
&8/1/84&
&9/1/84&
&10/1/84&
'Bill'
24.8
24.7
25.2
25.3
'Kate'
23.4
22.5
21
22.1
'Totals:'
#$48.20#
#$47.20#
#$46.20#
#$47.40#
!PRIVATE
B4=B2+B3
C4=C2+C3
04=02+03
E4=E2+E3
The text version (.OOC) of these table files is:
Bill
Kate
Totals:

7/1/84
24.8
23.4
$48.20

8/1/84
24.7
22.5
$47.20

9/1/84
25.2
21
$46.20

10-6

10/1/84
25.3
22.1
$47.40

CHAPTER 11
SYNERGY CONVENTiONS

Consistency of the human interface, within an application and
from one application to the next, contributes to ease of use.
The user learns to recognize familiar words and formats and
familiar actions on the screen, and familiar keystrokes on the
keyboard.
The user develops a consistent conceptual model of the
system so that new areas of an application can be explored with a
measure of confidence and a minimum of surprise.
Synergy provides such a consistent framework with:
..

Application windows that have common features

•

A window manager that is independent of all applications

•

The clipboard for moving data between applications

•

A menu and HELP interface that has a consistent feel from one
application to the next

However,
Synergy
handling
meanings

there is still a wide margin for variation within the
framework.
The wording of menu optiofls, the method of
files, the movement of the cursor in windows, even the
of words, can vary from one application to another.

Sometimes there are valid reasons for this variation.
Each
application developer has to make the tradeoffs between meeting
the needs of the application and being consistent with the rest
of the applications.
This chapter presents the Synergy conventions as they were
conceived and practiced by Synergy developers. A few of the
conventions are arbitrary,
but many reflect carefully chosen
compromises.
Most of the conventions are the result of much
trial and error.

11-1

Section 11.6 discusses some alternative models that were adopted
by the developers of the Synergy applications to handle certain
demands of the applications.

11.1

WINDOW CONVENTIONS

These are the conventions that apply to application windows,
as
opposed to the more specialized windows that are used for menus
and HELP.

11.1.1

Titles

•

Applications should use titles on all windows. A title area
is highlighted automatically when the window is the front
window, which gives the user a constant cue as to where the
center of attention is.
Furthermore, the title area can be
used for the clock icon and a waiting message when the
application starts a time-consuming operation.

•

If the application uses only one window, the application name
might go in the title.
But if the application has two or
more windows, the title should probably name the contents of
the window. Applications such as Spreadsheet and Calculator
accomplish both aims in one word. The Graph application
labels one window "Data", and the other "Graph." "Graph Data"
and "Graph Picture" are alternate choices.

•

Be sure to consider using the clock icon and a message in the
title area when your application performs a time-consuming
task.
You should turn off the blinking cursor in your window
when the clock icon is shown.
(If the cursor remains on, the
user is led to believe that he should be typing.
See Cursor
Use, below.)
The waiting message that accompanies the icon should be short
and should use a word or phrase from the last menu choice or
the last user action.
Thus, "Loading spreadsheet," "Writing
clipboard," "Searching database."
For example, the window that Synergy displays when it is
loading an application is designed to keep the user aware of
what is happening. That window has a blinking cursor as
well, even though the user is not being invited to type
anything.
The idea is to give reassurance that the machine
is doing its work.

11-2

WINDOW CONVENTIONS

•

If you permit the user to change the size of your application
windows, you should gauge the length of the title and the
waiting messages so that they make sense in a narrow window,
even if they get truncated.

11.1.2
•

Cursor Use

The Synergy developers discovered that a blinking cursor is
very important on a screen full of windows.
The window with
the highlighted title is the front window, so the user's
attention is naturally attracted to it but even then, a
blinking cursor serves to focus the user's attention to a
smaller area and to signal that the application is waiting
for user input.
The corollary of this convention is that whenever the
application is not prepared to accept input, it should
consider turning off the cursor and should indicate why by
displaying a wait message in the title line of the window.
Both of these actions keep the user aware of what is
happening.
If either action is lacking, the user spends some
time wondering if all is well.

•

The user also gets information about the state of the
application from the shape of the cursor, and whether or not
it blinks.
The blinking cursor should be reserved for the point of
greatest interest. On a spreadsheet or data grid the cursor
is in the form of a bar while the user is simply moving
between cells. As soon as the user begins to type something
into a cell, the cursor changes to a single character to
emphasize that the next or previous character is the most
important point.
rf the entry of data is echoed on another
line (not in the cell), as in Spreadsheet, the cell remains
highlighted.
In effect. there are then two cursors, a
nonblinking cursor showing the cell that is being modified
and a blinking cursor showing the focal point of the data
being typed by the user.
Be careful about the size of a blinking cursor.
If a large
area of the screen begins to blink, it is very hard on the
user. When the cursor is large, consider using a blinking
"rubber band" around a nonblinking, highlighted area.

11-3

WINDOW CONVENTIONS
11.1.3

•

Size and Location

Often it seems that an application should use a window that
occupies the full screen. Developers who are familiar with
full-screen editors or full-screen spreadsheets think that a
smaller window is too restrictive. Indeed, when the user is
intent on only one task, a full-screen window may be best
since it may have the least distractions. However, when the
user wants to do two or more tasks at once (e.g., calculate
some results from numbers in a report, and consult a
spreadsheet or graph while writing a report summary), it may
be advisable to allow the windows to shrink to something
smaller than full screen, so that the other application's
window can remain in view while action takes place in the
front window.
Of course, there may be practical limitations on the minimum
window size.

•

Your application should remember the size of the application
window from one use of the application to the next. This is
easily done by storing the size in the ContextBlock that is
saved by the calIon the Done service (WIDON) and retrieved
for you by the calIon the Initialize service (WIINI) at
start-up.
You have the problem of whether the application window is
being sized by the user in relation to the data file that he
is manipulating or whether the size relates to the
application in general. For example, the Graph application
records its window sizes and locations in the data file, so
that when the user selects that data file, the windows adjust
to the location and size that the user considered appropriate
for that data. Spreadsheet and PROSE PLUS, however, record
the window size and location in the context block since the
window size is independent of the spreadsheet or the
document.

•

You may feel that there is a natural location for an
application window. For example, the calculator window
belongs on the lower right, near the auxiliary keypad that is
used to do the calculations. The user may feel otherwise,
however, and you cannot prevent the window from being moved.
Your application should remember where the user put the
window and put it back there on the next start-up of your
application.

11-4

WINDOW CONVENTIONS
And, if it becomes necessary to alter the size of the window
in the course of the application, and changing the size also
necessitates changing the location, the application should
restore both the size and the location after the special need
is completed. For instance, Calculator expands its window
when the user selects the print function, but restores the
size and location when printing is ended.

11.2

MENU CONVENTIONS

Many of the menu conventions are built into the high-level menu
services. The high-level menu services represent much trial-anderror work on the human interface of menus.
Still, there are
places in the Synergy applications where a developer resorted to
the primitive services in order to achieve a special effect.
Some of these are discussed in the following sections.
Two points are worth noting:
•

Even when the high-level services are used, there are many
conventions to be followed that are not enforced, or even
supplied, by the Synergy window server. They require careful
attention when the application is implemented.

•

If you resort to using the primitive services to achieve a
special effect, please consider copying, as much as possible,
the actions of a similar high-level service in order to
minimize the difference between your menu interface and the
standard menu interface.

11.2.1

Placement

•

Always place flow control menus at the top left of the
screen.

•

A pop-up menu (usually a small, single-choice menu) that
appears as a result of some action that takes place in the
application window, could be displayed close to the point of
the window action. A good example of this is the mode
selection menu that is displayed by the Calculator when the
user presses the MODE key. An alternative approach, when the
cursor moves around the application window (PROSE PLUS), is
to center the menu in the window. If it is possible to fix
the location of the pop-up menu, either within the
11-5

MENU CONVENTIONS
application window or on the screen, you may provide more
consistency for the user.

•

11.2.2

pelling and Capitalization

s center an Old File menu or Any File menu on the

Menu opt'ons should
punctuat'on rules.

all

observe

the

same

capitalization

and

•

options should be short, but not so short as to be
ic. A verb and an object, or a verb and a phrase are
usua ly the best combinations. The articles "a," "an," and
"the' are usually unnecessary.

•

All

enu options should be left-justified.

•

are spelled out in full, never abbreviated.

•

The irst word of a menu option always begins with an
uppe
letter, but the remaining words of the option are
lowercase, unless they are proper names or the word

•

options do not have terminating punctuation (period or

•

Set- p menu options are displayed as two parts, the option
text on the left, and the current setting on the right. The
opti n text should end with a colon. The spelling and
punc
of the setting should follow the same rules as a
menu option, i.e., leading uppercase only, no terminating
punc uation.

•

When the settings of a binary option on a set-up menu are
simi ar in spelling, and therefore easy to mistake (such as
"Off' and "On"), supply leading spaces on one of the
sett'ngs, so that when the user switches the setting, the
I change is more dramatic.
(See the Cell Formats Menu
readsheet for an example.)

)

o avoid menu options on the same menu that begin with
• Try
the arne characters, which force the user who likes to type
the enu response to resort to the ARROW keys or a long
type in.
(See the menu that is used to select the number of
deci al places in the Spreadsheet's cell format for a good
exam Ie. )
11-6

MENU CONVENTIONS

Good examples

Poor examples

Load data

Load the data
Load Data
Write data to the Clipboard.
Dec Plcs

Write to clipboard
Decimal places:

11.2.3

Structure and Wording

•

Menu options that are identical, but occur in separate
applications, should have the same wording.

•

Flow control menus have considerable visual structure, in
that they have a title line and one or more submenus.
The
Synergy developers discovered that the placement of certain
common options into the same submenu, at the same relative
position and with the same wording, contributed greatly to
the ease with which users could move between applications.
The titles of the flow control menus for the Synergy
applications are shown below:
Fii
Datamanager
Spreadsheet
PROSE PLUS
Graph

File
File
File/Edit
File/Edi t

F12
Edit
Edit
Attributes
Graph

F13

ADDTNL OPTIONS

Select
Personalize
Personalize
Text

Format
Format
Format
Format

Options that pertain to file operations are always grouped
into the leftmost submenu under the title, "File." Operations
that pertain to generic editing are grouped in the second
submenu under the title "Edit," but are included with the
file operations if necessary.
Operations that seem to be
personal preference; are grouped in the third submenu under
the title "Personalize." Options that pertain to formatting
or structure of the window or data are grouped in the
rightmost submenu under the title "Format."
within the File submenu, the Read/Write clipboard options and
the Load/Save options are grouped at the bottom of the
submenu, as follows:

11-7

MENU CONVENTIONS

Spreadsheet

Read
Save data

Graph

Read
Write

PROSE PLUS

...

Write

Save data
Save graph
Load data

...

Datamanger

Read
Write

. ..

Save work area
Load form

That is, "Read from clipboard" precedes "Write to clipboard"
if both are present. The clipboard options precede the
Save/Load options.
"Save ... " options precede "Load ... "
options.
The standard wording is "Read from clipboard"
clipboard" and "Save data" and "Load data".
•

and "Write to

Set-up menus always have a single column of options. The
appearance of the cursor varies on a set-up menu, depending
on whether the option under the cursor is calling for a
type-in (single character cursor) or a selection with the DO
key (cursor bar).
It is less distracting for the user if the
option types are grouped so that all the type-in options are
together, and all the selection options are together.
In
fact, if there are many options of each kind, you should
consider having two set-up menus, one for type-in options and
one for selection options.
You always code the last two option lines of a set-up menu as
SKIP options, with standard wording.
(Since they are SKIP
options, the cursor can not descend to them. The user does
not think of them as options, but instead sees them as a
reminder of what should be done to exit from the menu.
Furthermore, since they are coded as SKIP options, the text
is automatically balded by the window server.) The second-tolast line is blank; the last line is "Press EXIT to accept
values." The word EXIT is in a box; this is coded in FCT as,
~SKIP

Press

$~32+{EXIT}$~32-

to accept

values.~SKIP

This convention is very important because it reminds the user
of an exception to the normal key usage in Synergy.
The EXIT
key normally means "leave the current activity without taking
action," and the DO key is normally used to complete action
on a menu, so a user who knows Synergy or P/OS will be more
11-8

MENU CONVENTIONS

inclined to attempt to complete the set-up menu by pressing
the DO key.
However, since the DO key is used to make
changes on the set-up menu, the EXIT key is used as the
completion key for set-up menus.
The user must have this
bolded reminder at the bottom of the set-up menu to prompt
the correct action.
This convention is the result of much experimentation with
other keying conventions and menu wordings.
Using any other
convention only weakens this one and will probably confuse
the user.
•

Message menus have no options, so the user responds to them
with a single keystroke, signifying that the message has been
seen.
The window server always recognizes the EXIT, MAIN
SCREEN, and F5 keys, but you should supply a termination key
list so the user can press other keys as well.
Your message
text should inform the user what key to press.
The
convention is to let the user press any of RESUME, RETURN,
ENTER and DO, even though the message text says only "Press
RESUME to continue."
If the user presses EXIT, you should interpret it as
equivalent to RESUME, not as a request to exit from the
application.

•

HELP menus have structure and wording conventions within the
menu and the HELP tree.
Both subjects are discussed in
Section 11.3.

•

Keys on the keyboard are always referred to by using the
boxed font.
The spelling of the function key names is
exactly as it appears on the keyboard keys or label strip,
except that the characters are all uppercase. This
convention is followed in the printed documentation as well
(see Section 11.7).
Notice that the boxed font lets you draw
the ARROW keys and the delete key as well (see Section
4.3.6).

11.3

HELP CONVENTIONS

11.3,1
•

Placement

HELP frames that are context-sensitive are positioned off the
window in the hope that they will not obscure the position of
the cursor in the window.

11-9

HELP CONVENTIONS
•

Some HELP frames are not related to the cursor position in
the window, and these are best centered on the window.
(See
the PROSE PLUS overview HELP frame that is provided when HELP
is pressed immediately after starting PROSE PLUS.)

11.3.2

Types of HELP Users

The user who presses the HELP key is not necessarily the
first-time user.
The following questions should be answered by
the HELP frame:
•

Where am I? The user is confused either because he is a new
user, or an infrequent user, or has been distracted and lost
his train of thought.

•

How do I complete this action? The user sees or knows what
is needed at the moment, but needs to be told how to complete
this action. This usually means he needs to know what key to
press.

•

What does this mean? The user wants to read about some
feature of the system, perhaps because he tried to use it and
failed.
He doubts his understanding of what is happening.

the primary
For a HELP frame that accompanies a menu option,
question is one of meaning.
The user usually knows how to
complete the action and the menu supplies enough context to
answer the "Where am I?" question.
For a HELP frame that accompanies an application window, however,
any of the three questions can be paramount in the user's mind.

11.3.3

Structure of HELP

Synergy services provide automatic recognition of the HELP
when a menu or message is being displayed on the screen.
application must recognize the HELP key itself
when
application is reading the keyboard.

key
The
the

Once a HELP frame is displayed on the screen, however,
Synergy
services provide automatic recognition of the NEXT SCREEN and
PREV SCREEN keys and the RETURN or DO keys for choosing options
on the HELP frames.

11-10

HELP CONVENTIONS
•

a HELP frame consists of three horizontal b.ands:
The HELP text at the top of the frame. This is the text
that explains what the help is about, and supplies the
help. You can explain what the help is about by making
the first line a centered title; but then you generally
have to skip a line and, that uses up two lines. It may
be better to work the subject of the help into the
opening words of the HELP message and just do without a
title. These are all header lines in the frame
definition.
The "Press RESUME ... " line. The last header line in the
frame definition must say "Press RESUME to leave HELP."
This is the exact wording and capitalization, and RESUME
should be boxed. In FCT, the line appears as
Press \$32+{RESUME}\$32- to leave HELP.
It is best to provide a visual cue that this line is not
part of the HELP text above it. This can be done by
centering the text of the line, or preceding it with a
blank line or a line of dashes. The extra characters
required by a line of dashes or the spaces to center the
message (in every HELP frame) will increase the size of
the frame file, however.
The "Press RESUME ... " line is a very important part of
the HELP frame. Users frequently request HELP, read
about how to press other keys to achieve a certain
result, but forget that they must press RESUME first, in
order to get out of the HELP mode. If this line is
omitted, users will press other keys and will become very
frustrated at the beeping provided by the Synergy HELP
service which is waiting for the RESUME key.
The HELP options. HELP frames are like single-choice
menus, in that they can have options arranged in a
column, row, ort matrix. If the HELP text that is
provided uses terms or concepts that might be confusing
to the user, you may want to provide options that, if
chosen, will lead to other HELP frames that explain those
terms or concepts.
If you cannot explain a concept in a single HELP frame,
you can provide an option, "More on this topic", that
leads to continuation of the HELP message.

11-11

HELP CONVENTIONS
If there are many concepts and HELP frames, the user may
feel that asking for HELP often leads into a maze, and
that he never is sure whether he has read all that he
needs to read.
You can prevent this feeling of being
lost in a maze of HELP frames by pr.oviding a HELP frame
called the HELP Index, and providing an option on every
HELP frame that leads to the HELP Index. The HELP Index
is explained below. The location of the option that
leads to it is normally on the far right of the options
(the last option line in the FCT frame definition), and
is spelled "HELP index".
(Notice capitalization!)
The options on a HELP frame are usbally arranged in a
single row using the FCT line,
.OPTIONS ROWS:l
If there is only one option (which leads to the HELP
Index), you can move it to the far right by putting one
or two SKIP lines ahead of it:
.OPTIONS ROWS:l
\SKIP
\SKIP
HELP index\ > HLPIDX

•

The HELP Index usually has only one header line with a
centered title, such as "Calculator HELP Index".
(Again,
notice capitalization.) It probably should have the "Press
RESUME to leave HELP" line, but that can be omitted if the
index is large.
The index is a matrix of options that lead to all the
significant HELP frames, the ones that explain concepts. The
index can be ar.ranged in any format, with blank (no-choose)
options separating the topics into logical groupings.
It is
probably not useful to ar.range the topics alphabetically if
there are more natural groupings of topics around certain
broad subjects.
The index should have two important entries that lead to
short HELP frames.
These are "Suspending ABC" and "Exiting
ABC", where ABC is your application name. New or infrequent
users may start up your application and then want to know how
to get out. They may be too timid to just press EXIT or MAIN
SCREEN and want to read about it before doing it.

11-12

KEY USAGE CONVENTIONS
11.4

KEY USAGE CONVENTIONS

unless your application uses a mouse or tablet, the user's input
device is the keyboard. Synergy observes most of the keyboard
conventions that are common to P/OS and adds some more of its
own.

11.4.1

The Auxiliary Keypad

Remember that the auxiliary keypad must be read in application
mode, not in numeric mode. Other applications and the window
manager rely on the fact that all bytes in the character-passing
buffer have been read in application mode, so that the auxiliary
keypad keys are distinguished from their look-alikes on the main
array of the keyboard. If your application intends to interpret
the auxiliary keypad keys as identical to the look-alike key on
the main array, you must read the keypad key in application
keypad mode and translate it to its equivalent value.

11.4.2

•

Individual Keys

F5 - The window server does not react to this key, except
that it always recognizes it as a terminator of a menu
operation and passes it back to the application.
The application must recognize this key, both as a return
parameter of any service call and also in its own keyboard
input. The application must respond to it by calling the
Suspend (WIINT) service to suspend itself.

•

INTERRUPT - The window server does not react to this key, and
the application should ignore it with a beep. P/OS treats
INTERRUPT/DO as the equivalent of CTRL/C.

•

RESUME - On the Synergy Main Menu, the window manager reacts
to this key by resuming the application that owns the front
window. On a HELP frame, the window server reacts to this
key by terminating the HELP frame. Otherwise, the window
server does not react to this key.
The application can react to the key, either by adding it to
a termination key list on a service call or by recognizing it
in its own keyboard input. In all cases, the meaning of the
reaction should be that of resuming the main activity after a
digression.

11-13

KEY USAGE CONVENTIONS
•

CANCEL - On a menu, the window server reacts to this key by
resetting any menu choices or set-up menu changes and by
moving the menu cursor to the first option. If the
application places CANCEL on the termination key list for a
service call, this reaction is bypassed an~ the key gets
returned to the application.
.
The application can react to the key, either by adding it to
a termination key list on a service call or by recognizing it
in its own keyboard input, but the meaning of the reaction
should be to reset or undo the most recent action or set of
actions.

•

MAIN SCREEN - The application should react to the key, either
as a termination key on a service call or by recognizing it
in its own keyboard input. The reaction should be to exit
from the application, with an automatic save of any data
files. The menu that offers a choice of saving or quitting
is not displayed when the MAIN SCREEN key is pressed.

•

EXIT - The application should react to the key, either as a
termination key on a service call or by recognizing it in its
own keyboard input. The reaction should be to exit from the
application, with a normal exit sequence, that displays the
Exit Menu, offering a choice of Save or Quit (if there is any
data to be saved). See the description of the Exit Menu in
Section 11.5.1.

•

Fll, F12, F13, ADDTNL OPTIONS - The application can react to
these keys, either by adding them to a termination key list
on a service call or by recognizing them in its own keyboard
input. The meaning of the reaction should be to display the
application's flow control menu, if there is one. Use the
individual key to select the proper submenu to display first.
(Fl1 for submenu 1, F12 for submenu 2, etc.) Once the flow
control menu is on the screen, the window server reacts
automatically to these keys, as well as the left and right
ARROW keys.
Be sure to recognize all four of the keys, even if your flow
control menu has fewer than four submenus. Associate all the
extra keys on the right with the rightmost submenu. Thus, if
you have only two submenus in your flow control menu, the
F12, F13 and ADDTNL OPTIONS keys all position the end user on
the second submenu.
If your application does not use a flow control menu, please
do not assign other meanings to these keys -- just beep the
keyboard.

11-14

KEY USAGE CONVENTIONS
•

HELP - The application should react to the key by recognizing
it in its own keyboard input. The response should be to
display a context-sensitive HELP frame (see Section 11.3).

•

F17, F1S, F19, F20 - The application can react to these keys,
either by adding them to a termination key list on a service
call or by recognizing them in its own keyboard input. The
response should be to begin an application-specific action.
The F17 key is used in Graph and Spreadsheet to mean "enter
edit mode," so if your application provides an edit mode (for
fields in your application window), consider using F17 to
invoke it.

•

FIND - The application can react to the key, either by adding
it to a termination key list on a service call or by
recognizing it in its own keyboard input. The response
should be to initiate a search or repositioning function.

•

INSERT HERE - The application can react to the key, either by
adding it to a termination key list on a service call or by
recognizing it in its own keyboard input. The response
should be to initiate a function that adds information (text,
records, etc.) to existing information.

•

REMOVE - The application can react to the key, either by
adding it to a termination key list on a service call or by
recognizing it in its own keyboard input. The response
should be to initiate a function that removes information
(text, records, etc.) from existing information.

•

SELECT - The application can react to the key, either by
adding it to a termination key list on a service call or by
recognizing it in its own keyboard input. The response
should be to choose the item indicated by the cursor
position. This key differs from DO in that DO initiates some
action as well as making the selection. SELECT implies an
intermediate step, whereas DO implies completing the
selections and movihg on to the action stage.
It is definitely confusing to give DO and SELECT the same
meaning, since that would erode this distinction .

•. PREV SCREEN - The application can react to the key, either by
adding it to a termination key list on a service call or by
recognizing it in its own keyboard input. The response
should be to move backward in time sequence or backward
through ordered information and to repaint the window with
other information. Backward means closer to the origin or
closer to the top or the left of the data in the window.

11-15

KEY' USAGE CONVENTIONS
•

NEXT SCREEN - The application can react to the key, either by
adding it to a termination key list on a service call or by
recognizing it in its own keyboard input. The response
should be to move forward in time sequence or forward through
ordered information and to repaint the window with other
information. Forwavd means away from the o~igin or closer to
the bottom or the right of the data in the window.

•

ARROW keys - The application can react to the key by
recognizing it in its own keyboard input. The response
should be to move the cursor (or the cursor-indicated object)
in the indicated direction within the window. When the
cursor moves over an expanse of data (text page or a data
grid) and hits the window edge, the entire window moves over
the data that appears to be behind the window. (Of course,
this is done by scrolling the data through the window, not by
moving the window on the screen!)

RETURN and ENTER - The application can react to these
• DO,
keys by recognizing them in its own keyboard input. The
response should be to begin an action that has been indicated
by some previous operation.
•

<X] key - The application can react to this key by
recognizing it in its own keyboard input. The meaning of the
response should be to delete the last typed character. The
key is reserved for editing typed input, and should not be
given other meanings.

FILE CONVENTIONS

11.5

Most applications access one or more files in which the user's
data is stored. Synergy provides menus for choosing the name of
an existing file and for naming a new file.
In addition, the
Synergy applications open and close files in standard ways.

11.5.1

•

File Access

If your application gives the user the choice of using an
existing data file, you should use the Old File service to
obtain the name of the file at start-up. If you also want to
allow the user to create a new data file at start-up, you can
either use the Old File and New File services or use the Any
File service.

11-16

FILE CONVENTIONS
•

The Synergy applications require that the user supply a
filename before a new file is created. The alternate
technique of creating the data file and then asking the user
for a filename is not used in Synergy.

•

If your application offers the opportunity to use an old file
or create a new file, you should either use the Any File
service, which provides both opportunities, or use Old File
first and include the INSERT HERE key on the termination key
list for the Old File menu. If the application gets back the
INSERT HERE key from the Old File service, it can then call
the New File service to get the name of the file to be
created.
Whether you use Old File or Any File in this sequence, you
must include the header line, "Press INSERT HERE to create
... " Look at the Spreadsheet, Graph, or PROSE PLUS menus for
examples of the header lines in Any File and Old File menus.
Be sure to examine the key returned by these calls. If the
user has accidentally started an application, he will press
EXIT or MAIN SCREEN and will be annoyed if you keep insisting
that he choose a filename before you allow early exit from
the application.

•

Since the file menus use the ADDTNL OPTIONS and FIND keys to
permit the user to alter the wildcard file specification, you
must be careful not to specify these keys in the termination
key list.

•

When the user presses the EXIT key to exit from the
application and there are open data files, the Synergy
convention is to ask the user what to do with the data files.
This exiting procedure is highly standardized.
An Exit Menu consists of a single-choice menu with a menu
title and two options arranged vertically. The menu title
has the name of the application and the words "Exit Menu",
such as "Spreadsheet Exit Menu". The two options consist of
the word "Save", and the word "Quit". The "Save" option
performs the actions necessary to preserve the user's work on
the data file, and the "Quit" option discards the user's
work. Again, Graph and Spreadsheet have good examples of
this exit procedure.
Notice that on the PROSE PLUS Exit Menu, there is a third
option, "Save without formatting," since PROSE PLUS has to
offer two methods of saving the text file.

11-17

FILE CONVENTIONS
The Exit Menu is always centered on the application's front
window.
You should be careful to examine the key returned by this
menu service, since it may be the EXIT key.
If the user
presses the EXIT key while on the Exit Menu, he is declining
the two choices for exiting from the application -- he wants
to continue running the application.
(The EXIT key is
occasionally struck by mistake while running the application.
This mistake takes the user into the Exit Menu.
You should
be sure to give the user a way to recover from this mistake
and resume the application.
Be sure to explain the use of
the EXIT key in the HELP frame for the the Exit Menu. Tell
the user something like, "Press EXIT to avoid making either
of these choices - the ABC application will continue.")
•

Synergy applications that use the Old File/Any File method of
start-up and the exit procedure described above also offer
"Load data" and "Save data" options on the File submenu of
their flow menu. These options give the user explicit
control, especially when the user wants to terminate
processing with one file and begin processing on another file
without leaving the application. Offering "Load" and "Save"
options on the File menu does not take the place of the Old
File/Any File start-up and the exit procedure, however.

11.5.2
•

Filenames

When your application uses an Old File or Any File menu
during start-up, you begin by supplying a wildcard file
specification.
The conventional wildcard file specification uses the current
user volume (SY:), the current user directory ([]), a
wildcard (*) for the filename, and the file type that the
application expects. The file service expands the SY:[]
portion to show the actual current volume and directory,
before displaying it on the screen. By not specifying a
version number, you cause the file service to display only
the highest-numbered version.
For example, the PROSE PLUS application might begin by
displaying all files that satisfy the wildcard file
specification, SY:[]*.DOC. When expanded, this might be
displayed as
BIGVOLUME:[USERFILESj*.DOC
11-18

FILE CONVENTIONS
The user can edit this file specification) using either the
FIND or AOOTNL OPTIONS key (see Section 7.4.1).
•

Standard file types are listed in the Tool Kit User's Guide.
Synergy defines additional file types:
User-Visible

System or Tool Kit

WRK
GIO
FRM
OAT
lOX
TBL

SFF - source frame file
OFF - object frame file

11.6

Spreadsheet data file
file of GIOIS instructions
Oatamanager form file
Oatamanager data file
Oatamanager index file
table file

ALTERNATE CONVENTIONS

Some Synergy applications do not follow everyone of these
conventions.
This section discusses important breaks with
convention to help you handle similar situations.

11.6.1

Graph

The set-up requirements on a graph are extensive.
The Graph
application uses a modified form of flow control menu in order to
simplify the process of selecting and modifying these set-up
characteristics. Normal flow control menus have hanging submenus
that are simple single-choice menus.
If this approach were taken
in the Graph application, the user would not have been able to
see the settings of related characteristics at the flow control
menu level. To see or change a setting would have required first
making a choice on the flow control menu and having the menu
disappear,
and then using a set-up menu. To move to another
set-up menu would mean exiting the current set-up menu,
going
back up to the flow control menu, and then down to another set-up
menu.
The developers decided to combine the three major set-up menus
into the flow control menu. Three of the hanging menus in the
Graph flow control menu are actually set-up menus.
The entire
Graph flow control menu is created by the Graph program without
using the flow control menu services. Graph creates a window at
the top of the screen that looks like the title part of a flow
control menu, then responds to the same keys that menu services
uses on flow control menus.
It displays the left-most menu by
11-19

ALTERNATE CONVENTIONS
calling menu services to put up a single-choice menu.
Graph
positions that menu under the title line, just as it would be
positioned by menu services as the submenu of a flow control
menu.
If the user requests one of the other three menus, Graph
uses a menu service to display the appropriate set-up menu, again
positioned just as it would be by menu services as the submenu of
a flow control menu. Graph alters the rendition of the "titles"
in the title line just as they are altered on a flow control
menu.
The effect is that the user thinks he is dealing with a flow
control menu,
and since the three submenus that are actually
set-up menus have the bolded message that reminds the user that
he is on a set-up menu, the break with convention is minimal.
The pick Patterns/Colors Menu displays patterns for the graph,
and if color is in use,
it displays the colors.
It is not
possible to display patterns and colors in menus using the menu
services, hence the developer was forced to create his own menu
using another window.
See the example program in Appendix A for a color
in the same way.

11.6.2

executed

Calculator

The developers of the Calculator felt that most users would
already have a strong conceptual model of a hand-held calculator.
The Professional keyboard has an auxiliary keypad and function
keys above it that suggested that these keys should be used
exclusively to create an interface to match the hand-held
calculator model.
The selection of modes of operation on a hand-held calculator is
done entirely through the keys.
Hand-held calculators do not
present flow control menus. The Calculator application has no
flow control menu, but generally uses mode-setting keys on the
calculator keyboard.
The Calculator application
does
not
recognize keys on the edit keypad or the main array because the
developers wanted to avoid altering the model of a hand-held
calculator.
The HELP key is used to put the Calculator application in HELP
mode, as it is for other applications, but once in HELP mode, the
Calculator application allows the user to proceed from the HELP
frame that describes one key to the HELP frame that describes
another key by a simple press of that key. This is an extension
of the normal HELP conventions which do not recognize special
keys.
11-20

ALTERNATE CONVENTIONS
In order to provide this response to the HELP key,
the HELP
frames were coded in the frame file as message frames with long
termination key lists. The calculator code displays them as if
they were HELP frames,
but calling the EXMESS service.
It
examines the key that is returned to determine what to do next.

11.7

DOCUMENTATION CONVENTIONS

Consider these guidelines in preparing the user documentation for
your application.

11.7.1

Terminology

The Synergy User's Guide introduces many terms that are used to
describe the Synergy window environment. The use of these same
terms in the documentation for your application reinforces their
meaning and avoids confusion on the part of the user. The chart
below shows the major terms; both spelling and capitalization are
important.
Synergy Window Manager
Synergy Main Menu
HELP index
HELP tree

wildcard
set-up
clipboard

Certain phrases have been deliberately
avoided. These are listed below:

used

deliberately

•

Use "suspend the application" rather than "interrupt the
application" to describe the action in response to the F5
key.
Using the word "interrupt" suggests use of the
INTERRUPT key.

•

Use "press DO" rather than "hit DO" or "type ~O." using "type
DO" could confuse the user into entering the letters "0" and

"0".
•

Use "enter" rather than "type" in giving directions to fill a
field or respond to a prompt. Example:
"Enter the
applicant's social security number."

•

Use "screen" rather than "display."

•

Use "select" when referring to the action of moving the
cursor to a menu option, and "choose" when referring to the
complete action of selecting and pressing the DO key. Thus,

11-21

DOCUMENTATION CONVENTIONS

Select the "New date" option and press DO to begin
the action of ...
or alternatively,
Choose the "New date" option to begin the action of ...
•

Use "option" rather than "entry" to describe the text that
can be selected on a menu, and put quotes around the option
text when referring to it. Thus,
Choose the "New date" option
rather than either of these:
Choose the New date option
Choose the "New date" entry

•

Use "front window" rather than "top window."

•

Use "hanging menu" or "submenu" to refer to a part of the
flow menu, rather than "pulldown menu."

•

Use "cursor" and "cursor bar" rather than "paddle" to refer
to the blinking rectangle on the screen.

•

Be sure to capitalize the names of keys. Although the key
captions on the keyboard are mixed case, the convention
throughout Professional documentation is to print the key
names in uppercase, using the same spelling as found on the
keyboard caption, e.g., ADDTNL OPTIONS.

11.7.2

Organization

Various users will read your documentation for different reasons.
The following organization is designed to meet these diverse
needs:
•

Start with an "Introduction to ... " section that describes
the product's major functionality with appropriate
illustrations.
Finish this section with a description of the
remaining sections of the documentation.
The Introduction section tells the reader what to expect from
the product and from the documentation.

11-22

DOCUMENTATION CONVENTIONS

•

Provide a "Sample Session" section that walks the user
through a session with your application.
This must be
carefully constructed, so that a user encounters no surprises
when using it.
It should also be carefully limited to the
major features of the application.
Avoid the temptation to
describe the bells and whistles of the product.
This is not
a full tutorial.
The sample session should be something that
a brand new user can get through in a half hour.
This section satisfies some user's need for assurance during
their first exposure to a product.
If it is well illustrated
with pictures of the screen, it can be read even when away
from the computer, so a user can read about the use of the
application without the embarassment of appearing unsure at
the keyboard.
This section can encourage a timid user to
approach the application.
The section is not intended for all users; sophisticated
users will skip this section.

•

Provide a "Concepts" section that explains what can be
accomplished with the application.
Define special terms in
the Concepts section, and discuss the actions of the
application without describing the mechanics of the software,
keyboard or screen.
Use terminology from the user's
experience.
If possible, use illustrations that show the
screen and its printed output.
This section is intended to answer the question, "What is
happening?" By isolating it from the next section, you can
avoid confusion between "what to do" and "how to do it."
This section may be read only once by a user, and then
occasionally consulted as a memory refresher.
Much of what appears in the Concepts section can be put into
the HELP tree that is reached through the on-line HELP Index.
There are benefits to writing the HELP frames and the
Concepts section at the same time.
You should question your
own understanding of any concept that you cannot explain in a
single HELP frame (two short paragraphs).
(See Section
11.3.)

•

Provide a "Using the Application" section that gives explicit
directions for using each part of the application.
Use only
the terms that have been described in the Concepts section,
and provide cross-references to the Concepts section, so that
users can easily refresh their memories on why they need to
do a specific action.

11-23

DOCUMENTATION CONVENTIONS

The "Using" section answers the user's "how to do it"
questions.
It should be designed to anticipate the problems
that USers can encounter.
The "Using" section will be consulted often, and it should be
carefully organized and indexed so that it can be used as a
reference manual.
Much of what appears in this section is also in the contextsensitive, on-line HELP frames.
In fact, both the
documentation and the on-line HELP frames can profit from
shared design.
•

Be sure to carefully index your documentation. A manual
without an index is very difficult to use as a reference.

11-24

APPENDIX A

APPENDIX A
BATON TWIRLER

A.1

INTRODUCTION TO BATON TWIRLER

The Tool Kit includes a sample Synergy application called Baton
Twirler.
Baton Twirler provides a simulation of one or more
batons twirling in the space enclosed by the window on your
screen.
You can install this application on your Synergy Main
Menu and execute it to see its functionality. The on-line HELP
frames provide all the description that is needed for its
execution.
All of the files needed to build Baton Twirler are also included
on the distribution media. Most of the files are listed in the
following sections of this appendix. They provide examples that
are referenced from the preceding chapters. The source files
contain extensive comments.
Many of the files required to build Baton Twirler are useful in
building other applications, if those applications are written in
the PRO/PASCAL language. Even if your application is written in
another language, you may find the PASCAL examples to be a useful
model of a high-level language interface to the Synergy services
and to the GIDIS (graphics-mode) part of the terminal subsystem.
The following sections include listings of:
•

BATON.PAS - This is the main module containing the logic of
the application. It uses the PASCAL %INCLUDE directive to
incorporate two other PASCAL files, GIDISOPS.PAS and
SYNERGY.PAS.

•

GIDISOPS.PAS - This is an include file that supplies the
formal definitions of the callable procedures that are used
to interface the PASCAL code to the GIDIS part of the
terminal subsystem. The procedures thamselves are coded in
the GIDIS.PAS file, for separate compilation.

A-l

INTRODUCTION TO BATON TWIRLER

•

SYNERGY.PAS - This is an include file that defines a number
of constants and structures that are useful in dealing with
the Synergy services.
It also supplies the formal
definitions of the callable Synergy services that are used
within BATON. PAS.
If you use this file in your application,
you will want to add definitions of the other Synergy
services that you need.

•

GIDIS.PAS - This file contains interfacing routines that take
calls from PASCAL code and construct and execute GIDIS
instructions.

•

BATONFRMS.SFF - This is the source frame file used by Baton
Twirler.

•

BATON.CMD - This is the command file that is submitted to the
PRO/Application Builder (PAB) in order to build BATON.TSK.
It references the BATON.ODL file.

•

BATON.ODL - This is the Overlay Descriptor File referenced in
BATON.CMD.

•

BATON. INS - This is the install file that is used to install
Baton Twirler as a Synergy application.

•

BUILD.CMD - This is an indirect command file that can be used
to build the application task image.

A few other files are required to build the entire application.
These files are included in the distribution media, but are not
listed here, since they do not illustrate any aspects of a
Synergy-specific application.
You may want to print them, and
may find them useful in your
work.
Their
names
are:
GETAKEY.MAC, KBSERV. MAC , and READMESG.MAC.
(The KBSERV.MAC file contains a subroutine named READKB, which
recognizes the call-back code and calls the MGTCB service.)

A-2

THE BATON. PAS FILE

A.2

THE BATON.PAS FILE

< Thi. PRO/Pa.cal progr.m i. provided with the Synergy Tool Kit to
)
< d.mon.trate how a simple application interacts with the Synergy service. to )
< use the windowing facilitie •• Also, since this progr.m make. extensive u.e )
< of PRO/GIDIS to do its output, this serves as an -illustration of to use
)
< BlOIS effectively in an application. Lastly, this progr.m shows how to
)
< is.ue P/OS Executive Directives directly from a PRO/Pa.cal progr.m.
)
<
)
< The ability to issue directives (EMT 377s) was inadvertantly omitted from )
< the PRO/Pa.cal V1.2 documentation. There is a n~ predefined procedure
)
< n.med DIR$ which takes a single par.meter. This par.meter should be the
)
< Directive Par.meter Block for the directive you are issuing. The format
)
< and contents for each directive is described in the P/OS System Reference
)
< Manual (chapt.r nine for Tool Kit version V2). To issue a directive,
)
< define a RECORD type for the OPB for the directive, and assign the fields
)
< of the record appropriately (with constants, addres.e. of ~uffer., etc.).
)
< Then simply invoke the OIR$ procedure, a. in:
}
)
<
OIR$( OPB_Record );
)
< To check the re.ult. of the directive, declare:
)
<
VAR $OSWI [External] Integer;
)
< and th.n do:
)
IF $OSW = 1 THEN .•.
<
)
<
)
< Thi s progr.m tak •• advantag. of color, i f the fty.t.m that it ex.cutes or.
< ha. color en.bled. Not only does the progr.m displ.y object. in different )
< color., the progr.m ch.ngeft the v.lue. in the color map. A Synergy progr.m )
)
< h.s to be somewhat careful when it com.ft to changing the color m.p. In
)
< moftt c •••• , Syn.rgy i.ol.t •• e.ch window from whatev.r goes on in .v.ry
)
< other window (that ift, .pplic.tion A c.nnot .ffect .pplic.tion B'.
)
< windows). Thi. is mad. possible through sep.r.te softw.reoom.intained
}
< contexts for e.ch window. For ex.mple, e.ch window has its own writing
< mode st.te, it. own cursor position, etc. However, this i. NOT true of the)
< color m.p. On the Professional, the color m.p applies to ALL windows; thus)
< if application A changes the color map, application B's windows change too. )
< So changing the color m.p h.s to be done keeping possible ·side eff.ct." in )
)
< mind. Most importantly, which of the eight entries in the color m.p you

< ch.nge i. crucial. A progr.m should virtually NEVER ch.nge entri.s 0 or 4. )
< Entry zero is .lways BLACK, and is used to displ.y text in windows, for the )
< windowfr.me surrounding •• ch window, etc. Entry four is .lw.ys WHITE, .nd )
< is used for the white b.ckground of .11 windows. I f . progr.m ch.ng.s the )
)
< color of those entries, you will get very entert.ining results! This
< s.mple progr.m t.kes gre.t c.re to only ch.nge entries 1, 2, 3, 5, 6 .nd 7. )

A-3

THE BATON.PAS FILE
~Include
~Include
~Include

'BatonFrm.tNoList'
'GIDISOp.tNoList'
'Synergy/NoList'

< Contains ordinal numbers for Frame IDs
>
< Contains declarations needed for GIDIS routines}

< Contains declarations for Synergy services

CONST
• 61;

• 2;
MaxPoints • 200;
MaxBatons - 10;
MaxColor • 7;

< Directive Identification Code for Get Time directive. }
< Length of GTIM Directive Parameter Block. }
< Largest number of segments a single Baton may have. }
< Largets number of simultaneous Batons allowed. }
< Number of entries in the Professional-300 color map. }

< Here are the data structure TYPE definitions specific to this module}
TYPE
A_Baton

• RECORD < Data .structure describing a Baton}
Newest, Hue: Integer;
Sticksl ARRAY [ O •• MaxPoints, 0 •• 3 ] Of Integer;
Speedl ARRAY [ 0 •• 3 1 OF Integer;
END < A_Baton } ;

ColorDescriptor

• PACKED RECORD
Redl
0 •• 7; < Contains the RGB intensity}
Greenl 0 •• 71 < values for a color.
}
Bluel O•• 71
END < ColorDescriptor } I

A-4

}

THE BATON.PAS FILE
PackedColorType

• PACKED RECORD
CASE Integer OF
11 ( WI Un.igned;
);
21 ( RI ColorDe.criptor; );
END < PackedColorType } ;

< Ca.e variant that maps )< ROB value. into a 16- )< bit binary word for
)< compact .torage.
)-

• PACKED RECORD
Low: 0 •• 255; < Simple structu~e that allows easy
)Hi: 0 •• 255; < use of both by~es in a 16-bit word. }
END < PackedBytes )• ARRAY [ O •• MaxColor ] OF PackedColorTypel
< A table large enough to contain ROB intensity value. )< for all eight entries in the Professional's colot map. )FunctionKeyNeme.·

TextKey,
TabKey,
Return,
FindKey,
InsertHere,
RemoveKey,
SelectKey,
PrevScreen,
NextScreen,
BreakKey,
SetUpKey,
SuspendKey,
InterruptKey, ResumeKey,
Cancel Key ,
MainScreenKey,
Exit,
Fll,
F12,
F13,
AddOptnsKey, HelpKey,
Do Key ,
F17,
F1S,
F19,
F20,
PF1,
PF2,
PF3,
PF4,
Up,
Down,
Right,
Left,
Delete );
< Enumerated type for use with the OetAKey(} subroutine. )< Note that the ordering of this list is unrelated to
)< the 16-bit integer Termination Key values that Synergy )< uses. (This ordering is purely for the convenience of )< the semple program.)
)-

GTIMdpbType

= PACKED RECORD
< Directive Parameter Block )D_CODE: [Pos(O,O)] 0 •• 255; < for the Get Time (GTIM)
)D_LGTH: [Pos(l,O)] 0 .• 255; < P/OS Executive Directive. )G_TIBA: [Pos(2,O),Unsafe) UnSigned;
END < GTIMdpbType )- ;

GTI~BUF

• PACKED RECORD < Buffer format used by GTIM directive )G_TIYRa [POS(O,O)] Unsigned; < Year
)G TIMOa [Pos(2,O)] Unsigned; < Month )G:TIDA: [Pos(4 , 0)] Unsigned; < Day
)
G_TIHR: [Pos(6,O)] Unsigned; < Hour
j
G_TIMII [Pos(S,O)] Unsigned; < Minute )G_TISC: [Pos(lO,O)] Unsigned; < Second )G_TICT: [Pos(12,O)] Unsigned; < Clock ticks of second )G_TICP: [Pos(14,0)] Unsignedl < Number of ticks/second )END < GTI~BUF )- ;

A-5

THE BATON.PAS FILE

ContextBlock: RECORD
CASE [nteger OF
1: ( CI PACKED ARRAY
1 •. MaxContext ] OF Char; )j
2: ( R: RECORD
WindowX:
Integerf {Position of the window}
WindowY:
Integer;
WindowWidth:
Integer;
{Size of the window}
WindowHeight:
Integer;
CPoints:
Integer; {How many and what size}
CBatons:
Integer; {Batons the user wants. }
SavedColorl:
PackedColorTypej {Values for the}
SavedColor2;
PackedColorTypej {entries in the}
SavedColor3:
PackedColorTypej
< color map that}
SavedColor5:
PackedColorType;
< the program
}
SavedColor6:
PackedColorTypej
< allows the
}
SavedColor7:
PackedColorTypej {user to change.}
LineThickness; PackedBytesj {Thickness of lines}
END < variant R } );
END { ContextBlock } i
< Allocate the 32-byte Context Block that Synergy keeps for us. The
}
< application can store ANYTHING it wants in these 32 bytes. Almost
}
< always, you will want to store the X,Y coordinates of your window(s),
}
< plus the width(s) and height(s). Beyond that, it's up to you. This
}
< sample application uses some of the remaining space to retain program
}
< variables which the end-user has control of. This way, the values of
}
< those variables are preserved one run of the application to the next,
}
< without the application having to create a file on the disk and store
}
< the values there, etc.
}
XStatus: StatusBlockj

< Array used to return success/failure status}
< from the various Synergy service calls.
}

WDescl WindowDescriptorj

< 32-byte Window Descriptor Block that is
}
< used to manage the program's main window. }

InputKey: FunctionKeyNamesj
InputChar: Charj
MainScreenRequested,
SuspendRequested,
Done: Booleanj
TitleText: Stringj

< These two varaibles are used when calling
}
< the GetAKey() routine to read the keyboard. }

< Becomes True if burried MAIN SCREEN is pressed}
< Becomes True if bUTried F5 is pressed}

< Loop control logic variable}

< Buffer, used to read message frames from frame file}

A-6

THE BATON.PAS FILE
ContextLength,
Ti tleLength,
Ti tleID,
Ti tleCounteT,
i ,

Index,
ColoTMoaplndex,
Points,
Boatons,
RndSeed:
tntegeT;

{ Used in WIINIMIDCJo.I SyneTgy c::aUs.
}
}
{ Holds the length of the stTing TitleText.
{ Holds the fTiame 10 of the fTiame used fOT the title stTing.}
{ CounteT, keeps tTac::k of • of times main pTOgTiam loop Tuns.}
{ GeneToal FOR loop c::ounteT fOT main pTOgTiam body.
}
{ AnotheT FOR loop c::ounteT fOT main pTOgTiam body.
}
{ AnotheT FOR loop c::ounteT fOT main pTOgTiam body.
}
{ How moany segments theTe aTe peT Baton.
}
{ How many Boatons theTe aTe in the window.
}
{ Used as seed fOT a Tandom numbeT geneTatoT.
}

ColoTMap: ColoTMapTypej

{The pTOgTiam'S yalues

fOT

the haTdwoaTe C::OlOT moap }

BoatonList: ARRAY [ 1 •• MaxBoatons ] OF A_Batonj
{ List of eac::h of the Batons that aTe mOYing in the window}

{ HeTe aTe the exteTnal pToc::eduTe definitions
[ExteTnoal(GETMES)]
PROCEDURE GetMessoage7( VAR FTameID:
VAR Msgl:
VAR Msg2:
VAR Msg3:
VAR Hsg4:
VAR Msg5:
VAR Hsg6:
VAR Hsg7:

[Re.dOnly]
[Unsafe]
[Unsafe]
[Unsafe]
[Unsafe]
[Unsoafe]
[Unsafe]
[Unsafe]

fOT

this module}

IntegeTj
StTingType;
StTingType;
StTingType;
StTingType;
StTingTypej
StTingTypej
StTingType ); SEQll ;

[ExteTnoal(GETMES)]
PROCEDURE GetMessage9( VAR FTiameID: [ReoadOnly] IntegeT;
StT ingType
[ Unsafe]
VAR Msgl:
StTingType
[Unsafe]
VAR Hsg2:
StTingType
[Unsafe]
VAR Msg3:
StTingType
[Unsafe]
VAR Hsg4:
StTingType
[Unsafe]
VAR Msg5:
StT i ngType
[Unsafe]
VAR Msg6:
StTi~gType
[ Unsoafe]
VAR Msg7:
StTingType
[Unsafe]
VAR Hsg8:
StTingType ) I SEQll j
[ Unsoafe]
VAR Msg9:
It is
{ Both of the aboye dec::laTations TefeT to the Siame pToc::eduTe.
( wTitten in MACRO to use the PDP-ll R5 c::alling sequenc::e (SEQll) , and is in
{ the module READMESG.MAC.
FUNCTICJo.I GetAKey( VAR ChaTPTessedl ChaT ) I Func::tionKeyNiameSI EXTERNAL;
{ This Toutine is WTitten in MACRO to use the PRO/Pasc::al FUNCTICJo.I c::alling
{ sequenc::e, and is in the module GETAKEY.MAC.

A-7

}
}

}

}
}

THE BATON.PAS FILE
PROCEDURE UnlKeyboaTdl
EXTERNAL;
PROCEDURE KBASTlnitialize; EXTERNAL;
< These Toutines aTe wTitten in MACRO to use the PRO/Pascal PROCEDURE
< calling sequence, and aTe in the module KBSERV.MAC.

}

PROCEDURE ExitStatus( Status I IntegeT )1 EXTERNAL;
PROCEDURE Detach;
EXTERNAL;
< These Toutines aTe contained in the PRO/Pascal ClusteT LibTary, PASRES.
< They may be called fTom any PRO/Pascal pTogTam.

}
}

{-----------------------------------------------------------------------------}
<-------------- Now begins the executable code fOT this module ---------------}
< Simple Tandom numbeT generatoT. As used by this pTogTam, it TetUTns
< numbeTs in the Tange 0 .• 1400. RndSeed is a global vaTiable.

}

BEGIN { Rnd }

RndS.ed := ( RndSeed
13077 + 6925
Rnd
1= lJAND( RndS •• d, %0'77777'

MOD 32768;
DIV 40

END { Rnd } ;

PROCEDURE ReadM.ssage( FTameID:
IntegeTI
VAR Length:
IntegeT;
VAR Message: [Unsafe] StTing ) j
{ ReadMessage Teads the specified message fTame, TetuTning the first line
< of it in a text stTing.
VAR
Offsets: ARRAY [ 1 •• 9 ] OF Integer;
XStatus: StatusBlock;
NumLines: IntegeTI

A-8

}
}

THE BATON.PAS FILE
[External(GETHES»)
PROCEDURE GetHessage2( VAR FrameID:
VAR Hsgl:
VAR Hsg2:
{ This definition is needed for the

[ReadOnly] Integer;
[Unsafe] StringType;
[Unsafe] StringType )i SEQ11;
following procedure.

[Global(FTLERR)]
PROCEDURE FatalError( FetchHeaderSI Boolean;
Length: Integer;
VAR Hessage: [ReadOnly,Unsafe] String

}

{ FatalError is called to abort the running program whenever it encounters }
}
{ any surprise, serious error situation that it cannot cope with/recover
}
{ from.
{ 'FetchHeaders' should be passed as True in the normal case; this means
}
{ that this routine should read some intro header messages from the frame
}
{ file to introduce what has happened to the program.
If 'FetchHeaders' is }
{ passed as false then instead of getting the intro messages from the frame}
{ file, hard-coded strings are used instead.
This is needed in case the
y
{ frame file hasn't been opened at the point the fatal error occurs.
}
CONST

JunkString

'_'j

{Any random string used as a stub}

VAR
Introl, Intr02: StringTypej
BEGIN { FatalError }
FlushGIDlSj

{Empty the output buffers}

IF FetchHeaders
THEN
BEGIN {Get the intY-o text from the frame file}
GetMessage2( FERROR, Intro1, Intr02 );
{ Use the Synergy Error Window a5
}
WIERW( XStatus,
{ a fail-safe mechanism for getting}
Introl.L, Introl.S,
{ 50me information on the 5creen.
}
Intro2.L, Intr02~S.
0, JunkString.
Length, Message,
0, JunkString ) j
END { then }
ELSE {Need to use the hard-coded 5trin9s }
WIERW( XStatus,
40,'
This application has encountered
40,'
the following unexpected problem -0, JunkString,
Length, Hessage, {Specific message goes here}
0, JunkString );
ExitStatu5( 1);
END

< Exit the program }

< FatalError }

A-9

THE BATON.PAS FILE
[Global]
PROCEDURE ETToT( ETToTClass, ETToTNumbeT, ETToTMsgLength: Integer;
VAR ETToTMsg: StTing;
VAR XFile: Text;
10Status, UserPC: Integer;
FileNameLengthl Integer;
VAR FileName: StTing );

< ETToT is a substitute fOT the PRO/Pascal Tun-time syst.m ETTor handler
')
< module. This Toutine is called whenever some ·catastrophic· eTror
}
< condition is encounteTed, fOT example failed file I/O operations that do }
< not specify ERROR-CONTINUE; memoTY pTotect tTaps; odd-address traps; etc. }
< Most applications should provide theiT own eTTOT handleT, since the one }
< that PRO/Pascal pTovides is veTY laTge (takes .ddTe5s space), plus the
}

< infoTmation that it displays when an error occurs is generally of little }
< help to the user running the application (sort of a re9ister dump). Your}
< errOT handler can display a more friendly message, directing the user to }
< some documentation or whatever.
}
VAR
Length: Integer;
Datal String;
BEGIN

< ETror }

ReadMessage( OTSERR, Length, Data);
< Read the error text}
FatalErTor( TTue, Length, Data); < Display the text & kill the task}
END

< Error }

[Global] PROCEDURE PVDetachl

< PVDetach detaches the keyboard, disabling the AST-input mechanism. Once }
< detached, any extTa read-ahead input is copied fTom our private buffer
}
< (KBBUF) into the Synergy type-ahead buffer (~ITBF) so that it is not lost.}
ChI CharI
BEGIN

< PVDetach }

FlushGIDIS;
< Make sure any buffered output is put out}
Detach; < Detach the terminal }
UnlKeyboardl < Make sure the keyboaTd is unlocked}
I_ KBBUF.Countl < Copy data from private to public}
FOR i .- 1 TO KBBUF.Count DO
BEGIN
RemoveFromQueue( KBBUF, Ch )1 < Get next character from KBBUF }
< Append it to Synergy ~ITBF
}
~ITBF.Characters[ i ] 1= ChI
END < for } ;

~ITBF.CurrentLength

A-10

THE BATON.PAS FILE

{ WriteString tak~s a pass~d string. This string is then written to the
}
{ screen, taking into account any rendition control sequences ~bedded in
}
{ the string to changE!' the font in mid-string.
}
{ NOTE: Normally, the appljcation do~§ NOT have to be concerned with doing }
{ the 9runt-work for rendition control sequences,
That is, whenever you
}
< call some Synergy service to display some text Synergy will automatically}
{ "do the Tight thing" to invoke your desired rltndition5. You ONLY nlted to }
{ do it yourself if YOU are going to do the GIDIS output of ill string with
}
{ rendition sequences in it to ill window yourself
}

VAR
Char;
Change, Renchtion, i : InteseT;

eM I

{ UseRendition is passed a Tentition word (Ii-bits), and does the neces- }
{ saTY things to cause subsltquent ch&ractltr output to be in the specified}
{ rendition.
}

VAR
Wr it i ngMode: Wr j t i ngMc.des;
Int4lPnsity, Italics, Alphabet! IntegltTj

Italics
:= OJ
Alphabltt
:= WI.Normal;
Writin9Mode 1= Rl'place;

{ To start with, assume no italics}
{ Assume normal font
}
{ Assume ·positivl' video'
}

Int&!nsity

IF UAND( Rend. B ) = 0
THEN

{Underline NOT wanted}

CASE Intensity OF
Alphabet:£ WI.Dim;
1,2: Alphabet 1= WI$NoTmall
3:
Alphab@t I - WI.Sold;
END { case }
01

ELSE {Underline IS wanted}
CASE lntl'nsi ty OF"
0,
{Dim-underline is not supported, so use normal}
1,2: Alphabet 1= WI.Underline;
3:
Alphabet 1= WI.SoldUnderlinej
END { case } i

A-ll

THE BATON. PAS FILE
IF UAND( Rend, 4 ) <> 0
THEN
Italics ICO 21
IF UAND( Rend, 16 ) <> 0
THEN
WTitingMode 1= ReplaceNegate;
IF.UAND( Rend, 32 ) <> 0
THEN
Alphabet I - WI_Boxed;
SetCellRendition( Italic.
);
SetAlphabet(
Alphabet
)1
SetWTitingMode(
WTitingMode);

BEGIN

< U.e italics

}

< Now that we know what }

< i swan ted, do it.

}

< WTiteString }

I - 0;
Rendition I - 2; < To .taTt with, we want plain, nOTmal intensity text}
U.eRendition( Rendition )1 < Select nOTmal Tendition }

"t'
t.

WITH StT DO
WHILE i < L DO
BEGIN < Examine (and maybe display) the next chaTacteT }
i
I - i + 11
Ch I - S[ i 1; < Get the next chaTacteT }
I F Ch <> ChT ( 28
THEN
PutChT( Ch
{ A nOTmal chaTact.T, pTint it }
ELSE
BEGIN < The staTt of a Tendition stTing }
Change I - 0;
Ch
I - '0';
< PTime the pump}
REPEAT < StaTt .canning digit .equence }
Chang. :- ( Change
10 ) + OTd( Ch ) - OTd( '0' );
i
I - i + 11
< Skip to next byte}
Ch
.- S[ i ] 1 < Get the next chaTacteT }
lHT I L
Ch < ' 0 ' ) OR ( Ch > ' 9' ) 1

IF Ch • '+'
THEN Rendition .- UOR( Rendition,
Change
ELSE Rendition I - UAND( Rendition, UNOT( Change
U.eRendition( Rendition)1
END < el •• } 1
END < while } ;
END

< WriteString }

A-12

) {Additi .... }
) ;

< In ... oke new T.sulting Tendition }

THE BATON.PAS FILE

< CountString is passed a string record.

It returns tne PRINTING lengtn of }
}
< been accounted for. (Rendition control sequences start witn an ASCII 28, )
< tnen nave some digits, tnen nave a "+" or "-"
Tney are described in tne }
< Synergy progrMlllling manual.)
}

< tne string, once tne rendition control sequences to cnange fonts nave

VAR
Cn: Cnar;
BEGIN < CountString }

WITH Str DO
WHILE i < L DO
BEGIN < Ex~ine
i
l-i+1;
Cn I"" S[ i ]; < Get tne next cnaracter )
I F" Cn <> Cnr ( 28 )
THEN
Len :- Len + 1 < Normal text cnaracter, count it >
ELSE
REPEAT < Start skipping over tne rendition sequence}
i
:- i + 1; < Skip to next cnaracter }
Cn 1= S[ i ]; < Get tne next cnaracter }
lNT I L ( Cn .. '+' ) OR ( Ch = '-' );
END < while} ;

END

< CountString }

PROCEDURE FillText( NumberOfStringsl Integer;
VAR Msg: [ReadOnly,Unsafe] StringArray );

< FillText simply takes an array of string records, and displays tnem one
>
< below the other in the current window. Tne strings are scanned to see if }
< tney contain rendition control sequences and are displayed appropriately. }

BEGIN < FillText }
FOR i I - 1 TO NumberOfStrings DO
BEGIN < Display the next string inside tne window ~
SetPosition( 2
CnaracterWidtn,
(i - 1)
CnaracterHeignt + ( CharacterHeignt DIV 2 ) )J
WriteString( Msg[ i ) J < Draw tne string in its proper position}
END < for } ;

END

< FillText }

A-13

THE BATON.PAS FILE

}

VAR
GTIMdpb: GTIMdpbtype;
TimeBuffer: GTIMSBUF;
BEGIN

< Directive Par~eter Block for the GTIM directive}

< Time buff.r us.d by the Get Time P/OS Oir.ctive }

< InitializeSyn }

Titl.IO
,- TITLE; < Assum. the normal title strin9 }
Cont.xtL.n9th :- MaxContext; < A.k for the max}
WIINI( XStatu., 2, ActualV.rsion,
Cont.xtL.n9th, ContextBlock,
ScreenWidth, ScreenH.i9ht,
Charact.rWidth, Charact.rHei9ht,
PixelWidth, PixelHei9ht,
ColorWi ndows );

< Call Syner9Y, t.lling it that

}

{ oth.r services.

}

< this application has just
}
< start.d and will be requesting}

WITH ContextBlock.R DO
BEGIN {What's in the Context Block from the last time we ran? }
IF ContextLength • 0
THEN
{ This is the first time this application has run.
In this}
BEGIN < case, there is no saved context from before, so we must
}
}
{ do a on.-time initialization of the context data.
TitlelD
:- TITLE2; {Special intro title}
WindowWidth
:= ScreenWidth DIV 2;
{Make beginning size}
WindowHei9ht
:- ScreenHei9ht OIV 2; {of half-screen.
}
WindowX
:- -32763; {We want the window in
}
WindowY
:- -32763; < the middle of the scr.en. }
CBatons
:= 1;
{Start with one Baton,
}
CPoints
I - 17;
< With a tail 17 segments long. }
Sav.dColor1.R
:= ColorDescript~r( 0, 0, 7);
{Set up nice}
Sav.dColor2.R
,- ColorOe.criptor( 0, 7, 0); {color map
}
Sav.dColor3.R
."' ColorO.scriptor( 7, 7, 0); < in case
}
Sav.dColor5.R
:- ColorO.scriptor( 7, 5, O)j < COLOR is
}
Sav.dColor6.R
,- ColorDe.criptor( 7, 0, O)j < usable.
}
Sav.dColor7.R
I"' ColorO •• criptor( 0, 2, 3 );
Lin.Thickn •••. Low ."' Pix.lWidth; < Lastly, choose to draw the}
LineThickne.s.Hi
,- Pix.lH.i9htj { •• gments with thin lines. }
END < th.n } ;
Batons
Point.
ColorMap[ 0 l.R
ColorMap[ 1 1
ColorMap[ 2 ]
ColorMap[ 3 1
ColorMap[ 4 ] .R
ColorMap[ 5 ]
ColorMap[ 6 1
ColorMap[ 7 1
END < with} ;

< Now copy permanent values to run-t ime }
}
< variables for duration of this run.
ColorO.scriptor( 0, 0, 0 ) ; < This index is BLACK }

I"' CBatons;

.,.,-

,- CPointsj

:- SavedColor1;
:- SavedColor2;
Sav.dColor3;
ColorO •• criptor( 7, 7, 7
SavedColor5;
:- Sav.dColor6;
:- Sav.dColor7;

A-14

) ;

{

This index is WHITE

}

THE BATON. PAS FILE
OPENME( XStatus, SFCTV$, 25, 'LB:[ZZBATON]BATONFRMS.OFF' ); { Open file}
IF XStatu~[ 1 ]

<> 1

THEN
FliltillError( FalsfII, 32, '
Can"t open our frame file.' ) j {Death}
{ The frame file is stored in LS:[ZZBATON] so that, in P/OS V3 Cluster}
{ configurations, the .OFF file can be shared among multiple users.
}
WITH GTIMdpb DO
BEGIN {Set up the Directive Parameter Block for the GTIM$ directive}
D_CODE := GTIM;
{ Directive Identification Code. }
D_LGTH := GTtM_len; {Parameter Block Length.
}
G_TlBA I~ Address( TimeSuffer), < One Parameter (buffer address) }
END { wi th } I

DIRSC BTIMdpb); (Issue the directive, find out the current time)
WITH TimeBuffer DO {Use low-order time values to init the RND seed}
RndSeed := UOR( UOR( G_TIM! * 37, G_TISC * 71 ), G_TICT * 293 );
END < InitializeSyn } i

PROCEDURECleanUpSynj
}

BEGIN { CleanUpSyn }

WlTH WDesc. ContextBlock .R DO
BEGIN { Load the data that
WindowX
l= XI
WindowY
;'" y.,
WindowWidth := Width;
WindowHIl? i 9 ht := Height;
CBatoos
I " Batons;
1'. POint51
CPoints
SavIII'dColorl 1= ColorHap[
SavedColor2 1= ColorMap[
SavedCo!or3 :'" ColorMap[
SlIIvt1dColor5 1= ColorMap[
SavedColorb 1''' ColorMap[
SavII'dColor7 :"" ColorMap[

END 0( I"i th }

is to be saved in the cont4L'xt block

< Rememb9r thll' window
{

!Oiz4L' and position in
the contll'xt block.

{

Also save the user-

}

{

settablll' program valulI'5.

}

{

}

}
}

1 ] i
2 ] ;
3 ] j
5 ] j
6 1i
7 ] I

WIDSW( XStatus, WDesc.ID)j {D.stroy the main window}
WIDON( XStatuli, MaxContext, Cont.xtBlock)j < T4L'll Syn4L'rgy we're through}

END {

CI~.nUpSyn

} I

A-15

THE BATON.PAS FILE
PROCEDURE MakeOurWindow;

< MakeOurWindow simply creates a window
{ a title.

fOT

the application, and gives it

Length: Integer;
Data: String; {Used to hold a possible error message string}
BEGIN

< MakeOurWindow }

WITH WDesc, ContextBlock.R DO
BEGIN {Fill in the window descriptor block}
WDesc
:= WDescModel;
< Inlt the bulk of it }
X
:- WindowXj
< Then fill in the specifics}
Y
1= WindowY;
Width
;~ WindowWidth;
Height
1= WindowHeight;
Flags.Color
:= True;
< We'll use color. if the user lets us }
Flags.Titled
:x True;
Flags.WhiteBorder
;= True;
Flags.ClearOnChange 1= True;
END { with} ;
WIC~(

XStatus, DescriptorLength, WDesc)j

< Create the main window}

IF XStatus[ 1 ] <> 1
THEN
BEGIN {Yipe5!
We got an error creating the window}
ReadMessage( NOWIND, Length, Data)j
< Get eTror text}
FatalETror( True, Length, Data)j {Display the text & kill task}
END { then } ;
WITH WDesc DO
BEGIN < Assign the miRimum and maximum range for the window size}
MinWidth IS 100; < The minimum window
}
MinHeight I - 100; < size i~ pretty tiny. }
MaxWidth I - ScreenWidth;
< The Maximum is }
MaxHeight ,- ScreenHeight; {the full .cre.n. }
END { with) ;
WISWP(

XStatu~,

DescriptorLength.

WD.~C)I

WITTL( XStatus,
END { MakeOurWindow } ;

A-16

}

{Tell the values to Synergy}

THE BATON.PAS FILE
PROCEDURE InitBaton;
}

VAR
Segment, ThisBaton, Inner: Integer;

{Some FOR loop counters and such}

BEGIN { InitBaton }
IF ColorWindows <> 0
THEN
BEGIN {Color is in use, so initialize the colors}
ColorMapIndex := 11
FOR Inner IZ 1 TO 7 DO
IF Inner <> 4 {Leave index 4 (WHITE)
THEN
SetColorMap( Inner, ColorMap[ Inner
ColorMap[ Inner
ColorMap[ Inner

alone}
l.R.Red,
l.R.Green,
l.R.Blue )1

WITH ContextBlock.R.LineThickness DO
SetPixelSize( Low, Hi, Low DIV 2, Hi DIV 2 );
WITH WDesc DO
SetOutputClippingRegion( 0,0, Width - PixelWidth, Height - PixelHei9ht )1
SetWritingMode( Replace
SetPrimaryColor(
7)1
SetSecondaryColor( 7 )1

SetPrimaryColor(
4);
SetSecondaryColor( 4 );

{Go back to drawing in white}

{Use index 7 for the window background}

FOR ThisBaton 1= 1 TO Batons DO {Initialize each of the Batons}
WITH BatonList[ ThisBaton ] DO
BEGIN
IF ColorWindows • 0
THEN
Hue :- 0 { Monochrome, draw them in the black colormap entry}
ELSE
BEGIN { Color is present and enabled}
I - UAND( Rnd, 7);
{Pick a random starting color}
OR ( Hue • 0 ) OR ( Hue • 4
IF ( Hue >- MaxColor
THEN
Hue I - 11 {Make sure that it is a legal color index}
END < else ) ;
Newest

I-

A-17

THE BATON.PAS FILE
FOR

:= 0 TO 3 DO

Inn~r

BEGIN

{

Init the X,Y f>pE!'edf> of both end-points of fir;;;,t ji.Rsment }
I'" ( Rlld DIV 44 ) + 4;
{Pid\ startl '3 ",peed}

Inner]

Speed[

IF Rlld ) 450
THEN
Spe~d[

:- -Speed[

I nller

Inner];

{Randomly flip

the sign}

REPEAT
(
coordi ni}tE''!;.
Stick ... [ 0, InoC!'T ] := Rnd;
Pick stll!'f t i oS
Dlt.) ;2
Stic:kf>[ 0, In1'1Io'T ] < ( i-lDesc.Width
~D ( St i ck~[ 0 , Inn.r ]
< ( WDesc, • He i 9h t Dll,) 2
AND ( S tick Ii [ () Inner ] >
20
END ( fOT )- I

UNTIL (

fOR Segroent

1 TO Point'!> DO

{PropiIIgi;!te b<'lse

~t:ick

into

they'.}

FOR Inner := 0 TO 3 DO
Sll!gment, Inner)

Sticks[

Inne'r

]

wi th )- ;

END {
END (

I'"

InitBaton )-

PROCEDURE Travel( VAl'. Node, Direction: Integer;
i-lhichBaton, Index, Max: Integer );
{ Travel is called to move onl!!' part Df a Baton one eyel.

t5 track.

~lDn9

}

BEGIN { Travel }

WITH BatonList[ WhichBaton ] DO
BEGIN
Node := Node

IF
OR

+ Dirli!ction;

{Add pos.iticn '" speed

get nl!!'W p s ti n}

Node <~ 0 ) OR ( Nod. }= Max) {If the Baton hits ~d9.
Abi>( Sticks[ Nl!'WlI.'st, Index
{01" it '3fl't'lf> too long,
- Stick5[ Nl!'West, UAND( Index + 2, 3
1)
Max
3

THEN

BEGIN

(Reflect this node (bounce it) )

Dir@ction
Node
END ( then )END { ';Ji th )-

-Direction;
:- Node + ( 2

* Direction );

END { Tr avel }

A-18

}
}

LE
PROCEDURE Twiddlae.t
}

VAR
PriorSfl'gmltnt,lnn'iH

BEGIN (Twiddl.Bat

)

WITH BiltonList

BEGIN
IF

Col(H~hndo""'$

THEN

BEGIN

{

follow }

Hue :'"

IF Hul!'

THEN
HI.I~

}

IF Hue
THEN
!-IIJ!!?

END { then
S~tPr illHI!TYCO

SetPosition(
Dr iilWLi n f:' (

... e'~~r.t by 'r!ll'dra.wing bll1!ckgr'ound }
du. [ NOIW!II"!H, 1 1 )
tic~;,$,{ NOIWli'st, :3 ]
);

+ 1;

int

,", eo ~J'iH'!lH

FOR I rll'l!ll'l'"
St i ck ...

Pr i

n t 0 .1 s;
Sagmll'n t ,

WITH WDltl'$c
BEGIN

~'ndl'>

of thi!> f i Tilt

SII'9I'!U!'IH

o • WhichBiilltDn, D, Width

TrOllv€tl(
Tr<ll!OJt!'l(
TTiillvlII!l(
Travtll(

}

);
WhichBaton, 1, H.ight );
, WhichBatDn, 2, Width );
, WhichS.ton, 3, H~i9ht );

END { wi t

Se-tPrim<llTyCol
S~tPoi.i t i

Nl!Yw"" " t, 1
iJi.[ N"';!II!1>t, :3 ]

THEN
Nll'W!II!lIi. t

's colo!'

;

);

wh i ch ~1t<;Ji'\IlHl t will b~ i n fro n t
• ch.ckin! for wrap-~round.

NOIW@lst l'"
IF NII.'WI'!l>t

< wi th :r

(11)0 1>I!l!gmll.'lH in i
!> (

DI'" iilWL:i n lJ!.' (

END

n~l

}

)

}

THE BATON.PAS FILE
PROCEDURE EnOlbleColoTs( VAR

N~OIIp:

[R~iildOnlyl

ColorMapType

{ En.bleColoTfi simply l"9fr9Shes the hardware color map with the CUTrent
{ pro9rammed color choices.
VAR
il

Int.seTj

}
}

{FOR loop counter}

BEGIN { EnableColors }

FOR i

IF i

1 TO 7 DO
<:I

{Skip inde!)( 4,

IffillV(!>

illS

WHITE}

THEN
WITH N.wHap[ i l,R DO
SetColorMap( i, Fl._d, Green, Blue ),

PROCEDURE Hibernate;
{ Hibernate i . called when the usel" pr~ •• ~. F5; th~ WIINT Synergy .eTvic~
}
{ is used to suspend the applicOlitiDn. This procedure is responsible for
}
{ knowing what to do if the end-usev ever changes the window size.
Usually}
{ this means Tefreshing the window based on its new width and height.
In
}
{ this program, thili is acc()mplish~d by mer~ly rll'-initializing the data
}
{ structures u!>Il!d to contain the X,Y position of the Baton se9ffients.
This }
( is done in case the window is reduced in size, such that part or all of ~ }
{ Baton !iu!9fflent mi9ht fall outr.ide the window (there is 1"10 l'fI'ason why this }
{ cannot be allowed to happen, as GIDIS is fully capable of clipping the
}
( 'overhanging" segments; this program simply chose not to allow it),
}
VAil:
WindowID,

N~idth,

NewHei9ht. WhyChange: Integer;

REPEAT

FlushGIDIS;
{Force out iilny buffeTed GIDlS output}
WIINT( XStatus, WhyChangE!, WindowID, NeWWidth, NewHeight)j
IF WhyChange
1

(Suspend)

THEN

BEGIN {Window size was changed, update its cont9nts }
WIGEW( XStatus, Descriptorlength, WO.sc);
{Get size & position}
InitBatoni {Re-init the data structures to fit the new size}
END { then } i
UNTIL WhyChange x 01
{O
m.ans th~ application ~hould resume ~xecution }

KBASTlnitializel

(Get the keyboard back for AST input}
EnableColoy§( ColorMap);
{R~fr~sh th. color map to our colors}

END { Hibernate} ;

A-20

THE BATON.PAS FILE
PROCEDURE HandleKey;
{ This (large) procedure processes all typed input (function keys) from the}
{ keyboard.
}
PROCEDURE HandleFCMKey( InputKey: FunctionkeyNames
{
{
{
{
{
{

HandleFCMKey is called when either Fll, F12, F13, or ADDTNL OPTIONS is }
pressed, with the intent being to display the proper leaf in the
}
application's main Flow Control Menu. As it turns out, this
}
application only has one leaf, but the code doesn't know that.
It is
}
written such that if the frame file were changed to include more leaves}
the code would work with th.m automatically.
}

VAR
MenulD,
OptionValue,
KeyPressed: Integer;
PROCEDURE HandlePersonalizeKey;
{
{
{
{

HandlePersonalizeKey is called when the user chooses the ·Change
Batons· option from the main Flow Control Menu. ~hat this procedure
does is to display a set~p menu (sometimes called a property sheet)
to solicit new program values from the user at the keyboard.

}
}
}
}

NumChanged, KeyPressed: Integer;
ChangedValues: PACKED ARRAY [ 1 .• 2 ] OF 0 .• 255;

~IXPS(

XStatus, KeyPressed,
{Display the setup menu}
NumChanged, ChangedValues,
DEFQ, 2, 4, Batons, 4, Points );

IF KeyPressed = ~F5
THEN SuspendRequested := True {Set flag. we'll get it next time}
ELSE
IF KeyPressed = PV$MAI
THEN MainScreenRequested 1= True
ELSE
IF NumChansed > 0
THEN
BEGIN {One or more were changed, so update things}
IF Batons < 1
THEN
Batons I - 1; {Do our own bounds checking on the values}
IF Batons) MaxBatons
THEN
Batons 1= MaxBatonsj

A-21

THE BATON. PAS FILE
IF Points ( 3
THEN
Poi ntf> I'" 3;
IF Points) MaxPoints
THEN
Point" := MaxPoints;
InitBatonj
END { then }

{Re-start the

A-22

Batons (data structures) }

THE BATON. PAS FILE
PROCEDURE HandleColorMap;

< HandleColorMap is called when the user chooses the ·Color map· option}
< from the main Flow Control Menu. What this procedure does is to
}

< create and process its own custom, special-purpose interface that

< allws the end user at the keyboard to change the colors in the color
< map.

}
}
}

FunctionKeYI FunctionKeyNames;
NewMap: ColorMapType;
Chi Char;
CurSiz, Gap, IndentX, IndentY,
Priorlndex, Colorindexl Integer;
MapWindowl WindowDescriptor;
PROCEDURE PutCursor;

< PutCursor pOSitions a semi-graphical cursor on the initial window
< used in changing the color map. (Initial means the horizontal

< strip of six squares for the six colors that can be changed.)

< The semi-graphical cursor is constructed as follows, First, a
< heavy black line is drawn around the square that the cursor is

< positioned on. Then, just inside of that heavy line, the real
< blinking GIDIS Rubber Band cursor is placed. The net effect is of
< a large hollow square cursor, whose inner edge is blinking.
CONST
Pixel • 10;

}
}
}
}
}
}
}
}

< Thickness of the line for the bulk of the cursor}

Newindex: Integer;

< This procedure draws the non-blinking first part of the cursor,
< the heavy hollow square.
BEGIN

< Draw }

DrawRelLine(
DrawRelLine(
DrawRelLine(
DrawRelLine(

(index-l)*(CurSiz+Gap) + IndentX - ( Pixel DIV 2 ),
IndentY - ( Pixel DIV 2 ) );
(Pixel + CurSiz + PixelWidth), 0
);
0,
(Pixel + CurSiz + PixelHeight) );
-(Pixel + CurSiz + PixelWidth), 0
);
0, -(Pixel + CurSiz + PixelHeight) ).

A-23

}
}

THE BATON.PAS FILE
BEGIN < PutCursor }
S.tPix.1Siz.( Pix.l, Pix.l, Pix.l DIV 2, Pix.l DIV 2); < F.t lin. }
S.tWritingMod.( Er.s.); < Pr.p.r. to .r.s• • ny .xisting cursor}
IF PriorInd.x <> 0
THEN
Dr~( PriorInd.x);

< Th.r. w.s .n .xisting cursor, .r.s. it }

N.wInd.x ,- ColorInd.x;
IF N.wInd.x > 3
THEN
N.wInd.x .- N.wInd.x - 11
PriorInd.x .- N.wInd.x,

< Slid. upp.r p.rt oy.r ind.x 4 }

< Rememb.r n.w cursor position n.xt tim. }

S.tWritingMod.( R.pl.c.); < Pr.p.r. to dr~ th. n.w cursor}
S.tOutputRubb.rB.nd( -1, 0, 0); < Dis.bl. th. Tubb.r b.nd }
IF N.wInd.x <> 0
THEN
BEGIN < Th.r. is • cursor w.nt.d, dr~ it in its n.w position}
Dr~( N.wInd.x );
S.tPosition( ( N.wInd.x - 1 )
CurSiz + a.p )
+ Ind.ntX + CurSiz + Pix.lWidth,
Ind.ntY + CurSiz + Pix.1H.ight ),
S.tOutputRubb.rB.nd( 2, ( N.wlnd.x - 1 )
CurSiz + G.p )
+ Ind.ntX - Pix.1Width,
Ind.ntY - Pix.1H.ight );
END { th.n }

* (

END < PutCursor }

A-24

THE BATON.PAS FILE

PROCEDURE ModifyEntry( Entry: Integer )j

< ModifyEntry manages the second, inner window portion of changing
}
{ the color map. This inner window has three black squares, one each}
{ for RED, GREEN, BLUE. This procedure allows the user to move
}
{ between the three color components, and increase or decrease their }
< respective intensities.
}
~R

FunctionKey: FunctionKeyNamesj
ChI Charj
EditWindow: WindowDescriptorj
N~Color, OldColor: ColorDescriptorj
Level, NewRGB, PriorRGB, CurSiz, Gap, IndentX. IndentYI Integer,
PROCEDURE PutlnnerCursor;
{ PutlnnerCursor positions a semi-graphical cursor on the second
{ window used in changing the color map, This cursor is produced
< similarly to how the PutCursor procedure above produces the
{ cursor for the first, outer window in 'Color map,"
CONST
Pixel = 10;

< Thickness of the square line}

BEGIN {Draw}
SetPosition( (Index-l)*(CurSiz+Gap) + IndentX IndentY - ( Pixel DIV 2 ) );
DrawRelLine(
(Pixel + CurSiz + PixeIWidth), 0
DrawRelLine( 0,
(Pixel + CurSiz + PixelHeight) );
DrawRelLine( -(Pixel + CurSiz + PixelWidth), 0
)1
DrawRelLine( 0, -(Pixel + CurSiz + PixelHeight) ) j
END { Draw} ;
BEGIN { PutlnnerCursor }
SetPixelSize( Pixel, Pixel, Pixel DIV 2, Pixel DIV 2)j < Thick}
SetWritingMode( Erase)1 ( Prepare to era~e any exi~tin9 cur~OT }
IF PriorRGB <>
THEN
Draw( PriorRGB ) j
PriorRGB 1= N.wRGB;
SetWritingMode( Replace ); { Prepare to draw the n.w cur~or }
SetOutputRubberBand( -1, 0, 0); < Disable the rubber band}
IF N.wRGB <> 0
THEN
BEGIN { There i~ a n.w one, draw it in its n.w position}
Draw( N.wRGB ~;
S.tPo~ition( (NewRGB-l)*(CurSiz+Gap) + IndentX + CurSiz,
IndentY + CurSiz )J
SetOutputRubberBand( 2, (N.wRG8-1)*(CurSiz+Gap) + IndentX.
IndentY );
END { then } I
END { PutlnnerCursor } I

A-25

}
}
}
}

THE BATON. PAS FILE
PROCEDURE Displ.yEditWindowl

< Displ.yEditWindow CT •• t.S the s.cond, inn.T window used in ·ColoT )
< m.p." This window h.s some instTuction., follow.d by thT •• bl.ck )
< squ.r.s r.pT ••• nting RED, GREEN, BLUE.
)
CONST
EditH.ight - 7;

< Height of the inneT window in text-lines)

M.g: ARRAY [ 1 •• EditHeight 1 OF StTingTypel
RGBText& StTingj
Longe.tStTing, Len, i: Integ.TI
BEGIN < Displ.yEditWindow )
GetMe.sage7( EDIMSG,
M.g[ 1 l, M.g[ 2 I, Msg[ 3 I, Msg[ 4 I,
M.g[ 5 I, M.g[ 6 I, Msg[ 7 I ),
< Call GetMe.s.ge7 to Te.d the instTuction.1 text fTom • m.ss.g • )
< fTame in the fTame file. GetM •••• g.7 Te.ds the entiTe fTam.
)
{ into a buffeT, then TetuTn. the S.p.T.te line. of the mes ••g •• )
LongestStTing I - 0;
FOR i 1 8 1 TO EditHeight DO
BEGIN {Compute longe.t stTing (contTol. width of the window) )
Len IS CountStTing( Msg[ i I ) j < Find the di.pl.y.d length)
IF Len> Longe.tStTing
THEN
Longe.tStTing I - Lenl
END { fOT )

WITH EditWindow DO
BEGIN < Fill in the window d •• CTiptOT block)
EditWindow
I - WDescModell
< lnit the bulk of it )
Width
.- Long.st5tTing
Ch.T.cteTWidthl
Height
:- ( EditHeight + 1 )
ChaT.cterHeight;
X
.- -32760; < Window c.nteT.d )
Y
.- ( 8
Ch.T.ct.THeight ) - 2048;
fl.g •• 5t.ck.ble
I - TTu.;
FI.g •. ColoT
.- TTue;
Fl.gs.Titled
I - Fal.ej
FI.gs.Whit.BoTdeT .- TTue;
END < with) I

*
*

FlushGIDIS;

< Flu.h .ny p.nding output to fiTst, out.T window)

A-2~

THE BATON.PAS FILE
RGBMSG, i, RGBText); {3 characters long}
SetAlphabet( ~I~8old );
S.tCellRondition( 2); {Italics}

Rf!'adH.~$age(

fOR i := 1 TO 3 DO
BEGIN {Display the 3 squares for R, G, B }
SetPosition( (i-l)*(CurSiz+Gap) + IndentX, IndentY
SeginFillj {Fill in a square in black}
DrawReILinfl'( (CurSiz), 0
);
DrawRfI'lLinll!( 0,
(Cu1"Siz) );
D1"awRlI!lLine( -(CuySiz), 0
)1
DrawRfI'lLinf!'( 0,
-(CurSiz) ) j
Endfill j

SfI'tPosition( (i-l)*(CurSiz+Gap) + IndentX + ( CurSiz DIV 2 ),
IndentY + ( CurSiz DIV 2 ) + PixfI'lHeight
- ( Charactfl'rHfI'ight DIV 2 ) );
SetWritingHode( Rf!'plac~e9ate );
PutChr( RGBText[ i ] ) ; {Label the square "R", "G", or "8" }
SetWritingHode( Replace );
END { for } j
SetCellRendition(
END {

{No italics}

O)j

DisplayEdit~indow

}

BEGIN { HodifyEntry }
OldColor
NE.'WColor
NI?WRGB
PriorRGB
CurSiz
Gap
Ind.ntX
IndentY

Entry ],R; { RenH!'mb Ii? 1" curr!!'nt RGB of color }
{ Star t
the new RGB value'!> wi th the current
{ The cursor wi 11 start on the RED square }
I'" 1;
{ Th4!!'1" Ii? is no existing cursor }
:= OJ
{ Compute I>ome layou t values }
:= Cha1"acterWidth * 4',
:= CharlllctiPrWidth * 4; _.
:"' Characte1"Width
* 14 ( Pix4l?1~idth * 3 ) ;
I'" CharacterHei'3h t * 4;
1""

N~ap[

:= OldColorj

}

SetOutputRubbe1"Band( -1, 0, 0)1 {Disable it }
{Display the RGB window}

DisplayEdit~indow;

REPEAT
EnableColors( N.wMap); {Refresh color map with current choices}
PutlnnerCursor; {Draw the cursor wherever it's suppo$!!'d to be }
flushGIDISj {Flush pending output prior to any keyboard wait}
KBASTlnitialize; {Attach the keyboard for AST input}
FunctionKey IE GetAKey( eM); {Read a keystroke}
PVDetach; {Detach. This also flushes the GIDIS buffer}
NE.'WRG8 OF
Level := NE.'WColor.RlPdj
2: l€'vel 1= NE.'WCO lor. Gr tum i
3: LltvC!'1 I'" NE.'WColor.Blue;
END { c.,,!!! } I
CASE

{
{

{

Remember the current level of
whichever component (R,G,B) the
curlior i 10 on.

A-27

}
}
}

THE BATON.PAS FILE

Su.p.ndKey,
MainScT •• nK.y,
Exit:

< Nothin9 to do Ti9ht now}

IF NewRGB - 3
THEN SoundB.ll < C.n' t move Ti9ht hom BLUE}
ELSE NewRGB
NewRGB + 1 ; { -Mov. Ti9ht a .quaTlP }

..-

L.ft:

IF NewRG8 - 1
THEN Sound8.11 < C.n't move l.ft fTom RED }
ELSE NewRG8
NewRG8 - 1 j < Mov. l.ft
.qU.Te }

•

Up:

IF L.vel - 7
THEN SoundB.ll < At m.ximum compon.nt •• tuTation }
ELSE L.vel .- L.vel + 1, < IncT •••• by • notch}

Down:

IF L.v.l • 0
THEN Sound8.1l < At minimum component •• tuT.tion }
ELSE Lev.l .- L.vel - 11 < d.CT •••• by • notch}

OTHERWISE
END <

c... }

IF ( FunctionK.y - Up ) OR ( FunctionK.y - Down )
THEN
BEGIN { Th. compon.nt
CASE NewRG8 OF
1:
NewColoT.R.d
.- L.v.l; { Rememb.T the new l.v.l fOT }
}
2: NewColoT.GT •• n .- L.v.l; { which.v.T compon.nt
3: NewColoT.81u •
• - L.v.li { (R,G,8) the CUT.OT i5 on. }
j
END <

c... }

NewM.p[ EntTY l.R .- NewColoTj
END < th.n } ,

{Upd.te coloT m.p with it }

UNTIL ( FunctionK.y - Exit
) {Si9nal. that the U•• T i . }
OR ( FunctionKey - Su.pendKey
) {don. ch.n9in9 thi. coloT }
OR ( FunctionK.y • M.inScTe.nK.y )j { ind.x now.
}
IF FunctionKey • Su.p.ndK.y
THEN Su.p.ndR.que.ted :- TTue < S.t fl.9, w.'ll get it n.xt tim. }
ELSE
IF FunctionKey - H.inScTe.nK.y
THEN M.inScT •• nR.que.ted :- TTue,
SetOutputRubbeTB.nd( -1, 0, 0), < Oi •• bl. Tubb.T b.nd }
Flu5hGIDIS, < Flu.h .ny Tem.inin9 output to thi. window}
WIDSW( XSt.tu5, EditWindow.ID).
END

< ModifyEntTY }

< O•• tTOY the window}

A-28

THE BATON.PAS FILE
PROCEDURE DisplayColorsj
{ DisplayColors creates the first, outer window used in ·Color map."
{ This window has some instructions, followed by six colored squares
< representing the six colormap indexes that the user can change.
CONST
WindowHeight • 9;

< Number of lines the window is tall}

Msgi ARRAY [ 1 •• WindowHeight ] OF StringType;
i, Len,
LongestStringl Integerl
BEGIN

< DisplayColors }

GetMessage9( COLMSG,
Msg[ 1 1, Msg[ 2 ], Msg[ 3 J,
Msg( 4 ], Msg[ 5 ], Msg[ 6 1,
Msg[ 7 ], Msg[ e 1, Msg[ 9 ] );
{ Call GetMessage9 to read the instructional text from a message}
{ frame in the frame file.
GetMessage9 reads the entire frame
}
< into a buffer, then returns the separate lines of the message. }
LongestString :- 01
FOR i := 1 TO WindowHeight DO
BEGIN < Compute longest string (determines the window width) }
Len IS CountString( Msg[ i ] ) j
IF Len> LongestString
THEN
LongestString := Len;
END < for }

WITH MapWindow DO
BEGIN < Fill in the window descriptor block}
MapWindow
.- WOescHodel;
< Init the bulk of it }
Width
1= LongestStrin9
CharacterWidth;
Height
1= ( WindowH.ight + 1 )
Charact_rH@i9htj
X
:= -32763;
< SCT@en center.d }
Y
1= Scr@enHeight DIV 5;
flags.Stackable
1= TTue;
Flags.Color
:= Tru@;
Flags.Titled
1= false;
Flags.WhiteBorder 1= Tru@1
END < with}

*
*

FlushGIDIS;

< Flush output

to curr@nt window before cr@atin9 new }

A-29

}
}
}

THE BATON.PAS FILE

FOR i :- 1 TO 6 DO < Di~play the 6 COlOT ~quaTe~ }
BEGIN
SetPo~ition( (i-1)*(CUTSiz+Gap) + IndentX, IndentY );
IF i <.. 3
THEN SetPTimaTyColoT(
ELSE SetPTimaTyColoT(

)

+ 1);

BeginFill; < Fill in a ~quaTe in
DTawRelLine( CUTSi z, o
);
DTawRelLine( ·0,
CUTSiz );
DT awRelLi ne( -CuTSiz, o
);
DTawRelLine( 0,
-CuTSiz );
EndFill;
END < fOT } ;

< Skip OVWT COlOT index 4 }
~olid

COlOT }

SetPTimaTyColoT( 0 );
END

< DisplayColoTs } ;

BEGIN

< HandleColoTMap }

I- ColoTMap;
< Init new map value~ with the CUTTent ones}
NewMap
ColoTIndex I"" 1; < The CUT~OT will ~taTt on the fiTst squaTe }
PTioTIndex I'"' 0; < TheTe is no existing CUTSOT }
:= ChaTacteT~idth * 4;
CUTSi z
Gap
* 3;
I" ChaTacteTWidth
I - ChaTacteT~idth
IndentX
* 11 DIV 2;
I nden tY
:- ChaTacteTHeight * 11 DIV 2;

DisplayColoTs;

< CTeate the outeT coloTmap window with 6 squaTes }

REPEAT
EnableColoTs( NewMap); < Make SUTe the COlOT map is CUTTent }
PUtCUTSOT; < Po~ition the CUT~OT on the chosen ~quaTe }
FlushGIDIS; < Flush pending output pTioT to any keyboaTd wait}
KBASTInitialize; < Attach the keyboaTd fOT AST input}
FunctionKey I - GetAKey( Ch); < Read a keystToke }
PVDetach; < Detach. This also flushes the GIDIS buffeT}

A-30

THE BATON.PAS FILE

SU5pendKey,
MainScr.enKev,
Exitl
{ Nothing to do right yet}
IF ColorIndex = MaxColor
THEN SoundSell {Can't move right from 6th ~quare }
ELSE
IF ColorIndex
3
THEN Colorlndex := 5 {Skip over index 4 }
ELSE Colorlndex a~ Colorlndex + 1; {Move right}

IF Color Index z 1
THEN SoundSell {Can't move left from 1st square}
ELSE
IF Colorlndex = 5
THEN Colorindex := 3 {Skip back over index 4 }
ELSE Colorlndex := Colorlndex - 1; {Move left}
Do Key ,
SelectKey,
Return:

ModifyEntry( Colorlndex)j

{Go set RGB components}

CancelKey:
OTHERWISE
END { case }
UNTIL ( FunctionKey = Exit
OR (FunctionKey
SuspendKey
OR ( FunctionKey
MainScreenKey );

{ Signals that the user is }
{ done changing all color }
{ indexes for now.
}

IF FunctionKey = SuspendK@y
THEN SuspendRequested 1= True {Set fla9. we'll get it next time}
ELSE
IF FunctionKey m MainScr •• nKey
THEN MainScreenRequested 1= True;

Colorlndex I - OJ { Set this up ~o that,."
}
PutCursoYj
{ the cursor wll be shut off. }
FlushGIDISj { Flush any r.mainin9 output to this window}
WIDSW( XStatus, MapWindow.ID)1

{D~stroy

the window}

ColorMap :- N.wMapi
{R.m~b~,
the n.w values}
Enabl.Colors( ColorMap)j {R.fresh the hardware colormap }

A-31

THE BATON. PAS FILE

< H.ndl.Lin.Thickn.ss is c.ll.d wh.n the us.r chooses the ·Line
< thickness" option from the m.in Flow Control M.nu. What this
< proc.dur. does is to creat. and process its own custom, sp.cial< purpose int.rf.c. th.t .llows the .nd user at the k.ybo.rd to change
< the thickness (both in X .nd in Y) of the line th.t the s.gments of
< the B.tons are drawn wi tho

}
}
}
}

}

\JAR

LineWindow: WindowD.scriptor\
FunctionK.y: FunctionK.yNam.s;
OldLow, OldHil Int.g.r;
ChI Ch.r;
PROCEDURE Displ.yLineWindow;

< Displ.yLineWindow cr •• tes the display u ••d fOT -Lin. thickn •••• •

)

< drawing of a sample B.ton on the Tight.

)
)

< This displ.y has some instruction.l t •• t on the l.ft, follow.d by • >
Thi. Toutin. CT •• t •• the

< displ.y window .nd fills in the t.xt on the l.ft.
C~ST

WindowH.ight

< Numb.r of lin •• the window is t.ll )

VAR
Msgl ARRAY [ 1 •• WindowHeight ] OF StringTyp.;
i, L.n, Long.stString: Int.ger;
BEGIN

< DisplayLineWindow >

G.tM.ssage9( LTHMSG,
Msg[ 1 ], Msg[ 2 ], Msg[ 3 ],
Msg[ 4 ], M.g[ 5 ], Msg[ 6 ],
Msg[ 7 ], Msg[ e ], Msg[ 9 ] );
< C.ll G.tM •••• g.9 to r.ad the instruction.l t.xt from. m•• s.g. }
< frame in the frame file. G.tM.ss.g.9 r.ads the .ntir. frame
}
< into. buff.r, th.n r.turn. the •• parate line. of the m•••• g •• }
Long.stString I - 0;
FOR i I - 1 TO WindowH.ight DO
BEGIN < Comput. long •• t string (d.t.rmin.s width of window)
L.n I - CountString( M.g[ i ] ) I
IF L.n > LongestString
THEN
Long•• tString .- L.nl
END < for } I
Long.stString

I-

Long •• tString + 41

A-32

< Add .p.c.r. on •• ch .ide >

THE BATON.PAS FILE
WITH lin.window DO
BEGIN < fill in the window descriptor block}
lin.window
,- WDescModell
< Init the bulk of it }
Width
,- longestString
CharacterWidthj
Height
,- ( WindowHeight + 1 )
CharacterHeightj
X
I - -32760;
< Window centered}
y
-32760, < Window centered}
flags.Stackable
'''' True,
flags.Color
I"" True;
nags.Titled
:= falsel
flags.Whit.Border 1= Trull';
END { wi th } I

*
*

flushGIDIS;

< flush any remaining output to current window}

fillText( WindowHeight, Msg);
END

< Write the text strings in window}

< Displaylin.window }

A-33

THE BATON.PAS FILE
PROCEDURE ShowLines;
{ ShowLines draws the sample eaton in the rightmost portion of the
{ ·Line thickness· display window, using the current X, Y thickness
{ values.

VAR
Xl, Yl, X2, Y2, i, Col, BoxSiz, CornerX, CornerV: Integer;
BEGIN { ShowLines }
BoxSiz
J . Character~idth
CornerX JK Character~idth
CornerV :- CharacterHeight

* 13;
* 31;
* 2;

SetOutputClippingRegion( CornerX, CornerY, BoxSiz, BoxSiz );
EraseClippingRegion; {Get rid of any old sample Baton}
ContextBlock.R.LineThickness DO {Use the n.w line}
SetPixelSize( Low, Hi, Low DIV 2, Hi DIV 2 ) j

~ITH

CornerX + BoxSi z;
CornerY;
X2 z= CornerXj
Y2 zS CornerV + 80 ;
Col := 0-,

J=
J.

{
{
{

Init the star t i ng }
}
position of the
}
sample Baton.

fOR i z= 1 TO 8 DO {The sample Baton is 8 segments long}
BEGIN {Draw the next segment}
Co 1 :- Co 1 + 1;
If Col" 4
THEN
Col :- 5; {Skip color index 4 }
If Col - MaxColor
THEN
Col Ja 1; {Cycle back to 1 }
If Color~indows .. 0
THEN SetPrimaryColor( 0
) {Black if monochrome
}
ELSE SetPrimaryColor( Col ); { Els. use proper color}
SetPosition( Xl, Yl );
DrawLin.(
X2, Y2 );

Xl
Xl - 28;
Yl z. Vl + 10;
X2 .- X2 + 301
Y2 Ja Y2 + 35;
END { for } ;

{Move the Baton along its track}

S.tPrimaryColor( 0);

{Back to drawing in black}

Lin~indow DO
S.tOutputClippingRegion( 0, 0, Width, Height)1

~ITH

A-34

< Full window}

}
}
}

THE BATON.PAS FILE

DisplayLineWindow;

< Create the display and its instructional text}

EnableColors( ColorMap); < Refresh the hardware colormap }
ShowLines; < Draw the sample Baton using current line thickness}
WITH ContextBlock.R.LineThickness DO
BEGIN < R.member current thickness}
OldLow 1= Low;
OldHi
:=Hi;
END < wi th } ;
KBASTInitializej

{Attach the keyboard for AST input}

REPEAT
FlushGIDIS;
FunctionKey

< Flush pending output prior to any keyboard wait}
GetAKey( Ch); < Read a keystroke}

WITH ContextBlock.R.LineThickness DO
CASE FunctionKey OF < Now process the keystroke}
SuspendKey,
MainScreenKey,
Exit:
{ Nothing to do now}
Lef t I

IF Low) PixelWidth
THEN
BEGIN {Reduce X thickness (Narrower) }
Low := Low - PixelWidth;
IF ( KBBuf.Count • 0 ) OR ( Low· PixelWidth
THEN
ShowLinesl {Update display if needed}
END { Lef t } I

Right:

IF Low < 200
THEN
BEGIN { Increase X thickness (Wider) }
Low := Low + PixelWidth;
IF ( KBBuf.Count x 0 ) OR ( Low )= 200
THEN
ShowLines;
END < R i gh t } I

Up:

IF Hi > PixelHeight
THEN
BEGIN < Reduce Y thickness (Shorter) }
Hi :- Hi - PixetlHeight;
IF ( KBBuf.Count • 0 ) OR ( Hi • PixelHeight
THEN
ShowLines;
END { Up } I

A-35

THE BATON.PAS FILE
I F Hi ( 200
THEN
BEGIN {IncTea~e Y thickness (Taller) )Hi := Hi + PixelHeight;
IF ( KBBuf.Count
0 ) OR ( Hi >- 200 )
THEN
ShowLinetsj
END { Down } ;

Down:

BEGIN {Reset to original line thickness}
Low := OldLowj
Hi
:= OldHi;
ShowLinesj
{And display it that way again )END { Cal eel Key } ;

CancelKey:

Sour.dBell j

• OTHERWI SE
END { case )lJ\ITIL
OR
OR

FunctionKey • Exit
( These keys signal that the )FunctionKey
SuspendKey
< user is done changing the }
FunctionKey
MainScreenKey); ( line thickness fDr now.
)-

IF FunctionKey
SuspendKey
THEN SuspendRequested := True (Sett flag.
ELSE
IF FunctionKey = MainScreenKey
THEN MainScreenRequested := Truej
PVDetachi

SD we'll get it next time )-

(Detach the keyboard )-

WIDSW( XStatus,

Line~hndow.ID);

(Destroy "Line thickness" wi.ndow )-

WITH ContextBlock.R.LineThicknes5 DO
BEGIN (Invoke the new line)
SetPixelSize( Low, Hi, Low DIV 2, Hi DIV 2 );

( New line is ~al1er )IF ( Low < OldLow ) OR ( Hi ( OldHi
THEN
InitBatonj
(Start them over to erase old debris )END { wi th )- ;

A-36

THE BATON.PAS FILE
BEGIN { HandleFCMKey }
PVDetach;

{Detach keyboard to allow Synergy to operate the Flow Menu}

EXFLOW( XStatus, KeyPressed, MenuID,
{ Process the Flow}
OptionValue, QIXFCM,
{ Control Menu.
}
Ord( InputKey ) - Ord( Fll ) );
IF (KeyPressed
~DO
OR ( KeyPressed
PV$RET
THEN
CASE OptionValue OF

{ A successfull terminator was pressed, }
}

{ see which option was chosen.

IF Colorf..Jindows = 0
THEN EXMESS( XStatus, K.. yPressed, NOCOLR )
{ Go change the color map
ELSE HandleColorMaPI

}

HandlePersonalizeKeYi

{

Go change the Batoros

HandleLineThicknessj

{

Go c han g e the line thickness

}

OTHERJ..II SE {Do No thi n9 } ;
END { CillOI' }
IF KeyPressI'd
PV$F5
THEN Su!>pendRequested := True {S .. t flag. we'll get it
ELSE
IF KeyPres!>ed = PV$MAI
THEN MainScreenRequested := True;
KBASTlnitializej

{Reattach the keyboard

END { HandleFCMKey } ;

A-37

fOT

AST input}

ne~t

time}

}

THE BATON.PAS FILE

IF SuspendRequested
THEN
BEGIN {F5 was pressed when we were in the middle of something before}
InputKey
:= SuspendKeYi
{Fake an F5 }
SuspendRequested :- False; {Dismit-s the request}
END { then }
ELSE
IF HainScreenRequested
THEN
BEGIN {MAIN SCREEN was pressed in the middle of something before}
InputKe~'
:= MainScreenKey;
{Fake <II MAIN SCREEN}
HainSc,..tt~nR£'quest.d := False;
{Dismiss the request}
END { th£'n }
ELSE
InputKey := GetAKey( InputChar);
CASE InputKey OF
Ex i t ,
HainScreenKey:

Done:= True;

{Set

{Read the REAL keystroke}

ill

flag so we will

exit}

SuspendKel' :

Hibernate;

HelpKey:

BEGIN
PVDl!:'tachj {·Free the keyboard for Synergy's use}
EXHELP( XStatus, OVERVW); {Give HELP}
KBASTlnitialize; {Get the keyboard back again}
END { help } ;

Fll, F12, F13,
AddOptn'iKeYI
InsertHere:

{Give control up to the Synergy Hain Menu}

HandleFCMKey( InputKey ) j

{Process Flow Memu request}

IF Batons < MaxBatons
THEN
BEGIN {Not at max, increase the number of Batons}
Batons := Batons + 1;
InitBaton;
{R~-start the n.w Batons}
END { then } i

IF Batons > 1
THEN
BEGIN (Not at min, decrease the number of Batons)
Batons 1 8 Batons - 1;
InitBatonj {Re-start the n.w .Batons }
END { thtm }
OTHERWISE SoundS.ll;
END ( ca,.. )-

{Ignore all other keys}

A-38

THE BATON.PAS FILE
BEGIN { Baton }
Initializ.Syn;
Mak4l.'0urWi ndow;
InitBatonl
KBASTlnitializej

{ S.t up ba5ic environmental thing5.
{ Create the playing field.
( Injt the Baton data 5tructure5.
< Attach the keyboard for AST input.

SuspendRequest4l.'d
I - Fals.;
MainScreenRequest.d :- False;
:e False;
Done
TitlitCounter
:- 0;

WHILE
KBBUF.Count <> 0
OR SuspendR4Pquested
OR MainScr.enRequ.st.d DO
Handl4PK.y;
FOR i := 1 TO Batons DO
TwiddlltBaton( i ) I

}
}
)
}

< Cl.ar a few )
< v ar i ables • }

< If any k.Y5 have be.n pr •••• d, }
< or F5 was press4Pd a ways back, }
}
< or MAIN SCREEN a ways back,

< go process them.

}

< Move .ach eaton a cycle.

}

IF ColorWindows <) 0
THEN
BEGIN < On a color system, rotate th. colors to follow the Batons )

FOR i I - 1 TO 5 DO
BEGIN < Roll th4P color map )
Ind4Px := i + ColorMaplnd4Px - 11
I F I nd.x ) 3
THEN
Index I - Index + 1; < Skip ovltr 4 )
IF Index )= MaxColor
THEN
BEGIN {Wrap around }
Index Ie Index - ( MaxColor - 1 >;
IF Index> 3
THEN
Ind.x ,- Ind.x + 1; < Skip ovtpr 4, afttpr wrap)
END { then } ;
!-lITH ColorMap[ Ind.x ] .R DO
IF i <- 3
Red, Gr.en, Blue )
THEN S.tColorMap( i ,
ELSE SetColorMap( i + 1, Red, Gr.en, Blu. ) I
END { for }
ColorMaplnd.x .- ColorMaplnd.x - 11
IF ColorMaplnd.x (. 0
THEN
ColorMaplndex I - MaxColor - 2; {Wrap around}

A-39

{

Skip over 4 )

THE BATON. PAS FILE
IF ( Titl.ID • TITLE2 ) AND ( Titl.Count.r < 1000 )
THEN
BEGIN < So the W.lcom. title is up (must b. the first time we'y. run) }

IF Titl.Count.r • 1000
THEN
BEGIN < Th. W.lcome Titl.'s tim. limit ~1000 cycles) has
< .xpir.d, .0 chang. the title to the normal title.
< loops takes 30-40 s.conds.)
R••dM••••g.( TITLE, Titl.L.ngth, Titl.T.xt );
PVD.t.ch; < Fr •• the t.rminal/keyboard for Synergy}
WITTL( XSt.tus, Titl.L.ngth, Titl.T.xt);
KBASTInitializ.;
END < th.n } I
END

}

(1000 )

< Set the new title}

< G.t the terminal/keyboard back}

< then } ;

UNTIL Don.;

< Don. is •• t to Tru. wh.n MAIN SCREEN or EXIT are pr •• s.d }

Cl.anUpSynj

< Tidy up .ft.r our.elve., and tell Synergy we're done}

< Once .11 this i. don., wh.n the -END.- i. r.ached b.low, PRO/Pascal will
< termin.te the running of this ta.k. Since this is the first and only
< t.sk in the applic.tion, when it t.rminat •• , the Synergy Window Manager
< will be notified by P/OS. Control will thus pa.s back to the Synergy
< Main M.nu (Window Man.g.r), re.dy for another application to be run.
END

}

< eaton } •

A-40

}
)
}
}
}

THE GIDISOPS.PAS FILE

A.a

THE GIDISOPS.PAS FILE

{ GIDlSOPS.PAS

}

C(l\IST
{
{

Fir~t.

~ll of the PRO/GIDIS
in \,)2.0 of PRO/GIDIS.

d~fin~

impIem~ntl!.'d

Begin_Define_Character
Eh'9i n_.F i.ll ed_I"" i 91.11' II'
Cnllate_Alphabet

Draw_Arcs
Draw_Charillcters
Draw_Lines
Draw_Piilck.d_Chal'act'1'l's
Draw_Rel_Arcs
Draw_Rel_Lin"'5End Define Character
End=Filled=Figure
Eno_Li 1St
End_Pi c:uJre
Erase_Clipp in 9_R4!'gion
Flush_Buffer
In it i ilIl i z e
lOlid_By_NiIII'IlE'

Load_ChanKter _Cell
New_Picture
NOP
Print_Scrll'en
Request_CeIl_Standard
Request_Current_Position
Request_Output_Size
R4I>quest_Status

R4i'quest_Version_Number
Scroll_Clippin9_Region
S6>t_Alphabet
Set_Area_Cell_Siz.
Set_Area_TE!xture
S~t_Area_T~xtur~_Size

Set_Cell_Display_Size
Set_C~ll_Explicit_Hov~ent

Set_Cell_Mov~ent_Mode

in~truction

op-code~

'" 8452;
'" 7936;
'" 11780 i
5888;
-< Plus length }
"" 8960;
-< Plus length }
{ Plus length }
'" 6400;
.. 18944; { Plus length }
{ Plus length }
6912;
{ Plus length }
'" 6656;
9216;
8192;
.. -32768;
'" 6144;
12288;
7168;
"" 257;
lC
9474;
8704;
{Plus length }
.. 1536 i
'" 0;
'" -29434;
13824;
= 14080;
14592;
'" 14848;
"" 18176;
.. 13314;
"' 97:.29!
.. 17666;
.. 3586;
'" 770;
.. 10242;
"" 10498;
'" 10753j

A-41

that are

}
}

THE GIDISOPS.PAS FILE
Set_Cell_Oblique
• 16641;
., 11009;
Set_Cell_Rendition
Set_Cell_Rotation
• 1126:5;
., 11522;
Set_Cell_Unit_Size
Set_Color_Map_Entry
• 4102;
Set_GIDIS_Output_Space
., 2308;
Set_line_Texture
.. 43:55;
Set_Output_Clipping_Region ., 1028;
Set_Output_Cur.oT
.. 1286;
Set_Output_Cur50r_Rendition ., 18433;
Set_Output_IDS
.. 3074;
Set_Output_Rubber_Band
.. 135711
Set_Output_Viewport
.. 3332 1
Set Pixel Si ze
• 4868;
.. ~121;
Set::::Plane::::Mnk
Set_Potoition
• 7426;
Set_Primary_Color
• 5377;
Set_Rel_Po.ition
.. 7682;
Set_Secondary_Color
.. 38411
Set_Writing_Mode
• 5633;

}

IO_WAL.
IO_WSD
MaxASCI I
MaxGIDIS
Max Queue
QICJ..I
QICJ..I_L.en
SD_GDS
StringMax

.. nO'410'1
{I/O function code, ASCII (text-mode) QIO. }
• nO'5410'1 {I/O function code, GIDIS (graphic.) QID. }
• 100; {Size of the ASCII (text-mode) QIO buffer (byte.) }
.. 100; {Size of the GIDIS (graphic.) QIO buffer (byte.) }
.. 80;
{Size of the private AST-driven input buffer}
• 3;
{Directive Identification Code for QICJ..I directive}
.. 12;
{Length of QIO Directive Parameter Block}
.. 11
{Special data type for IO.WSD .ignifying GIDIS }
.. 801
{U.ed to allocate character array. }

A-42

THE GIDISOPS.PAS FILE
TYPE
CharCel1

• ARRAY [ 1 .. 16 ] OF Integerj

Quttue

• RECORD

{Holds GIDIS char

cell~

{ Structure of the priYate, AST-driYen >
{ input buffer that modules KBSERV.HAC >
Last I
{
and GETAKEY.HAC manage.
>
Count: InteglHI
Data: PACKED ARRAY [ 1 .• MaxQueue ] OF Chari
END { Queue } j
Fir~t,

.. PACKED ARRAY
5tringType

1 .. StringHax ] OF Char;

= RECORD
L:

1 n t eger ;

5: String;
END { StringType }

{ Structure that contains}
{ a string with a counted}
{ length.
}

StringArray
= ARRAY [ 1 .. 99 ) OF 5trin9Typej
{ Array of arbitrary len9th used to declare some [Unsafe) parameters.
~ritingModes

= ( Transparent, TransparentNegate,
Comp 1 emen t ,
Overlay,
Replace,
Erase,
NoMode );

QIOdpbType

ComplementNe9ate,
OverlayNe9ate,
ReplaceNegate,
EraseNegate,

= PACKED RECORD

D_CODE: [Pos(O,O)]
D_LGTH: [Pos(1,O)]
Q_IOFN: [Pos(2,0)]
Q_IOLU: [Pos(4,O)]
Q_IOEF: [Pos(6,0)]
Q_IOPR: [Pos(7,O)]
Q_IOS8: [Pos(B,O),Unsafe]
Q_lDAE: [Pos(10,O),Unsafe]
Q_IOPL: [Pos(12,O) ,Unsafe)
END { QIOdpbType } i

A-43

}

{ List of the
}
{ supported GIDIS }
{ writing modes. }

{ Directiye
}
0 •• 255j
{Parameter block}
O .. 255j
{ f o r the Queue
}
Unsi9ned; { I/O Request
}
Unsigned; { (QIO/QI~) P/OS }
0 •• 255;
{ExecutiYe
}
0 .. 255;
{Dir.ctiye~.
}
Unsigned,
Unsignttdj
ARRAY ( 1 •• 6 ] OF Unsigned!

THE GIDISOPS.PAS FILE

< HeTe aTe definitions fOT a laTge numbeT of geneTal-puTpose pToceduTes, most}
< of which aTe Telated to doing video output using the PRO/GIDIS inteTpTeteT. )
[ExteTnal] PROCEDURE FlushASCII; EXTERNAL;
[ExteTnal] PROCEDURE StoT~SCII( Count: IntegeT;
VAR Data: [ReadOnly,Unsafe] StTing ); EXTERNAL;
[ExteTnal] PROCEDURE FlushGIDIS; EXTERNAL;
[ExteTnal] PROCEDURE StoTeGIDIS( Count: IntegeT;
VAR Datal [ReadOnly,Unsafe] StTing ); EXTERNAL;
[ExteTnal] PROCEDURE SoundSell; EXTERNAL;
[External] PROCEDURE PUtChT( ChI ChaT ); EXTERNAL;
IntegeT;
[External] PROCEDURE PutStTing( length:
VAR ChaTS: [ReadOnly,Unsafe] StTing ); EXTERNAL;
[ExteTnal] PROCEDURE SetPosition( X, YI IntegeT ); EXTERNAL;
[ExteTnal] PROCEDURE DTawline( X, Y: IntegeT ); EXTERNAL;
[ExteTnal] PROCEDURE DTawRelLine( X, YI Integer ); EXTERNAL;
[External(SORB)] PROCEDURE SetOutputRubbeTBand( BandType,
BaseX, Sa~eY: IntegeT ); EXTERNAL;
[ExteTnal] PROCEDURE SetWritingMode( Model WTitingModes ); EXTERNAL;
[ExUTnal(SCME)] PROCEDURE SetColorMapEntTy( Map, Indn, R, G, B,
Mono: IntegeT ); EXTERNAL;
[External] PROCEDURE SetAlphabet( WhichAlphabet: Integer ) j EXTERNAL;
[External] PROCEDURE SetCellRendition( Rendition: Integer ); EXTERNAL;
[External] PROCEDURE SetPTimnyColoT ( ColoT: In tegeT ) j EXTERNAL;
[Ex ternal J PROCEDURE SetSecondaTyColor( ColoT: IntegeT ); EXTERNAL;
[External] PROCEDURE SetPixelSize( Width, Height, XOffset,
YOffsetl [Unsafe] IntegeT ); EXTERNAL;
[External] PROCEDURE SetOutputClippingRegion( UppeTLeftX, UppeTleftY, Width,
Heightl Integer ); EXTERNAL;
[ExteTnal] PROCEDURE ETaseClippingRegion; EXTERNAL;
[ExteTnal] PROCEDURE 8eginfill; EXTERNAL;
[ExteTnal] PROCEDURE Endfill; EXTERNAL;
[ExteTnal(CT~lp)] PROCEDURE CTeat~lphabet( Width, Height, Extent,
WidthType: Integer ); EXTERNAL;
[ExteTnal] PROCEDURE LoadChaTicteTCell( Index, Width, Height: IntegeT;
VAR RasteTI [ReadOnly,Unsafe] ChaTCe11 ); EXTERNAL;
[ExteTnal] PROCEDURE SetAreaTexture( Alphabet: Integer;
Indexl [Unsafe] Integer ); EXTERNAL;
[External(SCDS)] PROCEDURE SetCellDisplaySize( Width,
Height: Integer ); EXTERNAL;
[External(SetUni)] PROCEDURE SetCellUnitSize( Width,
Height: Integer ); EXTERNAL;
[External] PROCEDURE DrawArc( X, Y, Angle: Integer ); EXTERNAL;
[External(DRARC)] PROCEDURE DTawRelArc( X, Y, Angle: Integer ); -EXTERNAL;
[External] PROCEDURE SetColoTMap( Index, Red, Green, Blue: Integer ); EXTERNAL;
[External] PROCEDURE EmptyQueue( VAR Que: Queue ), EXTERNAL;
[External] PROCEDURE AddToQueue( VAR Que: Queue, ChI Char ); EXTERNAL;
[External] PROCEDURE RemovefromQueue( VAR Que: Queue; VAR ChI Char ) j EXTERNAL;

A-44

THE SYNERGY.PAS FILE

A.4

THE SYNERGY. PAS FILE

{ SYNERGY,PAS

}

CONST
DescriptorLength
32;
MaxContext
:: 32;
MaxTBFSi ze
.. 80;
{
{
{
{
{
{
{

{ Length of iii window descriptor block (bytes) }
{ Size of Synergy Cont@xt Block (bytes) }
{ Size of the Synergy typeahead buffer HITBF }

These are the GIDIS _lphabet numbers for the pr.-Ioad.d fonts that
Synergy provides.
Your application can to _ GIDIS SET_ALPHABET
instruction specifying one of thes. numbers, and then do DRAW_CHARACTERS
and DRAH_PACKED_CHARACTERS instructions to display the normal ASCII,
DIGITAL Multinational, and VT100 Special Graphics characters on the
screllm (the ASCII, Multinational and Line Drawing charactll.'rs arE' all
folded together into each of the fonts 9 to 14).

HI.Special
HI.Dim
HI$Normal
WI.Sold
HI.Underline
WI.SoldUnderline
HI.Soxed

}
}
}
}
}
)
}

= 7;
= 9;
• 10;
= 11;
= 13;
== 14;
z 15;

{ These are the values for the Tel"mi nat i CHI Keys that iii program passes to
}
{ Synergy in II Tlitrmination Key List, and the valulits that -Synergy rlitturns as }
{ KeyPressed values.
}

PV$RET .. 269;
PV$FND .. 513;
Pl.nSEL :: 516;
Pl.nBRK "" 525;
PV$RES III 530;
Pv.Fll .. 535;
PV$HLP .. 540;
Pl.nF17 .. 543;
PVf.PFl .. 547;
Pv.UP '" 551 ;
PV$COH '" 555;
PV$O
559;

PV$4
PV$8

.. 563;

'" 567;

Pl.nINS '" 514 ;
PV$PRE
517;
PV$SET '"' 526;
Pv.CAN .. 531;
PV$F12 '" 536;
Pv.DO '" 541;
PVSF18 .. 544;
F\.I$PF2 Ill: 548;
PI.n~ '" 552;
PV$HIN .. 556;
PV$l
560;
.. 564;
Pv.5
.. 568;
Pv.9

PV$REM '" 515;
PV.NEX "-518;
PV$F5 .. 527;
PlJt.HAI '" 532;
PV$F13 .. 537;
Pv.Fl9 '" 545;
PV$PF3 "" 549;
PVt.!UT .. 553;
PV.PER '" 557;
RV$2
.. 561;
.. 565;
Pv.6
Pv.DEL '" 569;

A-45

Pl.nINT "" 529;
PV$EXI == 533;
Pv.ADD .. 538;
PVSF20 .. 546;
PV$PF4 .. 550;
Pv.LEF .. 554;
Pv.ENT '" 558;
.. 562;
PV$3
PV.7
'" 566;

THE SYNERGY.PAS FILE

TYPE
StatusBlock
= ARRAY [ 1 •• 2 1 OF IntegeTj
{ TWO-WOTd array that success/failure status information is returned 1n
{ from the various Synergy service calls.
WindowDescriptor • RECORD
10:

}
}

{Thi~

is a Synergy Window Descriptor Black}
[Pos(D,D)]
Integer;
Xl
[Pos(2,0)]
Unsigned;
VI
[Pos(4,0»)
Unsigned;
Width:
[Pos(6,O)]
Unsigned;
Height:
[Pos(B,O)]
Unsigned;
flags:
(Pos(lO,O)] PACKED RECORD
Stackable:
[Pose 0)] Boolean;
Titled:
[Pose 1)] Boolean;
Hidden:
[Pose 2») Boolean;
COIOT:
[Pose 3») Boolean;
WhiteBorder:
[Pose 4)] Booleanj
ClearOnChange: [Pose 5)] Boolean;
Unused6:
[Pose 6») Boolean;
VT100_Style:
[Pose 7)] Boolean;
Invisible:
[Pose 8») Boolean;
Unused9:
(Pose 9)] Boolean;
ThreePlane:
[Pos(10)] Boolean;
Unused11:
(Pos(ll)] Boolean;
Unu~ed12:
[Pos(12)] Boolean;
Unusedl3:
[Pos(l3)] Boolean;
Unused14:
[Pos(14)] Boolean;
Unusedl5:
[Pos(15)] Boolean;
END { Flags } ;
MinWidth:
[Pos(12,O)] Unsigned;
MinHeight:
[Pos(14,O») Unsigned;
MaxWidth:
[Pos(16,O)] Unsigned;
MaxHeight:
[Pos(18,O)] Unsigned;
XOffset:
[Pos(20,O») Unsigned;
VOffset:
[Pos(22,O») Unsigned;
fr8meWidth:
[Pos(24,O)] Unsigned;
Fr8meHeisht: [Pos(26,O)] Unsigned;
OwnerTasklD: [Pos(28,O)] ARRAY [ 1 •• 2 ] OF Unsigned;
END { WindowDescriptor } I

WordArray
{

= ARRAY [ 1 •• 99 ] OF Inteser;

Used in miscellaneous places where arrays of

{used.

indeterminant size are
}
This is made possible through the PRO/Pascal [Unsafe] attribute. }

A-46

THE SYNERGY.PAS FILE

WOesdModel • WindowOescriptor( 0, 0, 0, 0, 0, ( 16 OF False ),
0, 0, 0, 0, 0, 0, 0, 0, ( 0,
)1
< This may be used in an assignment statement to fill in all the fields}
< of a window descriptor block- in one fell swoop.
}

°)

WITBF: [External) RECORD
MaxSize:
Integer;
CurrentLength: Integer;
Characters:
PACKED ARRAY
1 •• MaxTBFSize] OF Chari
END < WITBF } ;
< Oefinition of the Syn~rgy-provided type-ahead buffer that is used to
< pass read-ahead characters from the application to Synergy and back.
ActualVersion,
ColorWindows:
integer;

< Returned from WIINI }
< Returned from WIINI }

CharacterH.ight: [External(CHARHI») Unsigned;
[Externill(CHARWI)] Unsigned;
CharilcterWidth:
Pix.1Height,
PixelWidth,
ScreenWidth,
ScreenHeight:
Unsigned;

< Returned from WIINI }
< Returned from WIINI }
< Returned from WIINI }
< Returned from WIINI }

A-47

< Returned from WIINI }
< Returned from WIINI }

}
}

THE SYNERGY.PAS FILE

PROCEDURE WIINI( VAR Status:
Statuli>Slock;
VAR Expect~dVersion: [Re.dOnly) Integer;
Intli!'g4l'rj
VAR ActualVersion:
VAR ContextLength:
InHtger;
[Unsafe]
String;
VAR ContextBlock:
VAR ScreenWidth:
Unslsnedj
VAR Scre.nHeight:
Unsigned;
Unsigned;
VAR CharacterWidth:
VAR CharacterHei9ht:
Unsisned;
VAR PixelWidth:
Unsi gned;
Unsigned;
VAR PixelHeisht:
VAR ColorWindows:
Integer ); SEQll;
PROCEDURE WIDON( VAR Status:
StatusBlock;
VAR ContextLenstht [ReadOnly]
Integer;
VAR ContextBlock: [ReadOnly,Unsafe] String ); SEQll;
PROCEDURE WIINT( VAR Status:
VAR WhyChanse:
VAR WindowID:
VAR NewWi dth I
VAR NE'WHei Stlt I

StatusBlock;
Integer;
Integer;
lntegll!'rl
Integer ); SEQll;

PROCEDURE WICRW( VAR Status:
StatusBlock;
VAR DescriptorLensth: [ReadOnly} Intll!'ger;
VAR Descriptor:
WindowDescriptor ); SEQll;
PROCEDURE WIDSW( VAR Status:
Statuli-Slock;
VAR WindowlD: [ReadOnly] Integer ) j SEQll ;
StiltusBlock;
PROCEDURE WIGEW( VAR Status:
VAR DescriptorLength: [ReadOn)y] Intlt9~1!'T ;
WindowDel>criptor
VAR Del>criptol'I

) ;

SEQll;

StatusBloc::kj
In tl!.'gfl'r j
WindowDescriptor

) ;

SEQll ;

PROCEDURE WISWP( VAR Status:
VAR DescriptorLength:
VAR Ottscriptorl

[f~eadOn 1 y ]

PROCEDURE WITTL( VAR Status;
StiltusBlockj
VAR TitleLength: (R~.dOnly]
Integer;
VAR TitleText:
[ReadOnly,Unsafe) String ); SEQ11,

A-48

THE SYNERGY.PAS FILE
PROCEDURE WIERW( VAR Statu$:
VAR l~nll [R.~dOnly]
VAR Msgl: [R~adOnly.Un$afe]
VAR L~n2: [Re.dOnly]
VAR Msg2: [R.adOnly,Unsafli']
VAR Len3: [Rli'illdOnly]
VAR Msg3: [R.adOnly,Unsafe)
,JAR Lfl'n4: n~.• lIIdOnly]
VAR Msg4: [ReadOnly,Unsafe]
VAR LenS: [Rl!'adOnly]
VAR Mli>g5: [RllIllldOnly,Unsafe]

Statu.Block;
Integli'rj
String;
Integerl
String;
Integer;
String;
Integ4L'r;
String;
Integ4L'rj
String ); SEQll;

PROCEDURE OPENME( VAR Status:
VAR Fil.versionNumberl [ReadOnly]
VAR F"iler·"'fi •• Len9th:
[ReadOnlyJ
VAR F ill!n lIIme I
[ReadOnly,Unsafe]

Status.Bloc:k I
Integer;
Integer;
String ) j SEQll;

PROCEDURE WIRMS( VAR .Status:
VAR LineCount:
VAR Lin.Offsets:
\JAR MessageBuffer:
\JAR FrameID:
VAl'. BufferSize:

StatusBloc:kj
Integer;
[ Unsafe]
i-lordArraYi
[Unsafe]
String;
[Rl?adOnly] I na'ger;
[RIPaldOnl y] Integli'r ); SEQll;

PROCEDURE WIXPS( VAR Statuf>:
\JAR KeyPrE'ssed:
\JAR NumChanged:
\JAR ChangedValuE!s:
VAR Fr&me-ID:
VAR NumEntries:
VAR EntrylClass:
\JAR EntrylValue:
VAR EntTy2Clafos:
\JAR En tTy2'v'alul?;

StatusBloc:k;
I n tI!~ger ;
Integer;
[ Unsah']
i-lordArray I
[Rl?adOrrly) Integer;
[ReadOnly] Intli'geT;
[ReadOnly] Integer;
Integer;
[ReadOnly) Integer;
Integer ) ; SEQll ;

StatusBloc:k;
PROCEDURE EXMESS( \JAR Status:
I n ulger;
\JAR KeyPrllPs .... d:
[Re.dOnly) Integer >; SEQll;
\JAR H4tnuID:
StatusBloc::k;
PROCEDURE EXFLOW( \JAR Status:
Integer;
\JAR K&>yPressed:
Integer;
\JAR HenuID:
Inu,g4!'r i
\JAR OptionValue:
\JAR Fr&meID:
[ReadOnly] IntegE'rj
\JAR InitialLeaf: [ReacOnly) Integer ); SEQll;
PROCEDURE EXHELP( VAR Status:
StatusBlock;
lJAR FramelD: [ReadOnly] Integer ) j SEQll;

A-49

THE GIDIS.PAS FILE

A.S

THE GIDIS.PAS FILE

MODULE GIDISI
~lnclude
~lnclud.

'GIDISOps/NoList'
'Syn.rgy/NoList'

< Cont.ins d.cl.r.tions needed for GIDIS routine~ }
< Cont.ins d.cl.r.tions for Syn.rgy s.rvices
}

CONST < Structur.d const.nt. )
QlOdpbMod.l • QIOdpbTyp.( Qlew, Qlew_L.n, IO_WSD, 5, 1, 0, 0, 0,
( 0 , 0 , 0 , SD_GDS, 0, 0) )j

VAR
XCh.r.cterHeight: [Glob.l(CHARHI)] Unsigned;
XCh.r.ct.rWidth:
[Global(CHARWI)] Unsigned;

< Return.d by WIINI }
< Returned by WIINI }

ASCIIBufferl [Glob.l] PACKED ARRAY [ 1 •. M.xASCII ] OF Char;
GIDISBuff.r: [Glob.l] PACKED ARRAY [ 1 •• M.xGIDIS ] OF ChaT;
< Th. two output buff.rs us.d by the routin.s in this module to do th.iT
< stuff. Th. output i. buff.r.d (QlO. don. wh.n buff.T fills, buff.T
< th.n ~pti.d) in oTder to get incr •••• d vid.o p.rform.nce.

}
)
}

ASCllQIOdpb: [Glob.l,Vol.tile] QIOdpbTyp.;
QIOdpb:
[Global,Vol.til.) QIOdpbTypej
< Dir.ctiv. P.rameter Blocks used by th.s. routin.s to issue QIOW
}
< Ex.cutive Directive., to .ctu.lly c.use output d.t. to be sent from the}
< .pplic.tion task, to the P/OS T.rmin.l Subsyst~ for subs.qu.nt display.)
State: [Global] PACKED RECORD
CUTsorOn: Bool.an;
END < Stat. ) ;
KBBuf: [Ext.rnal,Volatil.] Qu.ue,
< The private AST-driven typ.-ah.ad buffeT us.d sol.ly by this
< application. Not. that it is DIFFERENT than the WITBF buff.r d.fin.d
< abov •. Our private buff.r (KBBUF) is circular, wh.reas the Syn.rgy
< buff.r (WlTBF) is lin.ar. Du. to th.ir diff.rent structure, w. cannot
< make double-duty of the Syn.rgy buff.r; thus w. cr.at. OUT own.

A-SO

}
}
}
}
}

THE GIDIS.PAS FILE

< Thi$ pToceduTe i$ automatically Tun by the PRO/Pa$cal Tun-time $y$t~
< when the pTogTam staTts up. This Toutine initializes some data
< stTuctuTe$ that the Test of this module depends on.
State.CuTsoTOn 1= False; < The gTaphics CUTSOT is initially off}
ASCIIQIOdpb
,- QIOdpbModel; < Initialize the DiTective PaTameteT }
QIOdpb
I - OIOd~lbModel;
< Blocks fOT the output QIOWs.
}
WITH OIOdpb DO
BEGIN
Q_IOPL[ 1 J I- ( AddTess( GIDISBuffeT ) )IIUnsigned;
Q_IOPL( 2 J I- 0;
< Set the length of the data to zeTO }
END < wi th } ;
WITH ASCIIQIOdpb DO
BEG-IN
Q_IOFN
I - I O_WAL ;
Q_IOPL[ 1
.- ( AddTess( ASCIIBuffeT ) ): :Unsigned;
Q_IOPL[ 2
:- 0;
< Set the length of the data to zeTO }
Q_IOPL[ 4 J I - 0;
END < wi th } ;
END

< loitializelO }

A-51

}
}
}

THE GIDIS.PAS FILE

PROCEDURE FlushG; FORWARDj
PROCEDURE FlushAj
}

BEGIN

< FlushA }

IF ASCIIQIOdpb.Q_IOPL[ 2 ) > 0
THEN
BEGIN < There is data in the buffer}
DIR$( ASCIIQIOdpb)j < Issue the directive to write text-mode }
ASCIIQIOdpb.Q_IOPL[ 2 ] := OJ < Reset the- buffer le-r.gth to zeTC' }
State.CursorOn := Falsej < This has disables the cursor}
END < then }
END

< FlushA } ;

[Global) PROCEDURE FlushASCII;
BEGIN < FlushASCI\ }
FlushGj
< Make sure any buffered GIDIS is put out first}
FlushAj
< Then flush any text-mode data}
END < FlushASCII } ;

[Global] PROCEDURE Stor.ASCII( Count: Integerj
VAR Data: [ReadOnly,Unsafe] String );

< Stor.ASCII takes the passed byte data, and appends it to the current
}
< contents of the text-mode QIOW output buffer. ~henever the buffer fills, }
< the data pending in ~e buffer is written out, and the buffer is then
}
< reset.
}

BEGIN < StoreASCII }
i

.- 0;

~ITH

ASCIIQIOdpb DO
i < Count DO < For each byte being output ..• }
BEGIN
IF Q_IOPL[ 2 ] • MaxASCII
THEN
FlushASC,I; < Buffer is full, dump it }
i .- i + 1; < Increment to next byte to store}
Q_IOPL[ 2 ]
Q_IOPL[ 2
+ 1j < Increment count of stored bytes}
ASCIIBuffer[ Q IOPL[ 2 ] ] ... Datar i ]; < Store the by te in 1 i st }
END < while} ; -

~HILE

END

< StoreASCII } I

A-52

THE GIDIS.PAS FILE
PROCEDURE FlusnG;
)

BEGIN { FlusnG )
WITH QIOdpb DO
IF Q_IOPL[ 2 ] > 0
THEN
BEGIN {Tnere i5 data in tne buffer)
DIRS( QIOdpb); {Issue tne write QIOW to GIDIS )
Q_IOPL[ 2 ] :- 0; {Reset tne buffer lengtn to zero)
END { tnen ) ;
END { FlusnG ) ;

[Global] PROCEDURE FlusnGIDIS;
BEGIN { FlusnGIDIS )
FlushA; {Hake 5ure any buffered ASCII (text-mode) data is put out)
FlusnG; {Tnen output any GIDIS data)
END { Flu5nGIDIS ) ;

[Global] PROCEDURE StoreGIDIS( Countl Integer;
VAR Data: [ReadOnly,Unsafe] String );
{
{
{
{

StoreGIDIS takes tne passed byte data, and appends it to tne current
content5 of tne grapnics-mode GIDIS QIOQ output buffer. Wneneyer the
buffer fills, tnedata pending in tne buffer is written out, and tne
buffer is tnen reset.

)
)
)
)

BEGIN { StoreGIDIS )
i

I-

WITH QIOdpb DO
WHILE i < Count DO {For eacn data byte to output ••• }
BEGIN
IF Q_IOPL[ 2 ] • HaxGIDIS
THEN
FlusnGIDISI {Buffer's full, dump it }
i I - i + 1;
{Incr.ment to next byte to store }
Q_IOPL[ 2 ) .- Q_IOPL[ 2 ] + 11 (Incr.ment count of stored bytes)
GIDISBuffer[ Q_IOPL[ 2 ) ) .- Data[ i la (Stor. the byte in list)
END ( wnile ) I
END ( Stor.GIDIS ) I

A-53

THE GIDIS.PAS FILE

}

WITH Qu. DO
BEGIN
Fir.t

L •• t

I-

Count I- 0;
END < wi th } ;
END

< EmptyQueue }

}

BEGIN < AddToQu.ue )
WITH Qu. 00
IF Count ( M.xQueue
THEN
BEGIN < The qu.u. i. not full, proc •• d )
IF L.st >- M.xQu.u.
THEN
L•• t I- OJ < Circul.r li.t; wr.p .round }
L.st
I- L•• t + 1; < Adv.nc. pointer}
Count
.- Count + 1; < Count thi. newbyt. )
O.t.( L•• t
.- Chi < Add the byte to thebuff.r )
END < th.n }
END < AddToQu.ue }
(Glob.l] PROCEDURE Remou.FromQu.u.( VAR QU.I Qu.u.; VAR ChI Ch.r

)j
)

BEGIN < Remou.FromQu.u. }
WITH Qu. 00
IF Count > 0
THEN
BEGIN < Th.r. i. d.t. in the qu.u., 9.t the n.xt byte}
th .- O.t.( First ]) < Pa •• out the olde.t byte)
IF Fir.t >- MaxQu.u.
THEN
Fir.t .- O. < Circul.r point.r; wrap around)
Fir.t .- Fir.t + 1; < Aduanc.- pointer to n.xt byte }
Count .- Count - 1; < O.cr •••• count by on. )
END < th.n } I
END

< Remou.FromQu.u. )

A-54

THE GIDIS.PAS FILE
[Global] PROCEDURE SoundB@ll;
BEGIN { SoundBell }
Stor~SCII( 1, 7)j
{Store ill ~ingle text-mode ASCII character, BELL}
Flu.hASCII; {And force it out right now}
END { SoundB@11 } ;
[Global] PROCEDURE PutChr( ChI Char );

< PutChr ~akes a character, and adds it to the GIDIS output buffer.

}

\JAR

Datal ARRAY [ 1 •• 2 ] OF Integer;
BEGIN < PutChr }
Data[ 1 ) := Draw_Characters + 1 i
< Op-code, plus pararn count of 1 }
Oata[ 2 ) := Ord( Ch );
StoreGIDIS( 4, Data);
< Send the GIDIS sequence to the output buffer}
END < PutChr } I
[Global] PROCEDURE PutString( Length:
IntegeT;
VAR Chars: [ReadOnly,Unsafe] String ) j

< PutStrins takes ill s@quence of characters, and adds them to the GIDIS
}
< output buffer (this is done with a DRAW_PACKED_CHARACTERS instruction for}
< performance sake).
}
VAR
i: I n teSt!'!' ;
Data: PACKED RECORD
ParanCour,t I [Pos(O,O» 0 •• 255;
[Pos(l,O)] 0 .• 255;
OpCode:
[Pos(2,0)] PACKED ARRAY
Text:
END { Data }

1 .• 82 ] OF Char;

BEGIN { PutString }
WITH Data DO
BEGIN
FOR i :- 1 TO Length DO {Copy in the characters to dntw }
Text[ i ] :- Chars[ i J;
OpCode
1= Draw_Pillck@d_Charillcters DIV 256;
{Compute opcode byte}
ParanCount
:= ( Length + 1 ) DIV 21
{Make ill word count, rounded up }
i I"" Length + 2;
{Count of text, plus Op-c:ode and Llmgth bytll'f. }
IF Odd( Length)
THEN
BEGIN {String being written is odd length, must make it eyen }
T.xt[ Length +.1 1 := Chr( 255); < Packed padding byte}
i ,- i + 1;
{Count the extra byte}
END ( th'm } I
StoreGIDIS( i, Data)1 < Add it to the GIDIS output buffer}
END { w.i th } I
END ( PutString } I

A-55

THE GIDIS.PAS FILE
{ The following
{ opeTations.

pToceduTe~

do a wide vaTiety of individual low-level GIDIS

}
}

[Global) PROCEDURE SetPosition( X, V: IntegeT );
\JAR

Data: ARRAV [ 1 .• 3 ] Of IntegeT;
BEGIN { SetPosition }
Data[ 1 ] :- Set_Po~ition;
Data[ 2 ] 10' X;
Data[ 3 ] :- V;
StoTeGIDIS( 6, Data );
END { SetPo~itiorl } ;
[Global] PROCEDURE DTawLine( X, V: IntegeT );
\JAR

Datal ARRAV [ 1 .. 3 ] Of IntegeT;
BEGIN { DTawLine }
Data[ 1 ] := DTaw_Lines + 2;
Datar 2 ] := X;
Data[ '3 ) := V;
StoTeGIDIS( 6, Data );
END { DTawLine } ;

{Op-code WOTd plus 2 paTams (1 cooTd paiT) }

[Global] PROCEDURE DTawRelLine( X, V: IntegeT );
\JAR

Data: ARRAV [ 1 •• 3 ] Of IntegeT;
BEGIN { DTawRelLine }
Datar 1 ] :- DTaw_Rel_Lines + 2;
Datar 2 ] .'" X;
Datar 3 ] 1" V;
StoTeGIDIS( 6, Data );
END { DTawRelLine } ;

{Op-code wOTd

\JAR

Data: ARRAV [ 1 •• 4 ] Of IntegeT;
BEGIN { DTawATc }
Datar 1 ] I - DTaw_ATc~ + 3;
Dat a[ 2 ] I - X;
Data[ 3 ] .- VI
Data[ 4 ] .- Angle;
StoTeGIDIS( 8, Data );
END { DTawATc } I

A-56

plu~

paTam~

(1 paiT) }

THE GIDIS.PAS FILE

\JAR

Data: ARRAY [ 1 •. 4 ] OF Integer;
BEGIN < Dr.wRelArc }
Data[ 1 ] :- Dr.w_Rel_Arcs + 3j
Data[ 2 ] P' Xj
Data[ 3 ] :- Yj
Data[ 4 ] :- Angle;
StoreGIDIS( 8, Data )j
END < Dr.wRelArc } I
[Global(SORB)] PROCEDURE SetOutputRubberBand( BandType,
BaseX, BaseY: Integer )j
\JAR

Data: ARRAY [ 1 •• 4 ] OF Integerj
BEGIN < SetOutputRubberBand }
Data[ 1 ] := Set_Output_Rubber_Bandj
Data[ 2 ] := BandTypej
Data[ 3 ] := BaseXj
Data[ 4 ] := BaseY;
StoreGIDIS( 8, Data )j
END < SetOutputRubberBand }

\JAR

Data: ARRAY [ 1 •• 2 ] OF Integerj
BEGIN < SetWritingMode }
Data[ 1 ] :- Set~riting_Mode;
Data[ 2 ] .- Ord( Mode );
StoreGIDIS( 4, Data );
END < SetWritingMode } ;

\JAR

Data: ARRAY [ 1 •• 2 ] OF Integer;
BEGIN < SetAlphabet }
Data[ 1 ] .- Set_Alphabet;
Data[ 2 ] :- WhichAlphabetj
StoreGIDIS( 4, Data );
END < SetAlphabet } I

A-57

THE GIDIS.PAS FILE

VAR
Data: ARRAY [ 1 •• 2 ] OF Integer;
BEGIN { SetCellRendition }
Data[ 1 ] := Set_Cell_Rendition;
Data[ 2 ] := Rendition;
Stor.GIDIS( 4, Data ) j
END { SetCellRendition }
[Global(SOHE») PROCEDURE SetColorMapEntry( Map, Index, R, G. 8,
Mono: Integer );

VAR
Data: ARRAY [ 1 •• 7 ] OF Integerj
BEGIN { SetColorMapEntry }
Data[ 1 ] := Set_Color_Map_EntrYI
Data[ 2 ] 1= Ord( Map
);
Data[ 3 1 := Ord( Index ) j
Data[ 4 ] := Ord( R
)j
Data[ 5 1 := Ord( G
);
Data[ 6 ] := Drd( B
)j
Data[ 7 ] := Drd( Mono
);
StoreGIDIS( 14, Data ) j
END { SetColorHapEntry } ;
[Global] PROCEDURE SetPrimaryColor( Color: Integer );
VAR
Datal ARRAY [ 1 •• 2 ) OF Integer;
BEGIN { SetPrimaryColor }
Data[ 1 ] := Set_Primary_Colorl
DlIIta[ :2 ] Z'" Color;
StoreGIDIS( 4, Data ) j
END { SetPrimaryColor } ;
[Global] PROCEDURE SetSecondllryColor( Colorl Integer
VAR

Datal ARRAY [ 1 •• 2 ] OF Integer;
BEGIN { SetSecendaryCelor }
Data[ 1 ] I - Set_Secondary_Color;
Data[ <2 ) P' Color;
StereGIDIS( 4, Data );
END { SetSecondaryColor }

A-58

THE GIDIS.PAS FILE
[Global] PROCEDURE SetPixelSize( Width, Height,
XOffset, YOffset:

[Un~.fe]

Integer );

\JAR
Data: ARRAY [ 1 •• 5 ] OF Integer;
BEGIN { SetPixelSize }
Data[

]

S~l't_Pixel_Sizej

Da t e [ 2 ]

: '" Wid t h ;
Data[ 3 ] := Height;
Data( 4 ] := XOffset;
Dill t a [ 5 1 : '" YOH ~e t ;

5toreGIDIS( 10, Data
END { SetPixelSize } ;

[Global] PROCEDURE SetOutputClippingRegion( UpperLeftX, UpperLeftY,
Width, Height: Integer ) j

\JAR
Data: ARRAY [ 1 .. 5 ] OF Integer;
BEGIN {
Data[
Data[
Data[
DllIta[
Data[

SetOutputClippingRegion }
1 J := Set_Output_Clippins_Regionj
2 ] := UpperLeftXj
3 ] := UpperLeftYj
4 ]
5 ]

:= Width;
: .. Hlil'i9ht;

StoreGIDIS( 10, Data ) j
END { SetOutputClippinsRe9ion }
[Global] PROCEDURE EraseClippingRegion;
BEGIN { Eras@ClippingRegion }
StoreGIDIS( 2, Erase_Clipping_R@gion );
END { EraseClippingRegion } I
[Glob~l)

PROCEDURE BeginFill;

BEGIN { SeginFill }
StoreGIDIS( 2, Begin_Filled_Figure );
END { Beginfill } ;
[Glob~l]

PROCEDURE EndFillj

BEGIN { EndFil1 }
StoreGIDIS( 2, End_filled_figure );
END { Set_Current_Position } j

A-59

THE GIDIS.PAS FILE
[Global(CREALP)] PROCEDURE

Creat~lphabet(

Width, Height, Extent,
WidthTypel Integer );

\JAR
Data: ARRAY [ 1 •• 5 1 OF Integer;
BEGIN < Creat~lphabet )
Data[ 1 ] I - Create_Alphabet;
DaU[ 2 ] I - Width;
Dat.[ 3 ] : .. Hei ght;
Data[ 4 ] I - Extent;
Deta[ 5 ] := WidthType;
StoreGIDIS( 10, Data );
END < Creat~lphabet ) j
[Global]
PROCEDURE LoadCh.racterCell( Index, Width, Height: Integer;
\JAR R.ster: [Re.dOnly,Un.afe] CharCell
\JAR
i: Integer;
Oat.: ARRAY [ 1 •• 19 1 OF Integer;
BEGIN < Lo.dCharacterCell )
Data[ 1 ] := Load_Character_Cell + Height + 2;
Data[ 2 ] : .. Index;
Data[ 3 ] I - Width;
FOR i :- 1 TO Height DO < Copy in the cell pattern data)
Data[ 3 + i ] I"' Ra.ter[ i ] j
StoreGIDIS( ( Height
2 ) + 6, Data );
END < LoadCharacterCell ) j

[Global] PROCEDURE SetAreaTexture( Alphabet: Integer;
Index: [Unsafe] Integer );
\JAR
Data: ARRAY [ 1 •• 3 ] OF Integer;
BEGIN < SetAreaTexture )
Deta[ 1 ] I - Set_Area_Texture;
Data[ 2 ] I - Alphabet;
Data[ 3 ] I - LlAND( Index, "0'377' );
StoreGIDIS( 6, Data );
END < SetAreaTexture ) I

< Only u.e low-order byte)

A-60

THE GIDIS.PAS FILE

VAR
Data: ARRAY [ 1 •. 3 ] OF Int.g.rl
BEGIN { SetCellOisplaySize }
Oata[ 1 1 I - Set_Cell_Oi~play_Size;
Data[ 2 ] 1= I-li dth;
Data[ 3 } IB H.ight;
StoreGIDIS( 6, Data ) j
END { SetCellDisplaySize }

VAR
Data: ARRAY [ 1 .. 3 ]

or Integer;

BEGIN { SetCellUnitSize }
Data[ 1 ] := Set_Cell_Unit_Size;
Data[ 2 ] := J..Iidth;
Data[ 3 ] :- Height;
StoreGIDIS( 6, Data );
END { SetCellUnitSiz. } ;

{ SetColorMap provides a easy interface to setting the Professional's color}
{map. The RED, GREEN, BLUE intensity values range from 0 (nothing) to 7
}
{ (full on).
}
VAR
Mono: Unsigned;
BEGIN { SetColorMap }

END { SetColorMap }
{ End of module GIDIS.PAS } I

A-61

THE BATONFRMS.SFF FILE
A.6

THE BATONFRMS.SFF FILE

This is actually a listing of the BATONFRMS.LST file that i-s
produced by the Frame Compiler Tool.
The line numbers and
cross-reference listing are produced by FCT.
Fi 1 e: BATONFRMS
1
2
3
4

5
6
7
8

9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

46
47
48

•!

FCT version 2.1

on 31-0ct-85 at 11:23 PM

Fr ame f i 1 e f or the Syner gy demon s t r at i on pr ogr am • Baton
Twirler".

.!--------------------------------------------------------------------First is the vector table containing the frames that the source

.!
.!

code refers to directly.

Add new frames to the end.

.TABLE
COLMSG, DEFQ,
EDIMSG, FERROR, LTHMSG, NOCOLR
NOWIND, OTSERR, OVERVW, QIXFCM, RGBMSG, TITLE, TITLE2
.

!---------------------------------------------------------------------

.!
.!

This frame contains text strings used on the Color Map window.
This frame must have EXACTLY nine (9) lines of text.

.Frame COLMSG Message
'\.$3+Edi t Colors
'\.
Choose the color to edit with the '\..32+{l}'\..32- and '\..32+{r}'\..32keys, and press '\..32+{DO}'\..32- to edit the chosen color.
'\.
(must be blank)
'\.
(must be blank)
'\.
(must be blank)
'\.
(must be blank)
'\..3+Press '\..32+{EXIT}'\..32- teo accept values.

.!--------------------------------------------------------------------This frame describes the "Color map" option on the Flow Control

Menu (which is itself stored in the frame QIXFCM).

.Frame CMHELP Help
.Home Column:Window:Off Row:Window:Off
'\.$3+Color Map'\. < INDEX
'\.
When run on a color system, the Batons are drawn
in color. Six separate colors are used, producing
a travelling ribbon with the moving Batons. You
can control the individual 6 colors that are used.
'\.
Press '\..32+{RESUME}'\.$32- to leave HELP.
.Options Rows:l
'\.
Skip
'\.
Skip
HELP index'\. > INDEX

A-62

THE BATONFRMS.SFF FILE
49

50
51
52

53
54
55

56
57
58
59
60
61
62

63
64
65
66
67

68
69
70

.!----------------------------------------------------------------------

•!

Thi s> frame? descr i b~s • Change Batons"

the flow Menu.

.Frame CQHELP H~lp
.Home Column:Window:Off RowlWindow:Off

This option displays a set-up menu that

~nables

you to change how many individual Batons there
.r~. and to change how long their tails are.

,
,

You can also prE1ss '$32+{ INSERT HERD'f>32- and '$32+<REMQ\JE}'$32to add or subtract eatons.
Press> '1I>32+{RESLHE},$32-' H' leave HELP.

. Op t ions Ro,,",'s: 1
Skip
Skip
HELP indE1x' > INDEX

,
,

71
72

73
74

.!------------------------------------------------------~-------------This is the setup menu that controls how many Batons there are.

.Frame DEFQ Setup
.Home Column:Window:Center Row:Window:Center

78
79
80

'$3+Choos. how many and Df what
'S3+size Batons you want.

.Optlons Columns:1

Number of Batons (1-10):'

1 Numeric:String

84
85
86
87

Length of tails (3-200):'

2 Nl.lmericString

Skip
Sid P

89
90

.!---------------------------------------------------------------------

92
93
94
95
96
97
98
99
100
101

.Fram~

This frame contains text strings used on the RGB color editing
window.
This frame must have EXACTLY seven (7) lines of text.

EDIMSG MessagE'

Choos. red, gr •• n, or blue with the 'S32+<I}'.32- and
'.32+{r}'.32- keys.
Use ~.32+{u}'.32- and '.32+{d}'11>32- to increase and
decrE1"'s. the RGB components.
,
(must be blank)
,
! (must be blank)
,

! (must be blank)
'$3+Pre ..., ,'!li32+<EXIT}'\,$32- to

A-63

accept value!;-,

THE BATONFRMS.SFF FILE
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

.!--------------------------------------------------------------------This HELP
is the main HELP Index for the application.
fr~e

.Fr~e INDEX Help
.Home Column:Window:Off Row:Window:Off

.Options Columns:2 Rows: 6

The Flow Menu'
Ch.nge Batons'
Line thickne ••'
Color map'

> ~PLE
> CQHELP
> LTHELP
> CMHELP

Anoth.r Topic'

> ~PLE

Empty .pacer.

Second column of entries:

More Topics'
Suspttnding'
Exi ting'
Wi ndow si ze'

> SAMPLE
> ~PLE
> ~PLE
> SAMPLE
Empty spacer.
Empty spaCE?r.

.!--------------------------------------------------------------------This framE? describes "Line thickness" on thE? Flow ME?nu.

.Fr~e LTHELP Help
_
.Home Column:Window:Off Row:Window:Off

,
The Batons are initially drawn with thin lines.
This option lets you change the pen or brush that
the lines are drawn wi tho ThE? siZE? of the brush
in X and Y can be controlled indttpendently.

Press '$32+<RESUME}'$32- to leave HELP.
.Options Rows:l
,
Skip
,
Skip
HELP index' > INDEX

A-64

THE BATONFRMS.SFF FILE
151
152
153
154
155
156
157
158
15~

160
161
162
163
164
165
166
167
168
16~

170
171
172
173
174
175
176
177
178
17~

180
181
182
183
184
183
186
187
188
18~

190
191
192
193
194
195
196
197

.!--------------------------------------------------------------------This frame contains text strings used on the Line Thickness

window.

This frame must have EXACTLY nine (9) lines of text.

.frame LTHMSG Message
Use the arrow keys to change
the line thickness:

,
! Space for picture.
'.4+Short
'.32+<u}'.32'.4+Narrow'.4- '.32+<1}'.32- '.32+<d}'.32- '.32+<r}'.32- '.4+~ide
'.4+Tall

'.3+Press '.32+<EXIT}'.32- to accept values.

.!--------------------------------------------------------------------This message frame must contain two lines of text; they can be

.!
.!
.!

at most 40 printing characters long (80 total). The lines are
displayed in an error window by the FataIError() procedure.

.frame fERROR Message
.!34567890123456789012345678901234567890
This application has encountered
the following unexpected problem --

Ruler for 40 columns.

.1--------------------------------------------------------------------This message is displayed if the user chooses the ·Color map·

option on the Flow Control Menu, when color is not available.

.Frame NOCOLR Message
.Home Columnl~indowlCenter RowlWindowlCenter
.Keys RESUME, RETURN, DO, ENTER
Because your system is not running in color
right now, you cannot manipulate the color
map.
If your Professional does have an EBO
option and a color monitor, and you want to
use color, tell Synergy by pressing '.32+<SETUP}'.32from the Synergy Main Menu.

Press '.32+<RESUME}'.32- to continue.

A-65

THE BATONFRMS.SFF FILE
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
2~2

.!--------------------------------------------------------------------This message frame must contain one line of text; this line can

.!
.!
.!
.!

be at most 40 printing characters long (80 total). The line is
displayed in an error window if the program cannot create its
main window (for any reason).

.Frame NOWIND Message
.!34567890123456789012345678901234567890
Cannot create the application window.

Ruler for 40 columns.

.!--------------------------------------------------------------------This message frame must contain one line of text; this line can

.!
.!
.!
.!

be at most 40 printin9 characters 10n9 (80 total). The line is
displayed ~n an error window if the program ever blows up with
some unexpected error fault.

.Frame OTSERR Message
.!34567890123456789012345678901234567890
Something has really 90ne wrong!

Ruler for 40 columns.

.!--------------------------------------------------------------------This HELP frame is displayed if the user presses HELP while the

.!
.!
.!
.!
.!

program is in "free-running" mode.
In this case, there is no
specific state or context that the program might give a
context-sensitive HELP frame about; so general intToductorytype HELP is given.

.Frame OVERVW Help
.Home Column:Window:Off Row:Window:Off
'S3+0verview of Baton Twirler
Welcome to the Synergy d~onstration application, Baton
Twirler. At any time while the Batons are twirling, you
can press 'S32+<F5}'S32- to t~porarily pause Baton Twirler and
return to the Synergy Main Menu (and then change the
window size or move it around). Pressing 'S32+<EXIT}'S32- will
stop Baton Twirler and return to the Synergy Main Menu.

You can also pTess 'S32+<F11}'S32-, which will display a menu of
options that enable you to modify the Batons in a variety
of ways.

Press 'S32+<RESUME}'S32- to leave HELP.
.Options Rows:1
,
Skip
,
Skip
,
Skip
HELP index' } INDEX

253

A-66

THE BATONFRMS.SFF FILE
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304

.!--------------------------------------------------------------------This is the main Flow Control Menu for the program.

.Frame QIXFCM Flow
.Home Column:ScreenlLeft Row:Screen:Top
.Options Rows:1
Personalize
.Options Columns:1
Change Batons'
Line thickness'
Color map'

Personalize Menu
2 ?CQHELP
3 ?LTHELP
1 ?CMHELP

.!--------------------------------------------------------------------This message contains exactly one line, of exactly three

.!
.!
.!
.!

characters. The characters are the labels to apply to the RED,
GREEN, BLUE color component squares that the edi ting \..'indow of
the ·Color map· option displays.

.Frame RGBMSG Message
RGB'

.!--------------------------------------------------------------------This HELP frame is just a sample.

.Frame SAMPLE Help
.Home Column:Window:Off Row:Window:Off
'$3+Sample HELP Frame' < INDEX
,
This is a sample Synergy HELP frame that shows the
sorts of things that can be done in any Synergy
frame (HELP, menu, setup, etc.). First, here's a
sample use of the DEC Multinational (~_~aeiou) and
Special Graphics characters <X80><PU1><VTS><PLU><PU1><X80) that are
available in the Synergy fonts.
,
Here i!O a sample use of renditions: You can use
'$3-Dim'$1+, Normal and '$3+bold'$2- intensities plus '$8+underline'$8-,
'$4+Italic'$4- and '$16+ Hilight '$16- for emphasis, and for
keyboard function key notation the '$32+<BOXED}'$32- font.
,
Press '$32+<RESUME}'$32- to leave HELP.
.Options Rows:1
,
Skip
,
Sk ip
HELP index'
> INDEX

A-67

THE BATONFRMS.SFF FILE
305
306
307
308
309
310
311

.!--------------------------------------------------------------------.!
This message line is the title for the main program window.
.Frame TITLE ME!'ssage
Baton Twirler'

312

313
314

!---------------------------------------------------------------------This message line is the secondary title for the main program

315
316

317

318

319
320
321
322

window. This title is only used th@ VERY first time the
application is run, and then ONLY for the first thirty seconds
or so that the program runs; ",fter that time is up, the program
changes the title to use the text in frame TITLE (above).

. Fr ame T I TLE2 MessagE.'
Baton Twirler (press HELP for details)'

**** No errors.
**** 8 blocks in BATONFRHS.OFF.
**** 18 frames.
Cross Reference listing_

LINE
34

17
54
76
93

175
107
136
157
186
206
218
231

fRAME

Referenced from line/frame.

CHHELP
COLHSG
CQHELP
DEFQ
ED It1SG
FERROR
INDEX

119/INDEX
9/.TABLE
117/INDEX
9/.TABLE
9/.TABLE
9/.TABLE
37/CHHELP
I50/LTHELP
11S/INDEX
9/.TABLE
9/.TABLE
lO/.TABLE
lO/.TABLE
10/.TABLE
10/.TABLE
lO/.TABLE
116/INDEX
128/INDEX
lO/.TABLE
lO/.TABLE

LTHELP
LTHMSG
NOCOLR
NOWIND
OTSERR
OVERIv'~~

258
276
283

QIXFCt1
RGBHSG
SAMPLE

310
321

TITLE
TITLE2

267/QIXFCM
265/QIXFCM

48/CHHELP
252/OVER'M

57/CQHELP
28G/SAMPLE

70/CQHELP
304/SAMPLE

139/LTHELP

125/INDEX

l26/INDEX

127/INDEX

266/QIXFCM

121/INDEX

A-68

THE BATON.CMD FILE

A.7

THE BATON.CMD FILE

Task builder Command (.CMD) File for the sample Synergy program.
The first line tells PAS to create the task image file with checkpointing
enabled and floating point context space allocated (both of which you almo5t
ALWAYS want). The details of the task structure ~re contained in the .DDL
file, referenced by the /MP ~itch.
Baton/CP/FP = Baton/MP
We can give the eventual running task any name we want. This name can be
used by other tasks running under P/OS to communicate with our task.
Task

= BATON

PRO/Pascal does not use the conventional RSX-llM-PLUS (and thus P/OS) area of
the task reserved for stack space usage.
Rather, it allocates the stack
itself in the PSECT $SDAT$. Thus it would be wasti.,g address space for us to
allocate room to the P/OS default stack (PAS defaults to 256 words).
Allocating zero words would be risky though, since Pascal DOES use the
default stack momentarily until its run-time system is initialized.
Stack

This task needs the PRO/Pascal run-time system (PASRES), which in turn needs
the Record Management Services library (RMSRES). At our option we have
included the DECnet extensions to RMS (DAPRES) to support remote file access.
CLSTR

= PASRES,RMSRES,DAPRES:RO

The following line modifies a part of the PRO/Pascal run-time system. As
described above, the Pascal Stack (containing subroutine linkage and local
variable ste,rage) is allocated in the $SDAT$ PSECT. Normally, the Pascal
Heap (containing dynamic memory from NEW/DISPOSE, file I/O buffers, etc.) is
automatically allocated at run-time by extending the task address region
(with EXTKf> directives).
But this requires a checkpoint operation whenever
the task is extended, and checkpointing is slow.
So we can ask PRO/Pascal
not to ever extend the task, and instead use the bottom portion of the stack
space (the $SDAT$ PSECT) to double as the heap.
CAUTION: If )Jou ever do
this, MAKE SURE you have allocated a largE? enough $SDATf> PSECT!
This usually
takes some trial and error to allocate enough space (but if you allocate lots
of extra room to be on the safe side, you use up extra address space).
GBLPAT
j

= Saton:$NOEXT:240

Lastly, define values for some global variables used by the program.

GBLDEF
GBLDEF
GBLDEF

SCRLLt-l:5
SCREFN:l
.. IDLE$:6
=:

Logical unit number for video output
Event Flag Number for video output writes.
Event Flag Number for keyboard input idles.

A-69

THE BATON.OOL FILE

A.S

THE BATON.OOL FILE

Overlay Description (.ODl) File for the sample Synergy program.
The Pascal $OOAT$ psect (where all the outer level variables live in a
program with the (Overlaid] attribute) and the Heap (where all dynamic
memory comes from) are made non-disk resident to reduce the size of the task
image file.
This is accomplished by grc.uping those modules of the program into one
segment (called OFLINE here), and including in that segment a dummy module
created with the .NAME directive (called SAVER here) that is given the NODSK
attribute. Any segment which has the NODSK attribute will not be allocated
any space in the on-disk .TSK task image file by the Task Builder. For
simplicity, this whole segment (OFLINE) is placed as a co-tree off the end of
the main .ROOT structure.
.PSECT
.PSECT
.PSECT

$ODAT$, RW, D, GBl, REL, OVR
$SOAT$, RW, 0, GBl, REL, OVR
$SDATO, RW, D, GBL, REl, OVR

Pascal Overlaid data.
Pascal stack/heap.
Top of stack/heap.

• NAME

SAVER, NODSK

Dummy module for NODSK.

; Here is the en t ire segmen t put together:

OFLINE:

.FCTR

$ODAT$ - $SDAT$ - $SDATO

- SAVER

; Here are the actual code modules for this task:
LIBS:
.FCTR
HODUlS: • FCTR

LB:[1,5]PasLib/LB - LB:[1,5]WinLib/LB
Baton - GIDIS - GetAKey - KBServ - ReadHesg

We need RHS in this task~ For P/OS V2.0 and greater, we might as well
include PRO/DECnet facilities in the task so that we could do transparent
remote file accesses if we ever worked with files. To include DECnet,
simply reference DAPRlX instead of RHSRLX, and add DAPRES to the CLSTR line
in the task builder command file.
(tlB:[l,5]DAPRLX
• ROOT

HODULS - LIBS - RHSROT, OFLINE

• END

A-70

THE BATON. INS FILE

A.9

THE BATON.INS FILE

! Syner~w/I 2
Name -eaton Twirler!

File [ZZPROVUE]SYNCHK2.TSK/Oelete
File [ZZPROVUE1SYNERR.HLP/Keep
Execute [ZZPROVUE1SYNCHK2.TSK/lns
Execute [ZZPROVUE1REMEXE.TSK/Rem
!

File BATON.TSK/Oelete
File [ZZBATON]BATONFRMS.OFF/OdeU
Execute [ZZPROVUE1INSAPP.TSK/Ins
!Install [ZZSYS1PASRES.TSK/Library
!Install BATON.TSK/Task
! Run BATON
Install [ZZPROVUE1SYNRUN.TSK/Task
Run WaMGR

A.9.l

The BATON.INB File

! Syner9y/I 2
Name -eaton TwirlerFile [ZZPROVUE1SYNCHK2.TSK/Oelete
File [ZZPROVUE1SYNERR.HLP/Keep
EXECUTE [ZZPROVUE1SYNCHK2.TSK/Ins/USR
EXECUTE [ZZPROVUE1SYNCHK2.TSK/lns
!

Execute [ZZPROVUE1REMEXE.TSK/Rem/USR
File BATON.TSK/Oelete/Network
File [ZZBATON1BATONFRMS.OFF/Oelete/Cluster
!

Execute [ZZPROVUE1INSAPP.TSK/Ins/USR
Execute [ZZPROVUE1INSAPP.TSK/Ins
!

!Install [ZZSYS1PASRES.TSK/Library
!Install BATON.TSK/Task/Network
!Run BATON
!

Install [ZZPROVUE1SYNRUN.TSK/Task/Cluster
Run WI$MGR

A-71

THE BUILD.CMD FILE

A.10

THE BUILD.CMD FILE

The Baton Twirler source files can be recompiled if you have
Version 1.2 (or later) of PRO/PASCAL installed on your Tool Kit
system. This indirect command file can be used to compile the
sources and link the result into a task image.
Indirect Command File to build the sample Synergy program.
This command file assumes that the frame file BATONFRMS.SFF has been run
through the Frame Compiler Tool to produce BATONFRMS.PAS and BATONFRMS.OFF.
(To do this, invoke FCT and specify "BATONFRMS" as the file to compile.)
You invoke this command file by typing "BUILD from PRO/Tool Kit Del.
PASCAL Baton/NoDebug/NoCheck
PASCAL GIDIS/NoDebug/NoCheck
MACRO Gt>tAKey
MACRO KBSElrv
t1ACRO ReadMesg
LINK @Bator.

A-72

APPENDIX B

APPENDIX B
TABLE OF SYNERGY SERVICES

Table B-1:

Table of Synergy Services

SYMBOL

NAME

PAGE

CLOSEM
DFLOW
DMESSA
DMULTI
DSINGL
EXFLOW
EXHELP
EXMESS
EXMULT
EXSING
MGTCB
NEWFLE
OLDFLE
OPENME
WICHW
WICOLD
WICRM
WICRS
WICRW
WIDEM
WIDES
WIDON
WIDSW
WIEF
WIENM
WIERW
WIEWT
WIGEW
WIGKM
WIGKS
WIHDR
WIHDW
WIlDA

Close Frame File
Dynamic Flow Control Menu
Dynamic Message Frame
Dynamic Multiple-Choice Menu
Dynamic Single-Choice Menu
Static Flow Control Menu
Static Help Menu
Static Message Frame
Static Multiple-Choice Menu
Static Single-Choice Menu
Expand Call-Back Code
Dynamic New File Name
Dynamic old File Name
Open Frame File
Change Size and position of Window
Get Selected File Name
Create Menu Window
Create String Editing Window
Create a Window
Destroy Menu Window
Destroy String Editing Window
Application Done
Destroy a Window
Edit String Field
Change Option in a Menu
Display Error Window
End wait Message
Get Window Parameters
Get Key from a Menu
Get Key from String Editing Window
Change Header Line
Hide a Window
ID of a Window at a Point

7-3
7-12
7-17
7-10
7-9
7-12
7 -10
7-16
7-10
7-9
4-22
7-23
7-21
7-2
6-5
7-21
7-30
7-26
6-5
7-33
7-28
5-1
6-6
7-28
7-33
6-7
6-7
6-8
7-33
7-29
7-34
6-8
6-9

B-1

SYMBOL

NAME

PAGE

WIINI
WIINT
WIPOF
WIPON
WIPOW
WIPPS
WIPS
WIRCMP
WIPSW
WIRFNT
WIRMS
WISCM
WISLW
WISWP
WISWT
WISYP
WITTL
WIXANY
WIXCHD
WIXNEW
WIXNUM
WIXOLD
WIXPS
WIXSHD
WIXSTR
WIXSWT
WIZCMP
WIZPSC

Application Initialization
Application Suspend
Turn Cursor Bar Off
Turn Cursor Bar On
Change Position of a Window
Change Cursor Bar Position
Dynamic Set-up Menu
Restore Synergy Color Map
Push a Window
Restore Synergy Fonts
Read Message Frame
Scroll Menu Options
Select' a Window
Set Window Parameters
start wait Message
Get System Parameters
Change Title of Front Window
Static Any File Name
Get Directory Name
Static New File Name
Numeric String Editing
Static Old File Name
Static Set-up Menu
Show Directory Names
Alphanumeric String Editing
Start wait with Message Frame
Zap Synergy Color Map
zap
Synergy
Primary/Secondary
Colors

5-2
5-3

B-2

7-35
7-35
6-9
7-35
7-14
4-5
6-9
4-7
7-3
7-35
6-10
6-10
6-11

5-4
6-11
7-24
7-25
7-23
7-18
7-21
7-13
7-25
7-17
6-12
4-4
4-4

Glossary

active application
The application
application.

using

the

front

window;

the

current

application
A task, or a group of closely interacting tasks.
character-passing buffer
An BO-character buffer that is passed between the window
server
and all Synergy applications, used to hold
keyboard characters that have been read but not yet
processed.
dynamic call
A calIon a Synergy service in which all
passed by parameters.

information

EBO
Extended Bitmap Option.
front window
The window that
interpreter.

addressable

through

the

GIDIS

GrDIS

Digital
on
the

Set;
a
General Image Display Instruction
supported
protocol
proprietary
graphics
Professional 300 Series.
GaS

GIDIS output Space
an isotropic mapping
coordinates used in all GIDIS instructions.

Glossary-l

screen

GLOSSARY
hardware pixel
The picture
hardware.

element

defined

the

video

display

header lines
Lines of text at the top of a window.
isotropic
Measured in equal units along the vertical and horizontal
axes.
logical pixel
A software defined picture element that is isotropic
is mapped to hardware pixels.

and

options
The items that can be selected on a menu.
owner task
The task in an application whose task name is used to
represent the owner of the windows created by the
application.
PIOS

The Professional Operating System.
positioning unit
A specified number of GOS units in both
and vertical directions,
on which a
positioned.

the horizontal
window may be

raster
A rectangular section of a bitmap display.
stackable windows
A sequence of windows defined and manipulated as a stack,
so that only the window on the front of the stack may be
manipulated.
static call
A calIon a Synergy service in which a frame 10 is a
parameter.
The frame 10 locates a frame in the frame
file that supplies most of the information needed by the
service.
stopped
A state in P/OS in which a task does not execute and does
not compete for memory.

Glossary-2

GLOSSARY
suspend
An action in which an application relinquishes control to
Synergy and does no terminal output or keyboard input
until Synergy permits it to resume.
task
The basic unit of execution in P/OS.
title line
A line of text that is incorporated into the top edge
the windowframe.

white border
An optional, narrow white area that separates
windowframe from the writable area of a window.

the

wildcard
An asterisk used in a portion of a file specification
order that matching will be bypassed on that portion.

window
A rectangular section of the screen that
can use to display information.

application

windowframe
A thin, dark line that surrounds a window on the
screen.

Synergy

window manager
A Synergy task that displays the Synergy Main Menu and
interacts with the user to control window size and
position and to start and stop applications.
window server
A Synergy task that does the actual work involved in
manipulating windows and in providing menu and HELP
services.
writable area
The area of a window
output instructions
window.

that
by

can be addressed in GIDIS
the application that owns the

Glossary-3

INDEX

ADDTNL OPTIONS key, 2-4, 2-7,
4-24, 7-11, 7-19, 7-22,
11-14, 11-17
Alphabets, 4-1, 4-5, 4-8, A-45
Alphastring menu
example, 8-23
FCT, 8-23
Any File service, 7-23
conventions, 11-6~ 11-17
APPL$DIR, 7-3
Application
abort, 2-6
active, 1-2
building, 2-9, 3-4, A-69
context, 5-1, 5-2, 11-4, A-6,
A-14, A-15
done, 1-4, A-15
exiting, 1-3, 2-16
initialize, 1-4, 5-2, A-14
installing, 1-3, 2-9, 3-4,
A-71
multi task, 1-2
removing, 1-3, 2-10
services, 1-4, 5-1
starting, 1-3, 2-14
suspend, 1-4, 3-2, 4-2, 4-3,
5-3, A-20
task names, 2-8
ARROW keys, 4-24, 11-16
AST 4 -13, 4 - 2 2
f

BINARY attribute, 8-15
Blank line in FCT, 8-9
Boxed font, 4-8, 7-6, 7-7, 11-8,
11-9, 11-11
BREAK key, 4-24
Call interface, 4-14
Call-back code, 4-21, A-2
CANCEL key, 4-24, 7-7, 7-20,
11-13

Character set, 4-10
Character-passing, 2-4, 3-1,
4-19, A-2, A-l0, A-47
Clipboard, 2-2, 3-4, 10-1
Clipping region, 4-12
Clock icon, 6-7, 6-11, 6-12,
11-2
CLOSEN, 7-3
CNTRLjC key, 2-6
Color Use, 4-4, 4-5
Color use, 1-10, 3-3, 4-3, 4-25,
5-2, 6-5, A-5, A-7, A-14,
A-17
Context block, 5-1, 5-2, 11-4,
A-6, A-14, A-15
Conventions, 11-1
Copyright notice, 2-7
CTRLjC, 11-13
DECnet, 4-16, 7-19
DFLOW, 7-12
Directory name services, 7-24
DMESSA, 7-17
DMULTI, 7-10
DO key, 4-24, 7-8, 7-10, 7-12,
7-19, 7-24, 11-10, 11-16
Documentation conventions,
11-21
DOWN ARROW key, 4-24
DSINGL, 7-9
DUMRUN.TSK, A-71
Dynamic call, 1-17, 7-4
EBO, 1-10
Edit mode
with F17 key, 11-15
ENTER key, 11-16
Error handling, 2-5, 6-7, A-9
Error returns, 4-15
EXFLOW, 7-12, A-37, A-49
EXHELP, 7-10, A-38, A-49

Index-1

INDEX

EXIT key, 2-7, 4-24, 7-7, 7-8,
7-13, 7-16, 7-24, 11-14,
11-17
EXMESS, 7-16, A-37, A-49
EXMULT, 7-10
EXSING, 7-9
F11 key, 2-4, 2-7, 4-24, 7-11,
11-14
F12 key, 2-4, 2-7, 4-24, 7-11,
11-14
F13 key, 2-4, 2-7, 4-24, 7-11,
11-14
F17 key, 4-24, 11-15
F1a key, 4-24, 11-15
F19 key, 4-24, 11-15
F20 key, 4-24, 11-15
F5 key, 2-4, 2-7, 3-2, 4-24,
4-25, 5-3, 7-7, 7-16, 7-24,
11-13
False (definition), 4-15
FCT
see Frame compiler
FDT file conversion, 3-3, 9-4
File usage
conventions, 4-22, 11-16
locked file, 4-23
names, 4-22, 11-18
type, 10-1, 11-19
Filename services, 7-18, 11-6
FIND key, 4-24, 7-19, 11-15,
11-17
Flow control menu, 2-4
conventions, 11-5, 11-7,
11-19, 11-20
example, 8-16, A-37, A-67
FCT rules, 8-15
services, 7-11
Fonts, 4-1, 4-5, A-45
boxed, 4-8
special, 4-7
text, 4-7
user-defined, 4-6, 4-26
FRAME command line, 8-4
Frame compiler

comment, 8-2
cross-reference, A-68
frame name, 8-4
language, 8-2
limitations, 8-15
object file, 8-1
operation on PRO/Tool Kit,
8-26
operation on VMS, 8-26
source file, 8-1, 8-2
with PASCAL, 8-2
Frame file
automatic close, 7-2
cross-reference, A-68
description, 7-1
from FDT, 3-3, 9-4
multiple files, 7-2
services, 7-1, A-1S
synchronization, 7-2
GIDIS
alphabets, 4-1, 7-7
color map, 4-1, 4-25
coordinates, 1-5, 1-12, 4-26,
6-2
cursor, 7-28
fonts, 4-1, 4-26, 7-7
instructions, 1-5, 1-9
output space, 1-12
pseudo coordinates, 6-2, 8-6
set-up, 4-1
state, 1-9, 4-1, 4-26
GOS
see GIDIS, output space
Hardware pixels, 1-12
HELP index, 8-20, 11-12
HELP key, 2-7, 4-24, 7-8, 7-34,
11-14
HELP menu
conventions, 2-5, 11-9, 11-20,
11-23
example, 8-21, A-38, A-62,
A-63, A-64, A-66, A-67
FCT rules, 8-20

Index-2

INDEX
placement, 11-9
service, 7-10
structure, 11-10
user types, 11-10
HELPframeID, 7-4, 8-11
HOLD SCREEN key, 4-23
HOME command line, 8-6
Horizontal tab key, 4-15
IDS, 4-12, 4-26

Initial states, 4-1
INSAPP.TSK, 2-10, A-71
INSERT HERE key, 4-24, 7-23,
11-15, 11-17
Install file, 2-9
INTERRUPT key, 2-6, 4-24, 11-13
Intertask communication, 4-12
Key codes, 4-23, 8-9, A-45
Key usage conventions, 11-8,
11-13
Keyboard, 3-1
conventions, 11-13
function key rules, 7-7,
11-13
key codes, 4-23, 8-9, A-45
keypad use, 3-2, 4-21, 11-13
set-up, 4-1
state, 4-1, 4-3, 4-21
KEYS command line, 8-9
limitation, 8-15
LEFT ARROW key, 4-24
Library
object, 2-9, 3-4, 4-14, A-70
Line-drawing characters, 4-10
Locked file, 4-23
Logical pixels, 1-12
MAIN SCREEN key, 2-7, 4-24, 7-7,
7-16, 7-24, 11-14, 11-17
Make screen white, 9-3
Menu
alphastring, 8-23
capitalization, 11-6

conventions, 11-5
definition, 1-16, 7-4
error status, 4-16
filename, 4-16, 7-18
flow control, 2-4, 7-5, 7-8,
7-11, 8-15, 11-5, 11-7,
A-37, A-67
HELP, 2 - 5, 7 - 4, 7 -1 0, 8 - 2 0,
A-38, A-62, A-63, A-64,
A-66, A-67
HELPframeID, 7-4, 8-11
HELPname, 8-11
high-level services, 7-4
message, 7-16, 11-9, A-8,
A-37, A-62, A-63, A-65,
A-66, A-67, A-68
multiple-choice, 7-8, 7-10,
8-4, 8-17
NextFrameID, 7-5, 8-11
NextName, 8-11, 8-20
numericstring, 8-23
option class, 7-13
options, 7-4, 11-6
NOCHOOSE, 7-5, 7-30, 7-35,
8-11
SKIP, 7-5, 7-30, 8-11, 11-8
OptionValue, 7-5, 7-30, 8-11
placement, 11-5
PrevFrameID, 8-11
PrevName, 8-11, 8-20
renditions, 7-6
services, 7-1
high-level, 1-16, 11-5
primitive, 1-16, 1-17, 4-16,
7-25, 7-30, 11-5
set-up, 4-16, 7-8, 7--12, 8-12,
8-15, 8-18, 9-1, 11-5,
11-6, 11-8, A-21
single-choice, 7-5, 7-8, 7-9,
8-17,11-5
spelling, 11-6
structure, 11-7
wording, 11-7
Message Board, 5-5
Message frame

Index-3

INDEX
binary type, 8-4, 8-13, 8-15,
8-22
conventions, 2-5, 11-9
display service, 7-16, A-37
example, 8-22, A-62, A-63,
A-65, A-66, A-67, A-68
FCT rules, 8-4, 8-21
in WIXANY service, 7-24
in WIXCHO service, 7-25
in WIXNEW service, 7-23
in WIXOLO service, 7-21
in WIXSHO service, 7-25
in WIXSWT service, 6-12
read service, 4-16, 7-3, A-8
MGOMS, 5-6
MGMSG, 5-5
MGTCB, 4-22, A-2
Multiple-choice menu, 7-8
example, 8-18
FCT rules, 8-4, 8-17
services, 7-10

P /05, 3 - 2, 3 - 3
Parameters
definition, xii
PASCAL with FCT, 8-2
password, 8-12
PFl key, 4-24
PF2 key, 4-24
PF3 key, 4-24
PF4 key, 4-24
Pixels, 1-12
POSRES, 3-2, 3-3
PREV SCREEN key, 4-24, 7-8,
8-20, 11-10, 11-15
PrevFrameID, 8-11
PRINT SCREEN key, 4-8, 4-23
Printing the screen, 4-8, 9-4
Property sheet
see Menu, set-up
Pseudo coordinates, 6-2, 8-6
Pseudo window, 6-4, 6-10
Raster file, 1-10, 4-16
RECEIVE DATA, 4-12
REMEXE.TSK, 2-10, A-71
REMOVE key, 4-24, 11-15
Renditions, 1-10, 4-7, 7-5, 7-6,
8-10, A-11
RESUME key, 2-5, 4-24, 7-8,

New File service, 7-22
conventions, 11-6
NEWFLE, 7-23, 11-6
NEXT SCREEN key, 4-24, 7-8,
8-20, 11-10, 11-15
NextFrameIO, 7-5, 8-11
NOCHOOSE, 7-5
see Menu, options
NOECHO, 8-11, 8-12
NOHELP, 7-5
Numericstring menu
example, 8-23
FCT, 8-23

11-13

RETURN key, 7-8, 7-10, 7-12,
11-10, 11-16
RIGHT ARROW key, 4-24
RMS 4 -16
I

Object library, 2-9, 3-4, 4-14,
A-70
OOL file, 3-4, 4-13, A-70
Old File service, 4-16, 7-19
conventions, 11-6, 11-16
OLOFLE, 4-16,7-21,11-6
OPENME, 7-2, A-1S, A-49
OPTIONS command line, 8-8
limitation, 8-15

Screen
coordinates, 1-12, 6-3, 6-9,
8-6
printing, 9-4
Scrolling menu options, 7-35
SELECT key, 4-24, 7-8, 7-10,
7-19, 11-15
SEND DATA, 4-12
Set-up
GIOIS, 4-1
keyboard, 4-1

Index-4

INDEX

text mode, 4-1
SET-UP key, 4-24
Set-up menu, 4-16
conventions, 11-5, 11-6, 11-8,
11-19
example, 8-19, A-21, A-63
FCT rules, 8-18
in VUE, 9-1
limitation, 8-15
services, 7-8, 7-12
Single-choice menu
conventions, 11-5
example, 8-17
FCT rules, 8-17
services, 7-9
Sixels, 4-8
SKIP, 7-5
see Menu, options
Stackable
see Windows, stackable
Static call, 1-17, 7-4
Status return values, 4-15
String editing
FCT rules, 8-23
high-level service, 7-17
primitive service, 7-26
Suspend, 1-4, 3-2, 4-2, 4-3,
A-20
Synergy call interface, 4-14
Synergy character set, 4-10
Synergy Interface Library, 3-4,
4-14
SYNNORMAL, 9-4
SYNREVERS, 9-4
SYNRUN, 2-11
System requirements, x
TAB key, 4-15
TABLE, 8-4
Table file, 10-1
Task build
see Application, building
Task communication, 4-12
Task control
see Application

Task names, 2-8
Termination Key List, 7-8
Text line in FeT, 8-10, 8-15
Text mode set-up, 4-1
True (definition), 4-15
Type-ahead, 2-4, 3-1, 4-19
UDK, 2-4, 4-21
UP ARROW key, 4-24
User
defini tion,· xii
User defined key, 2-4, 4-21
VDM reference, 10-2
Vector table, 8-24
VT window, 1-4, 1-11, 3-3, 4-1,
4-3, 4-4, 4-5, 6-2
VUE application, 9-1
welcome message, 2-7
WHITE application, 9-3
WI$MGR, 2-11
WICAL, 4-15
WICHW, 6-1, 6-5
WICOLD, 7-21, 7-24
WICRM, 7-30, 7-34
WICRS, 7-26, 7-29, 7-34
WICRW, 4-2, 6-1, 6-5, 6-10,
A-16, A-26, A-29, A-33,
A-48
WIDEM, 7-32
WIDES, 7-28
WIDON, 5-1, 5-2, 11-4, A-15,
A-48
WIDSW, 6-6, A-15, A-28, A-31,
A-36, A-48
WIEF, 7-28
WIENM, 7-33
WIERW, 6-7, A-9, A-49
WIEWT, 6-7, 6-11
WIGEW, 1-15, 5-4, 6-1, 6-6, 6-8,
A-15, A-20, A-48
WIGKM, 7-32, 7-33
WIGKS, 7-27, 7-29
WIHDR, 7-34

Index-5

INDEX
WIHDW, 6-6, 6-8
WIlDA, 6-9
WIINI, 5-1, 5-2, 11-4, A-14,
A-48
WIINT, 1-11, 4-2, 4-3, 4-25,
5-3, 7-32, 11-13, A-20,
A-48
Wildcard, 7-19, 11-18
Window
attributes, 1-7
clear on change, 1-8, 5-4,
6-2
color, 1-8, 6-2
conventions, 11-2
coordinates, 1-12, 6-2, 6-3,
8-6
create service, 1-6, 4-2, 6-5,
A-16, A-26, A-29, A-33
cursor use, 11-2, 11-3
definition, 1-4
descriptor block, 6-1, 6-5,
6-8, 6-9, 6-10, A-16,
A-26, A-46
descriptor block the width
and height of the
writable part, 6-S
destroy service, 6-6, A-1S,
A-28, A-31, A-36
dimensions, 1-13
error service, 6-7, A-9
error status, 4-16
frame, 1- 7, 1-13
front, 1-2, 1-5, 2-3, 4-16,
6-4
hidden, 1-8, 6-2, 6-6, 6-7,
6-8, 6-10
hide service, 6-6, 6-8
ID, 4-16, 6-4, 6-6, 6-9
invisible, 1-8
limitations, 1-10, 2-6, 4-16
location, 1-7, 1-11, 1-15,
4-16, 5-4, 6-S, 6-9, 8-6,
11-4
manager, 1-2, 6-4
next, 6-4

parameter service, 6-8, 6-10,
A-15, A-16, A-20
3-plane, 1-9
position, 1-7, 1-11, 1-15,
4-16, 5-4, 6-5, 6-9, 8-6,
11-4
pseudo, 6-4, 6-10
push service, 6-9
rear, 6-4
resources, 1-10, 2-6, 4-16
select service, 1-6, 6-10
server, 1-2
services, 1-15
size, 1-7, 1-11, 1-13, 1-15,
4-16, 6-5, 6-6, 11-2,
11-4
stackable, 1-7, 4-25, 6-2,
6-5, 6-8, 6-9, 6-10, 7-27,
7-31
tiling, 1-6
title, 1-7, 1-13, 4-16, 6-2,
6-11, 11-2, A-16, A-40
VT, 1-4, 1-8, 3-2, 4-1, 4-3,
4-4, 4-5, 6-2
wait message, 6-7, 6-11, 6-12
white border, 1-8, 1-14, 6-2
whole screen, 6-4
windowframe, 1-7, 1-13
writable area, 1-7, 6-2
WINDOW command
in FDT, 9-4
WINLIB, 2-9, A-70
WIPOF, 7-34
WIPON, 7-34
WIPOW, 6-1, 6-9
WIPPS, 7-32, 7-34
WIPS, 7-14
WIPSW, 6-9
WIRCMP, 4-S
WIRFNT, 4-7
WIRMS, 4-16, 6-12, 7-3, 7-16,
A-8 f A-49
WISCM, 7-33, 7-35
WISLW, 6-4, 6-6, 6-8, 6-10

Index-6

INDEX
WISWP, 6-1, 6-6, 6-10, A-16,

A-48
WISWT, 6-11, 6-12
WISYP, 5-4
WITBF, 4-20, A-l0, A-47
WITTL, 6-11, A-16, A-40, A-48
WlXANY, 7-24, 11-6
WIXCHD, 7-25
WIXNEW, 7-23
WIXNUM, 7-18
WIXOLD, 7-21

WIXPS, 7-13, A-21, A-49
WIXSHD, 7-25
WIXSTR, 7-17, 7-18
WIXSWT, 6-12
WIZCMP, 4-4
WIZPSC, 4-4

<X] key, 4-24, 11-16
ZAP, 9-4

Index-7

READER'S COMMENTS

Synergy
Programmer's Manual
Order No. AA-EU61A-TH

NOTE: This form is for document cOmments only. DIGITAL
will use comments submitted on this form at the company's discretion. If you require a written reply and
are eligible to receive one under Software Performance Report (SPR) service, submit your comments
on an SPR form.
Did you find this manual understandable, usable, and well-organized?
Please make suggestions for improvement.

Did you find errors in this manual? If so, specify the error and the page number.

fI)

£
Ol

"iii

:5
u
Q)
fI)

a::

Please indicate the type of reader that you most nearly represent.
Assembly language programmer
o Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
o Other (please specify) _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __

o
o
o
o

Name ________

________________ Date ____________

Organization _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
Street ______________________________________________
City _ _ _ _ _ _ _ _ _ _ _ _ _ _ State ________ Zip Code - - - - - - - - or
Country

I
I
I
I

Do Not Tear - Fold Here and Tape __________________________________________ 1

mamaa D

11111

No Postage
Necessary
if Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

Professional 300 Series Publications
DIGITAL EQUIPMENT CORPORATION
146 MAIN STREET ML05-2/T77
MA YNARD, MA 01754-2571

I
I
I
I
I
- - - - Do Not Tear - Fold H e r e - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - I
I
I
I
I
I

OIl

:;::