Digital PDFs

AA-L319B-TE

December 1984

208 pages

Original

8.3MB

Document:	VAX FMS 2.2 Form Driver Reference Manual 198408
Order Number:	AA-L319B-TE
Revision:
Pages:	208
Original Filename:	http://bitsavers.org/pdf/dec/vax/vms/layered_product/AA-L319B-TE_VAX_FMS_2.2_Form_Driver_Reference_Manual_198408.pdf

OCR Text

VAX FMS
Form Driver Reference Manual
AA-L3198-TE

August 1984
This manual describes how the Form Driver component of the Forms
Management System (FMS) on VAX/VMS works. It provides language-independent information required to design forms and develop programs that use FMS forms for gathering and displaying
data.

This manual is part of the VAX FMS document set that supersedes
the VAX FMS Version 2.0 and 2.1 document sets.

Operating System:
Software:

VAX/VMS Version 4.0

VAX FMS Version 2.2

digital equipment corporation • maynard, massachusetts

First Printing, January 1983
Revised, August 1984

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 be used or
copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is not
supplied by Digital Equipment Corporation or its affiliated companies.
Copyright© 1983, 1984 by Digital Equipment Corporation.
All Rights Reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document requests the
user's critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-10
DECSYSTEM-20
DEC US
DECwriter

DIBOL
EduSystem
IAS
MAS SB US
MICRO/PDP-11
Micro/RSX
MicroVMS
PDP

PDT
RSTS
RSX
TOPS-20
UNIBUS
VAX
VMS
VT

~nmnomo

ZK2575

HOW TO ORDER ADDITIONAL DOCUMENTATION
In Continental USA and Puerto Rico call

800-258-1710

In New Hampshire, Alaska, and Hawaii call

603-884-6660

In Canada call 613-234-7726 (Ottawa-Hull)
800-267-6146 (all other Canadian)

DIRECT MAIL ORDERS (USA & PUERTO RICO)*
Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire 03061

DIRECT MAil. ORDERS (CANADA)
Digital Equipment of Canada Ltd.
940 Belfast Road
Ottawa, Ontario K1 G 4C2
Attn: A&SG Business Manager

DIRECT MAIL ORDERS (INTERNATIONAL)
Digital Equipment Corporation
A&SG Business Manager
c/o Digital's local subsidiary or
approved distributor

*Any prepaid order from Puerto Rico must be placed
with the local Digital subsidiary (809-754-7575)
Internal orders should be placed through the Software Distribution Center (SOC), Digital Equipment
Corporation, Northboro, Massachusetts 01532

Contents
Page

Preface
Chapter 1 Introduction
1.1

Terminals, Workspaces, Forms, and Fields
1.1.1
1.1.2
1.1.3
1.1.4

1.2
1.3

Terminal Control Areas and Form Workspaces
Form Management Calls.
1.3.1
1.3.2
1.3.3
1.3.4

1.4
1.5
1.6
1.7
1.8
1.9
1.10
1.11
1.12

Terminals . .
Workspaces.
Forms . . . .
Fields . . .

Control Calls. . .
Form-Level Calls . .
Field-Level Calls ..
Utility Calls . . . .

Memory-Resident Forms and Form Libraries
Multiterminal and Multiform Operations
Debug Mode . . . . .
Scrolling Operations .
User Action Routines.
Named Data . . . . .
Terminal Key Functions . .
Current States. .
Operator Aids . . . . .
1.12.1 Help. . . . . .
1.12.2 Screen Refresh .

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

. . 1-7
. . 1-7
. . 1-7
. . 1-7
. . 1-7
. . 1-8
. 1-8
. . 1-8
1-10
1-10
1-10

Chapter 2 Form Driver Interaction
2.1

Interaction with the Form Description
2.1.1
2.1.2
2.1.3
2.1.4
2.1.5
2.1.6

Storing and Accessing Form Descriptions
Displaying a Form . . . . . . . . .
Terminal Control . . . . . . . . . .
Using Workspaces to Store Forms . .
The Help Function . .
Field Processing Order . . . . . . .

. . 2-1
. . 2-1
. . 2-2
. . 2-5
. . 2-5
. . 2-7
. . 2-8

iii

2.1.7
2.1.8

Text, Field-Marker Characters, and Video
Attributes
Processing Fields .

. 2-9
. 2-9
. 2-9

2.1.8.1
2.1.8.2

Field Pictures .
Right Justified and Left Justified Field
Attributes .
2.1.8.3 Clear Character. and Fill Character
Attributes .
2.1.8.4 Default Field Value
2.1.8.5 Autotab Attribute .
2.1.8.6 Response Required and Must Fill Attributes.
2.1.8.7 Fixed Decimal Attribute .
2.1.8.8 Display Only Attribute .
2.1.8.9 No Echo Attribute.
2.1.8.10 Supervisor Only Attribute
2.1.8.11 Scrolling
2.1.8.12 Date and Time Attributes

2.2

2.2.3
2.2.4
2.2.5

2-13
2-13
2-15

Field Completion UARs.
Help UARs.

2.2.2.1
2.2.2.2

2-15
2-16
2-16
2-18
2-20
2-21
2-22

Pre-Help UAR.
Post-Help UAR

Help Request Processing
Function Key UARs
Legal Actions in a UAR .

Interaction with the Terminal Operator.

2.3.1

Signaling and Recovering from Errors

2.3.1.1
2.3.1.2
2.3.1.3
2.3.2

2.3.2.4
2.3.2.5
2.3.2.6
2.3.2.7
2.3.2.8
2.3.3
2.3.4
2.3.5
2.3.6

2-22

Help Key and Help Messages.
Checking Operator Responses from Your
Program.
Refreshing the Screen: Typing CTRL/R.

2-23
2-23
2-23
2-24
2-24

Field Editing Functions.

2.3.2.1
2.3 . 2.2
2.3.2.3

VTlOO Alternate Keypad Mode .
The Cursor's Initial Position in a Field .
Inserting a Field Value: The Default
Function
The Signed Numeric Picture .
Deleting a Character .
Deleting a Field .
Moving the Cursor to the Right.
Moving the Cursor to the Left

2-25
2-25
2-26
2-26
2-27
2-27
2-27
2-28
2-31
2-33

Switching the Insertion Modes.
Field Terminators
Field Terminators and Form Driver Calls
Field Terminating Functions

2.3.6.1
2.3.6.2
2.3.6.3
2.3.6.4

2-10
2-10
2-10
2-10
2-11
2-11
2-11
2-12
2-12
2-12

User Action Routines.

2.2.1
2.2.2

2.3

. 2-9

Signaling that the Form Is Complete .
Moving the Cursor to the Next Field .
Moving the Cursor to the Previous Field
Scrolling Backward

2-33
2-33
2-34
2-35

2.3.6.5
2.3.6.6
2.3.6. 7
2.3.6.8
2.3.7
2 .4

Alternate Keypad Mode Terminators

2-37
2-38

Form Driver Key Functions .
Form Driver Key Codes . . .

2-38
2-39

Control Keys . . . . . . .
Escape Sequences .
Gold Sequences .

2-39
2-40
2-41

Defining Keys . . . . . . . . . . .

2-46

2.4.2.1
2.4.2.2
2.4.2.3
2.4.3

Checking Call Status. . . . . . . .
2.5.1
2.5.2

2.6

2-35
2-36
2-36
2-37

Key Functions and Key Codes . . .
2.4.1
2.4.2

2.5

Scrolling Forward . . . . . . . .
Exiting Scrolled Area Backward
Exiting Scrolled Area Forward
Illegal Terminator Interaction

Debug Mode Support for Application Program
Development . . . . . . . . . . . . . .
Signaling the Terminal Operator About
Program Errors .

AST Considerations . . . . . . . . . . . . . . . . . . . . . .

2-46
2-49
2-50
2-51

Chapter 3 Programming Techniques and Examples
3 .1

Scrolling . . . . . . . . . . . . .

. . 3-1

3.1.1
3.1.2
3.1.3

. 3-2
. . 3-3
. . 3-3

Controlling Scrolled Areas.
Scrolling Forward . . . . . .
Scrolling Backward . . . . .

3.2

Validating a One-Character Field - Using
a UAR . . . . . . . . . . . . . . . . . .
3.3 Producing Hard Copy - Using Named Data
3.4 Storing Message Text - Using Named Data
3.5 Converting Function Keys to Field Entry .
3.6 Filter for Function Keys . .
. ....
3.7 Range Checks for Fields . . . . . .
3.8 Simulating the GETAL Call . . . .
3.9 Reducing Display Times for Forms .
3.10 Checking Status - Three Methods .
3.11 Paging . . . . . . . . . . .
. ....
3.12 FMS Advanced Programming . . .
3.12.1 FMS Performance . . . . .
3.12.1.1 FMS Libray Performance
3.12.1.2 Form Driver Performance
3.12.1.3 Overlaying. Form Design . .

. 3-4
. 3-5
. 3-7
. 3-8

3-10
3-12
3-14
3-18
3-18
3-21
3-22
3-22
3-22
3-23
3-25

Chapter 4 Linking the Application and Setting Up the Terminals
4.1

Linking . . . . . . . . . . . . . . . . . . . .

. . 4-2

Linking with the Form Driver Library . .
Linking with Memory-Resident Forms . .
Linking with a UAR Vector . . . . . . .

. . 4-2
. . 4-2
. 4-3

4.1.1
4.1.2
4.1.3

4.1.4
4.1.5
4.1.6

Direct Terminal Output. . . . . .
Terminal State at Program End . .
Firmware Bug Workaround

. . 4-3
. 4-4
. . 4-4

Chapter 5 Form Driver Calls
ADLVA-Alter Data Line Video Attributes .
AFCX-Alter Field Context
AFVA-Alter Field Video Attributes
ATERM-Attach Terminal.
..
AWKSP-Attach Form Workspace .
BELL-Ring Terminal Bell.
. .
CANCL-Cancel Call
..
5.8 CDISP-Clear Screen and Display Form
5.9 CLEAR-Clear Screen .
5.10 CLEAR._VA-Clear Video Attributes. . .
5.11 DEL-Remove Form from Memory-Resident Form
List.
. .
. .
5.12 DFKBD-Define Keyboard.
. .
. .
. .
. .
. .
5.13 DISP-Display Form.
. .
5.14 DISPW-Display Loaded Form .
5.15 DPCOM-Define Comma as Decimal Point.
. .
5.16 DTERM-Detach Terminal
. .
5.17 DWKSP-Detach Form Workspace.
5.18 Fl}{_SCREEN-Repair Overwritten Lines of Terminal
Screen
. .
. .
'5.19 GET-Get Value for Specified Field
..
5.20 GETAF-Get Value for Any Field
5.21 GETAL-Get All Field Values .
5.22 GETDL-Get Data Line from Terminal.
5.23 GETSC-Get Current Line of Scrolled Area.
..
5.24 ILTRM-Retum Illegal Terminators
5.25 LCHAN-Set Channel for Form Library File
5.26 LCLOS-Close Form Library.
5.27 LEDOF-Tum Terminal LED Off .
5.28 LEDON-Tum Terminal LED On .
5.29 LOAD-Load Form Without Display .
5.30 LOPEN-Open Form Library . .
5.31 NDISP-Mark Form in Current Workspace as
Not Displayed.
. .
. .
5.32 PFT-Process Field Terminator.
5.33 PUT-Output Value to Specified Field . .
5.34 PUTAL-Output Values to All Fields .
5.35 PUTD-Output Default to Specified Field
5.36 PUTDA-Output Default Values to All Fields.
5.37 PUTL-Output Line to Screen .
5.38 PUTSC-Output Data to Current Line of
Scrolled Area
. .
. .
. .
5.39 READ-Read Form into Memory .
5.40 RET-Retum Value for Specified Field . .
5.41 RETAL-Retum Values for All Fields. . .
5.42 RETCX-Retum Current Context
5.43 RETDI-Retum Named Data by Index . .
5.44 RETDN-Retum Named Data by Name
5.1
5.2
5.3
5.4
5.5
5.6
5.7

. -5-2
. 5-3
. 5-4
. 5-6
. 5-9
5-10

5-11
5-12
5-13
5-14
5-15

5-16
5-18
5-21

5-22
5-23
5-24

5-25
5-26
5-28
5-30

5-32
5-34
5-36
5-37
5-38

5-39
5-40
5-41

5-42
5-43

5-44
5-47

5-48
5-49
5-50
5-51
5-53
5-54
5-55
5-56
5-57
5-59

5-60

vii

Preface
This manual describes the VAX FMS Form Driver, the run-time component
of the Forms Management System for use with the VAX/VMS operating
system.

Intended Audience
The manual is intended for programmers who wish to use FMS with any of
their application programs being written in BASIC, BLISS-32, C, COBOL,
FORTRAN, PASCAL, or PL/I (those languages documented in the VAX FMS
Lar,,guage Interface Manual). Readers are expected to be familiar not only
with a programming language but with the VAX/VMS system.
Readers are also expected to be familiar with the information in Chapter 2 of
the VAX FMS Utilities Reference Manual, Form Characteristics. This material discusses form characteristics that are specified by means of the Form
Editor or Form Language when a form is being designed.
Readers having little or no experience with FMS are urged to read the Introduction to VAX FMS before reading this manual.

Chapter Summary
Chapter 1 presents an overview of the Form Driver, briefly discussing 12
basic topics.
Chapter 2 discusses Form Driver interaction with form descriptions, user
action routines, terminal operators, key functions and key codes, call status,
and asynchronous system traps (ASTs).
Chapter 3 offers programming techniques and examples from the Sample
Application Program in various languages. The FMS Sample Application
program (SAMP.BAS), a part of the FMS distribution kit, is designed to be a
demonstration program and learning tool. (Examples from SAMP appear
throughout the FMS document set.)
Chapter 4 shows how to link object modules with the Form Driver and,
optionally, with memory-resident forms or user action routines. This chapter
also discusses terminal use in FMS programs.

Chapter 5 describes all Form Driver calls in alphabetical order, each giving
first the generic format of the call with its arguments, followed by definitions
of all arguments in the order they must be specified (along with information
on how they are passed and whether they are read or written), then a description of what the call does, and finally a list of status codes (in alphabetical
order) that can be returned to the program as a result of the execution of the
call.
Throughout this manual, names of calls are usually referred to informally as,
for example, CDISP. When calls are actually issued in programs, though, all
names ofFMS calls begin with the prefix FDV$ (for example, FDV$CDISP).
To find the language-specific way of issuing a call, you must consult the
appropriate chapter in the VAX FMS Language Interface Manual.
In this manual the phrase "GET-type calls" refers to any of the following
calls: GET, GETAF, GETAL, and GETSC (but not GETDL). The phrase
"PUT-type calls" refers to the calls PUT, PUTAL, PUTD, PUTDA, and
PUTSC (but not PUTL).
Appendix A gives a comprehensive summary of information on all FMS calls.

Documentation Conventions
Uppercase letters

In commands and examples, indicate that the user
types the item exactly as shown.

Lowercase letters

In commands and examples, indicate variables for
which the user is to substitute a word or value.

Brackets [ ]

Indicate that the item is optional.

Braces { }

Enclose lists from which one element is to be chosen. A
vertical bar ( I ) separates the choices.

Red print

Indicates what the user types.

CTRL/x

Indicates that the user holds down the key labeled
CTRL and presses another key.

Goldx

Indicates that the user presses the Gold key before
pressing the second key.

Ellipsis ...

Indicates that the preceding item can be repeated.

Chapter 1
Introduction
The Form Driver, the run- I time component ofFMS, is a subroutine package
that is linked with your program. The Form Driver accepts calls from your
program, maintains FMS data structures, and issues terminal 1/0 calls to
communicate with the terminal operator.
As shown in Figure 1-1, the Form Driver is one of three parts of an FMS
application.
_[

.1.

Application
Program

Form
Driver

---

Video
Terminals

1--

ZK-1836·84

Figure 1-1 Form Driver Communication
Knowledge of the following 12 topics is basic to an understanding of the Form
Driver. This chapter offers brief introductions to these topics:
• Terminals, Workspaces, Forms, and Fields
• Terminal Control Areas and Form Workspaces
• Form Management Calls
• Memory-Resident Forms and Form Libraries
• Multiterminal and Multiform Operations
• DebugMode
• Scrolling Operations
• User Action Routines
•Named Data
• Terminal Key Functions
• Current States
• Operator Aids

1-1

1.1

Terminals, Workspaces, Forms, and Fields
The primary work of the Form Driver is the manipulation o-r terminal
images, form workspaces, forms, and form fields.

1.1.1

Terminals

The Form Driver controls one or more terminals, performing such tasks as
displaying forms, soliciting data from the terminal operator, and displaying
messages. The terminal is controlled by the character sequences and escape
sequences sent to it by the Form Driver.
An application program using FMS can process forms on any of the
VT100/VT200 compatible terminals or on the VT52 terminal. The Form
Driver supports calls that manage terminals' initialization, their use, and
their release by FMS.
In an FMS application, a separate area of memory is associated with each
terminal. This area is called a terminal control area or TCA. Once a TCA is
associated with a terminal, the application program controls that terminal's
activity by issuing calls that specify the terminal's TCA.

1.1.2 Workspaces
Workspaces are areas of memory in which the Form Driver stores form
descriptions for the forms being processed. More than one form workspace
can be associated with a terminal, but each workspace can be associated with
only one terminal at a time. The Form Driver supports calls that initialize
workspaces, associate them with TCAs, load them with form descriptions,
and release them from TCAs.

1.1.3

Forms

A form consists of(l) background text and fields, which are displayed on the
screen, and (2) Named Data, which is not displayed. Internally, a form is composed of the data structures used by the Form Driver to create and manipulate the image on the screen. These data structures (called form descriptions) /
are created by FMS utilities (Form Editor, Form Language Translator, and
Form Upgrade Utility). (See the VAX FMS Utilities Reference Manual.)
The Form Driver supports calls that load these form descriptions into workspaces and perform the many functions defined for forms and their fields.
When a form is loaded into a workspace, the workspace becomes associated
with the form. Consequently, reference to a workspace is a reference to the
form stored in it.
Because a workspace can be associated with only one terminal at a time, displaying any given form on more than one terminal requires loading the form
into workspaces associated with other terminals as well.

1-2

Introduction

1.1.4 Fields
A field is a portion of the form that has variable data associated with it. The
Form Driver supports many calls controlling the manipulation of field data.
Some calls allow the terminal operator to enter or change field data. Others,
for. example, allow the application program to display data in fields, to get
data that the operator entered in fields, or to change field video attributes.
Field ,attributes, assigned when a form is created, affect the way the Form
Driver processes field input and output. For example, a field having the
Response Required attribute requires that the terminal operator enter at
least one character in the field.
When the Form Driver processes groups of fields (in a singleform) with a single call, it processes them in the order specified in the form description. The
Form Driver controls movement from field to field, the order in which field
values are returned to your program or written to a terminal, and the definition·of "first" and "last" fields in forms.
··

1.2

Terminal Control Areas and Form Workspaces
Terminal control areas (TCAs) and form workspaces are maintained in a
hierarchy as shown in Figure 1-2. The application program shown uses several terminals. Attached to the application program is a list of TC As that tells
the Form Driver which terminals it can use. Attached to the first TCA is a list
of wo,kspaces that can contain forms for processing on that TC A's t~rminal.
Similarly, a list of workspaces is attached to the second TCA.
Application
Program

Terminal
Control Areas

Worikspaces

Form Driver

TCA 1

WKSP 1a

Calls
TCA 2
WKSP 1c

•
WKSP 2a

••

•

ZK-1837-84

Figure 1-2 Terminal Control Areas and Workspaces

Introduction

1-3

Although you refer to forms and fields by name, you usually do not need to
refer to a TCA name to specify a particular terminal or to refer to a workspace
name to specify where you want to load a form. The Form Driver establishes a
"current terminal" and "current workspace". Each call that affects a terminal
or workspace acts upon the current terminal or current workspace, unless the
call explicitly specifies another TCA or workspace.
The Form Driver provides calls to make another terminal or another workspace the current one. By including such calls in your program, you can avoid
having to specify the terminal and workspace for each call your program
issues.

1.3 Form Management Calls
The Form Driver supports four classes of form management calls:
1. Control
2. Form-level
3. Field-level
4. Utility
These calls are introduced in the following sections and documented fully in
Chapter5.

1.3.1

Control Calls

Your program issues the following calls to make connections and disconnections between FMS units such as terminals, form workspaces, files, and form
libraries:

1-4

ATERM

Attach terminal

AWKSP

Attach form workspace

DTERM

Detach terminal

DWKSP

Detach form workspace

LC HAN

Set channel for form library file

LC LOS

Close form library

LOPEN

Open form library

STERM

Set current terminal

SWKSP

Set current workspace

TC HAN

Set terminal channel

Introduction

1.3.2 Form-Level Calls
Your program issues the following calls to perform general form-level
operations:
CDISP

Clear screen and display form

DEL

Delete form from memory

DISP

Display form

DISPW

Display loaded form

GETAL

Get all field values

LOAD

Load form without display

NDISP

Mark form in current workspace as not displayed

PUTAL

Output values to all fields in a form

PUTDA

Output default values to all fields in a form

READ

Read form into memory

RETAL

Return values for all fields in a form

1.3.3 Field-Level Calls
Your program issues the following calls to perform field-level operations on a
form:
AFCX

Alter field context

AFVA

Alter field video attributes

GET

Get value for specified field

GETAF

Get value for any field

GETSC

Get current line of scrolled area

PFT

Process field terminator

PUT

Output value to specified field

PUTD

Output default to specified field

PUTSC

Output data to current line of scrolled area

RET

Return value for specified field

RETFN

Return current field name

RETFO

Return field names in order

RETLE

Return length of specified field

Introduction

1-&

1.3.4

Utility Calls

Your program issues the following calls to perform operations not falling into
the preceding classifications:

1-6

ADLVA

Alter data line video attributes

BELL

Ring terminal bell

CANCL

Cancel call

CLEAR

Clear screen

CLEAR_VA

Clear screen video attributes

DFKBD

Define keyboard

DPCOM

Define comma as decimal point

FIX_SCREEN

Repair overwritten lines of terminal screen

GETDL

Get data line from terminal

ILTRM

Return illegal terminators

LEDOF

Tum terminal LED off

LEDON

Tum terminal LED on

PUTL

Output line to screen

RETCX

Return current context

RETDI

Return Named Data by index

RETDN

Return Named Data by name

RETFL

Return form line

RFRSH

Refresh screen

SCR_WIDTH

Set screen width

SIGOP

Signal operator

SPADA

Set keypad to application mode

SPOFF

Turn supervisor-only mode off

SPON

Turn supervisor-only mode on

SSIGQ

Set signal to quiet mode

SSRV

Specify status recording variables

STAT

Return status from last call

STIME

Set field entry timeout

USER-REFRESH

Set up user-supplied refresh routine

WAIT

Wait for operator

Introduction

1.4

Memory-Resident Forms and Form Libraries
The Form Driver gets the forms required by various calls either from a memory-resident set of form descriptions or from a form library you specify in a
Form Driver call. You can make forms memory resident either by building
them into your application program or by loading them into the set of memory-resident forms at run time. Memory-resident form modules are created
by one of the Form Application Aids; form libraries are built and maintained
by the Form Librarian.

1.5

Multiterminal and Multiform Operations
An application program using the Form Driver can control one or more terminals and manipulate one or more forms on each terminal by using control
calls (STERM or SWKSP) to define a new current terminal or current workspace. Note that for this version ofFMS you can use these calls to control only
one terminal at a time.

1.6

Debug Mode
The Form Driver has a Debug mode of operation that is useful for the debugging of an application program that uses FMS. When the application program is in FMS Debug mode, it runs normally until the Form Driver returns
a status code indicating an error. At this time, a message is displayed on the
bottom line of the screen, and the Form Driver waits for the operator to press
the Enter Form key before proceeding. (Any other input is ignored.)
The Form Driver Debug mode is not associated with any other debugging aid.

1.7

Scro IIi ng Operations
You can use the GET, GETAF, GETSC, PFT, PUT, and PUTSC calls in your
program to take advantage of the scrolling capabilities of the VTlOO. With
these calls you can control scrolled areas in forms.
The hardware scrolling capabilities of the VT100NT200 are simulated for
VT52 terminals by software. The performance of scrolling operations is
therefore much slower for VT52s.

1.8

User Action Routines
When a form is designed, the form designer can specify that subroutines supplied by you be called from the Form Driver as part of the processing of the
form. These subroutines are called user action routines (UARs).
A user action routine can be called under any of the following conditions:
1. When processing for a field is finished
2. When the terminal operator requests help
3. When the terminal operator presses a function key
4. When a screen refresh operation is requested

Introduction

1-7

When linking your program, you must include an object module containing
the names of all the user action routines to be called. You generate such an
object module by using the FMSNECTOR command. (See Chapter 4 of this
manual and the VAX FMS Utilities Reference Manual, Chapter 6, Form
Application Aids.)

1.9 Named Data
Nall).ed Data is data first associated with a form when the form is being
designed. It is not a visible part of the form that appears on the operator's
screen. Rather, it is form-oriented information your program can use that you
might otherwise have to keep in your program. Two calls are available to you
for accessing this information. (See Chapter 3 for examples of the use of
Named Data.)

1.1 O Terminal Key Functions
Many Form Driver actions are taken in response to the pressing of certain
terminal keys by an operator. FMS has assigned functions to keys, but you
can change the correspondence between keys and functions to whatever you
want. Therefore, this manual refers not to a physical key but to the function
that the key performs (regardless of which key implements the function).
Accordingly, the name of a key function has its initial letter capitalized
rather than its entire name capitalized, which is the way names of actual
keys are indicated. (See Section 2.3 subsections for default definitions of all
keys used by the Form Driver.)

1.11

Current States
The Form Driver establishes certain "current states" that are important to
know about when you are writing your program:
1. Current Terminal -The terminal (with all its characteristics) currently
in use

Although you can control more than one terminal in your FMS application, the Form Driver calls affect only one terminal at a time - the current
terminal. The Form Driver provides calls to change the current terminal.
The current terminal is undefined if no terminal is in use.
2. Current Workspace - The form workspace currently in use

Although you can work on more than one workspace in your FMS application, the Form Driver calls affect only one workspace at a time - the current workspace. Your program issues calls to change the current
workspace. The current workspace is associated with the current terminal. Whenever your program switches to another terminal, therefore, it
inherits the new terminal's current workspace.
The current workspace is undefined if the current terminal is undefined,
or if no workspace is presently associated with the current terminal.

1-8

Introduction

You can manipulate a form only by first loading it into a workspace by
means of a LOAD, DISP, or CDISP call.
3. Current Field - The most recent field specified in a call for operator input
(or the first modifiable field in a form, if no input call has been executed
yet) and any index associated with the field
The current field normally is available by default when you do not supply a
name for the field name argument in a subsequent call.
The current field and its index are associated with the current workspace.
If your program switches to another workspace, it inherits a new current
field and index.
If a field does not have the Indexed attribute, its index is defined as zero.
The current field and its index are undefined if there are no fields in the
form or if no workspace is defined.
4. Current Scrolled Line -The line in any scrolled area that the Form Driver
is currently working on
This line is initially the first (top) line in a scrolled area, but you can move
up or down in the area to a new current scrolled line by issuing a PFT call
in your program.
The current scrolled line is aesociated with any scrolled area being worked
on in the current workspace. The current scrolled line is undefined if the
form in the workspace has no scrolled areas.
5. Last Terminator Code-The most recent field terminator code returned by
a call in your program
This code is associated with the current workspace. If your program
switches to another workspace, it inherits the new workspace's last terminator code.
The last terminator code is undefined if no field terminator has been
entered for the form.

6. Last Status Code -The most recent status code returned by a Form Driver
call in your program
This code is associated with the current workspace if one is defined. If no
current workspace is defined, the code is associated with the current terminal provided one is defined. If no current terminal is defined, the code is
associated with the Form Driver itself.
This method of associating the last status code with more than one possible object is available so that when your program switches from one terminal to another, or from one workspace to another, it gets the most recent
status code appropriate to its context.

Introduction

1-9

7. Last 1/0 Status Code-The most recent 1/0 status code returned by a Form
Driver call in your program
The Form Driver handles this code the same way it handles the last status
code.
8. Current Library Channel -The 1/0 channel to be used any time your program needs access to the associated form library
For example, you might want to open or close a form library or to retrieve a
form for processing. The Form Driver uses the current library channel.
The current library channel is associated with the current terminal.
9. Supervisor-Only Flag - The flag used to control the processing of fields
having the Supervisor Only attribute
This flag is associated with the current terminal and is undefined if the
current terminal is undefined. The supervisor-only flag is on by default.
10. Timeout Value -The time (in seconds) that an operator has to respond
(with each typed character) to a call for input from a terminal
If the operator fails to respond within the specified time, the call is
aborted. This value is associated with the current terminal and is initially zero, meaning no timeout limits are in effect. The timeout value is
undefined if the current terminal is undefined.

11. Current Signal Mode -The mode in which the Form Driver gets an operator's attention
Two modes are available to you - ringing the terminal bell and reversing
the screen video. The reverse-video signal continues until the operator
types a valid character. The current signal mode is associated with the
current terminal. The default m.ode is to ring the bell (the only mode for
VT52 terminals).

1.12 Operator Aids
1.12.1 . Help

When the Form Driver is waiting for input, the operator can request help by
pressing the Help key. Either a help form or a single line of help is available.
In either case, the help supplied is specified when the form is designed. Single-line help messages remain on the bottom line of the screen until the operator presses another key.
If a help form is displayed, the Form Driver waits for the operator to press the
ENTER key before reconstructing the original screen. If the operator presses
the Help key again, instead of ENTER, additional help is displayed if it is
available. Any other input is ignored. (The terminal bell rings or the screen
video reverses if input has been rejected.)

1-10

Introduction

1.12.2 Screen Refresh
By pressing the Refresh key, the operator can update the screen image. That
is, the screen is cleared, and all forms attached to the terminal and displayed
are redisplayed. Forms no longer attached to the terminal or marked as not
displayed, that were on the screen from a previous display call, are not redisplayed. (You can also issue a RFRSH call from your program.)
A screen refresh also restores the keypad mode, provided your program has
previously issued a SPADA call (the Form Driver does not otherwise know
the keypad state). The refresh operation also restores the terminal LEDs to
the state they were in before the refresh occurred.

Introduction

1-11

Chapter 2
Form Driver Interaction
The Form Driver interacts with your program and with terminals associated
with the Form Driver. Discussion of such interactions is concerned with the
degree of control your program has in:
• Manipulating forms internally
• Displaying forms on the terminals
• Soliciting terminal operators' responses to requests for field-by-field form
data
Some limitation is imposed on both your program and the operator prior to
run time, by the way the forms are designed. Thus, for example, field attributes are already assigned for forms, as is the order in which fields are
processed in some calls.
Other considerations are concerned with:
• Who has control over the modification of fields in a form, and when
• How control is passed to a terminal operator
• When different levels of help for fields and forms are displayed for an
operator
• What keys and keypad layouts can be made available to an operator on
VT100-NT200- and VT52-compatible terminals.

2.1

Interaction with the Form Description
2.1.1

Storing and Accessing Form Descriptions

Your program can store and access form descriptions in either of two ways:
• As disk-resident forms, by reading them directly from a form library file
that has been stored on a disk
• As memory-resident forms, for which binary form descriptions (stored as
object modules) are linked with the program

2-1

Both ways make use of form descriptions that have been created with the
Form Editor, Form Language Translator, Form Upgrade Utility, or Form
Converter, and that have been processed with the Form Librarian or Form
Application Aids. (See the VAX FMS Utilities Reference Manual.)
For example, after using the Form Editor to create a form description, you
must use the FMS/LIBRARY/CREATE command to store the description in a
form library file or the FMS/MEMORY_R,ESIDENT command - a Form
Application Aid - to produce an object module that permits access as a
memory-resident form. You must then link the object program with the Form
Driver and any other object modules you want to reside in memory, in order to
form the executable FMS application program. (See Figure 2-1.)

NOTE
It is not necessary to build a single large object module containing all memory resident forms for an application. Multiple
memory resident form objects produced by FMS can be linked
into an executable image.

Main program
object module

-Link

Form library

ZK-18??-84

Figure 2-1: Building an Application Program

2.1.2

Displaying a Form

There are three ways you can access a form. The method you use depends on
where the form description resides:
• Resides only in the form library
• Resides in the form library, but is made memory resident at run time
• Is linked with the application program and is memory resident at all times
during program execution

2-2

Form Characteristics

A typical procedure for displaying a form at the beginning of an FMS application is:
1. Make a terminal known to the Form Driver. (Use the ATERM call.)

2. Allocate an internal storage area - form workspace - in which the Form
Driver is to store the form description, including field values and other
form requirements. (Use the AWKSP call.)
3. If the form is disk resident:
• Identify the I/O channel the Form Driver is to use for reading form
descriptions from the form library file. (Use the LC HAN call.) 1
• Open the form library file. (Use the LO PEN call.)
4. If you want that disk-resident form to become memory resident, read the
form description into memory. (Use the READ call.)
5. Display the form. (Use the CDISP or DISP call if the form description is
disk resident.)
The Form Driver provides two calls that both load workspaces and display
forms - CDISP and DISP. The CDISP call clears the entire terminal screen
before displaying a form. The DISP call clears only the screen lines that are
required by the form, in its description, that you want to display.
If you use short forms, you can use the DISP call to create for the operator a
screen display that is composed of more than one form or part of a form. In
such an instance, only one form would normally be active for the operator,
although y,ou could use special techniques like those described in Chapter 3 to
switch back and forth among forms.

For each call to display a form, the Form Driver checks the set of memoryresident forms first. When memory-resident and disk-resident form descriptions have the same form name, the Form Driver uses only the memory-resident version.
You can load a form from any source into a workspace, but not display the
form on the terminal screen, by issuing the LOAD call. You can then put values in fields of the form and display the form later by means of the DISPW
call. Use of these calls may reduce the amount of output to the screen, since
the fields of the form do not have to be written twice - once with the default
values and once with the application-defined values.
The name that you assign to a form with the Form Editor or Form Language
Translator is the only information that the Form Driver needs to read the
form from its form library file or to find its memory-resident description. Similarly, the name that you assign to a field is all the Form Driver requires,
regardless of where you locate the field within the form. As long as changes to
form and field characteristics have no effect on the logic of your program, you
can change the characteristics without ~ayi:Qg to modify yourprogram.
1. You can eliminate this step if you include the 110 channel as an input argument in the
following LOPEN call.

Form Characteristics

2r-3

The following is a description of the screen management role of the Form
Driver when overlaid forms are present and when your program issues PUTL
and GETDL calls to reference lines that are parts of forms. Whenever the
Form Driver is directed to output a value to the screen by a PUT-type field
call - PUT, PUTAL, PUTD, PUTDA, or PUTSC - or is directed to request
input from the operator by a GET-type field call - GET, GETAF, GETAL, or
GETSC - it first checks to see if the form containing the field is still intact on
the screen. If the form has been disturbed, part or all of it is redisplayed.
A form is disturbed in one of two ways:
1. Part of it has been overlaid by another form in a subsequent DISPW call,

RFRSH call or operation, or help request.
2. Part of it has been overlaid by a PUTL or GETDL call.
No matter what part of the form has been overlaid, the form can be redisplayed in its entirety.
The Form Driver functions as a screen manager. It keeps track of every line
on the screen belonging to every displayed workspace. Whenever a line is
altered through the calls CLEAR, PUTL, GETDL, DISPW, CDISP, or DISP,
the Form Driver knows that the line has been affected. If the line is affected
by PUTL, GETDL, or CLEAR, the Form Driver knows that the line has been
completely cleared.
If a line is overlaid by the display of another form that clears some lines, then
those cleared lines are noted. (A form that overlays another form, without
clearing lines, is assumed not to interfere with the underlying form. A form
interferes with another form only if it has area-to-clear lines, and then it
interferes only with those lines.)
The Form Driver checks the lines of the form when information is sent to a
screen field (by a PUT-type call), when information is requested of the screen
(by a GET-type call), when help and UAR processing terminates, or when a
new form is displayed. If any line has been cleared, as described above, the
Form Driver rewrites all the affected lines of the screen by calling
FDV$FULSCREEN internally. Thus, your program need do nothing if the
screen has been affected by calls on the Form Driver, since the Form Driver
knows and will fix the screen before the next 1/0 operation affecting fields.
The Area to Clear attribute of a form is included in the description of the
form. Therefore, at design time, the form designer should consider how much
of the screen should be included in this attribute. Even if the form does not
specify text or fields for a line, the Area to Clear attribute may specify that
the line be blank when the form is displayed.
The Form Driver honors the form description whenever the form is referenced. Ifa form is being redisplayed unexpectedly, it is most likely that part of
the form has been overwritten.

2-4

Form Characteristics

2.1.3 Terminal Control
Your application program can use either VT100-NT200- or VT52-compatible
terminals to display forms and to solicit responses from a terminal operator.
Before you can use any terminal to display a form, you must first attach it to
the application program by issuing an ATERM call.
More than one terminal can be attached to an application program, but only
one terminal at a time can be performing 1/0 operations. That terminal is
called the current terminal. Other attached terminals continue to display
any images already on their screens.
At run time, the Form Driver keeps a list of all terminals attached to the
application program. Form Driver calls can reference only terminals on this
list; a few exceptions use the program's default terminal.
In an FMS application, a terminal control area (TCA) is reserved for each
attached terminal. Once a TCA is initialized, the application program controls terminal activity by issuing calls that specify, implicitly or explicitly,
the associated terminal control area.
Form Driver calls that manage the initialization of terminals and their
release are:
ATERM Attach a terminal for use by an application program
DTERM Detach a terminal from the list of attached terminals
STERM Make the specified terminal the current terminal
You should detach terminals before leaving FMS; otherwise, the terminals
may continue to output assigned video attributes when they are no longer
associated with FMS. If you do not explicitly detach a terminal from within
your program, video attributes assigned to the terminal remain in effect until
you reattach the terminal and modify its attributes.

2.1.4

Using Workspaces to Store Forms

To process forms, your program must supply one or more workspaces in memory. Each workspace can contain only one form description. Workspaces are
internal to FMS and are inaccessible to the terminal operator.
Each attached terminal can have one or more workspaces associated with it,
but the Form Driver can access the form in only one workspace at a time- the
current workspace. All other attached workspaces are considered passive at
that time and can be used only for storing their form descriptions.
Each workspace can be associated with only one terminal at a time. That is,
no workspace can be simultaneously associated with more than one terminal.
For example, if you want to display a form on two terminals at the same time,
you must provide different workspaces for them and load the form into both
workspaces.

Form Characteristics

2-5

An advantage of using multiple workspaces is to allow the simultaneous control of multiple forms on the screen. For example, you can display a form
stored in one workspace, switch to another form workspace by issuing a
SWKSP call and display the form stored there either at the location specified
at form definition time or at a screen location appropriately positioned by
means of an "offset" argument in the display call. The Form Driver maintains
the context of each workspace including, for example, the current field name.

A screen refresh under application control- issuing a RFRSH call - or under
operator control- pressing CTRL/R or CTRL/W - clears the screen of all text
and redisplays all forms currently marked as displayed for the current
terminal.
The Form Driver supports calls that associate workspaces with terminals,
load workspaces with form descriptions, display forms from workspaces, and
release workspaces. These calls are:
AWKSP Attach a workspace to a terminal control area.
CDISP

Clear the screen and load a workspace with a form from a library or
a memory-resident form list; then display the contents of the workspace. (The form is marked as being displayed for a later refresh
operation.)

DISP

Load a workspace with a form from a library or a memory-resident
form list; then display the contents of the workspace. (The form is
marked as being displayed for a later refresh operation.)

DISPW Display the contents of a workspace. (The form is marked as being
displayed for a later refresh operation.)
DWKSP Detach aworkspace from the list of attached form workspaces.
LOAD

Read a form description from the library or memory-resident list
into the form workspace.

NDISP Mark a form as being not displayed, but do not delete it from the
workspace. ("Not displayed" means not displayed in a refresh operation.)
SWKSP Make the specified workspace the current workspace.
You can detach workspaces either individually by issuing a DWKSP call or
collectively by issuing a DTERM call.
Figure 2-2 shows two VTlOO-compatible terminals attached to an FMS
application. Each terminal must be attached by an ATERM call to the Form
Driver in the application program before being used by a terminal operator.
Each terminal has attached to it any number of workspaces. Each workspace
can store one form description and must be attached to a specific terminal by
an AWKSP call before a form description can be stored in it.

2-6

Form Characteristics

Application
Program Calls
Channel 1

Terminal 1

Channel 2

Terminal 2

Workspace 1A

Workspace 2A

Workspace 1B

Workspace 28

Workspace 2C

ZK-1838-84

Figure 2-2: Attached Terminals and Related Form Workspaces
You maintain control over which form is being updated by specifying the current terminal and the current workspace. The STERM call specifies which
terminal is the current terminal. The SWKSP call specifies which of that terminal's workspaces contains the form description to be updated.
To work on a different form in a workspace attached to a terminal that is not
the current terminal, you need issue only a SWKSP call, since the Form
Driver automatically switches to the associated TCA. For example, if the current workspace is workspace lB and you want to address the form in workspace 2C, you issue the following:
CALL FOV$SWKSP <WKSPZC>

You can determine the current terminal and workspace at any time by issuing a RETCX call to ensure that the proper form is being updated.

2.1.5 The Help Function
Whenever your program issues a call for an operator response, the Form
Driver can display two levels of help if the operator requests it- help for the
field in which the cursor is located and help for the entire form. When the
operator presses the Help key once, the Form Driver displays the help text
that was specified as a field attribute, if any was specified. Then, when the
operator presses the help key again, the Form Driver displays the Help form
that was specified as a form-wide attribute, if any was specified.

Form Characteristics

2-7

The operator can erase any help form and have the Form Driver restore the
original form at any time. The cursor's position in the original form and all
field values are unchanged. If the help form does not overlay the current form,
the current form remains on the screen. Otherwise, the help form replaces the
portion of the current form that it overlaps.
For each form in your application, both the help text for fields and the help
forms have to be specified when the form is created or changed with the Form
Editor or the Form Language. Help forms for any disk-resident forms must be
stored in the same form library file as the latter.

2.1.6

Field Processing Order

The Form Driver processes multiple fields of a form in the order specified in
the form description. This order determines where "next" and "previous"
functions take the cursor when the operator presses the corresponding keys
to move from field to field. It is also the order in which field values are
returned in GETAL, PUTAL, RETAL, GETSC, and PUTSC calls and the derivation of"first" and "last" fields in forms and scrolled lines.
Your program can, nonetheless, control the order in which the operator works
with fields. Your program can completely control the access order by issuing a
GET call to get the value of a specified field. By repeating this call and specifying different fields, your program requires the operator to complete the
fields in the order specified.
Your program can allow the operator partial control by issuing the GETAF
call, which allows the operator to choose any field in the form. The operator
can respond in only one field, but it can be any modifiable field in the form.
Since this call also identifies the name of the completed field, your program
can then direct the operator to any other field.
Your program can allow the operator complete control over the order of modifying fields by issuing GETAL, the call for all field values. But the Form
Driver returns the field values to your program in a single character string
with fields appearing in the order specified in the form description. The Form
Driver returns to your application when the operator signals that the entire
form is complete.
In the returned field values, the length of each field value is the full length of
the field. If the operator enters a value that is shorter than the field, that
value is padded out to the field length with the fill character assigned to the
field. For a right-justified field, the fill characters precede the value; for a leftjustified field, they follow the value.
Two calls, PUTAL and PUTSC, output more than one field value. The PUTAL
call specifies new workspace values for all fields in the form and displays the
values ifthe form is displayed. The PUTSC call loads the workspace and displays the field values for one line of a scrolled area.
In both PUTAL and PUTSC, a single character string of field values is written in the order specified in the form description.

2-8

Form Characteristics

2.1.7

Text, Field-Marker Characters, and Video Attributes

After displaying a form, the Form Driver normally is concerned with only the
information that relates to the fields, such as the field picture, the fill and
clear characters, the default value, and the line of help information. Unless
the operator presses the Refresh key, the Form Driver makes no further use of
information that is not related to the fields, such as the text in the form, the
field-marker characters, or the video attributes of the characters displayed.
In particular, the field values that the Form Driver returns do not contain any
of the field-marker characters that the operator sees, such as the hyphen, decimal point, slash, and minus sign. In addition, the field values that your program passes to the Form Driver to display must not include field-marker
characters. These field-marker characters are used for display only. They
identify certain positions within a field.
2.1.8

Processing Fields

2.1.8.1 Field Pictures - The Form Driver checks the field pictures only when
the operator is typing field values. The values that your program passes to the
Form Driver for display are not checked for correspondence with the field
pictures.

When the operator is responding, a field picture is used to:
• Check that each character satisfies the requirements of the picture character at the corresponding position. For example, in a field that has the mixed
picture 999AAA, the Form Driver accepts only digits in the first three positions and only letters in the last three positions.
• Limit the operator's use of the Insert and Overstrike modes of entering field
values. For example, the operator cannot change the combination of modes
used for a fixed-decimal field or use Insert mode when completing a field
that has a mixed picture.
·
2.1.8.2

Right Justified and Left Justified Field Attributes -

The Form Driver

uses the Right Justified and Left Justified attributes to:
• Determine the position of the cursor when it is first displayed in a field.
• Align the field value both on the screen and in the form workspace when
the value is shorter than its field. The value in a right-justified field always
ends at the rightmost character position in a field; the value in a left-justified field always starts at the leftmost character position in a field.
• Determine when the operator has filled a field if the field has the Autotab
attribute.
• Set the default mode of entering values in a field. Insert mode is the default
for a right-justified field, and Overstrike mode is the default for a left-justified field.

Form Characteristics

2-9

Clear Character and Fill Character Attributes - The Clear Character
and Fill Character attributes affect the way fields whose values do not fill the
field are padded on the screen and in the form workspace. The clear character
is displayed, and the fill character is inserted as padding in the form workspace. A field with no value is displayed with only the assigned clear character and is stored in the form workspace with only the assigned fill character.
2.1.8.3

Where padding an input field value is necessary, the Zero Fill attribute
directs the Form Driver to pad with zeros in the form workspace. If Zero Fill is
not specified, space characters are used to pad in the workspace.
The clear character can be any printing character.
Default Field Value - When you display a form, the Form Driver displays the default field values and stores them as the current field values in
the form workspace. But the Form Editor, the Form Language Translator,
and the Form Driver do not check the default values.

2.1.8.4

Although the Form Editor and the Form Language Translator allow you to
assign the numeric default value 13467 for a field with the picture AAAAA,
for example, and the Form Driver displays such a value, the Form Driver does
not allow the operator to enter the value. Therefore, when developing your
application, you must check that the default value is proper for the field.
2.1.8.5 Autotab Attribute - When the operator types the character that fills a
field having the Autotab attribute, the Form Driver terminates the field as if
the operator had pressed the Next Field key. (However, different terminators
are returned for fields completed by the Autotab attribute and by the Next
Field key.)

If a field has the Autotab attribute, the Form Driver determines that the field
has been filled as follows:

• For a Must Fill attribute assigned to the field, the operator must have
entered enough characters to fill the field.
• For a left-justified field, the operator must have typed a character in the
rightmost character position of the field.
• For a right-justified field, the leftmost character position must contain a
character other than the fill character.
2.1.8.6 Response Required and Must Fill Attributes - The Form Driver checks
the validity of an operator's response in a field having the Response Required
or Must Fill attribute.

In a field that has the Response Required attribute, the field must contain at
least one character other than the assigned fill character before the program
will continue to the next field.
In a field that has the Must Fill attribute, the field must contain nothing or
must be filled completely. The Form Driver does not accept a field value that
is shorter than the field length or a value that contains a fill character.

2-10

Form Characteristics

The occurrence of such checking depends on which call your program issues
for an operator response. For the call to get all the form's field values from the
operator (GETAL), for example, the Form Driver checks the values for each of
these fields when the operator terminates input to the field by pressing the
Next Field key or the Enter Form key. In addition, when the operator presses
the Enter Form key, the Form Driver checks all modifiable fields in the form.
For other calls, the Form Driver checks the values only when the operator
terminates the field with the Next Field key or the Enter Form key.
2.1.8.7 Fixed Decimal Attribute - The Form Driver makes use of the Fixed

Decimal attribute to:
• Align the parts of the field value that are to the left and to the right of the
decimal point. The Form Driver retrieves input from the part to the left of
the decimal point as a right-justified field and the part to the right as a leftjustified field.
• Determine the fill and clear characters for the left and right parts of the
field. The Form Driver displays the part to the right of the decimal point as
if it were in a zero fill, clear character zero, and left-justified field, regardless of whether the Zero Fill or Clear Character attribute is assigned.
The Form Driver applies the assigned Zero Fill or Clear Character attribute only to the part of the value that is to the left of the decimal point. Note
that if the fill character for the field is not zero, the Must Fill attribute
requires entry and does not allow the usual option of leaving the field
empty.
• Determine the position of the cursor when it is first displayed in a field. The
cursor is placed at the decimal point, the hanging cursor position for the left
part of the field. Output to fixed-decimal fields is treated as if the field were
right justified. Such output should not include the decimal point, which is a
field marker in fixed-decimal fields.
Display Only Attribute - Fields having the Display Only attribute
allow you to display their values without letting an operator enter new values. The Form Driver does not allow the operator to position the cursor in a
display-only field. When the operator presses the Next Field or the Previous
Field key to move the cursor from field to field, the cursor jumps past displayonly fields as if they were part of the form's background text. Note, however,
that data values of these fields are returned from calls such as GETAL and
RETAL.
2.1.8.8

2.1.8.9 No Echo Attribute - The Form Driver uses the No Echo attribute to
prohibit field values from being displayed in fields. Not even the clear character or assigned video attributes are displayed in that field. When the operator
enters a value in an No Echo field or when your program issues a call to display a field value in an No Echo field, the Form Driver returns the field value
to your program and stores it in the form workspace but does not display it.

Form Characteristics

2-11

When your program uses the SPON call
to turn on the supervisor-only mode, the Form Driver prevents the operator
from entering values for fields that have the Supervisor Only attribute. After
your program issues the SPON call, the Form Driver treats all fields that
have the Supervisor Only attribute as display-only fields. This state, which
remains in effect until you issue the SPOFF call, applies to all forms that are
displayed on a given terminal. When the program issues the SPOFF call, the
Form Driver ignores the Supervisor Only attribute until the program issues
the SPON call again.
2·.1.8.10 Supervisor Only Attribute -

The initial state for a terminal is SPON. That is, when a terminal is attached,
its supervisor-only flag is turned on, thereby disallowing input to fields having the Supervisor Only attribute.
2.1.8.11 Scrolling - Although the Form Editor, the Form Language Translator, and the Form Driver do not allow you to use a form that is longer than
23 screen lines, these components allow you to define sections within a form
for displaying portions of large data tables.

A data table is called scrolled because you can "roll" it upward or downward
to display the lines that you want the operator to see or to work on. A scrolled
area is a window into a form, showing a relatively large amount of data a few
lines at a time.
A scrolled area can be as small as one line. Within one form you can define as
many separate scrolled areas as will fit within 23 lines. Each line can have as
many separate fields as will fit on one screen line. Within each scrolled area,
however, all lines must be identical with respect to the number, size, and
attributes of fields and all other details.
Because the Form Driver can store field values only for the fields that are on
the terminal screen, your program must maintain all scrolled area field values that are not displayed - that is, all the values that are "above" and
"below" each scrolled area. When your program scrolls the lines of a scrolled
area upward or downward, the program must collect the lines of values
scrolled out of the area and display any line of values scrolled into the area.
Chapter 3, Programming Techniques and Examples, includes some programming examples of scrolled area use.
Date and Time Attributes - If a field has one of these attributes, the
Form Driver automatically displays the system date or time in the field
either when the form is loaded or at any other time when the field default is
loaded. The date or time is updated whenever the field default is explicitly
loaded; a PUTD or a PUTDA call causes the update, whereas a RFRSH call
does not.
2.1.8.12

Note that only the field default processing is affected; you cannot supply a
field default for such a field. You can supply any other field attributes and
process the field the way you want, but whenever the field default is displayed
by the Form Driver, the date or time is displayed.

2-12

Form Characteristics

2.2

User Action Routines
A user action routine (UAR) is a subroutine that provides special processing
during the execution of an FMS application program. A UAR is not in-line
code; rather, it is often coded and compiled separately from your program and
is called from the Form Driver. A UAR's object code is later linked with your
program's .OBJ file to form the executable run-time module.
Each UAR is associated with a form or with fields within a form. When a form
is designed, the form designer can request that the UAR be called whenever
an application program processes that form or field. Then, during execution
of the application program, the UAR is automatically called when the terminal operator presses:
• A field terminator key to signal termination of a field or a form (called a
field completion UAR)
• The Help key (called a help UAR)
• A function key that is not reserved for FMS (called a function key UAR)
When the UAR ends, it returns a completion code to the Form Driver, indicating whether the routine executed successfully or failed. A UAR can include a
return context call (RETCX) to the Form Driver to get any current context
information it might require or any other Form Driver call - for example
RET - to get values of fields.
The following actions are required before a user action routine can be used:
1. The form designer must use the Form Editor or the Form Language
Translator to assign a name and associated parameters to the UAR.

2. The form designer must use the appropriate Form Application Aid to
create a UAR vector module.
3. The application programmer must code the proce4ure that the UAR is to
perform.
4. The application programmer must link the object module containing the
names of all U ARs to be called with the application program.

2.2.1

Field Completion UARs

A field completion user action routine is a function routine that is executed at
run time whenever the operator finishes entering data in a field - that is,
when an Autotab field has been filled or a field terminator key has been
pressed.
A field completion UAR is not called under these conditions:
• The field terminator is Previous Field
• The terminator is a function key not reserved for FMS
• The field was terminated with an illegal terminator (see description of
ILTRM)

Form Characteristics

. 2-13

(A function key transformed into a Next Field or an Enter Form terminator
by a function key UAR does, however, cause a field completion UAR to be
called.)
During the Assign phase of the Form Editor or in using the Form Language
Translator, the form designer can identify the name of the UAR and a parameter associated with it. The parameter is a string of up to 80 characters.
Each modifiable field in the form can have up to 15 field completion U ARs
associated with it. During program execution these UARs are executed each
time the operator finishes entering data in a field.
A field completion UAR is also called when your program issues a PFT call
with a terminator code of FDV$K__FT_NTR. This facility lets your program
check the validity of each nonscrolled field, just as the Form Driver checks
operator data entry for Response Required or Must Fill fields. Note that in a
GETAL call, the Enter Form function causes the Form Driver to call all field
completion U ARs for nonscrolled fields.
All field completion U ARs are functions that return status codes. These codes
indicate whether or not a UAR performed successfully. The status codes
returned by the UAR and the corresponding actions that the Form Driver
performs are listed below. The Form Driver interprets any other code as a
programming error, terminates the GET-type call, and returns a status code
of FDV$_UAR.
Status codes returned by UARs do not comply with VMS coding standards
(for cross-system compatibility reasons).
If a timeout occurs or a CANCL call is issued while the operator is performing
a field input operation, the input operation ends immediately, no field completion U ARs are called, and any field value returned is undefined.

FDV$K_UVAL__FAIL

Field validation failure. The Form Driver assumes
that the field data is in error and requires that the
field be reentered. This is the same condition that
occurs when the operator types a character that
does not agree with the field picture; the Form
Driver rejects the input, and the operator is
required to reenter the data. No further UARs
associated with this field are called if this code is
returned.

FDV$K_UVAL_suc

Field validation success; continue processing. The
Form Driver calls any additional action routines
associated with this field. If no more exist, the
Form Driver completes the field entry normally.
If there is no field entry UAR, the Form Driver acts
as if one were called and returns this completion
code.

2-14 ,

Form Characteristics

FDV$K_UVAL--END

Field validation success; end further processing of
the field. No more UARs associated with this field
are called, and the field processing terminates normally.

See Chapter 3 for examples of field completion U ARs.

2.2.2

Help UARs

The operator requests help by pressing the key designated as the Help key.
There are two times during the processing of help that a UAR can be called.
Before the normal Form Driver-supplied help processing begins, the "prehelp" UAR is called. After the normal Form Driver-supplied help processing
is exhausted, the "post-help" UAR is called.
2.2.2.1 Pre-Help UAR - A pre-help UAR is called to allow your help text to
intercept any help processing provided by FMS. Based on the completion code
returned by the UAR, the Form Driver acts as follows:

FDV$K_UHELP_NO

The Form Driver assumes that no help processing
was performed and proceeds with the normal help
processing. That Help was pressed once already is
recorded, and any subsequent pressing of the Help
_key does not result in the Form Driver's calling the
pre-help UAR again.
lfno pre-help UAR was specified for the form, the
Form Driver acts as if one were called and returns
a code ofFDV$K_UHELP_NO.

FDV$K_UHELPED

The Form Driver assumes that help was given by
the UAR and provides no further help processing
for the request. The Form Driver notes that the
operator has pressed the Help key at least once for
the current field. Any subsequent pressing of the
Help key does not, therefore, result in the Form
Driver's calling the pre-help UAR again.

FDV$K_UHELP_ALL

The Form Driver assumes that help was given by
the UAR and provides no further help processing
for the request. The Form Driver does not record
that the operator pressed the Help key once
already, and therefore any subsequent pressing of
the Help key results in the Form Driver's calling
the pre-help UAR again. This completion code
allows a UAR to take over all help processing by
ensuring that every -time the Help key is pressed,
the pre-help UAR is called.

The Form Driver interprets any other code as a programming error. The
GET-type call or the WAIT call is terminated, and a status code of
FDV$_UAR is returned.

Form Characteristics

2r-15

2.2.2.2 Post-Help UAR - This UAR is called to allow your program to supply

some form of additional help after the the Form Driver-supplied help
messages are exhausted. Based on the UAR completion code returned, the
Form Driver does the following:
FDV$K-UHELP_NO

The Form Driver issues its HELP EXHAUSTED
message. If the operator presses the Help key
again, the help sequence starts over again.
If no post-help UAR was specified, the Form Driver
acts as if it called one and returns a completion
code of FDV$K_UHELP_NO.

FDV$K_UHELPED

The Form Driver assumes that the post-help UAR
has provided additional help information to the
operator. If the operator presses the Help key
again, the help sequence starts over again.

FDV$K_UHELP_ALL

The Form Driver assumes that the post-help UAR
has provided additional help information to the
operator. If the operator presses the Help key
again, the UAR is called again.

The Form Driver interprets any other code as a programming error. The call
is terminated, and a status code ofFDV$_UAR is returned.
The Form Driver allows a depth of 15 in UAR nesting. Help is handled internally as a UAR, so it contributes 1 to the nesting depth each time the HELP
key is pressed. A pre-or post-help UAR adds another level to the depth.

2.2.3 Help Request Processing
When the Form Driver is processing an input call by your program, the operator can request help from the system by pressing the Help key. The current
request then stops, and the Form Driver acts as follows:
1. If the operator.has not previously pressed the Help key during the process-

ing of the current field, the following actions occur:
a. The Form Driver calls the pre-help UAR. If the UAR returns the status
code FDV$K_UHELP_NO, the Form Driver attempts to display a single help line for the current field. (See the discussion ofUARs above for
information on UAR status codes.) Ifno help line exists for the field, the
Form Driver goes on to step 2; otherwise, the Form Driver displays the
help line, and processing of the the Help key is complete. The next time
the operator presses the Help key, processing starts with step 2.
b. If the UAR returns FDV$K_UHELPED as a status code, the Form
Driver assumes that the normal single-line help is to be suppressed and
that the UAR has provided separate help. As in step la, the next time
the operator presses the Help key, the Form Driver begins processing it
according to step 2.

2-16

Form Characteristics

c. If the UAR returns FDV$K_UHELP_ALL, the Form Driver again
assumes that no further help is needed, but in addition ends its progression through the help support chain. When the operator presses the
Help key again, the Form Driver processes the key according to step 1
again.
2. If step 1 has already been performed, either because a single-line help has
already been given or because none could be given and the Form Driver
proceeded automatically to this step, the following happens:
a. If a help form is associated with the current form, it is displayed on the
screen. Any subsequent pressing of the Help key begins processing
according to step 3.
b. Ifno help form is associated with the form displayed, the post-help UAR
is called.
c. If the UAR returns a status code of FDV$K_UHELPED, the Form
Driver assumes that the UAR provided help in addition to the forms
already displayed. Processing of subsequent pressing of the Help key
resumes according to step 1.
d. If the UAR returns a status code of FDV$K_UHELP_ALL, the Form
Driver assumes that the UAR provided help in addition to the forms
already displayed. Processing of subsequent pressing of the Help key
resumes according to step 2 again.
e. If the UAR returns a status code of FDV$K_UHELP_NO, the Form
Driver assumes that the help available to the operator is exhausted and
proceeds according to step 4.
3. If the operator presses the Help key again, the following occurs:
a. If a help form is associated with the Help form already on the screen,
the new help form is displayed. Any subsequent pressing of the Help
key begins processing according to step 3 again. (The help form on the
screen may have been placed there either during step 2a or by a previous execution of this step.)
b. Ifno help form is associated with the help form displayed, the post-help
UAR is called.
c. If the UAR returns a status code of FDV$K_UHELP_ALL, the Form
Driver assumes that the UAR provided help in addition to the forms
already displayed. Subsequent pressing of the Help key resumes
according to step 3 again.
d. If the UAR returns a status code of FDV$K_UHELPED, the Form
Driver assumes that the UAR provided help in addition to the forms
already displayed. Processing of subsequent pressing of the Help key
resumes according to step 1.
e. If the UAR returns a status code of FDV$K_UHELP_NO, the Form
Driver assumes that the help available to the operator is exhausted and
proceeds according to step 4.

Form Characteristics

2-17

4. All help is presumed to be exhausted. The Form Driver prints a message
indicating that no help is available. Any future Help key processing
resumes according to -step 1 again, allowing the operator to see the full
help sequence again.
Note that when a single help line is displayed, it is displayed on the bottom
line of the screen and is removed from the screen the next time a key is
pressed. When .a help form is displayed, all or part of the screen - depending
on the help form description - is first cleared. The help form is then displayed,
and the Form Driver waits for the operator by executing a WAIT call until the
operator presses either the Help key or one of the two default Enter Form
keys, ENTER or RETURN.

NOTE
This is one of two occasions in the Form Driver- the other is
when you are in Debug mode - that specify the ENTER key or
the RETURN key as choices for the operator, rather than the
more general Enter Form key, which could indicate a redefined
alternate key. This arrangement guarantees that you can get
out of help mode regardless of how you have redefined keys.
If RETURN or ENTER is returned, the form in the current workspace is

returned to its state prior to the displaying of help, and input processing is
resumed. If FDV$K_FT_HELP is returned, the operator has pressed the
Help key, and the Form Driver behaves according to the description above.
A help UAR can change the screen by putting up new forms in workspaces
other than the one current at the time of the UAR call. The Form Driver automatically restores the current workspace and redisplays the current workspace's form if it is overlaid by UAR action.
If a timeout or a cancel condition occurs during help processing, the call is
terminated without restoration of any part of the screen. Your program can
remove any single-line help from the bottom of the screen by issuing a PUTL
call and can restore the rest of the screen by issuing a RFRSH call.
Any call to a PUT or a GET function restores the current workspace's form
automatically. Thus, even with a timeout or a cancel condition, your program
need not issue a RFRSH call if the same form and workspace are going to be
used.

2.2.4 Function Key UARs
A function key UAR can be called whenever the operator presses a key not
interpreted by FMS. Function keys include all nondata keys that are not
FMS functions: control keys, special keys that produce escape sequences - for
example, the Uparrow key - and Gold sequences, described later in this
chapter.

2-18

Form Characteristics

FMS uses some of these keys for editing or for field terminators. You can redefine keys associated with these functions or delete the functions, thus freeing
more keys for your program. See Section 2.4.2 for lists of all function keys.
When the operator presses one of these keys during input to a GET-type call
or a WAIT call and if the current workspace has a form in it that is marked as
being displayed and that has a function key UAR, the Form Driver calls the
function key UAR. Further processing depends on the value returned by the
UAR, as listed below.
If your program has requested that illegal terminators be returned to it
instead of being signaled to the operator (see description of the ILTRM call in
Chapter 5), the Form Driver also calls a function key UAR with the illegal
terminator. (See Section 2.3.6.8.)

The function key UAR can issue a RETCX call to determine which function
key the operator pressed.
Depending on the completion code returned by the UAR, the Form Driver
acts as follows:
FDV$K_UKEY-ERR

The Form Driver assumes that no function is
defined for the key, the pressing of the key is
treated as an illegal keystroke, an error is signaled, and the key is ignored. No field completion
UARs are called.

FDV$K_UKEY_TRM

The Form Driver resumes processing of the
GET-type call or WAIT call, treating the function
key as a key to be returned to your program as a
terminator. That is, the code immediately terminates any input operation and is returned as the
field terminator code. No field completion UARs
are called.

FDV$K_UKEY_NXT

The Form Driver completes field or WAIT processing, treating the function key as if the operator
had pressed the Next Field key. If the call is a
GET-type call, Must Fill and Response Required
attributes are checked, and field completion U ARs
are called next if any are defined for the field. If
this function key results in completion of the
entire call, Next Field is recorded as the field terminator character.

Form Characteristics

2-19

FDV$K_UKEY_NTR

The Form Driver completes field or WAIT processing, treating the function key as if the operator
had pressed the Enter Form key. If the Form
Driver is processing a GET-type call, Must Fill and
Response Required field attributes are checked,
and field completion U ARs are called next if any
are defined for the field. This completion code
causes Enter Form to be recorded as the field terminator if the operator entered data that was recognized as valid by the Form Driver.

FDV$K_UKEY_suc

The Form Driver resumes processing of the WAIT
or the current field, but otherwise ignores the key,
assuming that the UAR successfully performed
any processing associated with the key. No field
completion U ARs are called.

The Form Driver interprets any other code as a programming error, terminates the GET-type call, and returns a status code of FDV$_UAR.

2.2.5

Legal Actions in a UAR

Your program can issue any Form Driver call from a UAR if you observe the
following restrictions:
1. You cannot detach the TCA or workspace that is current at the time the

UAR is executing.
2. You.cannot alter the current ~orkspace by loading a new form into it.
Your program can issue PUT or GET calls, switch to a' new workspace, load a
new form into a workspace, clear the screen, or take any action you might
take if no UAR were to be called. The Form Driver automatically restores the
pre-UAR context after the UAR completes its execution. If a UAR changes
the screen, the Form Driver ensures that the form in the current workspace is
restored to the screen.
The context restored by the Form Driver is:
• Current terminal
• Current workspace
• Current field
• Last terminator entered

2-20

Form Characteristics

Note that the Form Driver does not restore the current field's cursor position
or mode of character insertion (Insert or Overstrike). This condition allows a
UAR to perform field editing and to reposition the cursor within a-field before
returning to the Form Driver.
You should be very careful about performing input from a UAR, since this is
recursive use of the Form Driver. It is easy to get into an infinite recursion by
issuing a GET from a field that calls a field completion UAR that issues a
GET, and so on. It is also important to be careful about issuing GET calls from
a function key UAR, for the same reason.
The Form Driver allows UARs to be nested to a maximum level of 15. Nesting
to a deeper level causes an FDV$_UDP error to be returned to the call that
generated the UAR.

2.3

Interaction with the Terminal Operator
The operator has no control until your program allows it by issuing one of the
five Form Driver calls for an operator response:
·
GET

To get the value of a specified field

GETAF

To get the value of a single field that the operator chooses

GETAL

To get all field values for the current form

GETSC

To get all field values for a line in a scrolled area

WAIT

To wait for the operator to enter a terminator

These five calls put the operator in control until the requirements of the call
are satisfied. For example, after your program issues the. GET call for the
value of a specific field, the operator can type and make corrections. The operator also can request help by pressing the Help key. It is only when the operator terminates the field by pressing a field terminator key, such as the Next
Field key, that the Form Driver returns control to your program.
Each of the four GET-type calls also returns a status code indicating that a
field has been modified - that is, that at least one character in the field has
been entered or deleted during the processing of the call. Note, however, that
if the operator enters a character and replaces it with the original value, the
field is still considered modified.
This section introduces the three kinds of operator activity:
• Correcting errors and requesting help
• Editing fields
• Terminating and choosing fields

Form Characteristics

2-21

2.3.1

Signaling and Recovering from Errors

The Form Driver responds to typing errors and invalid uses of the editing and
field termination functions by signaling the operator and displaying
messages on the bottom line of the screen.
For all errors, the Form Driver either rings the terminal bell or reverses the
video according to the signal mode that is in effect (see description of the
SSIGQ call) and ignores the invalid character or function. The Form Driver
also displays a one-line explanation at the bottom of the screen. For example,
when an operator tries to enter a letter in a field that has been designed to
accept only numbers, the Form Driver signals the operator and displays the
following message:
NUMERIC REQUIRED

The Appendix of the VAX FMS Utilities Reference Manual lists and explains
all messages that can appear.
The Form Driver also provides a Debug mode of operation, which produces a
set of error messages that help you in developing and refining your FMS
application programs. If you are running your program in Debug mode and
an error occurs as the result of a call on the Form Driver, the Form Driver
stops your program, signals you, displays the Debug mode message on the
bottom of the screen, and waits for you to press the ENTER or the RETURN
key, regardless of how you have redefined any keys, before _continuing execution of your program.
2.3.1.1

Help Key and Help Messages -

The Help function can display two

levels of information.
When the operator presses the Help key for the first time, the Form Driver
determines whether a help message exists for the current field. If such a oneline help message exists, the Form Driver displays it on the last line of the
screen. The cursor remains in place within the field.
If the one-line help message is not sufficiently helpful, the operator can press
the Help key a second time. The Form Driver then determines whether a help
form exists for the current form.
If a help form exists, the Form Driver displays it while saving the context of

the current form. Each help form can have yet another help form associated
with it that is also displayed.
The operator presses the Enter Form key to return to the original form. In
response, the Form Driver restores the form and cursor to what they were
before the Help key was pressed.

2-22

Form Characteristics

If no one-line help message for a field exists, the Form Driver displays the
help form directly. When no more help is available, the Form Driver displays
a message to that effect on the last line of the screen. When the operator next
types a field terminator, the Form Driver clears the last line.

Note that although this is the normal sequence for help processing, help
UARs can alter it. See Section 2.2.2.
Your program
must be responsible for checking operator responses at certain times. The
Form Driver cannot distinguish valid operator responses from invalid ones in
two instances.

2.3.1.2

Checking Operator Responses from Your Program -

First, although the Form Driver accepts only the operator responses that
meet the requirements of a field attribute that was assigned with the Form
Editor or the Form Language Translator,. the Form Driver cannot detect a
field value that is invalid in your application. Second, when an operator uses
certain function keys to terminate work with a field, the Form Driver does no
field checking (Response Required, Must Fill, or Field Completion UARs),
leaving that task to your program.
In both of these instances, you can design your program to detect errors and
other conditions and to display messages for the operator. Chapter 3 describes
some processes and techniques.
Refreshing the Screen: Typing CTRL/R - Hold down the CTRL key
and press the R key on the keyboard. When the operator types this character,
the Form Driver refreshes the screen. That is, the screen is cleared, and all
forms currently marked as displayed are redisplayed.
2.3.1.3

2.3.2

Field Editing Functions

Table 2-1 summarizes the field editing functions that the Form Driver provides and lists the default keys that control the functions. These functions are
executed entirely by the Form Driver. You can implement additional functions for the operator by interpreting any function keys not used by FMS.
Such functions are implemented by your program after the Form Driver
returns control to it.

Form Characteristics

2-23

Table 2-1: Field Editing Keys, Functions, and Usage for the Form Driver
Default Key

Usage

Function

Leftarrow

Cursor Left

Moves the cursor to the preceding data character position within the field, skipping any
field-marker character.

Rightarrow

Cursor Right

Moves the cursor to the next data character
position within the field, skipping any fieldmarker character.

DELETE

Delete Character

In Insert mode, deletes the character at the
cursor's left and closes the space.
In Overstrike mode, moves the cursor to the
preceding character position within the field,
but deletes it only when the character is the
last nonblank one in a left-justified field.

LINEFEED or F13

Delete Field

Deletes the entire field and resets the mode of
character insertion to the default mode for the
field (Overstrike or Insert).

PFl or Blue

Gold Key

Starts a Gold, or 2-character, sequence. Pressing the Gold key several times is equivalent to
press.ing it once.

PFl DELETE or
Blue DELETE

Reset

Cancels a Gold sequence. If the operator cannot remember if a Gold sequence was started,
this sequence safely allows the retyping of the
function.

PF1PF3or
Blue Gray

Insert Mode

Sets Insert mode.

PF3orGray

Overstrike Mode

Sets Overstrike mode.

PF, Red or Help

Help

First, displays the help text for the cursor's
field and then displays successive help forms
for the current form.

CTRL/R

Refresh Screen

Refreshes the screen, with all forms marked
as displayed.

Most
keyboard
keys

Insertion

The keys for the printing characters on the
keyboard insert their characters. In the normal, or numeric, keypad mode, the numeric
and punctuation keys on the keypad also
insert their characters.

VT100Alternate Keypad Mode - You can set the VTlOOterminal to an
alternate keypad mode or back to a normal (numeric) keypad mode by issuing
the SPADA call. Regardless of the terminal's keypad mode, the editing and
terminator functions remain the same.

2.3.2.1

2.3.2.2 The Cursor's Initial Position in a Field - The initial position of the cur-

sor in a field depends on whether the field has the Right Justified, Left Justified, or Fixed Decimal field attribute.
For right-justified fields, the initial position is just to the right of the last
c~racter position in the field. This position is called the hanging cursor position because the cursor hangs off the end of the field.

2-24

Form Characteristics

For left-justified fields, the initial position is the leftmost character position
in the field.
The cursor's initial position for a fixed-decimal field is the decimal point that
the Form Driver displays. The decimal point is a field-marker character. It is
not stored in the form workspace or returned to your program as part of the
field value.
The decimal point in a fixed-decimal field is the rightmost period or comma in
the field, whichever one is in effect. Any other periods or commas are treated
as normal field-marker characters. A comma is usually used as a decimal
point in Europe, and a period is normally used elsewhere.
The Form.Driver treats the left part as a right-justified field and the right
part as a left-justified field. With the cursor at the initial position, the Form
Driver displays the first digits that the operator types in the part to the left of
the decimal point until the operator types a decimal point. Then the Form
Driver displays the digits that the operator types in the part of the field that is
to the right of the decimal point.
As the operator edits a fixed-decimal value, the Delete Field function deletes
the entire value and returns the cursor to the initial position. The Delete
Character function also deletes the digits in the field value. If the cursor is
just to the right of the decimal point, however, the Delete Character function
moves the cursor back to the decimal point but does not delete it.
2.3.2.3 Inserting a Field Value: The Default Function - For VTlOO keys the

Form Driver accepts the standard letters, numbers, and special characters on
the keyboard that meet the requirements of the field.
For the keyboard keys, insertion of values in fields is the default function. For
the numeric and punctuation keys on the keypad, insertion is also the default
when the keypad is in the normal, or numeric, mode. In both instances, the
operator types values as if using a typewriter.
Insertion is invalid only when it does not meet the field's requirements. For
example, letters are invalid where numbers are required. For a field that does
not have the Autotab attribute, all characters are invalid when the field is
full.
2.3.2.4 The Signed Numeric Picture - A signed numeric picture is treated in

two special ways by the Form Driver. One way allows for acceptance of an
alternate character for the conventional decimal point. The default is for the
Form Driver to allow the period in an N picture and to return it to your program as part of the value of the field.
·
For European-style decimal points, your program issues the DPCOM call
with an argument of 1. The Form Driver then accepts the comma as the decimal point for the current terminal. After this call, only the comma is recognized as a decimal point in a signed numeric picture. Calling DPCOM with an
argument of 0 reestablishes the initial decimal point character, the period. In

Form Characteristics

2-25

either case, the decimal point in signed numeric pictures is returned to your
program as part of the field value, unlike the decimal point in fixed-decimal
fields.
The other special treatment is that the entry of a sign ( + or - ) or a decimal
point in a field position having an N picture .causes the entire field to be
checked for valid data. If the field already has a sign or a decimal point, the
character is rejected. Thus, any field having an entire signed numeric picture
is allowed only one sign and only one decimal point. (A mixed picture field
could have more than one sign or decimal point if the additional signs or decimal points were entered into positions that were not signed numeric.)
Note that the Form Driver does not check the position of a sign in a field containing a signed numeric picture; therefore, the sign can occur in the middle
rather than at the beginning or the end of the field. You can write a field completion UAR to enforce a particular position for the sign if your application
requires it.
2.3.2.5 , Deleting a Character

• Default VTlOO Key:

DELETE

The Delete Character function normally deletes the character that is to the
left of the cursor. The function has different effects, however, in Insert and
Overstrike modes.
In Insert mode, the Delete Character function deletes the character to the left
of the cursor and closes up the space. In a left-justified field, the value remains
left justified; in a right-justified field, the value remains right justified.
In Overstrike mode, the Delete Character function moves the cursor one
character to the left. The function does not delete a character in Overstrike
mode except when the character is the rightmost character entered in a leftjustified field.
The Delete Character function is invalid when the cursor is on the leftmost
character in a field.
2.3.2.6 Deleting a Field

• Default VTlOO Key:

LINEFEED

• Default LK201 Key:

F13

Regardless of the cursor's position in a field, the Delete Field function deletes
all characters in the field except field-marker characters. The Form Driver
then displays the assigned clear character for the field and in the form workspace fills the field with the assigned fill character. When the function is complete, the cursor is at the initial position for the field - the leftmost character
for a left-justified field, to the right of the rightmost character for a right-justified field, and on the decimal point for a fixed-decimal field. In addition, the
mode of character insertion is reset to the default mode for the field (Overstrike or Insert).
The Delete Field function is always valid input in a field.

2-26

Form Characteristics

2.3.2.7

Moving the Cursor to the Right

• Default VTlOO Key:

(Rightarrow)

The Cursor Right function normally moves the cursor one character to the
right within a field. However, the cursor always skips the field-marker characters, such as the hyphen (-) and the slash {/).
The Cursor Right function is invalid when the cursor is to the right of the
rightmost character in a field - that is, in the hanging cursor position.
2.3.2.8

Moving the Cursor to the Left

• Default VTlOO Key:

+- (Leftarrow)

The Cursor Left function normally moves the cursor one character to the left
within a field. However, the cursor always skips the field-marker characters
in a field.
The Cursor Left function is invalid when the cursor is on the leftmost character of a field.

2.3.3

Switching the Insertion Modes

• Default VTlOO Keys:

PF3 on the keypad for Overstrike
PFl and PF3, in sequence, on the keypad for
Insert

While the operator is typing a field value, the Insert and Overstrike insertion
modes control how the Form Driver displays the characters. For most of the
different types of fields that can be designed, the operator can control the.
insertion mode by using the Insert and Overstrike functions.
When either the operator or your program first moves the cursor to a field, the
Form Driver sets the insertion mode according to the attributes of the field.
Insert mode is the default for right-justified fields, and Overstrike mode is the
default for left-justified fields.
While the operator types in the Insert mode in a left-justified field, the Form
Driver inserts each character at the cursor's position. The cursor, the cursor's
character, and all characters within the field that are to the right of the cursor
are shifted to the right. In a right-justified field, all characters to the left of
the cursor are shifted to the left, and the character is inserted to the left of the
cursor.
In Overstrike mode, the Form Driver replaces the cursor's character with the
character typed and moves the cursor to the right.
In fields that have mixed pictures, Insert mode is invalid. In fixed-decimal
fields, the Insert and Overstrike functions are ignored, because of the special
data entry conventions that fixed-decimal fields require. In all other
instances, the Insert and Over-Strike functions are valid.

Form Characteristics

2-27

2.3.4

Field Terminators

Each of the keys listed in Table 2-2 controls a field terminator. The Autotab
field attribute also controls a unique terminator. When an operator presses a
key that terminates a field or completes a field that has the Autotab attribute,
the Form Driver either processes the terminator itself and displays the effect
for the operator or returns a unique field terminator code to your program and
leaves the processing to the program. Table 2-2 also gives the processing and
code that the Form Driver uses for each field terminator key.
When you set the VTlOO keypad to alternate keypad mode, the Form Driver
also treats the keypad's numeric keys, comma key(,), hyphen key(-), and decimal point key (.) as field terminators. The codes for these alternate keypad
mode terminators are returned to your program. In addition, keys not
assigned to the Form Driver that are in the following groups are terminators:
control keys, all 2-key sequences beginning with the Gold key - PFl key by
default - and all keys producing escape sequences, such as the Uparrow key.
Table 2-2: Default Field Terminator Keys, Values, Symbols, and Effects
Default
Key

ENTER
or RETURN
(Enter Form)

Value
(Decimal)

Symbol

Description

FDV$K_FT_NTR

Terminates all entries in the form. If
the call being processed is a GETAL
and ifrequired entries are not complete, the Form Driver refuses to
accept the terminator, and the operator remains in control. If required
entries are complete, the terminator
is returned to the program. Therefore, the final effect depends on the
next call that the program initiates
for an operator response.
If any other call is being processed,
only the requirements for the current field must be satisfied. In such
an instance, control is returned to
the program.

TAB
(Next Field)

FDV$K_FT_NXT

Valid only when the current field is
not the last modifiable field in the
form. Moves the cursor to the initial
position of the next field.
Processed by the Form Driver for the
GETAL and GETSC calls and, until
an entry is typed or modified, for the
GETAF call. Returned to the program for the GET call and, after an
entry is typed or modified, the
GETAFcall.

FDV$K_FT_SNX

Scroll forward to the next field. The
Next Field key or the Autotab attribute in a full field terminated input
in the last field of a scrolled line.
Always returned to the program.
(Continued on next page)

2-28

Form Characteristics

Table 2-2: (Cont.) Default Field Terminator Keys, Values, Symbols, and
Effects
Default
Key

Value
(Decimal)

Symbol

Description

BACKSPACE
orF12
(Previous Field)

FDV$KJ'T_pRV

Valid only when the current field is
not the first modifiable field in the
form. Moves the cursor to the initial
position of the previous field.
Processed by the Form Driver for the
GETAL and GETSC calls and, until
an entry is typed or modified, for the
GETAF call. Returned to the program for the GET call and, after an
entry is typed or modified, the
GETAFcall.

None
(Autotab)

FDV$K_FT_SPR

Scroll backward to the previous field.
The BACKSPACE key terminated
input in the first field in a scrolled
line. Always returned to the program.

FDV$K_FT_A.TB

PFl Uparrow
(Exit
Scrolled
Area
Backward)

FDV$K_FT_xBK

Valid input only when the current
field is in a scrolled area. Moves the
cursor out of the scrolled area to the
initial position of the previous field
.that the operator is allowed to complete. Invalid ifthe scrolled area has
the first readable field in the form.

PFl Downarrow
(Exit
Scrolled
Area
Fordward)

FDV$K_FT_xFw

Valid input only when the current
field is in a scrolled area. Moves the
cursor out of the scrolled area to the
initial position of the next field that
the operator is allowed to complete.
Invalid if the scrolled area has the
last readable field in the form.
(Continued on next page)

Form Characteristics

2-29

Table 2-2: (Cont.) Default Field Terminator Keys, Values, Symbols, and
Effects
Value
(Decimal)

Symbol

Description

Downarrow
(Scroll
Forward)

FDV$K_FT-8FW

Valid input only when the current
field is in a scrolled area. The scrolled area is scrolled up, and the current line remains the same physical
line, with new data, or the cursor
moves down one line, and that line
becomes the new current line. The
cursor moves to the initial position of
the first field that the operator is
allowed to complete in the current
line. When processed during a
GETAF call, acts like Exit Scrolled
Area Forward because GETAF operates only on current scrolled line.

Uparrow
(Scroll
Backward)

FDV$K_FT_SBK

Valid input only when the current
field is in a scrolled area. The scrolled area is scrolled down, and the
current line remains the same physical line, with new data, or the cursor
moves up one line, and that line
becomes the new current line. The
cursor moves to the initial position of
the first field that the operator is
allowed to complete in the current
line. When processed during a
GETAF call, acts like Exit Scrolled
Area Backward because GETAF
operates only on current scrolled
line.

Default
Key

This section describes .how your program can use the field terminators and
Form Driver calls to guide an operator from field to field in a form in any
order.
1. Using the GETAL call

• The program initiates the GETAL call.
• The operator uses, at any time, the field terminator keys that move the
cursor from field to field - nonscrolled fields only. The Form Driver
processes these field terminators without returning them to the
program.
• When the operator presses the Enter Form key, the Form Driver checks
for valid values for every nonscrolled modifiable field in the form. If a
field value is found to be invalid, the Form Driver moves the cursor to
the field, and the operator must enter an acceptable value.
When all values are acceptable, the Form Driver returns the field terminator code and the string of field values to the program. If the operator
presses any non-FMS function key, no checking occurs, and the function
key code and string of values are returned to the program.
• The program is then in control of what the operator does next.

2-30

Form Characteristics

2. Using a series of GET calls
• The program initiates the GET call. The operator can type and change
only the entry in the specified field. The Form Driver checks for valid
field data for any field but one terminated by a function key or the Previous Field key.
• When the operator presses a field terminator key, the Form Driver
returns the field terminator code and the single field value to the program. The program then is in control of what the operator does next. For
example, on the basis of the field value or the field terminator, the program can specify the same field or another field in the next GET call.
2.3.5

Field Terminators and Form Driver Calls

When your program issues a call to get an operator response, the Form Driver
allows the operator to type an entry in a field or a terminator in response to a
WAIT call. When the operator presses a field terminator key that completes
the call, the Form Driver passes the field response and the field terminator
code to the program and prohibits the operator from further typing. For a
WAIT call, the Form Driver accepts any terminator or function key and
returns it to your program.
Only the following four Form Driver calls allow the operator to respond in a
field:
GET

To get the value and the field terminator for a specified field

GETAF

To get the value for any one field that the operator chooses, as well
as the field name and the field terminator

GETAL

To get all field values for the current form and the last field terminator used

GETSC

To get all the field values from the current line of a specified
scrolled area and the last field terminator used

For each of these four calls, the Form Driver checks all field terminators. For
example, with the cursor in the first field in a form, the Form Driver accepts
the field terminator for the Next Field key but does not accept the field terminator for the Previous Field key.
Table 2-3 lists the four calls and shows the field terminator keys that complete each call.
The GET call leaves control of responding to any field terminator to your
program.
The GETAF call solicits input for one field but returns control to the program
as soon as the operator modifies a field and presses any field terminator key,
or presses the Enter Form key or any non-FMS terminator key - CTRL key
combination, function key, or Gold key sequence. (A non-FMS terminator can
always complete a call.)
The GETAL call leaves the Form Driver in control of responding to any field,
terminator except when the operator presses the Enter Form key.

Form Characteristics

2-31

The GETSC call leaves the Form Driver in control within a line of a scrolled
area until the operator presses the Enter Form key or any function key that
results in an exit from the scrolled line.
Table 2-3: GET-type Calls and Their Field Terminators
Call

Field Terminator Keys that Complete the Call

GET

Any valid field terminator key, the.Autotab code, or any non-FMS key

GETAF

Enter Form key or any typed field entry followed by any valid field terminator key,
the Autotab code, or any non-FMS key

GETAL

Enter Form key or any non-FMS key

GETSC

Enter Form, Scroll Backward, Scroll Forward, Exit Scrolled Area Backward, Exit
Scrolled Area Forward, Next Field (or Autotab) out oflast field, Previous Field out
of first field, or any non-FMS key

The following principles summarize Tables 2-2 and 2-3:
1. The effects of the field terminator keys cannot be changed from what

DIGITAL has desi~ed in the following calls:
• GETAL
• GETSC
• GETAF before the operator makes a field entry
2. When the operator presses the default Enter Form key or, in response to
the GET call, any field terminator key, the program alone controls the
effect that the operator sees.
For example, if you use the GETAL call in a program, the Next Field key
advances the cursor from field to field according to the order that is built into
the form description. But if you use a series of GET calls instead of the
GETAL call, the program is passed the field terminator code for the Next
Field key and can react to it in any way you specify.
Your program can, for example, issue the PFT call. After the operator uses
any field terminator that returns control to the application program, the program can initiate the PFT call, making the Form Driver follow the effects of
any field terminator key. In the example of a GET· call terminated by the operator's pressing of the Next Field key, the program can react by specifying the
Previous Field key in the PFT call. Then, the effect of the next GET call is to
move the cursor back to the previous field in the form.
Alternatively, your program can issue another GET call. In the example of a
GET call terminated by a Next Field function key, the program can react with
another GET call that specifies by name the next field that the operator is to
complete, regardless of where the field appears on the operator's screen.

2-32

Form Characteristics

2.3.6

Field Terminating Functions

The operator presses terminator keys to move to new fields or a new form.
How the Form Driver processes these functions depends on the current Form
Driver call that is being executed. In many instances, the Form Driver gives
your program an opportunity to intercept and change the terminator function that the operator has used. The Form Driver identifies each terminator
function by means of a unique terminator code.
Because the Form Driver can be executed from either a VT52-, a VTlOO-, or a
VT200-compatible terminal, a set of terms common to both devices is
required to describe logical field terminating functions. In addition, since
your program can modify the association between keys and functions, the
field terminators are referred to by their functions rather than by the names
of particular keys.
Table 2-1 describes the relationship between the logical function keys
referred to in this manual and their corresponding default physical keys on
VT52-, VTlOO-, and VT200-compatible terminals, with an LK201 keyboard.
2.3.6.1

Signaling that the Form Is Complete

• Default VT100NT200 Keys:

ENTER on the keypad
RETURN on the keyboard

• Terminator Code
Value:
Symbol:

0
FDV$K_FT_NTR

The· Enter Form key signals that the operator has completed the current
form.
When a GETAL call is issued, the Form Driver does not accept the Enter
Form key until all field values satisfy their field requirements. A Response
Required field must have a response of at least one character, a Must Fill field
must be either empty or filled, and all field completion UARs must return
success values.
For any other Form Driver call, control is returned to the program if the
requirements for the current field value are satisfied.
2.3.6.2

Moving the Cursor to the Next Field

• Default VT100NT200 Key:

TAB

• Terminator Code
Value:
·Symbol:

1 (when terminating a field outside of a scrolled area)
FDV$K_FT_NXT

Value:
Symbol:

6 (when terminating a field at the end of a scrolled line)
FDV$K_FT_SNX

The Next Field function is valid only when the requirements for the current
field value - Response Required, Must Fill, or field completion UARs - are
satisfied.

Form Characteristics

2-33

The effects of the Next Field function depend on the Form Driver call that is
being executed.
For the GETAL and GETSC calls and for the GETAF call before the operator
enters or changes a field value, the Form Driver processes the function
directly and moves the cursor to the initial position of the next modifiable
field.
For GETSC at the end of a scrolled line, control is returned to the program.
For the GET call and for the GETAF call after the operator enters or changes
a field value, the Form Driver transfers control to the program. The next call
in your program determines what the operator sees. For example, after the
operator terminates a field with the Next Field key, your program might display a new form, calculate and display a value in a display-only field, or issue
another call for another operator response in a specific field.
The function is invalid when the cursor is in the last nonscrolled modifiable
field of the form.
2.3.6.3

Moving the Cursor to the Previous Field

• Default VTlOO Key:

BACKSPACE

• DefaultLK201 Key:

F12

• Terminator Code
Value:
Symbol:

3 (when terminating a field outside of a scrolled area)
FDV$K__FT_pRV

Value:
Symbol:

7 (when terminating a field at the beginning of a scrolled line)
FDV$K__FT_SPR

The effects of the Previous Field key depend on the Form Driver call that is
being executed.
For the GETAL and GETSC calls and for the GETAF call before the operator
enters or changes a field value, the Form Driver processes the function
directly and moves the cursor to the initial position of the previous modifiable
field.
For GETSC at the beginning of a scrolled line, control is returned to the program. For the GET call and for the GETAF call after the operator enters or
changes a field value, the Form Driver transfers control to the program. The
next call in your program determines what the operator sees.
The function is invalid when the cursor is in the first nonscrolled modifiable .
field of the form.

2-34

Form Characteristics

2.3.6.4 Scrolling Backward

• Default VT100NT200 Key:

t (Uparrow)

• Terminator Code
Value:
Symbol:

9
FDV$K_FT_SBK

The Scroll Backward key is valid only when the cursor is in a field that is
within a scrolled area. For GETAF before the operator enters or changes a
field value, the Form Driver processes the key directly and moves the cursor
to the initial position of the first modifiable field before the scrolled area, as if
the key were the Exit Scrolled Area Backward key.
The function transfers control to your program for GET and GETSC and for
GETAF after the operator enters or changes a field value. Therefore, you can
choose to use the function in any way you want, and the effects that the operator sees depend on the next calls that your program issues.
The Form Driver processes the Scroll Backward terminator when you specify
its code in the PFT call. The Form Driver either moves the cursor to the preceding data line within the scrolled area and places the cursor at the initial
position of the first modifiable field in that data line or scrolls the area backward and places the cursor at the initial position of the first modifiable field in
the current line.
When the cursor is on the top screen line of the scrolled area, or if the program
specifies data to update the top line, the Scroll Backward function scrolls the
bottom scrolled line of information off the screen, scrolls a new line of information into the top line of the scrolled area, and moves the intermediate
scrolled lines downward. If the cursor is on the top line and if your program
specifies values for the new line ofinformation, they are displayed; otherwise,
the default field values are displayed.
The function is invalid when the cursor is in a field that is not within a
scrolled area.
2.3.6.5 Scrolling Forward

• Default VT100NT200 Key:

(Downarrow)

• Terminator Code
Value:
8
Symbol: FDV$K_FT_SFW
The Scroll Forward function is valid only when the cursor is in a field that is
within a scrolled area. For GETAF before the operator enters or changes a
field value, the Form Driver processes the key directly and moves the cursor
to the initial position of the first modifiable field after the scrolled area, as if
the key were the Exit Scrolled Area Forward key.
The function transfers control to your program for GET and GETSC and for
GETAF after the operator enters or changes a field value. Therefore, you can
choose to use the function in any way you want, and the effects that the operator sees depend on the next calls that your program issues.

Form Characteristics

2-35

The Form Driver processes the Scroll Forward key when you specify its code
in the PFT call. The Form Driver either moves the cursor to the next data line
within the scrolled area and places the cursor at the initial position of the first
modifiable field in that data line or scrolls the area forward and places the
cursor at the initial position of the first modifiable field in the current line.
When the cursor is on the bottom screen line of the scrolled area, or if the
program specifies data to update the bottom line, the Scroll Forward function
scrolls the top scrolled line of information off the screen, scrolls a new line of
information into the bottom line of the scrolled area, and moves the intermediate scrolled lines upward. If the cursor is on the bottom line and if your program specifies values for the new line of information, they are displayed;
otherwise, the default field values are displayed.
The function is invalid when the cursor is in a field that is not within a
scrolled area.
2.3.6.6

Exiting Scrolled Area Backward

• Default VT100NT200 Key Sequence:

PFl followed by the Uparrow

• Terminator Code
Value:
4
Symbol: FDV$K__FT_XBK
The Exit Scrolled Area Backward key is valid only when the cursor is in a
field that is within a scrolled area. The function transfers control to your program unless your program is executing a GETAF call and the operator has
not yet entered or changed a field value. Therefore, you can usually use the
function in any way you want, and the effects that the operator sees depend
on the next calls that your program issues.
The Form Driver processes the Exit Scrolled Area Backward key when you
specify its code in the PFT call, except when your program is executing a
.GETAF call. The Form Driver moves the cursor to the initial position of the
first modifiable field preceding the scrolled area.
The function is invalid when:
1. The cursor is in a field that is not within a scrolled area.
2. No modifiable field precedes the scrolled area.
2.3.6.7

Exiting Scrolled Area Forward

• Default VT100NT200 Key Sequence:

PFl followed by the Downarrow

• Terminator Code
Value:
5
Symbol: FDV$K__FT_XFW
The Exit Scrolled Area Forward key is valid only when the cursor is in a field
that is within a scrolled area. The function transfers control to your program
unless your program is executing a GETAF call and the operator has not yet

2-38

Form Characteristics

entered or changed a field value. Therefore, you can usually use the function
in any way you want, and the effects that the operator sees depend on the next
calls that your program issues.
The Form Driver processes the Exit Scrolled Area Forward key when you
specify its code in the PFT call, except when your program is executing a
GETAF call. The Form Driver moves the cursor to the initial position of the
first modifiable field following the scrolled area.
The function is invalid when:
1. The cursor is in a field that is not within a scrolled area.
2. No modifiable field follows the scrolled area.
2.3.6.8 Illegal Terminator Interaction - If your program issues the ILTRM call

with an argument of 1, any terminator that is illegal in its current context for example, a Previous Field terminator in the first field of a form - is converted to a special terminator code, treated as ifit came from the pressing of a
function key, and sent to a function key UAR, if any. (See the description of
the ILTRM case in Chapter 5.)
The terminators that are affected are: NXT, ATB, PRV, XBK, XFW, SFW, and
SBK.
The first five of these are illegal if there is no next or previous field. The last
four are illegal if the current field is not in a scrolled area.
The illegal terminator symbols and values are:
FDV$K_FT_ILG_NXT = 11
FDV$K_FT_ILG_pRV = 12
FDV$K_FT_ILG-ATB = 13
FDV$K_FT_ILG_XBK = 14
FDV$K_FT_ILG_xFw = 15
FDV$K_FT_ILG_SFW = 16
FDV$K_FT_ILG_SBK = 17

2.3.7 Alternate Keypad Mode Terminators
Normally, the numeric and punctuation keys on the VTlOO and LK201
keypads produce the same numbers and characters that the corresponding
keyboard keys produce. Therefore, for many common applications, the operator can enter numeric data by using the keypad rather than the keyboard.
For special applications, you can set the VT100NT200 to alternate keypad
mode by issuing the SPADA call from your program or by entemg the DCL
command
$

SET TERMINAL/APPLICATION-KEYPAD

prior to running your application. You can then design the applications to use
the numeric and punctuation keys on the keypad as field terminator keys.

Form Characteristics

2-37

The Form Driver then passes the alternate keypad mode terminators to the
program immediately, regardless of whether the Response Required, Must
Fill, and UAR requirements are satisfied for the form.
Tables 2-6 and 2-7 include lists of the keypad keys that are affected by the
alternate keypad setting and the code that is returned to your program for
each key. Each character returned is the last character in the escape sequence
generated by the key in alternate keypad mode.

2.4

Key Functions and Key Codes
This section provides a fuller explanation of the roles of function keys, key
functions, and key codes and gives their values.

2.4.1

Form Driver Key Functions

Form Driver key functions are actions the Form Driver takes in response to
special keystroke sequences. Key functions, vallies for the DFKBD call, and
default key sequences are given in Table 2-4.
Table2-4: Key Functions
Function
Name

Description

FDV$K_KFJ)LCHR
FDV$K_KF_CRSRT
FDV$K_KF_CRSLF
FDV$K_KFJ)LFLD
FDV$K_KF_INS
FDV$K_KF_OVR
FDV$K_KF_GOLD
FDV$K_KF_RESET
FDV$K_KF_RFRSH
FDV$K_KFJIELP
FDV$K_KF_NXT
FDV$K_KF_pRV
FDV$K_KF_NTR

Delete character
Move cursor right
Move cursor left
Delete Field
Set Insert mode
Set Overstrike mode
Start Gold sequence
Reset Gold sequence
Refresh screen
Help
Next field
Previous field
Form or field complete

FDV$K_KF_SBK
FDV$K_KF_SFW
FDV$K_KF_xBK
FDV$K_KF_xFw

Scroll backward
Scroll forward
Exit scroll area backward
Exit scroll area forward

Default VTlOO
Key sequence .

DFKBD
Value

DELETE
Rightarrow
Leftarrow
LINEFEED
PF1PF3
PF3
PFl
PFlDELETE
CTRL/R
PF2
TAB
BACKSPACE
RETURN
ENTER
Uparrow
Downarrow
PFl Uparrow
PFl Downarrow

1
2
3
4
5
6
7
8
9

10
11
12
13

14
15
16
17

The first nine key functions are called the editing key functions; they are handled internally by the Form Driver and are not returned to your program.
Interpretation of the other key functions is context dependent - they may be
illegal, interpreted by the Form Driver, or returned to the calling program as
terminators.
Terminators are values returned to the calling program to indicate how input
requests were completed. That is, terminators are key codes with a context.

2-38

Form Characteristics

Key functions in the proper context can give rise to a terminator code- not
the same as the key function code. In addition, these key function terminators
can be processed by the PFT call. Key codes that are not key functions are
returned as terminators to the calling program.
For the DFKBD call, FDV$K_KF_NONE is 0, and FDV$K_KF_DFLT is-1.

2.4.2

Form Driver Key Codes

Form Driver key codes are 16-bit encodings of certain key sequences. These
'Sequences, listed in Table 2-5, are control characters, legal ANSI escape
sequences, and 2-stroke sequences beginning with the Gold key.
The definitions include the keystroke combinations interpreted by the Form
Driver. Each combination has a coded value - an integer word - associated
with it. The key codes are used in two ways. The most common is as the terminator to a field; the Form Driver returns terminators, and these are the codes
for those terminators. The other way is to use these values as the key codes
passed to the DFKBD call.
All ASCII graphic characters are treated as data by the Form~Driver and are
not available for use as terminators, except as the second key in a Gold
sequence. The remaining keystroke combinations are divided into three
groups as follows:
1. Control keys, including the DELETE key
2. Escape sequences, including keypad application mode keys, cursor position keys, and program function keys
3. Gold sequences
Control Keys - Control characters-ASCII codes 0 to 31(decimal)and the DELETE key - ASCII code 127(decimal) are not allowed as data in
fields. A control character not defined as a key function is returned to the calling program as a terminator.
2.4.2.1

Control characters can be assigned to key functions, and several are assigned
as defaults. The Form Driver key codes for control keys are listed in Table
2-5.
Note that the operating system may preempt the use of some control keys for example, CTRL/Y. Using control keys other than those assigned as the
defaults may lead to unexpected results.
In Table 2-5, the first column contains the ASCII name· for the control key,
and the second column contains the ASCII value in decimal. Some of these
codes - for example, CR - are produced by editing keys on the keyboard.
Others are available only by holding down, the CTRL key and pressing
another key.
The third column contains the name of the key the operator presses while
holding down the CTRL key. The fourth column contains the Form Driver key
code - the value to be used for the "defkbd" argument of the DFKBD call, or
the value of the key as a terminator.

Form Characteristics

2-39

Note that the low-order byte of the key code is the 7-bit ASCII code for this
key. For those keys used as part of the default Form Driver keyboard, the last
column has the name of the associated key function. Some control keys have
special meanings in terminals and cann~t be used as terminators. This
restriction is noted in the last column, although the absence of a note should
not be taken as a guarantee that the key is ~vailable.
Table 2-5: Key Codes for Control Characters
ASCII
Name

Value
(Decimal)

NUL
SOH
STX
ETX
EOT
ENQ
ACK
BEL
BS
HT
LF
VT
FF
CR

00
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18

SI
DLE
DCl
DC2
DC3
DC4
NAK
SYN
ETB
CAN
EM SUB
ESC
FS
GS
RS

DEL

20
21
22
23
24
25
26
27
28
29
30
31
127

CTRL/Key
@

A
B

D
E
F
G

H
I
J

K
L
M
N
0
p
Q
R

v
w
x
y

Key Value
(as terminator)
1024+00
1024+01
1024+02
1024+03
1024+04
1024+05
1024+06
1024+07
1024+08
1024+09
1024+10
1024+11
1024+12
1024+13
1024+14
1024+15
1024+ 16
1024+17
1024+18
1024+19
1024+20
1024+21
1024+22
1024+23
1024+24
1024+25
1024+26

]
I\

FDV$1LKF_pRV
FDV$1LKF_NXT
FDV$1LKF_I)LFLD
FDV$K_KF_NTR

FDV$K_KF_RFRSH

Not available

[

Default
Assignment

1024+28
1024+29
1024+30
1024+31
1024+127

FDV$K_KF_I)LCHR

2.4.2.2 Escape Sequences - The second group of keys consists of the cursor
control keys, the program function keys, and the application keypad keys
(Table 2-6). Note that the cursor controlkeys and program function keys 1 to
3 are all assigned default Form Driver key functions. The key codes for the
default editing functions are not returned to the program; instead, their functions are performed. For the terminator key functions, the context selected
terminator code corresponding to the key function is returned.

2-40

Form Characteristics

Table 2-6: Key Codes for Escape Sequences
Default
Key Function

Key Code

Value

Name of Key

FDV$ILAR_UP
FDV$K_AR_DOWN
FDV$K_AR_RIGHT
FDV$K_AR_LEFT
FDV$K_PF_l
FDV$K_PF_2
FDV$K_pF_3
FDV$K_PF_4
FDV$K_KP__NTR
FDV$K_KP_COM
FDV$K_KP_HYP
FDV$ILKP_pER
FDV$K_KP_O
FDV$K_KP_l
FDV$K_KP_2
FDV$K_KP_3
FDV$K_KP_4
FDV$K_KP_5
FDV$K_KP_6
FDV$K_KP_7
FDV$K_KP_8
FDV$K_KP_9
FDV$K_FILE1
FDV$K_FILE2
FDV$K_FILE3
FDV$K_FILE4
FDV$K_FILE5
FDV$K_FILE6
FDV$K_FK_F6
FDV$K_FK_F7
FDV$K_FK_F8
FDV$K_FK_F9
FDV$K_FK_F10
FDV$K_FK_Fll
FDV$K_FK_F12
FDV$K_FK_F13
FDV$K_FK_F14
FDV$K_FK_HELP
FDV$K_FK_DO
FDV$K_FK_Fl 7
FDV$K_FK_F18
FDV$K_FK_F19
FDV$K_FK_F20

99
100
101
102
103
104
105
106
107
108
109
110
112
113
114
115
116
117
118
119
120
121
33
34
35
36
37
38
49
50
51
52
53
55
56
57
58
60
61
63
64
65
66

Uparrow
Downarrow
Rightarrow
Leftarrow
VTlOO PFl, VT52 Blue
VTlOO PF2, VT52 Red
VTlOO PF3, VT52 Gray
VT100PF4
Alternate keypad ENTER
Alternate keypad ,
Alternate keypad Alternate keypad .
Alternate keypad 0
Alternate keypad 1
Alternate keypad 2
Alternate keypad 3
Alternate keypad 4
Alternate keypad 5
Alternate keypad 6
Alternate keypad 7
Alternate keypad 8
Alternate keypad 9
LK201 El
LK201E2
LK201E3
LK201E4
LK201E5
LK201 E6
LK201 F6
LK201F7
LK201 F8
LK201 F9
LK201Fl0
LK201 FU
LK201F12
LK201Fl3
LK201 F14
LK201HELP
LK201DO
LK201 F17
LK201Fl8
LK201 F19
LK201F20

FDV$ILKF_SBK
FDV$ILKF_SFW
FDV$ILKF_CRSRT
FDV$K_KF_CRSLF
FDV$1LKF_GOLD
FDV$K_KFJIELP
FDV$K_KF_OVR
FDV$ILKF__NTR

FDV$ILKF_pRV
FDV$ILKF_DLFLD
FDV$K_KF_HELP

2.4.2.3 Gold Sequences - The last group consists of sequences starting with

the Gold key. Any key not preempted by the terminal can follow the Gold key.
Pressing a Gold key more than once is equivalent to pressing it once. The
operator can cancel a Gold key, sequence by entering the
FDV$K_KF-RESET key function; that is, the sequence FDV$K_KF_GOLD
FDV$K_KF-RESET is equivalent to the null sequence.
The key or escape sequence following the Gold key determines the key code as
listed in Table 2-7. The sequences expected to be used most often are given
names.

Form Characteristics

2-41

Table 2-7: Key Codes for Gold Escape Sequences
Key Code

Value

FDV$K_GAR_UP
FDV$K_GAR_J)OWN
FDV$K_GAR_RIGHT
FDV$K_GAR__LEFT
FDV$K_GPF_l

227
228
229
230
231

FDV$K_GPF_2

232

FDV$K_GPF_3

233

FDV$K_GPF_4
FDV$K_GKP_NTR
FDV$K_GKP_COM
FDV$K_GKPJIYP
FDV$K_GKP_pER
FDV$K_GKP_O
FDV$K_GKP_l
FDV$K_GKP-2
FDV$K_GKP_3
FDV$K_GKP_4
FDV$K_GKP_5
FDV$K_GKP_6
FDV$K_GKP_7
FDV$K_GKP_8
FDV$K_GKP_9
FDV$K_GFILE1
FDV$K_GFK_E2
FDV$K_GFK_E3
FDV$K_GFK_E4
FDV$K_GFK_E5
FDV$K_GFK_E6
FDV$K_GFILF6
FDV$K_GFK_F7
FDV$1LGFILF8
FDV$K_GFK_F9
FDV$K_GFK_F10
FDV$K_GFILF11
FDV$K_GFK_Fl2
FDV$K_GFK_Fl3
FDV$1LGFK_Fl4
FDV$1LGFKJIELP
FDV$K_GFK-1)0
FDV$K_FK_Fl 7
FDV$K_GFILF18
FDV$K_GFK_Fl9
FDV$K_GFK_F20

234
235
236
237
238
240
241
242
243
244
245
246
247
248
249
161
162
163
164
165
166
177
178
179
180
181
183
184
185
186
188
189
191
192
193
194

Key Sequence
Gold Uparrow
Gold Downarrow
Gold Rightarrow
Gold Leftarrow
Gold PFl (VTlOO)
Gold Blue (VT52)
Gold PF2 (VTlOO)
Gold Red (VT52)
Gold PF3 (VTlOO)
Gold Gray (VT52)
GoldPF4
Gold Alt keypad ENTER
Gold Alt keypad ,
Gold Alt keypad Gold Alt keypad .
Gold Alt keypad 0
Gold Alt keypad 1
Gold Alt keypad 2
Gold Alt keypad 3
Gold Alt keypad 4
Gold Alt keypad 5
Gold Alt keypad 6
Gold Alt keypad 7
Gold Alt keypad 8
Gold Alt keypad 9
LK201 GOLD El
LK201 GOLD E2
LK201 GOLD E3
LK201 GOLD E4
LK201 GOLD E5
LK201 GOLD E6
LK201 GOLD F6
LK201 GOLD F7
LK201 GOLD F8
LK201 GOLD F9
LK201 GOLD FlO
LK201 GOLD Fll
LK201 GOLD Fl2
LK201 GOLD Fl3
LK201 GOLD Fl4
LK201HELP
LK201DO
LK201 GOLD Fl 7
LK201 GOLD Fl8
LK201 GOLD Fl9
LK201 GOLD F20

Default
Key Function
FDV$1LKF__xBK
FDV$1LKF__xFW
. FDV$ILKF_GOLD
FDV$1LKFJIELP
FDV$1LKF_INS

FDV$1LKFJIELP

Note that the value for a Gold escape sequence is 128 plus the value for the
escape sequence.
No symbols are defined for normal graphic or control keys preceded by the
FDV$K_KF_GOLD key function because there are so many of them. Table
2-8 gives the key codes for these key sequences.

2-42

Form Characteristics

Table 2-8: Key Codes for Gold Sequence
Key
NUL
SOH
STX
ETX
EOT
ENQ,
ACK
BEL
BS
HT
LF
VT
FF
CR

SI
DLE
DCl
DC2
DC3
DC4
NAK
SYN
ETB
CAN
EM
SUB
ESC
FS
GS
RS

SP
!
"
#

$
%

'
(
)

I
0
1
2

3
4

ASCII Value
(Decimal)
00
01
02
03
04
05
06
07
08
09
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
49
50
51
52

Gold Key

Default
Assignment

256+00
256+01
256+02
256+03
256+04
256+05
256+06
256+07
256+08
256+09
256+10
256+11
256+12
256+13
256+14
256+15
256+16
256+17
256+18
256+19
256+20
256+21
256+22
256+23
256+24
256+25
256+26
Not available
256+28
256+29
256+30
256+31
256+32
256+33
256+34
256+35
256+36
256+37
256+38
256+39
256+40
256+41
256+42
256+43
256+44
256+45
256+46
256+47
256+48
250+49
256+50
256+51
256+52
(Continued on next page)

Form Characteristics

2-43

Table 2-8: (Cont.) Key Codes for Gold Sequence
Key
5
6
7
8
9
;

<
>
?
@

A
B

c
D

E
F

G
H
I
J
K
L
M
N
0
p
Q

u
v
w

xy
z
[

\
]
A

'
a
b
c
d
e
f
g

h
i
j
k

ASCII Value
(Decimal)

Gold Key

53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

256+53
256+54
256+55
256+56
256+57
256+58
256+59
256+60
256+61
256+62
256+63
256+64
256+65
256+66
256+67
256+68
256+69
256+70
256+71
256+72
256+73
256+74
256+75
256+76
256+77
256+78
256+79
256+80
256+81
256+82
256+83
256+84
256+85
256+86
256+87
256+88
256+89
256+90
256+91
256+92
256+93
256+94
256+95
256+96
256+97
256+98
256+99
256+100
256+101
256+102
256+103
256+104
256+105
256+106
256+107

Default
Assignment

(Continued on next page)

2-44

Form Characteristics

Table 2-8: (Cont.) Key Codes for Gold Sequence
Key

ASCII Value
(Decimal)

Gold Key

Default
Assignment

108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

256+108
256+109
256+110
256+111
256+112
256+113
256+114
256+115
256+116
256+117
256+118
256+119
256+120
256+ 121
256+122
256+123
256+124
256+125
256+126
256+127

FDV$1LKF_RESET

m
n
0

p
q
r

t
u
v

x
y
z
{

I
}

DEL

NOTE
The key sequences listed below are reserved for future use by
FMS. FMS may use them as default assignments in future versions. If you use any of them now, you may have to alter your
programs later.
• GoldPF2
•Gold TAB
• Gold BACKSPACE
• Gold CTRL/R
• Gold CTRL/W
• Gold LINEFEED
• Gold RETURN
• Gold Rightarrow
• Gold Leftarrow
In addition, on the LK201 terminal keyboard, the following
key sequences are reserved for future use by FMS:

•El
• E2

• E3
• E4

Form Characteristics

2-46

• E5
• E6
• Gold El
• GoldE2
• GoldE3
• GoldE4
• GoldE5
• GoldE6
•Gold TAB
• Gold F12
• Gold F13
•Gold HELP

2.4.3 Defining Keys
The following example shows how to use the DFKBD call to switch the functions of the RETURN and the TAB keys. After this call is executed, RETURN
or numeric keypad ENTER will mean Next Field (FDV$KJT_NXT), and
TAB will mean Enter Form (FDV$KJT_NTR). The example is given in
FORTRAN.
INTEGER TCA<3>
INTEGER*2 KEYTABLE<4> I FDV$K_KF_NTRt
1033,
1
FOV$K_KF_NXTt 1037 I
CALL FOV$ATERM <%DESCR <TCA) , 12, 1 >
CALL FOV$0FKBD<%DESCR<KEYTABLE> ,z)

2.5

Checking Call Status
To improve the effectiveness of VAX FMS applications and to reduce the time
required for you to produce fully debugged applications, the Form Driver
maintains the completion status of each call and provides five ways for you to
obtain the status:
• Issuing the STAT call, which returns the Form Driver status code for the
most recent call that was processed. The STAT call also returns the RMS
system error code if a call fails because of an error in opening or reading a
form library file or if other system problems are associated with terminal
1/0. The status is returned as an integer longword as specified in an argument of the call.
• Issuing the SSRV call to establish either one or two global variables in your
program to receive the FMS status after every FMS call.

2-46

Form Characteristics

• Issuing any call as a function returning a value. The returned status argument conforms to the VMS calling standard. The status is returned as an
integer longword. Each language has a different way of obtaining the VMS
return status immediately from a call. For example, in FORTRAN, the subroutine call is:
CALL FOV$STAT<JSTAT1JSTAT2>

The function value return call is:
JSTAT=FDV$GET<FI01FVAL1TERM>

• Using the Form Driver Debug mode for displaying explicit messages about
the status of erroneous calls for added support while an FMS application isbeing developed.
• Using the VAXNMS message facility with FMS. You can signal FMS
errors from your program by using the standard VMS message facility. (See
Table 2-9 for a list of the VAX FMS status returns.) You do this by using the
LIB$SIGNAL call. See the Common Run Time Library Manual for a
description of this call.
When a VMS status is returned, it can be signaled as shown below:
STATUS=FOV$LOPEN <'BADFILE'>
CALL LIB$SIGNAL <%VAL <STATUS>>

Table 2-9 lists and describes the FMS status codes and the corresponding
VMS status codes, which are global symbols. For FMS applications, the STAT
call returns one of the listed numeric codes in the first of its two status
arguments.
Two of the status conditions listed in Table 2-9 indicate an error in trying to
open or read a form library file - code values FDV$-10L and FDV$-10R. In
these two instances, the STAT call also returns, in the second status argument RMS system error codes that help to define the exact cause of the problem. For RMS errors, see the VAX/VMS System Messages and Recovery
Procedures Manual.
In addition, error code FDV$_SYS indicates that the Form Driver has
encountered an unexpected error in dealing with the operating system - terminal services, usually. The RMS code can be accessed to find the error status
returned to the Form Driver, which may identify the problem - for example,
network link lost.

Note that the status value FDV$-DLN - data specified too long for outputis reported only in Debug mode and is not returned to your program. Regardless of Form Driver support for Debug mode, the specified data is truncated
when displayed, and the Form Driver completes the call in the normal way.

Form Characteristics

2-47

Table 2-9: FMS and VMS Status Codes

VMS
Status

FMS
Status

Code

Meaning

FDV$-8UC
FDV$.JNC
FDV$_MOD

1
2
3

FDV$__1MP
FDV$_FSP
FDV$__10L

-2

FDV$_FLB
FDV$__1CH
FDV$_FCH

-5
-6

-7

FDV$_FRM
FDV$_FNM

-8
-9

FDV$.LIN
FDV$_FLD
FDV$__NOF
FDV$__DSP

-10
-11
-12
-13

FDV$__NSC
FDV$__DNM
FDV$__DLN

-14
-15
-16

FDV$_UTR
FDV$__10R

-17
-18

FDV$JFN

-19

FDV$__ARG
FDV$__1NI
FDV$_STR
FDV$-1VM

-20
-21
-22
-23

FDV$_FVM

-24

FDV$__1TT
FDV$_TCA
FDV$_STA
FDV$_WID

-25
-26
-27
-28

FDV$__NFL

-29

Successful completion of the call.
Form is incomplete after a PFT call.
Input successful. Field value in "fldval" has been modified by the
operator.
Length specified in "wksp" descriptor is not large enough.
File specification in a LOPEN call was invalid.
Form Driver encountered an error while reading the form library.
(It reads the form library to verify that the file is a form library
file.)
Specified file was not a form library.
Channel specified was either in use or invalid.
Form was not resident, and when the Form Driver attempted to
search for it in a form library, the current library channel was not
open.
Form description is invalid.
Binary form description could not be found either in the form
library, or in the list of memory-resident forms.
Line or portion of form lies outside the visible screen range.
Field doesn't exist, or index value is invalid for field.
Form contains no fields.
Form contains only Display Only fields, or the specified field is
Display Only.
Field named is not a field in a scrolled area.
No Named Data is associated with the specified name or index.
Value argument supplied more data than was required, and some
data was discarded.
Field terminator code is invalid.
1/0 error occurred while Form Driver was reading in a form from
the form library. The 1/0 error code is recorded in the current state.
You can obtain it by issuing the STAT call.
Field terminator code specified in the PFT call cannot be processed
in the context indicated.
Incorrect number of arguments for call.
No workspace is defined.
Value being returned is too large for the variable allocated for it.
Not enough virtual memory could be allocated (either for the TCA
or for the workspace).
An error occl!ll'l'ed in freeing virtual memory allocated to the
application.
Invalid terminal type.
Terminal Control Area is invalid or undefined.
Size of specified TCA is too small.
Form being displayed does not fit on the screen (132-column form
ona VT52).
No form loaded into workspace.

-3

-4

(Continued on next page)

2-48

Form Characteristics

Table 2-9: (Cont.) FMS and VMS Status Codes
VMS
Status
Code

FMS
Status
Code

Meaning

FDV$_1BF

-30

Area not large enough to hold the form.

FDV$_NDS

-31

Form is marked as being not displayed, so no input is possible.

FDV$_UDP

-33

UAR depth was exceeded.

FDV$_UAR

-34

UAR returned an illegal code.

FDV$_UNF

-35

UAR was specified, but not found.

FDV$_CAN

-39

Call was terminated by a CANCL call.

FDV$-1{1F

-40

Illegal key function was specified in DFKBD.

FDV$-1{EX

-41

Too many key codes were defined for some key function in DFKBD.

FDV$-1{T

-42

Key code was given two key functions in DFKBD.

FDV$-1{1L

-43

Illegal key code was given in DFKBD; that is, the key was not on
the list in Chapter 2.

FDV$_TMO

-44

Operator took longer to respond than was allowed by the timeout
value associated with the current terminal, for a GET-type call or
WAIT call.

FDV$_LLI

-45

The Form Driver's internal buffer was not large enough to store
the line image requested (in a RETFL call). The line image
returned is truncated.

FDV$_VAL

-47

The value of an argument is outside the allowed range.

FDV$--1FU

-48

Illegal function while in currently active UAR.

FDV$-8YS

-49

Form Driver encountered system error response.

FDV$--1NA

--50

Request information not available.

2.5.1

Debug Mode Support for Application Program Development

To use the Debug mode of the VAX Form Driver, you need to make the following logical assignment at DCL level:
$ ASSIGN YES FOV$0EBUG

You can then run your application program without having to do any relinking. In Debug mode, the Form Driver reports explicit messages for status conditions of erroneous Form Driver calls. The Form Driver in Debug mode is
useful during VAX/FMS program development.
You can assign and deassign the FDV$DEBUG logical name during execution of your program, since the Form Driver checks the the name upon each
occurrence of an error.
Once you have debugged the program, you should deassign the Form Driver
Debug mode. When your program is running, the operators do not see the
Debug mode messages provided explicitly for program debug. See Section
2.5.2 for signaling the operator.

Form Characteristics

2-49

In Debug mode, the Form Driver signals you by ringing the terminal bell or
reversing the screen video characteristics and displays a message on the bottom line of the screen for any of the error status conditions listed in Table 2-9.
The Appendix in the VAX FMS Utilities Reference Manual lists the messages.

After displaying a Debug mode message, the Form Driver places the cursor in
the lower right corner of the screen until you press the ENTER or the
RETURN key, regardless of how you may have redefined any keys. This process prevents your program from clearing or overwriting a Debug mode message before you have seen it. When you press the ENTER or the RETURN
key, the bottom line is cleared, and your program resumes. It can then issue
the PUTL call to display program-related messages on the bottom screen
line.
The error code is returned to the calling program.
Because the Form Driver explicitly signals all call errors when Debug mode
is in effect, you can use the Form Driver to debug your FMS program. Therefore, after debugging a program, you may choose not to test for certain errors
that should not occur in a fully debugged application - such errors as an
incorrect field name or form name or an incorrect number of arguments in a
call. The safest procedure is, of course, to check status after every Form
Driver call.
Even in a finished FMS program, you should check, at a minimum, 1/0 errors
after calls that:
• Open and close a form library file
• Display a form and must therefore read a form library file
• Solicit operator responses

NOTE
FMS does not interact with the VAX/VMS Debugger.

2.5.2 Signaling the Terminal Operator About Program Errors
Your program can signal an operator about a .problem by issuing the
PUTL call. Here is an example of an 110 error being reported. The following illustration shows one way you can use the PUTL call with the
other status and error-checking features:
1. The program encounters an 1/0 error while trying to display a
form.
2. The program detects the error by checking for a status of <0, using
the STAT call. The call returns the error code -18 (FDV$-10R) ,for
an error in reading a form library file.
3. The program uses the status code as an index into a list of programspecific messages.

2-50

Form Characteristics

4. The program issues the PUTL call to display the message on the
bottom screen line and a SIGOP call to get the operator's attention.
The program then immediately issues the WAIT call to ensure that
the message remains visible until the operator sees it and responds
to it.
The calls are described in full in Chapter 5.
In BASIC:
100 CALL FOV$COISP <FORMNAME>
110 CALL FDV$STAT <FMSSTATUS>
ZOO IF FMSSTATUS < 0
THEN
CALL FDV$PUTL ('FORM
FORMNAME +
CALL FDV$SIGOP
CALL FOV$WAIT
I+

2.6

NOT FOUND')

AST Considerations
The FMS Form Driver is optionally AST reentrant, but you must follow certain rules or risk severe problems, which the Form Driver cannot detect.
1. You must not attach the terminal (ATERM) with No AST support (default

is AST support).
2. You can send output to the current form from an AST with no restrictions,
although such output is more expensive in both time and characters sent
to the screen. The reason for the added expense is that the Form Driver
must always save and restore the video attributes and cursor position of
the interrupted program.
3. You must not request input from an AST program.
4. You must not detach or switch a terminal or workspace or change a workspace involved in any current operation.
There may be additional restrictions on the use ofFMS from ASTs, depending
on the version of the operating system in use. See the VAX FMS Installation
Guide and Release Notes for details.

Form Characteristics

2-51

Chapter 3
Programming Techniques and Examples
Programming techniques are ways a programmer can exploit the capabilities
of software inventively. In a new or greatly changed product, such ways are
not likely to be immediately apparent to a new user.
Typically, techniques evolve naturally through normal use - the user combines facilities in a certain way out of a need to accomplish a specific task, for
example; or realizes that a facility meant to do one task is just the thing to
solve some other kind of problem.
Descriptions of such techniques make up this chapter, along witli programming examples. The following routines, written in various languages, are
taken from the FMS Version 2 Sample Application Program (SAMP). The
routines illustrate the value of using such capabilities as Named Data and
the various kinds of user action routines (UARs). Their value is in preserving
as much as possible, the independence of the application program - that is,
Named Data is associated with the form, and UARs are called from the Form
Driver.

3.1

Scrolling
Because the Form Driver can store field values only for the fields that are on
the terminal screen, your program must maintain all scrolled area field values that are not displayed; that is, all the values that are "above" and "below"
each scrolled area. When your program scrolls the lines of a scrolled area
upward or downward, the program must collect the lines of values scrolled
out of the area, and display any line of values scrolled into the area. (See the
section called "Scrolling" in Chapter 2 for some discussion of this topic.)

3-1

3.1.1
13000
13001
13005
13010
13015
13030
13035
13040
13072
13075
13080
13085
13090
13095
13100
13105
13110
13115
13120
13125
13130
13135
13140
13145
13150
13155
13160
13165
13170
13171
13175
13180
13185
13190
13192
13195
13200
13205
13210
13215
13220
13225
13235
13245
13250
13255

3-2

Controlling Scrolled Areas

DEF FN.VUEREG
!+

Subroutine VUER~G
View the checK resister and scroll throush it.
Also disPlaY totals for current session.
Put UP resister forM.
CALL FDV$CD I SP ( REG I ST
I

\ C=FN.SRVCHK

!+
! Get nuMber of lines in scroll area froM forM NaMed Data (iteM 1>.
!-

NSCROL$ = '
! Pre-extend strins variable before call <BASIC only).
CALL FDV$RETDI< 1%1 NSCROL$ >
\ C=FN.SRVCHK
NSCROL% = VAL< NSCROL$ )
!+
! Put lines f roM checK resister array into scrolled area.

The window is initially froM iteM 1 UP to iteM
Min<NSCROL$1LASTREGNUM%>, that ist UP to the size of the scrolled
area or the size of the resister, whichever is less. AssuMe there
is at least one line (the initial deposit).
!-

MINWINDOW% = 1
CALL FDV$PUTSC < 'NUMBER' , REGARRAY$ <1 > > ! Fi rs t 1 in e
CURLINE% = 1
! Res iteM cursor is on
WHILE ( CURLINE% < LASTREGNUM% AND CURLINE% < NSCROL%
CURLINE% = CURLINE% + 1
CALL FDV$PFT< FDV$K_FT_SFWt 'NUMBER' >
CALL FDV$PUTSC< 'NUMBER', REGARRAY$( CURLINE% ) >
NEXT
MAXWINDOW% = CURLINE%
+

Get inPut froM faKe field of scrolled line and do what it says:
KPd • or RETURN/ENTER => return to Menu
UPARROW or TAB => scroll forward
DOWNARROW or BACKSPACE => scroll bacKward
all others
=> isnore
Note that there is no forM function Key UAR so this routine
handles all terMinators itself (by isnorins illesal ones>.
CALL FDV$GET< FAKE$1 TERMINATOR%t 'FAKE' )
WHILE NOT < TERMINATOR% = FDV$K_FT_NTR OR TERMINATOR% = FDV$K-KP-PER >
IF TERMINATOR% = FDV$K_FT-SFW OR TERMINATOR%
FDV$K_FT-SNX THEN C=FN.SCRF
IF TERMINATOR% = FDV$K_FT-SBK OR TERMINATOR% = FDV$K_FT-SPR THEN C=FN.SCRB
CALL FDV$GET< FAKE$1 TERMINATOR%t 'FAKE' )
NEXT
FNEND

Programming Techniques and Examples

3.1.2 Scrolling Forward
See also VUEREG routine at line 13000.
13500
13501
13505
13510
13512
13513
13515
13520
13525
13530
13535
13540

DEF FN.SCRFWD

13545
13550
13555
13580
13585
13587
13570
13580

13585
13580
13688

!+
! Subroutine SCRFWD -- Scroll forward.

CURLINE% is the line in the register that the cursor is on.
MINWINDDW% and MAXWINDDW% deliMit the Part of the register
currently disPlaYed in the scrolled area
!-

!+
! If
!-

cursor is at the end of the register, report, and return

IF CURLINE% = LASTREGNUM% THEN
CALL FDV$PUTL< 'Last line of register'
FNEXIT
If cursor not at the last line of a window, Just move down
If cursor is at the last line of a windowt
move window forward one line,
write the new last line to the last line of the scrolled area
Move current line Pointer forward
!-

IF CURLINE% <> MAXWINDDW% THEN
CALL FDV$PFT< FDV$K_FT_SFWt 'NUMBER' )
ELSE
MINWINDDW% = MINWINDOW% + 1
MAXWINDDW% = MAXWINDOW% + 1
CALL FDV$PFT< FDV$K_FT_SFWt 'NUMBER', REGARRAY$( MAXWINDDW% ) )
CURLINE% = CURLINE% + 1
FNEND

3.1.3 Scrolling Backward
See also VUEREG routine at line 13000.
13700
13701
13705
13710
13712
13713
13715
13720
13725
13730
13735
13740
13745
13750
13755
13760
13765
13787
13770
13780

13785
13790

DEF FN.SCRBAK
!+

Subroutine SCRBAK -- Scroll backward
CURLINE% is the line in the register that the cursor is on.
MINWINDDW% and MAXWINDDW% deliMit the Part of the register
currently disPlaYed in the scrolled area
!-

!+
! If
!-

the cursor is at the beginning of the register, rePortt and return

IF CURLINE% = 1 THEN
CALL ¢DV$PUTL< 'First line of register'
FNE1<IT

Move current line Pointer back
!-

IF CURLINE% <> MINWINDDW% THEN
CALL FDV$PFT< FDV$K_FT_S6Kt 'NUMBER' >
ELSE
MINWINDDW% = MINWINDOW% - 1
MAXWINDDW% = MAXWINDOW% - 1
CALL FDV$PFT< FDV$K_FT_S6Kt 'NUMBER', REGARRAY$( MINWINDDW% ) )
CURLINE% = CURLINE% - 1
FNEND

Programming Techniques and Examples

3-3

3.2

Validating a One-Character Field - Using a UAR
Purpose
To check single-character fields for valid data input.

Description
Frequently when using forms as menus to select one of several options, a single-character field is used to enter a letter or number indicating the desjred
option. Although it is possible to have the application program test each of
these fields separately to ensure that a valid choice has been entered, it is
much more convenient to use a single UAR for this purpose.
Whenever a character is typed in a single-character field, the character is
immediately checked against a list of permissible characters, and the operator is not allowed to proceed unless the character entered is found in the list.

Programming Technique
For you to use this technique for validating a single-character field, the associated data string of a field completion UAR must be set to contain a string of
all the valid character responses. If space is a valid response, it must be
embedded in the string, since trailing spaces are ignored.
When the data validation UAR is activated, it uses the RETCX call (Return
Current Context) to recover the associated data string, and the RETFN and
RETcalls to get the field name and field value, respectively.
It then searches the associated data character string for the field value. If the
value is found, the UAR returns successfully, allowing a GETAL in progress
to proceed normally to the next field. If the value is not found, the UAR
returns validation failure, which causes the Form Driver to signal the operator and stay in the current field.

This technique is also used throughout the Form Editor for validating the
selections for form and field attributes.

Example
16010
16015
16017
16020
16025
16030
16035
16040
16045
16050
16055
16060
16065
16070
16075
16080
16085

3-4

VALIDl
UAR for field validation of any one character field. The
UAR associated data has in it the lefal characters allowedt
excePt that blank is not allowed unless it aPPears before
the first trailinf blank. For example an assoc. value strinf
'aqr' imPlies that onlY the letters at qt and rare allowed.
A strinf ' aqr' means that blank is accePtable in addition
to at qt and r. Note that this routine is case sensitive
(that ist it checks for correct case>. You can fet around
case sensitivity by usinf the force-uppercase field attributet
and Puttinf only capitals into the UAR associated value
strinf.
!
!-

This routine can be used with any form and field since
it determines the context for itself.

Programming Techniques and Examples

16088
16089
16090
16095
16096
16097
16098
16099
16105
16110
16120
16125
16127
16130
16135
16140
16142
16145
16150
16160
16165
16170
16175
16185

16210

DECLARE INTEGER CONSTANT
&
FDVSK_UVAL_SUC= 1000t !Field coMPletion success &
FOV$K_UVAL-FAIL=1001 !Field COMPletion failure
! Pre-extend the strinfs into which FMS will return values
!-

FRMNAMS = SPACESC31)
UARVALS = SPACESCBO>
FLDNAMES = SPACESC31>
FVALUES = SPACESCl>
!+

Retrieve context: we will ifnore TCA address• WKSP addresst FRMNAMSt
CURPOSt FLDTRMt INSOVRt and HELPNUM usinf only UARVAL$1 and
onlY the initial, non-blank characters of it.
Retrieve field naMe and index.
! Retrieve field value.
CALL FDVSRETCXC TCAlt WKSPlt FRMNAMSt UARVALSt CURPOSlt FLDTRMlt INSOVRlt HELPNUM% )
UARVALS = TRMSC UARVALS >
CALL FDVSRETFNC FLDNAMES1 FINDEXl )
CALL FDVSRETC FVALUESt FLDNAMESt FINDEX% )
!+

! To be validt FVALUES Must occur in the strinf UARVALS
!-

IF POSC UARVALSt FVALUES1 1> > 0 THEN
VALID1 = FDV$K_UVAL_suc !Success
ELSE
CALL FDVSPUTLC 'Illefal value' >
VALID1 = FDVSK_UVAL-FAIL
FUNCTIONEND

3.3 Producing Hard Copy - Using Named Data
Purpose
To produce a printable image of a form or portion of a form.

Description
A common application requirement is to produce a printable copy of a form on
the screen. Complications arise if only part of the form is to be printed or if
only one form out of a set of multiple forms on the screen is to be printed. The
program could select particular lines to be printed, but doing so would destroy
some of the program/form independence that is one of the chief virtues of
FMS. Changes to the layout of a form might then require the program to be
changed when the changes would be only cosmetic and should not be affecting
the program.

Programming Technique
The RETFL call returns the printable image of an individual line on the
screen. These line images are suitable for writing directly to a line printer or
to a file for later printing. If the entire screen is to be printed, a program loop
requesting lines one through twenty-three will produce the twenty-three line
images.
When only part of the screen is required, the difficulty is in knowing which
lines to ask for in the RETFL call. A common technique is to store the range of
the lines to be printed with. the form itself. At form creation time the form
designer knows what lines are to be printed and puts the numbers of the first

Programming Techniques and Examples

3-5

and last lines to be printed in the form's Named Data. The program accesses
the Named Data to find the first and last lines to print and uses them as limits
on the program loop calling RETFL. Then, if the form layout is ever changed
so that a different range oflines should be printed, the form designer changes
the Named Data and the unchanged program still produces the desired
result.
Example

The following extract from the FMS Sample Application program shows this
technique in action. The form has two Named Data items with names FIRST
and LAST indicating the first and last lines to print. Each item has two characters representing the number. The program reads those Named Data items,
which are character strings, converts them to numbers for internal use, and
uses them as limits on a loop that includes a call on RETFLand a statement
that writes the line images to a data file.
The following segment is shown in FORTRAN. See the VAX FMS Language
Interface Manual for the equivalent code segment for any other languages
supported by FMS. That manual also has descriptions of the CHECK form.
SUBROUTINE PRINT-THE-CHECK

Print the check into the file SAMPCH.OAT
CHARACTER*BO LINE
CHARACTER*Z
FIRSTL,
1
LASTL
INTEGER
1

c
c
c

FIRST_LINE_NUMBERt
LAST_LINE_NUMBERt

LINELENGTH
DPen check writin~ file.
for every check.

Note there's a new version

OPEN<UNIT=Zt FILE='SAMPCH.DAT', STATUS='NEW',
1
CARRIAGECONTRDL='LIST', RECORDSIZE=BO >

c
c

Get the toP and bottoM lines of the check froM the naMed data
(first two characters>.
CALL FOV$RETDN ( 'FIRST' , FI RSTL )
CALL CHECK-FMSSTATUS<>
CALL FOV$RETDN< 'LAST', LASTL )
CALL CHECK_FMSSTATUS<>

c
c

Get lines froM forM.
Write to file.
READ <FIRSTLt '<IZ> ') FIRST-LINE-NUMBER
READ <LASTLt '<IZ> ') LAST-LINE-NUMBER
DO I = FIRST-LINE-NUMBER, LAST_LINE_NUMBER
CALL FOV$RETFL< I, LINE, LINELENGTH >
WRITE<Z, <A> I) LINE< 1 :LJNELENGTH>
END DO
CALL FOV$PUTL< 'Check written to file' >
CLOSE <2>
END
I

3-6

Programming Techniques and Examples

3.4

Storing Message Text - Using Named Data
Purpose
Keep operator message texts independent of your program.

Description
Messages to the terminal operator are often changed during development of
an application. To keep the messages independent of the peculiarities of a
particular programming language, you can use files and modules that contain only message text.
When a form changes, it is often necessary to change the message file also.
Even after program development, convenient change of operator messages is
desirable. A program product may need to change both forms and message
files to be tailored for a new customer. A program that is used by operators
who speak different languages must maintain different form and message
files for each language.

Programming Technique
One way of simplifying control of operator interaction is to keep all text that
is presented to an operator in an FMS form. In the case of a multilingual environment, the application designer can develop forms that all request the
same information, but that have background text appropriate to the language (for example, German and French).
All forms for a single language are collected in a form library. There may be
several such libraries, each containing forms having identical names, with
the only difference being the background text. The first form that the application displays is a menu form requesting the operator to select a language. The
application opens the appropriate form library according to the language
selected.
Thereafter, when a form is called from the library (for example, with a CDISP
call), the named form is read from the library and displayed on the screen,
presenting text in the operator's language. The application doesn't need to be
concerned with the language at that point, since the previously made choice
controls the form displayed now.
Since the application must occasionally display additional messages (perhaps by means of the PUTL call to the bottom line of the screen), it is consistent to store the text of those messages in the Named Data of the form. Either
the name or index of the Named Data item can be used as an identifier to
retrieve the text from the form before sending it to the operator.

Programming Techniques and Examples

3-7

In the multilingual environment, these messages can be in the selected language. Even for single language environments, storing the message with the
form makes sense, since the messages often relate to the form. The form
designer can change the form and the related messages in the same place,
saving time and the usual confusion when separate files must be used
together.

Example
The Sample Application shows one example of how to use Named Data to
store message text in the DEPOSIT form. After the operator has entered
checking account deposit information, SAMP wishes to display a message to
the effect that the operation is done and the operator should press the
RETURN key to continue. The form used for deposit entry has such a message stored in the Named Data item with the name DONE.
The following extract from the FORTRAN SAMP shows how this can be done.
Consult the VAX FMS Language Interface Manual to see the form definition
for DEPOSIT and the SAMP in any of several languages.
CHARACTER*80

DONE·

CALL FDV$RETDN< 'DONE' t DONE >
CALL FDV$PUTL< DONE >
CALL FDV$WAIT

3.5

Converting Function Keys to Field Entry
Purpose
Provide an easy way of accepting either function keys or text in a field to
select an option from a menu.

Description
In menu entry forms it is often desirable to allow the operator to enter the
choice in one of two ways: enter the option followed by a terminator, or enter a
function key. It is often inconvenient to implement such a design, since it
involves two sets of validations instead of just one (making sure the text is
correct, or if that is blank, making sure the function key is correct). Nonetheless, the convenience of a single keystroke menu response makes it worth
considering.

Programming Technique
A function key UAR can convert a function key to the text string it is
equivalent to. The UAR then outputs that text string to the menu's choice
field as if the operator had entered the text. The return code for the UAR tells
the Form Driver to process the field as if the operator had pressed the
RETURN key instead of a function key. The Form Driver then calls any field

3-8

Programming Techniques and Examples

completion UARs or returns control directly to the calling program, which
only has to look at the text, regardless of whether it has been entered from the
keyboard or by means of a function key.
Example

The Sample Application's MENU form has a function key UAR that converts
six function keys into the text strings "l", "2", "3", "4", or "5". The function
keys accepted are all on the application keypad. The key 1 and the key period
(.) are both converted to the string "1"; the key 2 is converted to the string "2";
keys 3, 4, and 5 are converted to strings "3", "4", and "5". All other function
keys are rejected. While this is a specific UAR, more general U ARs to do this
conversion can be written.
The following extract from the COBOL SAMP shows how this can be done.
Consult the VAX FMS Language Interface Manual to see the form definition
for DEPOSIT and the SAMP in any of several languages.
IDENTIFICATION DIVISION+
PROGRAM-ID.
TAKE15
INITIAL.
****************************************************************
*
Function key User Action Routine for the MENU forM of SAMP+*
keYPad 1-5 into field values 1-5.
*
* Convert
keYPad Period into field value 1.
*
* Convert
ReJect all other function keys with error Messa~e.
******************************************************************
DATA DIVISION.
WORKING-STORAGE SECTION.
COPY "FDVDEF".
COPY "SAMPCOB".
COPY "SMPCOBUAR"+
**

Declarations specific to this UAR.

*01
01

FIELD-VALUE PIC X<1> VALUE SPACE+
ILLEGAL-FUNC_KEY-MSG PIC X<20)
VALUE "Illesal function keY"•
GIVING RETURN_STATUS.
PROCEDURE DIVISION

* Retrieve context: isnore all but TERMINATOR

CALL "FDV$REtCX" USING BY REFERENCE ADDRESS_TCAt
BY REFERENCE
ADDRESS_WKSPt
BY DESCRIPTOR FORM-NAMEt
BY DESCRIPTOR UAR-DATAt
BY REFERENCE
CURSOR_POSITIONt
BY REFERENCE
TERMINATORt
BY REFERENCE
INSOVR_STATUSt
BY REFERENCE
HELP-STRIKES.

*Do the conversion, disPlaYinS the value converted if found+
* ReJect if not one of the expected terMinators.

EVALUATE TERMINATOR
WHEN FDV$K_KP_1 MOVE "1" TO FIELD-VALUE
WHEN FDV$K_KP_2 MOVE "2" TO FIELD-VALUE
WHEN FDV$K_KP_3 MOVE "3" TO FIELD-VALUE
WHEN FDV$K_KP_a MOVE "4" TO FIELD-VALUE
WHEN FDV$K_KP_5 MOVE "5" TO FIELD-VALUE
WHEN FDV$K_KP-PER MOVE "1" TO FIELD-VALUE
END-EVALUATE.
IF FIELD-VALUE = SPACE THEN
CALL "FDV$PUTL" USING

Programming Techniques and Examples

3-9

BY DESCRIPTOR ILLEGAL_FUNC_KEY-MSG
CALL "FDV$SIGOP" ·
Just i~nore it now+
*
MOVE FDV$K_UKEY_suc TO RETURN-STATUS
ELSE
CALL "FDV$PUT" USING BY DESCRIPTOR FIELD-VALUE
BY DESCRIPTOR N-MENU-OPTION
*
Treat as if it is RETURN+
MOVE FDV$K_UKEY_NTR TO RETURN-STATUS
END-IF+
EXIT PROGRAM+
END PROGRAM TAKE15+

3.6

Filter for Function Keys
Purpose
Allow only certain function keys to be returned to the program.

Description
FMS defines a great many function keys (control keys, Gold sequences, terminal function keys, alternate keypad keys), but most applications only need a
few keys active during the processing of a particular form. Other keys can be
rejected or ignored. On return from a GET-type call the application can determine whether the terminator is legal, but this is such a common requirement
that a general purpose routine can save a lot of trouble.

Programming Technique
Define a general purpose function key UAR for the form, that allows only certain function keys to be returned to the program. One way of doing this is to
have the UAR associated data be a string that has the keycodes of the legal
function keys.
The form designer then specifies the UAR in the Form Phase of the Form
Editor or in the FORM statement of the Form Language, with an associated
data value representing just those function keys that are legal. (About
twenty keys could be specified in this fashion, more than an operator can usually deal with.) The function key UAR reads the associated data string and
compares the values found there to the keycode received, rejecting the key if
no match is found.
Alternatively, if you want to change the legal function keys more often than
you switch the form, or if you wish to have more keys than can be listed in the
eighty bytes of the UAR data, define a COMMON area with an array containing the legal keycodes, and a variable specifying how many different
keycodes are currently in the array.
The application program updates the array and the counter variable whenever it determines that a different set of functions is legal. A function key
UAR can access the array in COMMON, comparing the key code received
against the legal values, and returning success to the Form Driver only if a
match is found.

3-10

Programming Techniques and Examples

Example
The Sample Application has a function key UAR called PASSKY that is used
on each of the data entry forms in SAMP. PASSKY implements the first of the
suggestions above - the UAR associated data string has the legal keycode
values. PASSKY is given below in its PASCAL version. Consult the VAX
FMS Language Interface Manual to find PASSKY in any of several languages. You can also find references to the SAMP forms that use PASSKY.
(It is possible to write a more efficient implementation of PASSKY than is

shown here. Instead of converting each of the character strings in the UAR
data string to binary and then comparing the binary number to the terminator, you can convert the terminator to a four character ASCII string (with
leading zeros) and then use a string function to see ifit appears in the UAR
data string. Each string in the UAR data would have to be four characters
long, with leading zeros, for this to work.)
FUNCTION PASSKY;
{ General function KeY uar to Pass only those froM the (sMall)
list in the uar associated value strins and reject all
others. The list is of the forM:
n <oneblanK> n <oneblanK> ••• n (ManYblanKs>
For exaMPle the strins '110 112' would accept Keypad Period
and KeYPad zero but no other function KeYS+ }
LABEL
VAR

1000;
NexttrM: INTEGER~
NonBlanK: INTEGER;
NextBlanK: INTEGER;

BEGIN
{Retrieve context: we will isnore TCA addresst WKSP addresst
FRMNAMt INSOVRt and CURPOSt usins only FLDTRM and
UARVAL+ }
FDV$RETCX< TCA :=Teat WKSP := WorKsPacet FRMNAM := FNTlnaMt
UARVAL := Uarvalt CURPOS := CurPOSt FLDTRM := FldtrMt
INSOVR := Insovrt HLPNUM := HlPnUM );
{ BreaK UP the list into nuMbers. ChecK each asainst the
terMinator+ If terMinator found in listt return success. }
NonblanK := 1;
< Besinnins of strinS}
WHILE <Uarval[NonblanKJ <> ' ') AND <NonblanK <= 80> DO
BEGIN
NextblanK := INDEX< SUBSTR<Uarval t NonblanK t
LENGTH<Uarval> - NonblanK + 1) t ' ')
IF NextblanK = 0
THEN NextblanK := 80
ELSE NextblanK := NextblanK + NonblanK - 1;
READV <SUBSTR(Uarval t NonblanK t NextblanK-NonblanK> t
Nexttr1T1);
IF FldtrM = NexttrM
THEN
BEGIN
PASSKY := FDV$K_UKEY-TRM; <Pass Key to aPPlication}
GOTO 1000;
END;
NonblanK := NextblanK + 1;
END;
PASSKY := FDV$K_UKEY_ERR;
{Let FDV do the beePinS}
1000: END;

Programming Techniques and Examples

3-11

3.7

Range Checks for Fields
Purpose
Ensure that a field contains values only in a particular range.

Description
Many fields can contain numeric values only in certain ranges, which are
known ahead of time and which do not need to change dynamically. For example, there may be a minimum order on certain items, or only certain temperature ranges may be possible in a laboratory environment. While it is possible
to check these values in the application, it is more convenient to define a general purpose field completion UAR.
UARs are particularly useful because the main logic of the application program does not then have to concern itself with validity checks of this sort. The
validity checks still have to be made, but they are made in a modular fashion
in a subroutine that does not clutter up the main line, and that is usually
more concerned with relationships between the entered data and a database
or realtime process.

Programming Technique
A range checking UAR can be specified for each field that requires range
checking. The lower and upper bounds for the field values are specified in the
UAR associated data, separated by a comma. If no lower or upper bound is
given, then no check for the bound is made, allowing ranges with open bounds
on one end. The UAR data can also contain an error message to be issued in
case of failure to satisfy the validity check.
Just putting a UAR on a field doesn't always mean that the UAR is called.
There are two conditions (other than error conditions, cancellation of the call,
and field timeout) under which the Form Driver does not call a UAR for a field
- the field was terminated by the Previous Field key, or the field was terminated by a user function key.
In either of these situations the program must realize that the field may have
invalid data. The program can take steps to guarantee that the UARs for the
field get called so that its validity is assured. The program may refuse to
accept such a terminator, and reestablish the read on the field or the form as a
whole.
The program may call the PFT routine with the Enter Form terminator
(FDV$K__FT_NTR). The Form Driver then checks all nonscrolled fields for
validity, calling their UARs and returning a special status code to the program if any field fails to pass all checks. The program can reissue the read for
the failed field and continue until the PFT routine returns success.

3-12

Programming Techniques and Examples

Example

The Sample Application program has a function, RANGE, that is called as a
field completion UAR. The BASIC version of RANGE is given below. Consult
the VAX FMS Language Interface Manual for examples of RANGE in other
languages. Refer to the CHECK form in that manual for the field that uses
this UAR.
Note that RANGE is not completely robust with respect to the UAR associated data string. A string that contains illegal numeric values on either side
of the comma will cause problems. If your program is debugged, RANGE
causes no problems, but a more general function would have to have some
method of either checking for valid numbers, or a method of recovering from
errors. The RANGE function in SAMP is used for integer values. Some of the
language implementations actually allow decimal numbers because of the
particular conversion functions used (for example, BASIC).
You can make RANGE more efficient if you require that the numbers in the
UAR string be fixed format instead of free format. For example, the lower
bound might occupy string positions 1-10; the upper bound, positions 11-20;
and the error message, positions 21-80. The advantage for RANGE is in not
having to scan for the numbers. The disadvantage, of course, would be for the
form designer - fixed format input is inconvenient and subject to error.
FUNCTION INTEGER RANGE
!+***~****************************************************************

! General Purpose UAR to check the

ranse of anY numeric item. The
associated UAR data must have one of the four forms:
LtU<sPace){messaSe}
tU<sPace){messaSe}
Lt<sPace){messaSe}
t<sPace){messaSe}
where L is lower bound, U is UPPer boundt and {messaSe} is an
OPtional error messase in case the field value is out of bounds.
If one of the bounds isn't sivent it isn't checked for.
If neither
bound is Sivent nothins is checkedt everYthinS succeeds.
If the
UAR value doesn't have a comma, a FDV$_UAR error messase is returned
to the callins Prosram by the FDV so the form desisner has to so
back and do it risht. If no {messaSe} is Sivent a simPle
"out of ranse U:L" Messase is siven to the hapless operator.

This UAR can work with any form and numeric field since it Sets
context itself. Care must be taken with fields usins field marker
Periods since those Periods are not returned to th~ Prosram.

!-********************************************************************

DECLARE INTEGER CONSTANT
&
FDV$K_UVAL_SUC= 1000, !Field completion success &
FDV$K_UVAL-FAIL=1001
!Field completion failure

! Pre-extend the strinss into which FMS will return values.
! Get context which Yields associated data value (iSnore other stuff).
! Ge~ current field name and index.
! Get field value.
!-

FRMNAM$ = SPACE$(31)
UARVAL$ = SPACE$(80)
NAME$= SPACE$(31)
NUMBER$ = SPACE$(132)
CALL FDV$RETCX< TCA%t WKSP%t FRMNAM$t UARVAL$t CURPOS%t FLDTRM%t &
INSOVR%t HELPNUM% >
CALL FDV$RETFN< NAME$, INDEX% >
CALL FDV$RET< NUMBER$t NAME$t INDEX%
NUMBER = VAL< NUMBER$ )

! Find comma and blank delimiters.

Programming Techniques and Examples

3-13

Check for lower bound.

COMMA?. = POS ( UARVAL$,
1 )
BLANK% = POS< UARVAL$1 SPACE$(1), COMMA% + 1 >
IF COMMA% = 0 THEN
RANGE= 0 ! Ille~al UARVAL strin~, FDV returns error
FUNCTIONEXIT
IF COMMA% <> 1 THEN
IF NUMBER< VAL< SEG$( UARVAL$1 11 COMMAZ - 1 > > THEN 20300
!+
! Check for upper bound
I

IF BLANK% <> COMMA% + 1 THEN
IF NUMBER > VAL< SEG$( UARVAL$1 COMMA% + 1, BLANK% - 1 ) > THEN 20300
!+
! Passed both tests successfullYt return success for UAR value
!

RANGE = FOV$K_UVAL_suc
FUNCTIONEXIT
!+
! Error in one of the bounds.
! Give error messa~e: either from the UARVAL or make one UP•
!-

IF SEG$( UARVAL$1 BLANK%+ 11 BLANK%+ 1 > <> SPACE$(1) THEN
CALL FOV$PUTL< SEG$( UARVAL$t BLANK%+ 1 t 80 > >
ELSE
CALL FDV$PUTL< 'Field value out of bounds. Must be in ran~e
SEG$( UARVAL$t 1 t BLANK% - 1 ) + '"•I
CALL FDV$SIGOP
!BeePt too.
RANGE = FDV$K_UVAL_FAIL
FUNCTIONEND

3.8

+ &

Simulating the GETAL Call
Purpose
General purpose structure for getting input from all fields in a form.

Description
One of the advantages of the GETAL call is that it allows the operator to progress through the form with the Next Field and Previous Field keys, filling in
fields in any order (subject to Response Required and Must Fill attributes,
and UAR validations). Only when the operator presses a function key or the
Enter Form key does the Form Driver return control to the application; and if
the Enter Form key is pressed, the Form Driver does not return control if any
field fails validation.
Even though a program requires input from each input field on a form, there
are many situations in which the GETAL call is inappropriate. GETAL does
not access scrolled fields, and in some cases the mainline program needs to
regain control after each field is entered.
The restriction on no scrolled fields is put on GETAL because the program
must know at all times what the current scrolled line is in a scrolled area. If
GETAL were to accept input from scrolled lines, and were to allow the user to
scroll down, the program's knowledge of the current scrolled line would not
match the Form Driver's knowledge. The reason for this mismatch is that

3-14

Programming Techniques and Examples

there is no way in FMS for the Form Driver to tell the application the number
of the current scrolled line, and no way to inform the application if the whole
area is to be scrolled.
The only way the current scrolled line is changed is by the application's
requesting a change (by means of the PFT call with the SFW, SBK, SNX, and
SPR terminators; or by means of PUTDA 's restoring the current scrolled
lines of all areas to one). Since the application controls scrolling it can always
know the current line.
A mainline program might wish to regain control after every field to achieve
special effects. These effects might not be appropriate for UAR processing for
a variety of reasons. The restrictions on UAR processing may be too severe for
the effect. For example, the effect might be to skip over some field if some
other field has a particular value, but a UAR cannot change the current field;
or, the language being used does not support external routines.
Although these are good reasons not to call GETAL, it is not advisable to give
up the operator's apparent freedom of order entry afforded by GETAL.

Programming Technique
It is possible to give the operator the same apparent freedom of control and
still have control return to the application for every field. The general idea is:
1. Perform a GET for the first (or any other field).

2. Do the special processing for the named field after control returns to the
program.
3. If the terminator specifies scrolling and you are in a scrolled area, update
your data pointers for that scrolled area. (The Form Driver does not normally return scrolling terminators if the field is not in a scrolled area.)
4. Call PFT, specifying the field name used in the GET, and the terminator
that was returned by GET. Ask that the new current field name be
returned by PFT. This step requests that the action expected by the operator be carried out, at least in the internal memory of the computer (changing the current field). Note that neither the cursor nor the screen changes
because of the PFTcall.

Programming Techniques and Examples

3-15

5. Inspect the return from the PFT call. It can be one of four values:
• FDV$-SUC: Success; the field name returned by PFT is the new current
field name. If the terminator was not FDV$K_FT_NTR, your program can
continue asking for input using the field name returned. If the terminator
was FDV$K_FT_NTR, then the input is finished.
• FDV$-1NC: The field terminator was FDV$_FT_NTR and some field
did not pass all the validation criteria. The current field is set to the first
such field and is returned to your program. Your program can continue
asking for input using the field name returned.
• FDV$_UTR: The field terminator was a function key and not a terminator known to FMS. The current field is not changed and its name is
returned to your program. You then choose what your program does
depending on the function key. You may choose to continue input from the
current field, which was returned to you.
• FDV$-1FN: The terminator requests an illegal function in the current
context (for example, Next Field at the end of the form). The only way this
can be returned is if you have changed Supervisor Only mode since the
GET statement. The GET call does not return a terminator that is illegal
in the current context, so it must be that the context has changed.
For example, at the time of the GET call, Supervisor Only mode was off
and there was a Supervisor Only field following the current field, making
the Next Field terminator legal. If you turn on Supervisor Only mode and
there are only Supervisor Only fields following the current field, the Next
Field terminator is now illegal. If you change the context you must decide
what to do next. (Note that turning on Supervisor Only mode may also
change the validity of the current field, since it may no longer be a modifiable field.)
6. Note that for the first three (normal) cases, your program may elect to continue input with the field that was returned to you by the PFT call. Your
program can loop back to use that field name in the next GET call. Using
the new current field name in the GET call makes it appear to the operator
as if the cursor has moved in response to the terminator entered, which it
indeed has, but only after the program has requested such movement.
When the FDV$_FT-NTR terminator is entered and PFT returns success for
it, your program knows that all the nonscrolled fields have been entered correctly. You can be assured that all scrolled fields that were entered with any
terminator other than FDV$_FT_pRV, FDV$_FT_SPR, or a function key
are correct. That is, the scrolled line fields were validated up to the farthest
point on the line reached.
Note that this technique works for any form since it does not need to know the
field names. Of course, if you wish to do special processing for particular
fields, you need the field names.

3-16

Programming Techniques and Examples

Example
The following code is extracted (in slightly modified form) from the Sample
Application. The technique is used in SAMP only for illustrative purposes
(there is no special processing done for a field). The difference between the
SAMP code and that given here is that the SAMP code does a GETAF for most
of the fields so that it regains control only after a field changes (except the
first). The code listed below regains control after every field. Depending on
the needs of your program, you may choose to do one or the other. The code
below also differs from the SAMP in the way the call status is obtained after
the PFT call.
The code segment below is for PL/I. Consult the VAX FMS Language
Interface Manual for the SAMP program using GETAF in your favorite
language.
SIMULATE: PROCEDURE
DCL
FIELDNAME CHAR<31 >, /*NaMe of field*/
FIELDINDEX FIXED BIN<31>, /*Index of field*/
FIELDVALUE CHAR<BO>; /*Value of field*/
FIELDNAME = '*';
I* Identifies first field in forM */
DO WHILE ('1'BH
CALL FOV$GET< FIELDVALUEt TERMINATOR, FIELDNAMEt
FIELDINDEX >
I*
I* Do any special Processinf f-0r field FIELDNAME here.
I*
/* Go to next or Previous field or leave forM
I*
*I
CALL FDV$PFT< TERMINATOR, , , FIELDNAMEt FIELDINDEX >;

I* If status is errort then PFT failed because terminator
I* was a keypad keYt which means return to caller.
I*
*I
CALL FOV$STAT< FMSSTATUS );
IF FMSSTATUS < 0 THEN RETURN;
IF TERMINATOR = FDV$K_FT_NTR
THEN IF FMSSTATUS A= 2
THEN RETURN;
ELSE oo;
CALL FDV$PUTL ( INPUT REQUIRED
CALL FDV$BELL;
ENO;
I* LooPt usinf new field name
*I
I

)

;

ENO;
END SIMULATE

Programming Techniques and Examples

3-17

3.9

Reducing Display Times for Forms
Purpose
Reduce the time to display a form and application supplied data.

Description
It is often the case that you will display a form (for example, with DISP) and
then immediately output data to all the form's fields. This results in the fields
on the forms being written twice - once as the result of the DISP call outputting the default values, and once as the result of PUT calls or the PUTAL call.
On a form with many fields this is a noticeable delay, especially on low-speed
lines, and is distracting.

Programming Technique
Instead of using a DISP call to load the form into a workspace and display the
form, and then using PUT calls, perform the following sequence:
1. Load the form into the workspace with LOAD (which does not display the
form).
2. Perform the initial PUTs or PUTAL. This changes the workspace but does
not output anything to the screen.
3. Call DISPW to display the form.
Note that this requires only one more Form Driver call (the DISPW call). It
produces a significant reduction in terminal output for some forms.

3.1 O Checking Status - Three Methods
Purpose
Determine result of Form Driver calls.

Description
Three methods of checking status of Form Driver calls are discussed in this
section - calling the Form Driver as a function, calling STAT, and setting up
status recording variables with SSRV. The first method is compatible with
the VMS calling standard. You would use the other two methods if you wish to
be able to report a secondary status when an error is detected. (See Section 2.5
in Chapter 2 - Checking Call Status.)

3-18

Programming Techniques and Examples

Programming Technique
In some situations, an error status does not indicate malfunctioning of your
program but rather a special situation. For example, your program might be
using Named Data as the list of valid table entries for a field. Asking the
Form Driver for the data associated with a Named Data name is the only way
of determining whether that Named Data item exists. If the Form Driver
returns an error, your program may use the existence of the error as information itself - that the table entry is not valid.
In these situations, an error response from the Form Driver is not unexpected
and does not represent a threat to the continuing execution of the program.
Any of the three error determination methods is useful in this situation, since
only the general status is needed. Using STAT is slightly more expensive
since it requires an extra Form Driver call to obtain the call status.
In checking for unexpected error situations, no matter which technique you
use, it is convenient to set up a subroutine to interpret the status of a call and
take appropriate action. The subroutine checks the status and returns if it
indicates success. If there is an unexpected error, the subroutine reports the
error and stops the process in some fashion you determine. if.the error is one
of the types that has a secondary error status associated with it (FDV$-10L,
FDV$_IOR, or FDV$_SYS) you may want to report the secondary status
also.

Example
A program that checks the Form Driver's function value return for an error
can use the status in a call to the VMS RTL signaling routines, so that the
message associated with the error is printed. It is still useful to do this in a
subroutine since the subroutine then obtains the secondary status and also
signals that. The program call on the subroutine would be used in the following manner (in PL/I):
CALLFMS = FDV$AWKSPC CHECKWKSPt 2000 );
CALL CHKSTAC CALLFMS >;

The subroutine could be written as follows:
CHKSTA: PROCEDURE< FMS_VMS_STATUS >
/*******************************************************
I* Subrou,tine CHKSTA
I* Check FMS status by looking at the Parameter which is
I* a VMS status variable. If there is an errort detach
I* the terminal to clean UP ~creen and then
I* outPut the error by signalling.
/*******************************************************/
DCL FMS_VMS_STATUS FIXED BINC31);
DCL SYS$PUTMSG
DCL MSG_VECC5)

ENTRY< ANY );
FIXED BINC31)

IF MODCFMS_VMS_STATUS12>=1 THEN RETURN;

I* Save the FMS error code in message vector for PUTMSG*/
I* Save the RMS status code in the message vector before
I*
making further calls */
I* Detach the terminal to clean up screen before Printing
I*
error message *I
MSG_VECCZ>
FMS_VMS_STATUS;
MSG_VECC3) = 0
/*Required for non-sYstem facility*/

Programming Techniques and Examples

3-19

MSG_VEC<S> = 0
/*In case RMS error mss needs it*/
CALLFMS = FDV$STAT< FMSSTATUS1 MSG_VEC<4> >
CALLFMS = FDV$DTERM< TCA );
I* Set messase vector count */
I* Output messase<s> */
IF MSG_VEC<4> = 0
THEN MSG_VEC<l> = 1
/*No secondary status*/
ELSE MSG_VEC<l> = 4
CALL SYS$PUTMSG< MSG_VEC );
STOP
END CHKSTA

The subroutine could be simplified if the secondary call status were not
needed. Instead of setting up a message vector, the RTL subroutine
LIB$SIGNAL or LIB$STOP could be used. For example, the following could
replace the entire body of the routine above:
DECLARE LIB$SIGNAL< FIXED BINARY<31) VALUE );
CALL LIB$SIGNAL< FMS_VMS_STATUS );

The Sample Application uses two subroutines to check for unexpected errors.
The first few calls use a subroutine that calls STAT to obtain the status of the
last Form Driver call. If the status obtained (which is the FMS, system independent status) is greater than zero, then the last call was successful and the
subroutine returns. If the last call was not successful, the subroutine
detaches the terminal (to clean up the screen) and prints the error codes
reported.
After the first few calls, SAMP sets up two status recording variables, FMSSTATUS and RMSSTATUS. The Form Driver sets the FMS status in these
variabies for every Form Driver call thereafter.
The SAMPs use FMSSTATUS in two ways. They call another subroutine that
checks for unexpected errors. This subroutine does not have to call STAT, but
merely checks the FMSSTATUS variable. If there is an error, it performs the
same error reporting as the first subroutine. The second way SAMP uses the
FMSSTATUS is immediately after a call to PFT in the routine that simulates
a GETAL call. Since the Form Driver set FMSSTATUS before returning to
SAMP, SAMP can immediately refer to the value of FMSSTATUS.
The following is an adaptation (in BASIC) of the two SAMP routines
described above. Consult the VAX FMS Language Interface Manual to see the
routines used in several languages.
DEF FN.GETSTA
!+*******************************************
! Subroutine GETSTA
! Check FMS status by callins STAT.
! If not success <>O>, Print and stop
!-***~***************************************

CALL FDV$STAT< FMSSTATUS%1 RMSSTATUS% >
IF FMSSTATUS% > 0 THEN FNEXIT
C~LL FDV$DTERM< TCA%<>
>
PRINT "FDV ERROR."
PRINT "",•FMS STATUS:"1FMSSTATUS%
PRINT ""1"RMS STATUS:"1RMSSTATUS%
STOP
FNEND

3-20

Programming Techniques and Examples

DEF FN.SRVCHK

!+*******************************************
!
!
!

Subroutine SRVCHK
Check FMS status by lookin~ at the status
recordin~ variables.

!-*******************************************
IF FMSSTATUSZ > 0 THEN FNEXIT
CALL FOV$DTERM< TCAZ<> >
PRINT "FDV ERROR."
PRINT ""t"FMS STATUS:" tFMSSTATUSZ
PRINT ""t"RMS STATUS:" tRMSSTATUSZ
STOP
FNEND

3.11

Paging
Purpose
To facilitate collecting multiple pages of data on a single form.

Description
Consider the form in the Form Editor used to collect User Action Routine
names and their associated data. A typical 23-line form might have space for
five such pairs of data entries. To enter more than five UAR specifications,
some extension technique must be employed. While scrolling is an excellent
technique for accessing more data than will fit on a single screen, it is best
used for accessing data records that can be compressed to a single line, since
scrolled areas must be scrolled one line at a time.
The idea behind paging is to have the user enter an entire page of data without changing the screen, and then clear the fields to enter a new page of data.
As the user tabs out of the last data field on the form, the form automatically
advances to the next page. Similarly, if the user backspaces out of the first
data field on the form, the form automatically moves back to the previous
page (if there is one).
Since TAB and BACKSPACE are the default FMS keys used to move to the
next or previous field in a form, no special action is required on the part of the
operator to move among fields on different pages. Ideally, the operator should
be able to move freely between pages to correct any previous entry just as he
would modify a previous entry in a form. To make it clear what data is actually being edited, a page number could be displayed at the top of the form, or
each data record could be preceded by a number that is updated to reflect the
current page.

Programming Technique
Several FMS features are used to produce the paging behavior described
above. The Form Driver PFT call (Process Field Terminator) is used to simulate GETAL processing. In addition, two special No Echo fields are added to
the form - one before the first data field, and the other after the last data field.

Programming Techniques and Examples

3-21

By having the application program know the names of these two fields, it is
possible for the program to detect when the user moves out of the last data
field of a form by requesting the name of the current field. Whenever the current field name matches the special first field, the program pages backward,
similarly when the current field name matches the special last field, the program pages forward.
Alternatively, you can avoid the two special fields and the GETAL simulation
by using the ILTRM (1) call with a GETAL call to have the Form Driver
return illegal terminators. Your program can then identify the illegal terminator FDV$K_FT_ILG_NXT as a request to go to the next page, since the
operator is attempting to go to the next field where there is none. A similar
action can take place for FDV$K_FT_ILG_pRV. The program would have to
filter out other illegal terminators.

Example
This technique is used in the Form Editor to enter Named Data and collect
field completion UAR data. A subroutine in the Form Editor is used to simulate GETAL processing except that it returns a special terminator code whenever it encounters fields named FIRST and LAS.T.

3.12

FMS Advanced Programming
The following chapter discusses advanced programming techniques in two
areas of FMS usage. The first section discusses how to enhance FMS performance; the second looks at the most effective way to design FMS overlaying
forms. A working familiarity with these techniques will help FMS users to
get the most out of FMS.

3.12.1

FMS Performance

This section provides information on how to maximize system performance
while using VAX FMS. Sub-sections include FMS Library Performance and
Form Driver Ordering of Calls.
The manner in which forms are stored
and arranged in FMS libraries can either help or hurt performance. By
observing the following, you are assured that your FMS form libraries will.
not hinder overall system efficiency:
3.12.1.1

FMS Library Performance -

Compression

always compress form libraries when transferring an
application from the development cycle to the production
cycle. Use the command:
$

Form Order

3-22

FMS/LIBRARY/CREATE library librarY.FLB

always insert commonly accessed forms in the library first.

Programming Techniques and Examples

Access Method

use the access method best suited to the application's
forms, choosing from the following:
1. Memory Resident:
• for forms that are displayed repeatedly such as main
menus,
• for times when the number of forms used by the application is small, or when the application is self
contained.
2. Dynamic Memory Resident:
• the dynamic memory resident list is searched first
when looking for a form,
• used for forms which are displayed for a selected function, such as sub-menus and "pages."
• also used when a memory resident form needs to be
replaced at run-time with a form of the same name from
a form library.
3. Media Resident:
• for forms that are seldom accessed, i.e. Help forms,
• used during application development when forms are
modified frequently and relinking is not desired.

Form Driver performance can be
enhanced by using the most current calls available and by correctly ordering
the Form Driver calls. FMS V2 calls are more efficient in both CPU time and
1/0. Using FDV$INIT causes extra 1/0 on every Form Driver 1/0 call. Following these suggestions, and observing the correct ordering of FDV calls, as
shown below, will maximize Form Driver performance.
3.12.1.2

Form Driver Performance -

Programming Techniques and Examples

3-23

Ordering of Form Driver Calls
Efficient

Inefficient

Displaying A Form
FDV$LOAD

FDV$LOAD

FDV$DISP

FDV$DISPW

Initializing Fields
FDV$DISP

FDV$LOAD

FDV$PUT

FDV$PUTAL

FDV$PUT

FDV$DISPW

FDV$PUT

Using Dynamic Memory Resident
Forms
FDV$LOAD

FDV$READ

FDV$LOAD

FDV$DISPW

Checking Status
FDV$xxxxx

FDV$SSRV

FDV$STAT

FDV$xxxxx

FDV$STAT

FDV$xxxxx

FDV$xxxxx
FDV$STAT

3.12.2

Designing Overlaying Forms

This section exists to help the programmer effectively use overlaying forms.
To design overlaying forms, the programmer should have a clear understanding of FDV screen management. Therefore, the following sections include a
list of FDV screen management rules, and an example of overlaying form
design.
FDV Screen Management Rules - This section lists screen management rules. It consists of lists detailing when the FDV repairs screens, when
the screen or workspace is broken, and the workspace repair sequence.

3.12.2.1

3.12.2.1.1

Screen repair occurs when:

• Operator requests a screen refresh

3-24

Programming Techniques and Examples

• Program calls FDV$RFRSH
• Returning from HELP
• Displaying a form
• Returning from a User Action Routine (UAR)
• Program calls FDV$PUTxx or FDV$GETxx to fields where the workspace that contained the fields was "broken."
1

3.12.2.1.2 The screen or workspace is "broken~ when: -

• The program calls FDV$GETDL on a line other than the last
• The program calls FDV$PUTL on a line other than the last
• The area to clear of an overlaying form clears lines of the form
• The program calls FDV$CLEAR
3.12.2.1.3 Workspace Repair Sequence - The workspace is repaired in this

order:
1. All workspaces, marked as displayed, are redisplayed in the order that
they were attached, except for the current workspace.
2. The current workspace is redisplayed.
3.12.2.2 Overlaying Form Design - The following example includes three
forms, each with its own values for Area To Clear (ATC). The ATC is the area
to be cleared when a form is displayed. A call to FDV$CDISP clears the entire
screen, marks all workspaces as "not displayed" and displays the new form.
However, to overlay forms as shown below, the programmer uses FDV$DISP,
which displays the new form, clearing only those lines specified by the ATC.

Programming Techniques and Examples

3-25

FORM A

ATC
3:10

FORM B

I
AT c
1: 23

FORM C

ATC 0:0

ZK-1840-84

Figure 3-1: Over laying Forms
The following table compares different form displaying calls and area to clear
combinations pertaining to overlaying forms, and their results.

FDV$CDISP
ATC 1:23

FDV$CDISP
ATC 0:0

FDV$CDISP
ATC 1:23

FDV$DISP
ATC 1:23

All WKSP marked
not displayed
except current

No modification
of other WKSP

FDV$CDISP
ATC 0:0

FDV$DISP
ATC 0:0

Screen cleared
and WKSPs marked
as not displayed

No screen clear
No modification
of other WKSP

FDV$DISP
ATC 1:23

FDV$DISP
ATC 0:0

Screen has been
broken

Screen has not
been broken

No
Difference

ZK-1841-84

Figure 3-2: Comparison of Overlaying Calls

3-26

Programming Techniques and Examples

Chapter 4
Linking the Application and Setting up the Terminals
In the development of an FMS application, there are initially three processes:
• Creating forms and form libraries
• Writing the application program
• Writing user action routines (UARs)
These must, of course, be made into linkable object files. You then can link
your object program with the Form Driver and, optionally, with any memoryresident forms or UARs you wish to include. (See Figure 4-1)
The Form Driver supports several terminal types and performs screen management correctly if you and your program follow certain procedures regarding setting the terminal characteristics and sending output to the terminal.

4-1

Memorv·
resident
forms

UAR vector
module

UAR object
module

Main program
object module

-- ---

ZK-1839-84

Figure 4-1 Linking the FMS Application

4.1

Linking
4.1.1

Linking with the Form Driver Library

Linking with the Form Driver Library is automatic, since the Form Driver
routines are linked as a shared image:
$

LINK MY PROG

4.1.2

Linking with Memory-Resident Forms

Using the Form Application Aid FMS/OBJECT gives you a linkable file of
memory-resident forms:
$

FMS/OBJECT formlist ••• /OUTPUT=MRF.OBJ

Then:
$

LINK MYPROG1MRF

The advantages of keeping forms in memory are:
1. Faster access

2. Reduced disk overhead

4-2

Linking the Application and Setting up the Terminals

The disadvantages are:
1. Larger executable disk images
2. Necessity to relink whenever a form changes

4.1.3

Linking with a UAR Vector

You use the Form Application Aid FMSNECTOR to get a vector module. The
module contains a table of U ARs. You must link the modules with your program so the Form Driver knows where the U ARs are when they are needed:
$ FMS/VECTOR FRMFIL1.FRMtMYLIB.FLB/FORM_NAME=<FORM1 tFORM3)/0UTPUT=UARS1.0BJ
$LINK MYPROGtUARS1 application:

4.2 Terminal Use in FMS Programs
4.2.1 Terminal Characteristics
To support a variety of terminals, to allow typeahead, and to conform with
DIGITAL's long-term terminal software strategy, the Form Driver queries the
operating system and not the terminal to find the terminal options and current characteristics. This means that you should set VMS's knowledge of your
terminal carefully before starting an FMS application program. One method
of doing this is by is~uing the following VMS command before running your
application:
$ SET TERMINAL/INQUIRE

VMS will then query the terminal and record the terminal's characteristics
correctly.
Between the issuing of this DCL command and its completion, you should not
type ahead. Putting the SET TERMINAL/INQUIRE command in your login
command file is a good idea.
If your terminal differs from VMS's knowledge of your terminal, your FMS
application may not perform correctly. You can see what VMS thinks your
terminal type is by issuing the following VMS command:
$ SHOW TERMINAL

You will see displayed values for terminal attributes: type, width, advanced
video, ANSLCRT, and DEC_CRT, among others. Your terminal should be
either a VT52, or it should have at least the ANSLCRT attribute. It should
also have the DEC_CRT attribute as appropriate. See the VAX documentation for an explanation of these attributes. Make sure that the terminal width
and the advanced video option attributes are set correctly for your terminal.

Linking the Application and Setting up the Terminals

4-3

4.2.2 Direct Terminal Output
To optimize output to the terminal, the FMS V2 Form Driver assumes that it
has sole control of the terminal once the terminal has been attached. Your
program should not normally send output directly to an attached terminal;
all output to an FMS terminal should go directly through FMS. Direct output
to the terminal will likely be displayed at unexpected positions with
unwanted video attributes, line attributes, or character set.
If your program changes the cursor position, video attributes, line attributes,

or character set, subsequent calls on the Form Driver may yield incorrect
results on the screen. The only circumstances under which you can send output directly to the terminal and not confuse the Form Driver is if you restore
any changes you have made before calling the Form Driver again. The
CLEAR_VA, FIX-8CREEN, and SCR_WIDTH calls may be used for this
purpose.

4.2.3 Terminal State at Program End
Because the Form Driver minimizes output, it will leave the terminal in an
awkward state if you fail to detach the terminal. Detaching the terminal
clears video attributes, clears the last line, and positions the cursor at the
bottom left corner of the screen with the terminal width set to that of the last
form displayed.
Note that the design of some terminals makes it impossible to determine
some of the attributes from the terminal sothat neither the Form Driver nor
your program can r..estore them once they have been changed:
•LEDs
• Character set
• Screen background
All these attributes remain in the state last set by the application program's
form use and terminal control calls.

4.2.4 Firmware Bug Workaround
Many VTlOOs have a firmware bug that the Form Driver must work around.
(This workaround itself may appear to be a bug, but it is not.) The firmware
bug appears when a scrolled area is immediately below a line having the
double-high or double-wide attribute, and the terminal is in jump scroll
mode. The bug is that the scrolled lines lose characters, or the terminal may
enter self-test mode.
The workaround used by the Form Driver is to set the line above the scrolled
area to be normal size during the scrolling and then reset it to double high or
double wide afterward. This may be visually disturbing but does not affect
your program. The visual effect can be avoided by not setting the line above a
scrolled area to double high or double wide in the form definition.

4-4

Linking the Application and Setting up the Terminals

Chapters
FORM DRIVER CALLS
The following sections contain descriptions of all Form Driver calls.
The call format shows the generic form of each call, with the FDV$ prefix you
must specify with each call name (for example, FDV$ATERM - not just
ATERM), and any arguments you must (or can) supply. Each argument is
defined, and it is noted whether the Form Driver reads the argument from
your program, writes (returns) it to your program, or both reads and writes
(modifies) it. In your program you terminate a call by pressing the RETURN
key unless the manual specifies otherwise.
You always specify an address for an argument rather than the actual data to
be processed by the call or returned to your program. Each argument definition indicates the method of passing the argument:
• By reference - The address contains the value itself (used for passing
integers).
• By descriptor - The address contains the address of a descriptor containing
necessary information (used for passing character strings or integer
arrays).
See the VAX FMS Language Interface Manual for details of the calling
requirements unique to each language (for example, CALL FDV$ATERM).
See also the appendix to this manual for a complete list of Form Driver calls
showing the procedure parameter notation.

Description
Describes what the call does, any relationships to other calls, and restrictions
on the use of the call.

Status Codes
Report for each call successful execution of the call or any failures that occur
during processing of the call.

5-1

ADLVA
5.1

Alter Data Line Video Attributes
FDV$ADLVA (video)
video

The video attributes code. Set to 1, any or all of bits 0, 1, 2, and 3 specify anyor all of
the Bold, Blink, Reverse, and Underline attributes, respectively (decimal value in
the range 0 to 15). Ifthe value of this argument is negative, the video attributes are
restored to their initial states. (Modified. Passed by reference.)

Attributes
Value
None
0
Bold
1
Blink
2
Blink and Bold
3
Reverse
4
Reverse and Bold
5
Reverse and Blink
6
Reverse, Blink, and Bold
7
Underline
8
Underline and Bold
9
Underline and Blink
10
Underline, Blink, and Bold
11
Underline and Reverse
12
Underline, Reverse, and Bold
13
Underline, Reverse, and Blink
14
Underline, Reverse, Blink, and Bold 15
Restore attributes to initial state
-n
(-n is any negative integer)

Description
Lets you alter the video attributes for the current terminal's data line. You
can also specify that these video attributes be restored to their original states.
The data line video attributes affect the appearance of (1) Form Driver
messages, which are output to the bottom line of the screen, and (2) other
lines of text, which are displayed by the execution of PUTL or GETDL calls.
This call returns the previous contents of video. The data line video attributes are returned encoded in the same format you used for the input of the
new video attributes.

Status Codes
FDV$_ARG
FDV$-CAN
FDV$-SUC
FDV$_SYS
FDV$_TCA

5-2

FORM DRIVER CALLS

Incorrect number of arguments.
Call was terminated by a CANCL call.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.

AFCX
5.2 Alter Field Context
FDV$AFCX (insovr,curpos[,fldnam[,fldidx]])
insovr

The code indicating whether Insert or Overstrike mode is in effect for a field.
(Read. Passed by reference.)
0 =No change
1 = Insert mode
2 = Overstrike mode

curpos

The cursor position within a field. The cursor position is 1 for the leftmost data
character in the field, 2 for the next data character to the right, n for the rightmost
character in the field, and n + 1 for the character position to the immediate right
of the rightmost data character (the hanging cursor position). Field-marker characters are not counted by the cursor. The range of the cursor, 1 ton + 1, is limited
to the number of data characters in the field plus 1. (Read. Pass~d by reference.)
For fixed-decimal fields, the range of the cursor is 1 to + 2, because the decimal
point is counted even though it is not a data character. This allows the cursor to be
positioned on the decimal point, in the hanging cursor position for the left-hand
part of the field.

fldnam

The field name. If fldnam is not specified, the current field is assumed. (Read.
Passed by descriptor.)

fldidx

The field index. (Read. Passed by reference.)

Description
Alters the default input mode of a field. This call specifies both the
Insert/Overstrike mode of the field and the cursor position in the field for any
GET-type call operation affecting the field.
The new context specified by this call remains in effect until the field is
processed as part of any GET-type call. The context is restored to its default
state when the operator exits the field. Note that if the input processing is
part of a GETAL or GETAF call, passing through the field in the normal
course of moving the cursor about on the screen restores the default field
context.

Status Codes
FDV$_ARG
FDV$_CAN
FDV$-DSP
FDV$-FLD
FDV$_INI
FDV$_NFL
FDV$_NOF
FDV$-SUC
FDV$_TCA
FDV$_VAL

Incorrect number of arguments.
Call was terminated by a CANCL call.
Form contains only display-only fieids.
Field does not exist, or index value is invalid for field.
No workspace is defined.
No form loaded in current workspace.
Form contains no fields.
Successful completion of the call.
No terminal control area (TCA) is defined.
The value of insovr or curpos is outside the allowed range.

FORM DRIVER CALLS

5-3

AFVA
5.3

Alter Field Video Attributes
FDV$AFVA (video[,fl.dnam[,fl.didx]])
video

The video attributes code. Set to 1, any or all of bits 0, 1, 2, and 3 specify any or all of
the Bold, Blink, Reverse, and Underline attributes, respectively (decimal value in
the range 0 to 15). If the value of this argument is negative, the video attributes are
restored to their initial states. (Modified. Passed by reference.)

Attributes

Value

None
Bold
Blink
Blink and Bold
Reverse
Reverse and Bold
Reverse and Blink
Reverse, Blink, and Bold
Underline
Underline and Bold
Underline and Blink
Underline, Blink, and Bold
Underline and Reverse
Underline, Reverse, and Bold
Underline, Reverse, and Blink
Underline, Reverse, Blink, and Bold
Restore attributes to initial state
n is any negative integer)

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
-n

fl.dnam

The field name. If fl.dnam is not specified, the current field is assumed. (Read.
Passed by descriptor.)

fl.didx

The field index. (Read. Passed by reference.)

Description
Lets you alter the video attributes of a field in a form. You can also use this
call to restore these video attributes to their original states. The field video
attributes immediately change on the screen and remain in effect until you
either issue another AFVA call to change them, or you redisplay the form by
issuing a DISP or CDISP call.
This call returns the previous contents of video. The video attributes for a
field are returned encoded in the same format you used for the input of the
new video attributes.
If you alter the video attributes of a field by issuing an AFVA call, you cancel
any input highlighting for the field. That is, if highlighting is in effect for the
form, it will not be used for this field. You restore highlighting by restoring
the default video attributes of the field.

5-4

FORM DRIVER CALLS

AFVA (Cont.)
Status Codes
FDV$-ARG
FDV$_CAN
FDV$_FLD
FDV$--1NI
FDV$_NFL
FDV$-NOF
FDV$_SUC
FDV$_SYS
FDV$_TCA

Incorrect number of arguments.
Call was terminated by a CANCL call.
Field does not exist, or index value is invalid for field.
No workspace is defined.
No form loaded in workspace.
Form contains no fields.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

5-5

ATERM
5.4

Attach Terminal
FDV$ATERM (tca,size,channel[,trmnal[,faketrmtyp[,options]]])

size

The name of a terminal control area. The TCA size, contained in the
descriptor, must be at least 12 bytes. (Modified. Passed by descriptor.)
'
The size of the TCA in bytes. (Read. Passed by reference.).(lgnored in VMS.)

channel

The logical 1/0 channel number for the terminal. (Read. Passed by reference.)

trmnal

The name of the terminal to be associated with the TCA. If trmnal is omitted,
the default is SYS$INPUT. (Read. Passed by descriptor.)

faketrmtyp

The name of the terminal type the Form Driver assumes for batch use. The
only valid string supported currently is "VTlOO". If this argument is givem,
there is no real input or output to the terminal. (Read. Passed by descriptQr.)

options

An integer specifying which Form Driver options are to be associated with
this terminal. When specifying the option, the integer is a longword with the
following bits:

tea

BIT Setting

Meaning

The screen shall not be cleared when attaching the terminal.

The Form Driver clears the terminal's video attributes after
each call (see CLEAR_VA)

AST support is not required. Requesting this option improves
performance (see AST considerations).

3-31

Reserved by Digital.

Description

Attaches a terminal to the Form Driver. You must issue an ATERM call for
any terminal the Form Driver needs to access for form processing. This call
makes the attached terminal the current terminal.
When you specify a channel, you are specifying a logical channel. FMS asks
VMS to assign a physical channel. If you want the Form Driver to use a particular channel, first issue ATERM and then issue TCHAN. Form Driver logical channel numbers are all interpreted modulus 256.
The channels specified in the Form Driver calls ATERM, LCHAN, and
L-OPEN are strictly local to FMS and have no relationship to Logical Unit
Numbers used by FORTRAN and BASIC. These channel numbers provide a
means of reference only. The Form Driver keeps an association list of all logical channels currently in use by the application program. Logical terminal
numbers and logical form library numbers must not conflict; that is, a logical
terminal channel number cannot be used as a logical form library channel
number.
ATERM lets you specify a terminal control area for this terminal. This area
maintains all necessary information about current terminal characteristics
and associations. Other calls refer to these areas implicitly or explicitly
whenever they need to indicate a particular terminal. The terminal must be
VT200-, VTlOO- or VT52-compatible.

5-6

FORM DRIVER CALLS

ATERM (Cont.)
When the faktrmtyp argument is used in ATERM to attach a fake terminal,
the terminal so attached is defined as a VTlOO type terminal with 65 lines
and 132 columns (instead of just 24 lines). This gives applications the opportunity to use such a fake terminal to produce a line printer report. Calls to
RETFL, for such a terminal, can access lines 1through65. Since the Form
Language and the Form Editor allow the production of forms only 23 lines
long, three forms in three workspaces (with appropriate offsets) are necessary
to produce a full screen of output.
If the faketrmtyp argument is not supplied (or is null), the terminal specified
in the trmnal argument is attached in the normal fashion. When faketrmtyp
is specified as the descriptor of a character string containing "VTl 00'', no
actual terminal attachment is made, and the trmnal argument is ignored.
Any calls for input on the terminal specified by this TCA result in FDV$--1TT
errors. All output normally directed to the screen is suppressed. However,
calls that normally produce output, such as CDISP and PUT, still modify the
workspace. The Form Driver can then be used as an output formatting tool.
The faketrmtyp argument causes subsequent calls to RETFL to produce line
images ·or what would have been displayed.
The options argument is useful when you want your program to retain part of
the current screen while FMS is using another part of the screen. The options
argument is further defined by setting the two low order bits of the argument.
Bit 0 is described above. Bit 1 set to 1 directs the Form Driver to reset the
video attributes and character set of this terminal to the clear state (no video
attributes and character set shifted in) after every Form Driver call. Bit 1 set
to 0 directs the Form Driver to leave the attributes of the terminal set
between calls to achieve minimal output.
The use of the second bit in ATERM makes it easier to perform direct screen
management between Form Driver calls, at the price of additional output on
every Form Driver call that touches the screen. A program that performs
direct screen management can choose either to attach the terminal with this
bit set, or to call FDV$CLEAR_ VA at appropriate times. Using
FDV$CLEAR_VA requires more care on the part of the program, but allows
the Form Driver to optimize output slightly.
AST support requires a great deal of overhead in the Form Driver. If your
application does not need AST reentrant support,· setting bit 2 greatly
reduces the overhead in the Form Driver and will improve its performance.
However, you must not set this bit if your applications use the Form Driver in
an AST fashion. This will cause unexpected results.
In addition, ATERM clears the screen and turns the LEDs off.
If you do not specify a terminal, the default terminal is attached.

FORM DRIVER CALLS

5-7

ATERM ccont.>
Status Codes

FDV$-ARG
FDV$_CAN
FDV$__ICH
FDV$_ITT
FDV$_IVM
FDV$_STA
FDV$-8UC
FDV$_SYS
FDV$_VAL

5-8

FORM DRIVER CALLS

Incorrect number of arguments.
Call was terminated by a CANCL call.
Logical channel specified was either in use or invalid.
Illegal terminal type.
Not enough virtual memory could be allocated for the TCA.
Size of specified TCA is too small.
Successful completion of the call.
Form Driver encountered system error response.
Either the faketrmtyp argument was given and it was not
"VTlOO", or the options argument was given and it was not
within the range of0-7.

AWKSP
5.5

Attach Form Workspace
FDV$AWKSP (wksp,size)
wksp

The form workspace location. The length (in bytes) recorded in the descriptor, must
be a value of at least 12. (Modified. Passed by descriptor.)

size

An estimate of the workspace size in bytes. If the size turns out to be too small, the
Form Driver automatically increases it. (Read. Passed by reference.)

Description
Attaches a form workspace to the current terminal. You must issue an
AWKSP call for any form your application processes on any terminal. This
call makes the attached workspace the current workspace.
The Form Driver uses the 12-byte area specified in the wksp descriptor as
linkage to an area that it allocates in virtual memory. This area is used to
store the variable part of a form description.
The size argument is an estimate of the storage space needed for a loaded
form. If you underestimate the amount of space you need, the Form Driver
automatically allocates more space - but a large enough estimate can save
time.
You can use the FMS/DIRECTORY command to find out the workspace· size
you need for each form you expect to use. (See the VAX FMS Utilities Reference Manual, Chapter 6, Form Application Aids.)

Status Codes
FDV$-ARG
FDV$_CAN
FDV$-1MP
FDV$_IVM
FDV$_SUC
FDV$_TCA

Incorrect number of arguments.
Call was terminated by a CANCL call.
Length specified in wksp descriptor is not large enough.
Not enough virtual memory could be allocated for the workspace.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

5-9

BELL
5.6

Ring Terminal Bell
FDV$BELL
Description

Rings the terminal bell. If the current terminal is defined, this call rings its
bell. If the current terminal is not defined, the call rings the bell on the application program's default terminal. This call rings the bell regardless of the
signal mode (see the SSIGQ and SIGOP call descriptions).
Status Codes

FDV$-ARG
FDV$_CAN
FDV$_SUC
FDV$_SYS

5-10

Incorrect number of arguments.
Call was terminated by a CANCL call.
Successful completion of the call.
Form Driver encountered system error response.

FORM DRIVER CALLS

CANCL
5.7 Cancel Call
FDV$CANCL

Description
Causes any other Form Driver call presently being processed on the current
terminal to be terminated with the error condition FDV$_CAN.
This call has no effect unless it is executed from an AST service routine or a
UAR, since no other call can otherwise be executing.
When executed, this call causes two things to happen:
1. All 1/0 operations associated with the current terminal are canceled.

2. Until the cancellation processing is complete, any other call involving the
same TCA as that of the call being canceled is itself canceled when issued.
This action is taken to ensure that all calls issued by a UAR are canceled
as well.
As a result of these two activities, the call normally terminates almost immediately. If a call has called a UAR, however, the call-processing code cannot
terminate processing until the UAR returns control to the Form Driver. Upon
return from a UAR, the Form Driver checks to see if the TCA is marked as
processing a CANCL operation and ifit is, the call is terminated.
If a call is canceled after its UAR has begun executing, any subsequent calls

the UAR might issue will also be terminated with the status of FDV$_CAN.
CANCL returns FDV$_SUC whether or not any call is canceled.

Status Codes
FDV$_ARG
FDV$_SUC
FDV$_SYS
FDV$_TCA

Incorrect number of arguments.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

5-11

CDISP
5.8

Clear Screen and Display Form
FDV$CDISP (frmnam[,offset])
frmnam

The name of the form. (Read. Passed by descriptor;)

offset

The position of the form on the screen. (Read. Passed by reference.)
• If offset contains 0, the Form Driver positions the form on the screen as specified
in the form description.
• If offset contains a nonzero value, the Form Driver moves the form up (if the
value is negative) or down (if the value is positive) by the amount specified.

Description
Executes a CLEAR call and then a DISP call, clearing all forms from the
screen (marking them as undisplayed) and displaying a new form. If any
other workspaces are attached to the current terminal, your program can
redisplay their forms by issuing DISPW calls on their workspaces. See the
description of the DISP call for additional details.

Status Codes
FDV$....ARG
FDV$_CAN
FDV$_FCH
FDV$_FNM
FDV$-FRM
FDV$-IFU
FDV$....INI
FDV$....IOR
FDV$....IVM
FDV$_LIN
FDV$_SUC
FDV$_SYS
FDV$_TCA

~12

Incorrect number of arguments.
Call was terminated by a CANCL call.
Form was not memory resident, and when the Form Driver
attempted to search for it in a form library, the current
library channel was not open.
Binary form description could not be found either in the form
library or in the list of memory-resident forms.
Form description is invalid.
Workspace cannot be loaded at this time because it is the
workspace for a currently active UAR.
No workspace is defined.
1/0 error occurred while Form Driver was reading in the form
from the form library. The 1/0 error code is recorded in the
current state. You can obtain it by issuing the STAT call.*
Not enough virtual memory could be allocated for the workspace.
Starting offset is invalid. Form does not fit on the screen if
offset by the amount specified.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

CLEAR
5.9 Clear Screen
FDV$CLEAR ([line.rl.r[,linecnt.rl.r]])
line

The number of the first line of the screen to be cleared. A value of zero specifies the
top of the screen. (Read. Passed by reference.)

linecnt

The number oflines to clear. If you specify 0, all lines from the line you.specified in
the line argument to the bottom of the screen are cleared. (Read. Passed by reference.)

Description
Clears all or part of the screen. If line is greater than zero, the screen is
cleared frem that line down; otherwise, the screen is cleared from the top
down. If linecnt is greater than zero, it specifies the number of lines to be
cleared. If it is zero, the screen is cleared to the bottom of the screen.
A refresh operation (whether by your program or by the operator) following a
CLEAR operation restores the entire screen, including the cleared area.
Following the CLEAR operation, the cursor is positioned at the leftmost character position on the first line cleared.

Status Codes
FDV$_ARG
FDV$_CAN
FDV$_LIN
FDV$_SUC
FDV$_SYS
FDV$_TCA

Incorrect number of arguments.
Call was terminated by a CANCL call.
Call specifies that some line not on the screen be cleared.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

5-13

CLEAR_VA
5.1 O Clear Video Attributes
FDV$CLEAR_VA

Description
Clears the screen of video attributes and sets certain other terminal attributes. It is useful when you want your program to write to, or control the
screen, directly, while a terminal is still attached to FMS. CLEAR,_VA performs the following operations:
For VT52-type terminals:
• Shifts in character set.
For VTlOO-type terminals:
• Shifts in character set.
• Turns off the screen's video attributes.
• Sets newline mode.
• Resets the scrolling area.
• Sets absolute origin mode.
This call does not affect the character sets currently selected in GO or G1 for
VTlOO-compatible terminals, the width of the screen, or the background color
of the screen.
CLEAR_VA should be issued in the following situations:
• Just before your program starts its own direct screen management
after FMS has been controlling the screen. This clears the screen of
any attributes (most importantly, video attributes) that FMS may
have left, so that your program can start with a known, clean screen.
• Just before your program calls FMS after your program has changed
any of the above attributes of the screen. This clears the screen of any
attributes your program may have left, so that FMS can continue with
a known screen.
See also the description of S.CR_WIDTH for information on a call that
informs the Form Driver that your program has changed the width of the
screen.

Status codes
FDV$_ARG
FDV$_CAN
FDV$_SUC
FDV$_TCA

5-14

Incorrect number of arguments.
Call was terminated by CANCL call.
Success.
No current terminal.

FORM DRIVER CALLS

DEL
5.11

Remove Form from Memory-Resident Form List
FDV$DEL(frmnam)
frmnam

The name of the form. (Read. Passed by descriptor.)

Description
Deletes a memory-resident form from the list of memory-resident forms you
loaded with the READ call. You cannot delete with this call those memoryresident forms that are built into the application program.
If the form you specified is not found, or ifit is in the set of forms built into the
application, this call returns the status code of FDV$_FNM.

Status Codes
FDV$_ARG
FDV$_CAN
FDV$_FNM
FDV$-8UC

Incorrect number-of arguments.
Call was terminated by a CANCL call.
Binary form description could not be found in the set of memory-resident forms that could be deleted (that is, those loaded
by a READ call).
Successful completion of the call.

FORM DRIVER CALLS

5-15

DFKBD
5.12

Define Keyboard
FDV$DFKBD (detkbd,kbdnum)
detkbd

An array of key functions and key codes. (Read. Passed by descriptor.)

kbdnum The number of entries in the detkbd array. Each entry is a pair of array slots.
Thus, the length of the array must be at least two times kbdnum. (Read. Passed by
reference.)

Description
The Form Driver has 17 functions and provides default keys to perform these
functions. However, the user can override these default Form Driver function
key assignments using defkbd. The defkbdargument is a one-dimensional
array of words, with kbdnum pairs of entries. (That is, defkbd is expected to
be two times kbdnumwords.) The first word of each pair is a Form Driver key
function, as defined below. The second word is a Form Driver key code as
defined in Chapter 2. Two special key codes are FDV$K_KF_DFLT and
FDV$K_KF_NONE.
1. FDV$K_KF-DFLT declares that the key code for the key function is to be

the default. (This restores the default after a previous change.)
2. FDV$K_KF_NONE declares that no key code is to be associated with the
key function. (The key function is deleted.)
The key codes in detkbd replace the current key codes for the current TCA.
Note that not all key functions need be specified in a given call. Only those in
detkbd are affected. The detkbdarray is merged with the currently active
table to produce the table used by the Form Driver.
As a result of the merging of detkbd and the current definitions, no key code
can be assigned more than one key function. Assigning FDV$K_KF__DFLT to
a key function assigns all key code defaults to that key function.
The following table lists the FDV functions and the default key assignments.

Function
Name

Description

VTlOO
Key Sequence

DFKBD
Value

FDV$K_KF_DLCHR

Delete character

DELETE

FDV$K_KF_CRSRT

Move cursor right

Rightarrow

FDV$K_KF_CRSLF

Move cursor left

Leftarrow

FDV$K_KF_DLFLD

Delete field

LINEFEED

FDV$K_KF_INS

Set Insert mode

PF1PF3

FDV$K_KF_OVR

Set Overstrike mode

PF3

FDV$K_KF_GOLD

Gold sequence starter

PFl

FDV$K_KF_RESET

Reset Gold sequence

PFlDELETE

(Continued on next page)

&-16

FORM DRIVER CALLS

DFKBD (Cont.)
Function
Name

VTlOO
Key Sequence

Description

DFKBD
Value

FDV$ILKF_RFRSH

Refresh screen

CTRL/R

FDV$ILKF_HELP

Help

PF2

FDV$K_KF_NXT

Next field

TAB

FDV$K_KF_PRV

Previous field

BACKSPACE

FDV$K_KF_NTR

Enter Form

RETURN or ENTER

FDV$K_KF_SBK

Scroll backward

Uparrow

FDV$K_KF_SFW

Scroll forward

Downarrow

FDV$K_KF_XBK

Exit scrolled area backward

PFl Uparrow

FDV$K_KF_XFW

Exit scrolled area forward

PFl Downarrow

The following example shows how to use the DFKBD call to switch the functions of the RETURN and TAB keys. After this call is executed, RETURN
(and the ENTER key) will mean Next Field (FDV$1LFT_NXT), and TAB
will mean Enter Form (FDV$K_FT_NTR). The example is given in
FORTRAN.
INTEGER TCAC3>
INTEGER-*2 KEYTABLEC4> I FOV$K_KF_NTRt 1033t
1
FOV$K_KF_NXTt 1037 I
CALL FOV$ATERM C%DESCR CTCA > t 12t1)
CALL FOV$0FKBDC%DESCRCKEYTABLE> 12)

Status Codes
FDV$_ARG Incorrect number of arguments.
FDV$_CAN

Call was terminated by a CANCL call.

FDV$-KEX

Too many key codes were defined for some key function.

FDV$_KIF

Illegal key function was given.

FDV$_KIL

Illegal key code was given; that is, the key was not on the
list in Chapter 2.

FDV$-KTW

Key code was given two separate key functions.

FDV$_SUC

Successful completion of the call.

FDV$_TCA

No terminal control area (TCA) is defined.

FORM DRIVER CALLS

5-17

DISP
5.13 Display Form
FDV$DISP (frmnam[,offset])
frmnam

The name of th~ form. (Read. Passed by descriptor.)

offset

Description
Displays a form, clearing the portion of the screen specified as the clear area
in the form description. Any portion of the screen not cleared is overwritten
by nonblank portions of the form. If offset has a value of zero, the form is
positioned as specified in the form description. If offsetcontains a nonzero
value, the Form Driver moves the form up (if the value is negative) or down (if
the value is positive) by the amount specified.
If the form does not fit on the screen (that is, if some portion of background
text falls outside the area of line 1 through line 23, or line 1 through line 14
for a non-AVO terminal in· 132-column mode)~ the Form Driver returns the
FDV$-LIN status code.
If the form specifies a screen width different from the current width, the
formwide screen width attribute determines the Form Driver's action:
• If the form does not have the screen width attribute, the Form Driver does
not modify the width. No error can occur with SO-column forms because
they always fit. Forms having 132 columns do not fit if the screen is currently set. for SO columns wide.

• If the form does have the screen width attribute, the Form Driver always
modifies the screen width. If the form is an SO-column form, but a 132-column form is already displayed on the screen, the 132-column form is
removed from the screen and marked as undisplayed. The form specified in
the call is displayed.
For terminals not capable of being switched to 132 columns, 132-column
forms cause an error.
If the form being displayed specifies that the screen video be modified when
the form is displayed, the screen video is set as directed, regardless of what
screen video specifications are associated with any other form already displayed from other attached workspaces.

5-18

FORM DRIVER CALLS

DISP (Cont.)
If the background text or fields of the form displayed overlap any background
text or fields of another form already displayed on the screen, the previous
text is replaced. If the screen is refreshed, however, the final screen image
may be changed because the workspaces are redisplayed in the· order they
were attached. The workspace's form that is current at the time of the refresh
is displayed properly.
The following may clarify the screen management role of the Form Driver
when overlaid forms are present, and when your program issues PUTL and
GETDL calls to reference lines that are parts of forms.
Whenever the Form Driver is directed to output a value to the screen by one
of the PUT-type field calls (PUT, PUTAL, PUTD, PUTDA, or PUTSC), or is
directed to request input from the operator by one of the GET-type field calls
(GET, GETAF, GETAL, or GETSC), it first checks to see if the form containing
the field is still intact on the screen. If the form has been disturbed in any way,
the Form Driver redisplays it.
A form is disturbed in one of two ways:
1. Part of it has been overlaid by another form (in a subsequent DISPW call,
RFRSH call or operation, or help request).

2. Part of it has been overlaid by a PUTL or GETDL call.
No matter what part of the form has been overlaid, the Form Driver ensures
that the entire form is displayed.
The Screen Area to Clear attribute of a form is included in the description of
the form, so that the form designer should consider how much of the screen
should be included in this attribute at design time. Even if the form does not
specify text or fields for a line, the Screen Area to Clear attribute may specify
that the line be blank when the form is displayed.
The Form Driver honors the form description whenever the form is referenced. If you find a form being redisplayed when you do not expect it, it is
most likely that part of the form has been overwritten.

Status Codes
FDV$_ARG
FDV$_CAN
FDV$-FCH
FDV$-FNM
FDV$-FRM
FDV$-1FU
FDV$-1NI

Incorrect number of arguments.
Call was terminated by a CANCL c~ll.
Form was not memory resident, and when the Form Driver
attempted to search for it in a form library, the current
library channel was not open.
Binary form description could not be found either in the form
library or in the list of memory-resident forms.
Form description is invalid.
Workspace cannot be loaded at this time because it is the
workspace for a currently active UAR.
No workspace is defined.

FORM DRIVER CALLS

5-19

DISP <cont.>
FDV$_10R
FDV$_IVM
FDV$_LIN
FDV$_SUC
FDV$_SYS
FDV$_TCA
FDV$_WID

5-20

110 error occurred while Form Driver was reading in the form
from the form library. The 1/0 error code is recorded in the
current state. You can obtain it by issuing the STAT call.
Not enough virtual memory could be allocated for the
workspace.
Starting offset is invalid. Form does not fit on the screen if
offset by the amount specified.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.
The form to be displayed will not fit on the screen (132-column form on a VT52).

FORM DRIVER CALLS

DISPW
5.14

Display Loaded Form
FDV$DISPW ([offset])
offset

Description

Displays on the current terminal a form already loaded in a workspace. A
form can be resident in a workspace but undisplayed for any of the following
reasons:
• It was previously loaded by a LOAD call.
• It was removed from the screen as a side effect of a CDISP call.

• It was a 132-column form that was removed from the screen as a side effect
of another display call that loaded an 80-column form having the screen
width attribute (see the description of the DISP call).
• It was marked as not displayed by the execution of an ND ISP call.

DISPW clears any portion of the screen (possibly offset by the offsetargument) that was specified as an area to be cleared in the form description. Any
other portion of the screen is modified only if it is overwritten by the background or field text of the form displayed. See the description of the DISP call
for additional details.
Status Codes

FDV$--1\RG
FDV$_CAN
FDV$_FCH
FDV$_FNM
FDV$-1NI
FDV$_LIN
FDV$_SUC
FDV$_SYS
FDV$_TCA
FDV$_WID

FORM DRIVER CALLS

5-21

DPCOM
5.15

Define Comma as Decimal Point
FDV$DPCOM ([dpmode])
dpmode

A value determining what the decimal point character is to be:
1 = Comma is accepted exclusively as the decimal point.
0 = Period is restored to its role as the decimal point.
(Read. Passed by reference.)

Description
Defines the comma, or redefines the period, exclusively, as the decimal point
for fields containing the signed numeric (N) picture. The decimal point is
returned to your program as part of the field value (unlike the decimal point
in fixed-decimal fields). The default is the period.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_SUC
FDV$_TCA
FDV$_VAL

f>-22

Incorrect number of arguments.
Call was terminated by a CANCL call.
Successful completion of the call.
No terminal control area (TCA) is defined.
The value of dpmode is outside the allowed range.

FORM DRIVER CALLS

DTE RM
5.16

Detach Terminal
FDV$DTERM (tea)

tea

The name of a terminal control area. (Modified. Passed by descriptor.)

Description
Detaches a terminal from the Form Driver. All workspaces associated with
the terminal are detached, and then the terminal itself is detached. No further Form Driver activity occurs with this terminal after DTERM is executed. Any forms displayed on the detached terminal remain on the screen.
When a terminal is detached, the character video attributes are cleared, the
scroll area (VTl OOs only) is set to the full screen, the bottom line is cleared,
and the cursor is placed at the leftmost position on the bottom line.
Normally, when the TCA is detached from the FMS application program, its
associated terminal is detached from the program. An exception to this rule
occurs if the channel was specified by the TC HAN call. Because TCHAN,
alone, specifies a physical channel rather than a logical one, the terminal is
not detached following a DTERM call.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$-FVM
FDV$--1FU
FDV$_SUC
FDV$-SYS
FDV$-TCA

Incorrect number of arguments.
Call was terminated by a CANCL call.
An error occurred freeing virtual memory allocated to the
application.
Terminal cannot be detached at this time because it is the
terminal for a currently active UAR.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

5-23

DWKSP
5.17

Detach Form Workspace
FDV$DWKSP (wksp)
wksp

The form workspace. (Modified. Passed by descriptor.)

Description
Detaches a form workspace from the current terminal. Any form that is currently displayed remains on the screen.

Status Codes
FDV$-ARG
FDV$-CAN
/FDV$__FVM
FDV$--1FU
FDV$--1NI
FDV$_SUC
FDV$_TCA

5-24

Incorrect number of arguments.
Call was terminated by a CANCL call.
An error occurred freeing virtual memory allocated to the
application.
Workspace cannot be detached at this time because it is the
workspace for a currently active UAR.
Workspace does not exist or is not associated with the current
terminal.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

FILSCREEN
5.18

Repair Overwritten Lines of Terminal Screen
FDV$FILSCREEN

Description
Programs which perform direct screen management may overlay lines of
forms displayed by FMS. Calling FIX_SCREEN will repair these lines with a
minimum of output. FIX_SCREEN is similar to RFRSH, but with two exceptions: FI:x_scREEN does not clear the screen first, and it outputs only those
lines which it knows to have been cleared.
Whenever information is sent to a screen field (by a PUT-type call) or
requested of the screen (by a GET-type call), the Form Driver checks the lines
of the form. If any line has been cleared as described above, the Form Driver
then repairs the affected lines of the screen by calling FIX_SCREEN internally. Thus, your program need do nothing if the screen has been affected by
calls on the Form Driver, such as CLEAR, PUTL, GETDL, DISPW, CDISP, or
DISP, since the Form Driver knows and will fix the screen before the next 110
operation affecting fields.
However, if your program performs direct screen management (that is, it
affects the screen without calling the Form Driver) the Form Driver will not
know when the screen has been affected and will not automatically fix it. If
you wish the Form Driver to restore the screen to the proper state after your
own direct screen management, you must first clear the lines through the
Form Driver. One way of doing this is through the CLEAR call. After the
CLEAR call the Form Driver will know that the lines need to be restored to
their proper form state.

FORM DRIVER CALLS

5-25

GET
5.19

Get Value for Specified Field
FDV$GET (fldval,fldtrm,ftdnam[,ftdidx])
fldval

The field value. The value consists of data characters, but no field-marker characters. If the operator does not enter a character for every position in the field, the
Form Driver fills the empty positions with fill characters. (Written. Passed by
descriptor.)

fldtrm

The field terminator that the operator entered to terminate input to the field.
(Written. Passed by reference.)

fldnam

The field name. (Read. Passed by descriptor.)

fldidx

The field index. (Read. Passed by reference.)

Description
Waits for the operator to type a value into the field you specified, and records
the field terminator in fldtrm. Iffldnam starts with an asterisk(*), the Form
Driver prompts the operator for input to the first modifiable field. If the field is
in a scrolled area, the operation is performed in the current scrolled line for
that area.
If the terminator is a function key not reserved for FMS, the form's function

Form Driver checks the field for Response Required, Must Fill, and field completion UAR requirements. If any requirements are not fulfilled, the operator
must continue input.
The value and its terminator are recorded in the workspace and are returned
to your program. If a field value is changed by the operator when this call is
executed, the status code returned is FDV$_MOD instead ofFDV$_SUC.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_DSP
FDV$-FLD
FDV$_1NI
FDV$_MOD
FDV$_NDS
FDV$_NFL
FDV$_NOF
FDV$_STR

5-26

Incorrect number of arguments.
Call was terminated by a CANCL call.
Form contains only Display Only fields, or the specified field
is Display Only.
Field does not exist, or index value is invalid for field.
No workspace is defined.
Field value in fldval has been modified by the operator. Otherwise, this code is the same as FDV$_SUC.
Form is marked as being not displayed, so no input is
possible.
No form loaded in workspace.
Form contains no fields.
Value being returned is too large for the variable allocated
for it.

FORM DRIVER CALLS

GET (Cont.)
FDV$_SUC
FDV$_SYS
FDV$_TCA
FDV$_TMO
FDV$_UAR
FDV$_UDP
FDV$_UNF

Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.
Operator took longer to respond than allowed by the timeout
value associated with the current terminal.
UAR returned illegal code.
UAR depth exceeded.
UAR specified but not found.

FORM DRIVER CALLS

5-27

GETAF
5.20

Get Value for Any Field
FDV$GETAF (fldval,fldtrm,fldnam[,fldidx])
fldval

The field value. The value consists of data characters but no field-marker characters. If the operator does not enter a character for every position in the field, the
Form Driver fills the empty positions with fill characters. (Written. Passed by
descriptor.)

fldtrm

The field terminator that the operator entered to terminate input to the field.
(Written. Passed by reference.)

fldnam

The field name. (Written. Passed by descriptor.)

fldidx

The field index. (Written. Passed by reference.)

Description
Allows the operator to move the cursor to any modifiable field in the current
form (that is, to any field that is not Display Only and not Supervisor Only
when the Supervisor Only flag is on) and to enter a value in that field only.
The cursor is initially positioned at the current field and index. The current
field name and index are updated in the workspace as the operator moves the
cursor.
If the terminator is a function key not reserved for FMS, the form's function
key UAR is called. The function key UAR may suppress the terminator,
ignore it, or change it before subsequent processing occurs.
If the terminator is not a Previous Field terminator or a function key, the
Form Driver checks the field for Response Required, Must Fill, and field completion UAR requirements. If any requirements are not fulfilled, the operator
must continue input.

The Form Driver records in the workspace the value and terminator that the
operator enters, and returns the input to your program. The operator can
move about the form using the Next Field and Previous Field keys. The call
ends when the operator modifies one field, presses the ENTER key, or types
any function key not reserved for FMS. If the operator modifies a field, the
Form Driver returns the status code FDV$__MOD instead ofFDV$_SUC.
If the form contains scrolled areas, only the current scrolled line for each area
is accessed by the call.

Status Codes
FDV$-ARG
FDV$-CAN
FDV$-DSP
FDV$_1NI
FDV$_MOD
FDV$_NDS

5-28

Incorrect number of arguments.
Call was terminated by a CANCL call.
Form contains only display-only fields.
No workspace is defined.
Field value in fldval has been modified by the operator. Otherwise, this code is the same as FDV$_SUC.
Form is marked as being not displayed, so no input is
possible.

FORM DRIVER CALLS

GETAF (Cont.>
FDV$_NFL
FDV$_NOF
FDV$_STR
FDV$_SUC
FDV$_SYS
FDV$_TCA
FDV$_TMO
FDV$_UAR
FDV$_UDP
FDV$_UNF

No form loaded in workspace.
Form contains no fields.
Value being returned is too large for the variable allocated
for it.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.
Operator took longer to respond than allowed by the timeout
value associated with the current terminal.
UAR returned illegal code.
UAR depth exceeded.
UAR specified but not found.

FORM DRIVER CALLS

5-29

GETAL
5.21

Get All Field Values
FDV$GETAL ([ftdval,ftdtrm[,ftdnam[,ftdidx]]])
ftdval

The values of all fields in the current form. The values are returned in the order
specified in the form description. They consist of data characters but no fieldmarker characters. If the operator does not enter a character for every position in
the field, the Form Driver fills the empty positions with fill characters. (Written.
Passed by descriptor.)

ftdtrm

The field terminator that the operator entered to terminate input to the field.
(Written. Passed by reference.)

ftdnam

The name of the starting field. (Read. Passed by descriptor.)

ftdidx

The index of the starting field. (Read. Passed by reference.)

Description
Allows the operator to move the cursor to any nonscrolled fields in the current
form that are modifiable (that is, to any nonscrolled fields that are not Display Only and not Supervisor Only when the Supervisor Only flag is on), and
to enter values in those fields. This call normally positions the cursor at the
first nonscrolled modifiable field - but if you specify a field with the :ftdnam
and fldidx arguments, input begins with that field instead.
The operator can move about the form using the Next Field and Previous
Field keys. The call ends when the operator presses the Enter Form key or a
non-FMS function key. The Form Driver processes each field terminator
according to the description of the PFT call.
If the terminator is a function key not reserved for FMS, the form's function

key UAR is called. The function key UAR may suppress the terminator,
ignore it, or change it before subsequent processing occurs.
If the terminator is not a Previous Field terminator or a function key, the
Form Driver checks the field for Response Required, Must Fill, and field completion UAR requirements. If any requirements are not fulfilled, the operator
must continue input.
Call processing ends if an error occurs, or if the operator presses a function
key that is not suppressed by a function key UAR.
If the operator presses the Enter Form key, but the form has nonscrolled fields
with Response Required or Must Fill attribute requirements not fulfilled, or
field completion UARs not satisfied, the Form Driver displays a message at
the bottom of the screen, signals the operator, positions the cursor at the first
field still requiring operator input, and awaits further input. (The operator is
not restricted to entering data in these fields. The Form Driver moves the cursor only to direct the operator's attention to the fields.)
Upon completion of the form, the values of all nonscrolled fields (including
display-only fields) are returned in fldval in the default field access order.
The final field terminator and the modify flag status are returned as well.

5-30

FORM DRIVER CALLS

GETAL (Cont.>
If the form contains any scrolled areas, they are ignored by this call.
Status Codes

FDV$-ARG
FDV$_CAN
FDV$-DSP
FDV$-1NI
FDV$-MOD
FDV$_NDS
FDV$_NFL
FDV$_NOF
FDV$_STR
FDV$_SUC
FDV$_SYS
FDV$_TCA
FDV$_TMO
FDV$_UAR
FDV$_UDP
FDV$_UNF

Incorrect number of arguments.
Call was terminated by a CANCL call.
Form contains only display-only nonscrolled fields, or the
field specified was display only.
No workspace is defined.
At least one field has been modified by the operator.
Form is marked as being not displayed, so no input is
possible.
No form loaded in workspace.
Form contains no fields.
Value being returned is too large for the variable allocated
for it.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.
Operator took longer to respond than allowed by the timeout
value associated with the current terminal.
UAR returned illegal code.
UAR depth exceeded.
UAR specified but not found.

FORM DRIVER CALLS

5-31

GETDL
5.22

Get Data Line from Terminal
FDV$GETDL (value,ftdtrm[,line[,prompt]])
value

The data line. (Written. Passed by descriptor.)

ftdtrm

The field terminator that the operator entered to terminate input to the field.
(Written. Passed by reference.)
·

line

The number of the line on which the operator's input is displayed. If you specify
zero or omit this argument, the display occurs on the last line of the screen (24 or
14). (Read. Passed by reference.)

prompt

The data line text. Used as a prompt for the operator. (Read. Passed by descriptor.)

Description
Waits for the operator to type a line of text from the terminal.
The following points are important for you to note:
• This call does not require a workspace or TCA.
• The terminator returned is not saved as the current terminator.
• Any terminator is legal.
• The text returned has a length in the range of 0 to 132 characters.
• The text cannot be longer than the current width of the screen used for the
input- that is, 40, 66, 80, or 132 characters, depending on the screen width
and the attributes of the line set by any form on the screen.
• If you specify text for the prompt argument, you reduce the size of the

allowed input by the length of the prompt. The operator cannot delete the
prompt.
• No function key or field completion UAR is called. Help is not available.
The input editing functions available are the same as for input to a field.
If line has a value that is not zero, the value specifies the line on the screen to
be used for the input. Ifline has a value of zero, the bottom line of the screen is

used. The Form Driver clears the line prior to input and does not restore it
after input is complete.
If the data line overwrites part of a form on the screen, the Form Driver may

redisplay part or all of that form when your program issues the next PUTtype or GET-type call to it.

5-32

FORM DRIVER CALLS

GETDL ccont.>
Status Codes
FDV$-ARG
FDV$_CAN
FDV$-DLN
FDV$_STR
FDV$_SUC
FDV$_SYS
FDV$_TMO

Incorrect number of arguments.
Call was terminated by a CANCL call.
Argument prompt supplied more data than was required,
and some data was discarded.
Value being returned is too large for variable allocated for it.
Successful completion of the call.
Form Driver encountered system error response.
Operator took longer to respond than allowed by the timeout
value associated with the current terminal.

FORM DRIVER CALLS

5-33

GETSC
5.23

Get Current Line of Scrolled Area
FDV$GETSC (fldnam,fldval[,fldtrm])
ftdnam

A field name identifying the scrolled area. The field name need not specify an input
field. (Read. Passed by descriptor.)

ftdval

ftdtrm

The field terminator that the operator entered to terminate input to the field.
(Written. Passed by reference.)

Description
Positions the cursor at the first modifiable field of the current scrolled line
within the scrolled area containing the named field. But if the previous call
was a PFT call that processed a field terminator of FDV$K_FT_SPR (Scroll
to Previous Line), the cursor is positioned at the last modifiable field in the
line.
The Form Driver then allows the operator to enter data in the modifiable
fields of the line, moving from one field to another either by pressing the Next
Field and Previous Field keys, or by filling a field having the Autotab
attribute.
If the terminator is a function key not reserved for FMS, the form's function

Form Driver checks the field for Response Required, Must Fill, and field completion UAR requirements. If any requirements are not fulfilled, the operator
must continue input.
The value of every field in the scrolled line is returned inftdval. When the
processing of a terminator would cause the cursor to exit the line, the call is
done. The call is also completed if the operator presses the Enter Form key or
a function key.
The most recent field terminator code is returned.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_DSP
FDV$_FLD
FDV$_INI
FDV$-MOD

5-34

Incorrect number of arguments.
Call was terminated by a CANCL call.
Form contains only Display Only fields.
Field does not exist.
No workspace is defined.
Field value in ftdval has been modified by the operator. Otherwise, this code is the same as FDV$_SUC.

FORM DRIVER CALLS

GETSC <cont.>
FDV$-NDS
FDV$-NFL
FDV$-NOF
FDV$-NSC
FDV$_SUC
FDV$_SYS
FDV$_TCA
FDV$_TMQ
FDV$_UAR
FDV$_UDP
FDV$_UNF

Form is marked as being not displayed, so no input is
possible.
No form loaded in workspace.
Form contains no fields.
Field named is not a field in a scrolled area.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.
Operator took longer to respond than allowed by the timeout
value associated with the current terminal.
UAR returned illegal code.
UAR depth exceeded.
UAR specified but not found.

FORM DRIVER CALLS

l>-35

ILTRM
5.24

Return Illegal Terminators
FDV$1LTRM (trmmod)
trmmod

A value determining whether illegal terminators are to be returned to your program, or treated as errors:
1 = Return illegal terminators.
0 = Do not return illegal terminators.
(Read. Passed by reference.)

Description
Allows your program to receive terminators that are normally illegal in certain contexts -for example, a Next Field terminator in the last field of a form
or a Scroll Forward in a nonscrolled field. You can also restore the default
state in which illegal terminators are not returned.
If your program issues ILTRM (1), any illegal terminator (listed below) from

the current terminal is converted to a special terminator code and is treated
as if it came from the pressing of a function key. The Form Driver sends the
code to the form's function key UAR (if any), where the code can be rejected,
converted to another terminator, or accepted. If there is no function key UAR,
the illegal terminator ends input for the current call and is returned to your
program.
Following is a list of illegal terminators, all marked by the characters ILG:
FDV$K_FT_ILG..-NXT
K_FT_ILG_pRV
K_FT_ILG-ATB
K_FT_ILG-XBK
K_FT_ILG_XFW
K_FT--1LG-8FW
FDV$K_FT_ILG_SBK

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_SUC
FDV$_TCA
FDV$_VAL

5-36

Incorrect number of arguments.
Call was terminated by a CANCL call.
Successful completion of the call.
No terminal control area (TCA) is defined.
The.value oftrmmod is outside the allowed range.

FORM DRIVER CALLS

LC HAN
5.25

Set Channel for Form Library File
FDV$LCHAN (channel)
channel

The logical 1/0 channel number for the form library. (Read. Passed by reference.)

Description
Specifies the current library logical channel. The current library channel is
associated with the current terminal, so the terminal must be defined prior to
execution of this call. Following the execution of LC HAN, the Form Driver
uses the specified channel for any LOPEN or LCLOS call processing.
Your program normally issues an LCHAN before executing any other call
that references the current library channel. The program can issue an
LOPEN call without issuing an LC HAN first, however, if you choose to specify a channel in the LO PEN call. You can use LCHAN to switch from one open
library to another open library.
The channels specified in the Form Driver calls ATERM, LCHAN, and
LOPEN are strictly local to FMS and have no relationship to Logical Unit
Numbers used by FORTRAN and BASIC. These channel numbers provide a
means ofreference only. The Form Driver keeps an association list of all logical channels currently in use by the application program. Logical terminal
numbers and logical form library numbers must not conflict; that is, a logical
terminal channel number cannot also be used as a logical form library channel number.

Status Codes
FDV$--ARG
FDV$_CAN
FDV$_ICH
FDV$_SUC
FDV$-TCA

Incorrect number of arguments.
Call was terminated by a CANCL call.
Logical channel specified was either in use or invalid.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

5-37

LC LOS
5.26

Close Form Library
FDV$LCLOS

Description
Closes the form library associated with the current library channel. The current library channel is associated with the current terminal, so the terminal
must be defined prior to the execution of this call.
Note that if a disk-resident form is displayed on the screen and you then issue
the LCLOS call, Help forms cannot be accessed from that library.

Status Codes
FDV$_ARG
FDV$_CAN
FDV$-FCH
FDV$--1CH
FDV$_SUC
FDV$_TCA

5-38

Incorrect number of arguments.
Call was terminated by a CANCL call.
Form library is already closed.
Channel specified was invalid.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

LEDOF
5.27

Turn Terminal LED Off
FDV$LEDOF (ledno)
ledno

The number (in the range 1 to 4) of a LED to be turned off. (Read. Passed by
reference.)

Description
Turns off the specified VTlOO light-emitting diode (LED) of the current terminal ifthe current terminal is defined. If the current terminal is not defined,
the call turns off the specified LED of the application program's default terminal instead. If the terminal is not a VTlOO-compatible terminal, the call is
ignored but a success code is returned.
If LEDOF is called without a TCA, all the LEDs for the default terminal are

turned off.
If at any time the operator presses the Refresh key, or if your program issues a

RFRSH call, the LEDs are restored to their previous states.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_SUC
FDV$_SYS
FDV$-VAL

Incorrect number of arguments.
Call was terminated by a CANCL call.
Successful completion of the call.
Form Driver encountered system error response.
The value of ledno is outside the allowed range.

FORM DRIVER CALLS

5-39

LEDON
5.28

Turn Terminal LED On
FDV$LEDON (led.no)
ledno

The number (in the range 1 to 4) of a LED to be turned on. (Read. Passed by
reference.)

Description
Turns on the specified VTlOO light-emitting diode (LED) of the current terminal if the current terminal is defined. If the current terminal is not defined,
the call turns on the specified LED of the application program's default terminal instead. Any other LEDs previously turned on for the default terminal
are turned off. If the terminal is not a VTlOO or a VTlOO-compatible terminal, the call is ignored but a success code is returned.
If at any time the operator presses the Refresh key, or if your program issues a

RFRSH call, the LEDs are restored to their previous states.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_SUC
FDV$_SYS
FDV$_VAL

5-40

Incorrect number of arguments.
Call was terminated by a CANCL call.
Successful completion of the call.
Form Driver encountered system error response.
The value of ledno is outside the allowed range.

FORM DRIVER CALLS

LOAD
5.29

Load Form without Display
FDV$LOAD (frmnam)
frmnam

The name of the form. (Read. Passed by descriptor.)

Description
Loads a binary form description into a workspace without displaying the
form. Although the workspace is linked to a TCA, any form loaded by means
of this call is marked as undisplayed and does not appear on the screen when
this call is executed. Similarly, the form is not displayed if a RFRSH call is
executed.
For a loaded but undisplayed form, all calls requiring operator action are illegal and return a status of FDV$_NDS. All other calls succeed, but where both
the screen and workspace would normally be altered or updated by the call,
only the workspace is altered - the screen is unaffected.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_FCH
FDV$_FNM
FDV$_FRM
FDV$_IFU
FDV$-INI
FDV$-IOR
FDV$-IVM
FDV$-SUC
FDV$-TCA

Incorrect number of arguments.
Call was terminated by a CANCL call.
Form was not memory resident, and when the Form Driver
attempted to search for it in a form library, the current
library channel was not open.
Binary form description could not be found either in the form
library or in the list of memory-resident forms.
Form description is invalid.
Workspace cannot be loaded at this time because it is the
workspace for a currently active UAR.
No workspace is defined.
1/0 error occurred while Form Driver was reading in the form
from the form library. The 1/0 error code is recorded in the
current state. You can obtain it by issuing the STAT call.
Not enough virtual memory could be allotted for the
workspace.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

5-41

LOP EN
5.30

Open Form Library
FDV$LOPEN (filspc[,channel])
filspc

The file specification for the form library you want to open. (Read. Passed by
descriptor.)

channel

The logical 1/0 channel number for the form library. If this value is zero, the value
you specified in the most recent LCHAN call for the current terminal remains in
effect. (Read. Passed by reference.)

Description
Opens the form library associated with the channel you specify. If you omit
the channel specification, the call assumes the current channel. (See also the
description of the LCHAN call.)
You must issue this call before any other calls that fetch forms from the form
library specified by filspc.
The channels specified in the Form Driver calls ATERM, LCHAN, and
LOPEN are strictly local to FMS and have no relationship to Logical Unit
Numbers used by FORTRAN and BASIC. These channel numbers provide a
means ofreference only. The Form Driver keeps an association list of all logical channels currently in use by the application program. Logical terminal
numbers and logical form library numbers must not conflict; that is, a logical
terminal channel number cannot also be used as a logical form library channel number.

Status Codes
FDV$-ARG
FDV$-CAN
FDV$-FLB
FDV$-FSP
FDV$-ICH
FDV$--10L
FDV$-IOR
FDV$-SUC
FDV$_TCA

5-42

Incorrect number of arguments.
Call was terminated by a CANCL call.
File specified was not a form library.
File specification was invalid.
Channel specified was either in use or invalid.
Form Driver encountered an error while reading the form
library (it reads the form library to verify that the file is a
form library file).
The Form Driver encountered an error while opening the
form library.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

NDISP
5.31

Mark Form in Current Workspace as Not Displayed
FDV$NDISP

Description
Marks the form in the current workspace as being not displayed. The effect of
this call is that on subsequent screen refreshes this form is not redisplayed,
and subsequent GETs for the form are illegal. If the form is already on the
screen, it remains there. To redisplay the form, your program must issue the
DISPW call. NDISP is useful if you are using more than one workspace.
NDISP can be particularly useful in some UARs. Normally, if a UAR needs to
use another form to perform its task, it must attach a workspace, issue a DISP
call to the workspace, and then detach the workspace when it is finished.
(Note that attaching a workspace is an expensive operation involving the
allocation of memory from VMS.) If the UAR does not detach the workspace,
then the UAR working form is shown on every refresh operation thereafter.
Marking the form in the workspace as being not displayed is more efficient
than the method described in the preceding paragraph. The workspace can be
attached and loaded first, before any GETs. Then, when the UAR is activated,
it can issue a DISPW to display the workspace when it needs it, and then perform an NDISP when it is finished. A Refresh operation at this time would
bring back the original form, but not the UAR's working form.
No error occurs if the form is already marked as being not displayed or if
there is no form in the workspace; such a form does not affect the screen.

Status Codes
FDV$-ARG
FDV$-CAN
FDV$-1NI
FDV$_SUC
FDV$_TCA

Incorrect number of arguments.
Call was terminated by a CANCL call.
No workspace is defined.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

0-43

PFT
5.32

Process Field Terminator
FDV$PFT ([fldtrm[,fldnam[,fldval[,nfldnam[,nfldidx]]]]])
fldtrm

The field terminator to be processed. (Read. Passed by reference.)

fldnam

A field name identifying a scrolled area. (Ignored in nonscrolled area.) (Read.
Passed by descriptor.)

fldval

The field values to be displayed if the screen is scrolled during processing of a scrolling field terminator. (Ignored in nonscrolled area.) (Read. Passed by descriptor.)

nfldnam

The current field name after the call has been completed. (Written. Passed by
descriptor.)

nfldidx

The current field index after the call has been completed. (Written. Passed by reference.)

Description

Processes a field terminator code. This call changes the current field or affects
the current scrolled line in accordance with the terminator you supply with
the call. If you omit fldtrm from the call, the Form Driver supplies the most
recent terminator that the operator entered from the current terminal.
Note that the PFT call does not itself change the screen or move the cursor. It
merely changes the current field for the workspace. Your program can then
get the name of the new current field (from nfldnam) and issue a GET call
specifying the new field name. The Form Driver then moves the cursor to the
new field.

Terminators

5-44

Action

FDV$K_FT_NTR=O

Tests all nonscrolled modifiable fields to see if they
satisfy the Response Required and Must Fill attributes and calls all field-validation routines for those
fields. If all fields satisfy the criteria, the Form
Driver returns the FDV$_SUC code to your program. If any fields do not satisfy the criteria, the
first such field (in order of access) becomes the current field, and the Form Driver returns the
FDV$_INC code.

FDV$K_FT_NXT = 1

Makes the next modifiable field (in order of access)
the current field. If the terminated field is the last
modifiable field in a scrolled line, the terminator
behaves like an FDV$K_FT_SNX. If the field is not
in a scrolled area and there is no next modifiable
field, the Form Driver returns the FDV$_IFN code.

FORM DRIVER CALLS

PFT (Cont.)
Terminators

Action

FDV$K_FT_PRV = 2

Makes the previous modifiable field (in order of
access) the current field. If the field is the first field
in a scrolled area, the terminator behaves like an
FDV$K_FT_SPR. If the field is not in a scrolled
area and there is no previous modifiable field, the
Form Driver returns the FDV$_IFN code.

FDV$K_FT_ATB=3

(Autotab attribute)
FDV$K_FT_NXT.

FDV$K_FT_XBK=4

Makes the first modifiable field preceding the scrolled area containing fldnam the current field. If
there is no modifiable field preceding the scrolled
area, the Form Driver returns the FDV$-1FN code.

FDV$K_FT_XFW = 5

Makes the first modifiable field following the scrolled area containing fldnam the current field. If
there is no modifiable field following the scrolled
area, the Form Driver returns the FDV$-1FN code.

FDV$K_FT_SNX = 6

Scrolls forward to next field (from Next Field or
Autotab terminator in last field of scrolled area).
Makes the next modifiable field in the scrolled area
containing fldnam the current field. The area is
scrolled up, and the new last line is filled with the
values in fl.dval, if you supplied them in the call (as
in a PUTSC call). If you omitted fldval, the Form
Driver supplies default values.

FDV$K_FT_SPR = 7

Scrolls backward to previous field (from Previous
Field terminator in first field of scrolled area).
Makes the previous modifiable field in the scrolled
area containing fldnam the current field. The area
is scrolled down, and the new first line is filled with
the values in fl.dval, if you supplied them in the call
(as in a PUTSC call). If you omitted fldval, the
Form Driver supplies default values.

FDV$K_FT_SFW = 8

Scrolls forward. Makes the first modifiable field in
the scrolled area containing fl.dnam the current
field. If the terminated scrolled line is the last in the
scrolled area, the area is scrolled up, and the new
last line is filled with the values in fldval, if you
supplied them in the call (as in a PUTSC call). Ifyou
omitted fldval, the Form Driver supplies default
values.

Behaves

FORM DRIVER CALLS

5-45

PFT (Cont.)
Terminators
FDV$K_FT_SBK = 9

Action
Scrolls backward. Makes the first modifiable field in
_the scrolled area containing ftdnam the current
field. If the terminated scrolled line is the first in the
scrolled area, the area is scrolled down, and the new
first line is filled with the values in ftdval, if you
supplied them in the call (as in a PUTSC call). Ifyou
omitted ftdval, the Form Driver supplies default
values.

If the field terminator code is not listed above, the Form Driver returns the

FDV$_UTR code to your program.
If the Form Driver returns the FDV$_IFN or FDV$_UTR status codes, the

current field does not change, and nftdnam and nftdidx, if you specified them
in the call, reflect this status.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$-DLN
FDV$_FLD
FDV$_IFN
FDV$-1NC
FDV$_INI
FDV$_NFL
FDV$_NOF
FDV$_NSC
FDV$_SUC
FDV$_SYS
FDV$_TCA
FDV$_UTR

. 5-46

Incorrect number of arguments.
Call was terminated by a CANCL call.
Value argument supplied more data than was required, and
some data was discarded.
Field does not exist.
Field terminator code cannot be processed in the context
indicated.
Form is incomplete. (Returned only when FDV$K_FT_NTR
is processed.)
No workspace is denned.
No form loaded in workspace.
Form contains no fields.
Field named is not a field in a scrolled area.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.
Field terminator code is invalid.

FORM DRIVER CALLS

PUT
5.33

Output Value to Specified Field
FDV$PUT (fl.dval,fldnam[,fl.didx])
fl.dval

The field value. The data passed must consist only of the characters to be displayed
in the data positions of the field. Field-marker characters must not be passed.
(Read. Passed by descriptor.)
Note that the Form Driver does not check the validity of the data against the field
picture.

fl.dnam

The field name. (Read. Passed by descriptor.)

fl.didx

The field index. (Read. Passed by reference.)

Description

Records the value specified by ftdval in the workspace, and, if the workspace
is marked as displayed, updates the field on the screen with the new data. If
ftdval is shorter than the field, then ftdval is justified as the field-justification attribute requires, and the remainder of the field is padded on either the
right or left, according to that field attribute. The clear character pads the
field on the screen, and the fill character pads the field in the workspace.
Ifftdval is null, the field is filled with its default value. If ftdval is too long for

the field specified, the ftdval string is truncated on the right, and the field is
filled in with the truncated value, from the leftmost portion of the output
string. The status code FDV$_DLN is displayed if the Form Driver is in
Debug mode, but FDV$_SUC is returned to your program.
If a field having the date or time attribute is to be filled with a default value,
and no default value is defined in the form description, the current date or
time becomes the default.

If the field you specify is in a scrolled area, the field is displayed on the current
scrolled line of that area.
Status Codes

FDV$_ARG
FDV$_CAN
FDV$_DLN
FDV$_FLD
FDV$_INI
FDV$_NFL
FDV$_NOF
FDV$_SUC
FDV$_SYS
FDV$_TCA

Incorrect number of arguments.
Call was terminated by a CANCL call.
Value argument supplied more data than was required, and
some data was discarded.
Field does not exist, or index value is invalid for field.
No workspace is defined.
No form loaded in workspace.
Form contains no fields.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

5-47

PUTAL
5.34

Output Values to All Fields
FDV$PUTAL ([frmval])
frmval

The values for al~ fields. (Read. Passed by descriptor.)

Description
Takes data from frmval, records it in the workspace, and, if the workspace is
marked as displayed, updates the screen with the new field values. You can
alter all fields or all nonscrolled fields of the form with this call.
If the form contains any scrolled areas, they are ignored by this call provided
frmval is specified. If you omit the frmval value, however, the scrolled areas
are restored to their default values, and the current scrolled line of each scrolled area is reset to the first line of the area.
If frmval contains more data than is required to define ~very field, the excess
data is discarded, and the Form Driver displays the status code of
FDV$-1)LN if Debug mode is in effect, but returns FDV$_SUC to your program. If frmval contains insufficient data to define every field, the remainder
are defined by the default values for the fields.

If a field having the date or time attribute is to be filled with a default value,
and no default value is defined in the form description, the current date or
time becomes the default.
The order of the field values in frmval is specified in the form description.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_DLN
FDV$_INI
FDV$_NFL
FDV$_NOF
FDV$_SUC
FDV$_SYS
FDV$_TCA

5-48

Incorrect number of arguments.
Call was terminated by a CANCL call.
Value argument supplied more data than was required, and
some data was discarded.
No workspace is defined.
No form loaded in workspace.
Form contains no fields.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

PUTD
5.35

Output Default to Specified Field
FDV$PUTD (fldnam[,fldidx])
fldnam

The field name. (Read. Passed by descriptor.)

fldidx

The field index. (Read. Passed by reference.)

Description
Causes the default value, if any, to be restored to the specified field. If none is
defined, the field is filled with fill characters in the workspace and with clear
characters on the screen. The values are displayed only if the workspace is
marked as displayed. PUTD duplicates a portion of the PUT function and is
provided to support those languages that do not allow omission of arguments
from a call.
If a field having the date or time attribute is to be filled with a default value,
and no default value is defined in the form description, the current date or
time becomes the default.
If the field you specify is in a scrolled area, the field default'is restored for the
current scrolled line only. ,

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_FLD
FDV$-1NI
FDV$_NFL
FDV$_NOF
FDV$_SUC
FDV$_SYS
FDV$_TCA

FORM DRIVER CALLS

5-49

PUTDA
5.36

Output Default Values to All Fields
FDV$PUTDA

Description
Causes the default values, if any, to be restored to all fields in a form. If none is
defined for a field, the field is filled with clear characters on the screen and
with fill characters in the workspace. Note that the default values are displayed only if the workspace is marked as displayed. This function duplicates
a portion of the PUTAL function and is provided to support those languages
that do not allow the omission of all arguments from a call.
If a field having the date or time attribute is to be filled with a default value,

and no default value is defined in the form description, the current date or
time becomes the default.
If the form contains any scrolled areas, the defaults are restored to the fields
in the scrolled areas, and the current scrolled line of each area is reset to the
first line of each area.

Status Codes
FDV$--ARG
FDV$_CAN
FDV$_INI
FDV$_NFL
FDV$-NOF
FDV$_SUC
FDV$_SYS
FDV$_TCA

5-50

Incorrect number of arguments.
Call was terminated by a CANCL call.
No workspace is defined.
No form loaded in workspace.
Form contains no fields.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

PUTL
5.37 Output Line to Screen
.FDV$PUTL (text[,line])
text

The line of text for the data line. (Read. Passed by descriptor.)

line

The number of the line on which the Form Driver displays the data line. If you
specify zero, the display occurs on the last line of the screen (24 or 14). (Read.
Passed by reference.)

Description
Displays text on the line specified by line; or ifthe line value is zero, on the
last line of the screen. The line is always deleted before the text is displayed.
Normally, the last line is line 24 of the screen. If the screen is in 132-column
mode, however, and the terminal lacks the Advanced Video Option, the last
line is line 14.
If line specifies the last line of the screen, the Form Driver clears the line of
text when the operator types the next character. If line is not zero, your program has to clear the line.
The text can be 40, 66, 80, or 132 characters, depending on the current screen
size and the attributes of the line. If the message does not fit on the current
screen, it is truncated and the status code of FDV$_DLN is reported if the
Form Driver is in Debug mode, although FDV$_SUC is returned to your program. A message longer than 80 characters is truncated on a VT52 terminal.
On a VTlOO with the advanced video option; the displayed line has the bold
video attribute by default. If the terminal does not have the advanced video
option, the line is displayed in the same video mode as the cursor (underline
or reverse video), which the operator sets by using the VTlOO's Set-Up mode.
If you specified video attributes in an ADLVA call, those attributes are used
instead.
If the terminal is a VT52, the line is displayed in normal video.
Ifline overwrites part of a form on the screen, the Form Driver may redisplay
part or all of that form when your program issues the next PUT-type or GETtype call to it. This is true even if the line overwritten was blank or was specified only in the area to clear portion of the form.

FORM DRIVER CALLS

5-51

PUTL (Cont.)
Status Codes

FDV$-ARG
FDV$_CAN
FDV$_DLN
FDV$_LIN

FDV$_SUC
DV$--8YS

5-52

Incorrect number of arguments.
Call was terminated by a CANCL call.
Value argument supplied more data than was required, and
some data was discarded.
The line argument is invalid. It is either negative or greater
than the number of lines that can be displayed on the screen
(24 lines normally, or 14 if in 132-column mode and on a
VTlOO without the advanced video option).
Successful completion of the call.
Form Driver encountered system error response.

FORM DRIVER CALLS

PUTSC
5.38

Output Data to Current Line of Scrolled Area
FDV$PUTSC (ftdnam[,ftdval])
ftdnam

A field name identifying the scrolled area. (Read. Passed by descriptor.)

ftdval

The field values. (Read. Passed by descriptor.)

Description

Outputs data to the scrolled area containing the field named in ftdnam. The
line in the scrolled area that is displayed is the current scrolled line for that
area.
All fields on the current line are updated with ftdval. If not enough data is
supplied in ftdval, the remaining fields are set to their default values, or
cleared if there is no default. If too much data is supplied, the Form Driver
truncates the data and reports the status code FDV$_DLN if Debug mode is
in effect, although FDV$_SUC is returned to your program.
If a field having the date or time attribute is to be filled with a default value,

and no default value is defined in the form description, the current date or
time becomes the default.
The order of the fields in ftdval is specified in the form description.
Status Codes

FDV$_ARG
FDV$_CAN
FDV$_DLN
FDV$_FLD
FDV$_INI
FDV$_NFL
FDV$_NOF
FDV$_NSC
FDV$_SUC
FDV$_SYS
FDV$_TCA

Incorrect number of arguments.
Call was terminated by a CANCL call.
Value argument supplied more data than was required, and
some data was discarded.
Field does not exist.
No workspace is defined.
No form loaded in workspace.
Form contains no fields.
Field named is not a field in a scrolled area.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

5-03

Read Form into Memory
FDV$READ (frmnam,mloc,mlocsiz,frmsiz)

frmnam

The name of the form. (Read. Passed by descriptor.)

mloc

The area in which the form is to be stored. (Modified. Passed by descriptor.)

mlocsiz

The size of the memory buffer that begins with mloc. (Read. Passed by reference.)

frmsiz

The size of the form in bytes. (Written. Passed by reference.)

Description
Reads a form from a form library into the memory area that you specify and
adds the form to the head of the list of memory-resident forms known to your
program. Any subsequent references to the form get the form description
from mloc rather than from the form library. The size of the form is returned
in frmsiz. (See also the description of the DEL call.)
You can have forms with duplicate form names on the list of memory-resident
forms, but only the form closest to the head of the list can be accessed.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$-FCH
FDV$-FNM
FDV$-FRM
FDV$_IBF
FDV$-10R
FDV$-SUC
FDV$_TCA

5--54

Incorrect number of arguments.
Call was terminated by a CANCL call.
Form was not resident, and when the Form Driver attempted
to search for it in a form library, the current library channel
was nof open.
Binary form description could not be found in the form
library.
Form description is invalid.
Area not large enough to hold the form.
1/0 error occurred while Form Driver was reading in the form
from the form library. The 1/0 error code is recorded in the
current state. You can obtain it by issuing the STAT call.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

RET
5.40 Return Value for Specified. Field
FDV$RET (ftdval,ftdnam[,fldidx])
ftdval

The field value consisting of data characters but no field-marker characters. If the
operator does not enter a character for every position in the field, the Form Driver
fills the empty positions with fill characters. (Written. Passed by descriptor.)

fldnam

The field name. (Read. Passed by descriptor.)

fldidx

The field index. (Read. Passed by reference.)

Description
Returns the value of the field you specify from the current workspace. The
data returned by the RET call is data already accepted from the operator by a
previous GET-type call, data displayed by a previous PUT-type call, or data
present by default. Note that unlike the GET call, RET accepts no input from
the operator.
Display-only fields are returned by this call.

Status Codes
FDV$-ARG
FDV$-CAN
FDV$-FLD
FDV$-INI
FDV$-NFL
FDV$_NOF
FDV$-STR
FDV$_SUC
FDV$_TCA

Incorrect number of arguments.
Call was terminated by a CANCL call.
Field does not exist, or index value is invalid for field.
No workspace is defined.
No form loaded in workspace.
Form contains no fields.
Value being returned is too large for the variable allocated
for it.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

5-55

RETAL
5.41

Return Values for All Fields
FDV$RETAL (frmval)
frmval

The values for all fields. The values returned consist only of the data character
positions in the fields. No field-marker characters are returned. If data characters
do not fill a field, the Form Driver fills the remainder of the field with the fill character. (Written. Passed by descriptor.)

Description
Returns the values of all nonscrolled fields from the current workspace. The
order in which the fields are returned is specified in the form description. The
data returned by the RETAL call is data already accepted from the operator
by a previous GET-type call, data displayed by a previous PUT-type call, or
data present by default. Note that unlike the GETAL call, RETAL accepts no
input from the operator.
Display-only fields are among those returned by this call.

Status Codes
FDV$-.ARG
FDV$-CAN
FDV$_INI
FDV$_NFL
FDV$_NOF
FDV$_STR
FDV$-SUC
FDV$_TCA

5-58

Incorrect number of arguments.
Call was terminated by a CANCL call.
No workspace is defined.
No form loaded in workspace.
Form contains no fields.
Value being returned is too large for the variable allocated
for it.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

RETCX
5.42

Return Current Context
FDV$RETCX (atca,awksp,frmnam,uarval,curpos,fldtrm,insovr,hlpnum)
a tea

The address of the current terminal control area. If this location is zero, no
TCA is defined. (Written. Passed by reference.)
Not all high-level languages are capable of handling addresses.

awksp

The address of the current workspace. If this location contains a zero, no
workspace is defined. (Written. Passed by reference.)
Not all high-level languages are capable of handling addresses.

frmnam

The name of the form being processed. (Written. Passed by descriptor.)

uarval

The value of the associated UAR text, if one is defined. (Written. Passed by
descriptor.)

curpos

The cursor position within the current field, if any. The cursor position is 1
for the leftmost data character in the field, 2 for the next data character to
the right, n for the rightmost character in the field, and n + 1 for the character position to the immediate right of the rightmost data character (the
hanging cursor position). Field-marker characters are not counted by the
cursor. The range of the cursor, 1 ton + 1, is limited to the number of data
characters in the field plus 1. (Written. Passed by reference.)
For fixed-decimal fields, the range of the cursor is 1 to n + 2, because the
decimal point is counted even though it is not a data character. This allows
the cursor to be positioned on the decimal point, in the hanging cursor position for the left-hand part of the field.
The curpos argument is always nonzero when a UAR is called during field
processing (a field completion UAR, function key UAR, or help UAR). This
argument can be zero if the RETCX call is executed when not in a UAR
doing processing for a field. Zero means that the default position will be
used for the next field access.
The curpos argument is not always zero outside UAR processing for a field.
If your program has previously issued an AFCX call on the current field,

setting a nonzero curpos, then that nonzero value will be reported.
fldtrm

The field terminator that the operator last entered either to terminate
input to a field or to respond to the execution of a WAIT call. (Written.
Passed by reference.)

insovr

A value indicating whether Insert or Overstrike mode is in effect for a field.
(Written. Passed by reference.)
1 =Default
2 = Insert mode
2 = Overstrike mode

The insovr argument is always nonzero when a UAR is called during field
processing (a field completion UAR, function key UAR, or help UAR). This
argument can be zero if the RETCX call is executed when a UAR is processing for a field. Zero means that the default position will be used for the next
field access.
The insovr argument is not always zero outs~de UAR processing for a field.
If your program has previously issued an AFCX call on the current field,

setting a nonzero insovr, then that nonzero value will be reported.
hlpnum

A value equalto the number of times the operator has pressed the Help key
for the current field. (Written. Passed by reference.)

FORM DRIVER CALLS

5-57

RETCX (Cont.)
Description
Returns the current context of the Form Driver as defined above. Your program can issue this call from a user action routine to determine the context in
which the UAR is called, although use ofRETCX is not limited to UARs.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_STR
FDV$_SUC

5-58

Incorrect number of arguments.
Call was terminated by a CANCL call.
Value being returned is too large for the variable allocated
for it.
Successful completion of the call.

FORM DRIVER CALLS

RETDI
5.43

Return Named Data by Index
FDV$RETDI (nmdidx,nmdval[,nmdnam])
nmdidx

The Named Data index. (Read. Passed by reference.)

nmdval

The Named Data text. (Written. Passed by descriptor.)

nmdnam The name of the Named Data. (Written. Passed by descriptor.)

Description
Returns the Named Data text you specify by index (rather than by name).
This call also returns the Named Data name.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_DNM
FDV$-1NI
FDV$_NFL
FDV$_STR
FDV$_SUC
FDV$_TCA

Incorrect number of arguments.
Call was terminated by a CANCL call.
No Named Data is associated with the specified index.
No workspace is defined.
No form loaded in workspace.
Value being returned is too large for the variable allocated
for it.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

fHS9

RETDN
5.44

Return Named Data by Name
FDV$RETDN (nmdnam,nmdval[,nmdidx])
nmdnam The Named Data name. (Read. Passed by descriptor.)
nmdval

The Named Data text. (Written. Passed by descriptor.)

nmdidx

The Named Data index. (Written. Passed by reference.)

Description
Returns the Named Data text you specify by name (rather than by index).
This call also returns the Named Data index.

Status Codes
FDV$_ARG
FDV$_CAN
FDV$_DNM
FDV$_INI
FDV$_NFL
FDV$_SUC
FDV$_TCA

5-60

Incorrect number of arguments.
Call was terminated by a CANCL call.
No Named Data is associated with the specified name.
No workspace is defined.
No form loaded in workspace.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

RETFL
5.45

Return Form Line
FDV$RETFL (line,value,linlen[,type])
line

The number of the form line to be returned. (Read. Passed by reference.)

value

The image of the line you request. (Written. Passed by descriptor.)

linlen

The length of the value line in bytes. (Written. Passed by reference.)

type

The type of output you want: 1 for current terminal image (including, for example,
escape sequences for video) and 0 for line printer image. Iftype has a value ofO, the
Form Driver makes the following correspondences. (Read. Passed by reference.)
1. All video attributes are ignored.
2. If the line indicated is double width, it is returned with each text item or field
item centered in the area it would have occupied.
3. If the line indicated is double size, then the first line is returned as a doublewidth line, and the second line is returned as a line of blanks.
4. If the line contains any line-drawing graphics, they are converted to standard
ASCII characters:
• The horizontal bar graphics are converted to ASCII dash characters(-).
• Vertical bar graphics are converted to ASCII vertical bar characters (I).
• All intersection graphics and corner graphics are converted to ASCII plus
characters ( + ). All other characters in alternate character sets remain
untranslated.

Description
Returns the form line you specify with the line argument. Usually, this is one
of the lines you would see if your program issued a RFRSH call, although your
program can issue RETFL to display lines from loaded, but undisplayed,
forms as well.
If the current terminal has any attached workspaces with undisplayed forms,
they are normally ignored by this call. But if undisplayed forms are the only
forms in the attached workspaces, they are all included in generating the line
image. Thus, your program can use undisplayed forms for report formatting
purposes.

When using multiple workspaces, a call to RETFL returns the image of a line
as it would appear on the screen after a RFRSH. More than one form may
contribute to the line if forms overlap, and the last form displayed does not
clear the line.
If type has a value of 1, the line image returned includes escape sequences
and control characters to present an exact image of the screen ifit were to be
displayed on the same kind of terminal as the current terminal. The image so
returned can be stored in a file and displayed later, or output to an intelligent
printer that understands the same control sequences as the terminal.

Since the length of such an image can easily extend beyond 132 characters
when there are many fields and text blocks on the line (especially if they specify varying video attributes and character sets), the buffer used has a capacity of 4000 bytes, which should be sufficient for all but multiple overlaid

FORM DRIVER CALLS

5-61

RETFL (Cont.)
forms on a single line. If the buffer overflows, the error FDV$_LLI is
returned. Saving, and later displaying, a very long line may cause problems
due to RMS or VMS restrictions on file record size or 1/0 record sizes.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$-1NI
FDV$_LIN
FDV$_LLI
FDV$_STR
FDV$_SUC
FDV$_TCA

5-62

Incorrect number of arguments.
Call was terminated by a CANCL call.
No workspace is defined.
Call specifies that some line not on the screen was requested.
The Form Driver's internal buffer was not large enough to
store the line image requested. The line image returned is
truncated.
Value being returned· is too large for the variable allocated
for it.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

RETFN
5.46

Return Current Field Name
FDV$RETFN (fldnam[,ftdidx])
fldnam

The field name. (Written. Passed by descriptor.)

fldidx

The field index. (Written. Passed by reference.)

Description
Returns the current field name and index from the current workspace. If the
field is not indexed, RETFN returns an index value of zero. If there is no current field, the Form Driver returns a null string of characters for the field
name.

Status Codes
FDV$--.ARG
FDV$_CAN
FDV$_INI
FDV$_NFL
FDV$_NOF
FDV$_STR
FDV$_SUC
FDV$_TCA

FORM DRIVER CALLS

5-63

RETFO
5.47

Return Field Names in Order
FDV$RETFO (ftdnum,fldnam,ftdidx)
ftdnum

The nth field in the form, where n includes the number of any identically named
indexed fields present. (Read. Passed by reference.)

fldnam

The name of the field corresponding to ftdnum. (Written. Passed by descriptor.)

ftdidx

The field index corresponding to fldnum. (Written. Passed by reference.)

Description
Returns the name and index of the nth field in the form - where n includes
the number of any identically named indexed fields present. If you want the
fifth field in the form (n = 5), it could have a unique name, or be, for example, FIELDl indexed down to the fifth field called FIELDl.
The field names can be in scrolled areas, but a field name in a scrolled area is
returned only once, unless the field also happens to be indexed.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_FLD
FDV$_INI
FDV$_NFL
FDV$_NOF
FDV$_SUC
FDV$_TCA

5-64

FORM DRIVER CALLS

RETLE
5.48

Return Length of Specified Field
FDV$RETLE (fldlen,fldnam[,fldidx])
fldlen

The length of the field. The length is defined as the number of data positions in the
field. The number of field-marker characters on the field has no effect in the determination of the length of the field. (Written. Passed by reference.)

fldnam

The field name. (Read. Passed by descriptor.)

fldidx

The field index. (Read. Passed by reference.)

Description
-Returns the length of the field you specify. The length of a field is the number
of data characters in the field exclusive of any field-marker characters.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$-FLD
FDV$__1NI
FDV$_NFL
FDV$_NOF
FDV$_SUC
FDV$_TCA

FORM DRIVER CALLS

5-65

RFRSH
5.49

Refresh Screen
FDV$RFRSH

Description
Redisplays all forms currently marked as being displayed on the screen. This
operation is identical to the one initiated by the operator's pressing of the
Refresh key. If several forms are on the screen, they are redisplayed in the
order that their workspaces were attached, except that the current workspace's form is always displayed last.
A screen refresh also restores the keypad mode. In addition, the refresh operation restores the terminal LEDs to the state they were in before the refresh
occurred.

Status Codes
FDV$--ARG
FDV$_CAN
FDV$-FCH
FDV$-1NI
FDV$_SUC
FDV$_SYS
FDV$_TCA

5-66

Incorrect number of arguments.
Call was terminated by a CANCL call.
Form was not resident, and when the Form Driver attempted
to search for it in a form library, the current library channel
was not open.
No workspace is defined.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

SCR_WIDTH
5.50

Set Screen Width
FDV$SCR_WIDTH (width)
width

An integer specifying the current width of the screen; must be either 80 or
132. (Read. Passed by reference.)

Description
Informs the Form Driver that your program has changed the width of the
screen from the value last known to the Form Driver. Your program must also
inform the operating system when it changes the screen width. The Form
Driver does not change the screen or inform the operatJ.ng system of screen
width changes as a result of this call. However, the Form Driver always
informs the operating system when other calls to the Form Driver change the
screen width. Your program can query the operating system at any time for
this information.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_SUC
FDV$_TCA
FDV$_VAL

Incorrect number of arguments.
Call was terminated by CANCL.
Success.
No current terminal.
Width was not 80 or 132.

FORM DRIVER CALLS

5-67

SIGOP
5.51

Signal Operator
FDV$SIGOP

Description

Signals the operator from the application program. Depending on the current
signal mode for the terminal, either the terminal bell is rung or the video of
the terminal is reversed until the operator next types a valid character (any
character that does not generate another Form Driver signal). See also the
description of the SSIGQ call.
This signaling is automatically performed prior to each error message issued
by the Form Driver.
Status Codes

FDV$-ARG
FDV$_CAN
FDV$_SUC
FDV$_SYS
FDV$_TCA

5-68

Incorrect number of arguments.
Call was terminated by a CANCL call.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

SPADA
5.52

Set Keypad to Application Mode
FDV$SPADA (mode)
mode

A value determining the keypad mode:
• If mode contains 0, keypad = numeric mode.
• If mode contains 1, keypad = application mode.
Any other values are erroneous. (Read. Passed by reference.)

Description
Sets the terminal keypad mode. In numeric mode, the terminal keypad keys
act as normal keys, returning the characters inscribed on them. When the
keypad is in application mode, the keypad keys act as field terminator keys.
The Form Driver resets the keypad of the current terminal to the selected
mode whenever a Refresh operation occurs.
If no current terminal is in effect (TCA not defined), the default terminal is

used in this call. Prior to the application making this call, the status of the
keypad is determined by its VMS status. See the SET and SHOW TERMINAL commands in the VAX/VMS Command Language User's Guide.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_SUC
FDV$_SYS
FDV$_VAL

Incorrect number of arguments.
Call was terminated by a CANCL call.
Successful completion of the call.
Form Driver encountered system error response.
The value of mode is outside the allowed range.

FORM DRIVER CALLS

5-69

SPOFF
5.53

Turn Supervisor-Only Mode Off
FDV$SPOFF

Description
Sets the supervisor-only mode flag to Off. Following this call, the operator can
alter fields marked as Supervisor Only in the form descriptions. The supervisor-only flag is altered only for the current terminal. There is a separate
Supervisor Only flag for each terminal.
The supervisor-only flag is set to On when the terminal is first attached.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$-SUC
FDV$_TCA

5-70

Incorrect number of arguments.
Call was terminated by a CANCL call.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORMDRIVERCALLS

SPON
5.54

Turn Supervisor-Only Mode On
FDV$SPON

Description
Sets the supervisor-only mode flag to be set to On. Following this call, fields
marked as Supervisor Only in the form descriptions are treated as displayonly fields. The Supervisor Only flag is altered only for the current terminal.
There is a separate Supervisor Only flag for each terminal.
The supervisor-only flag is set to On when the terminal is first attached.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$-SUC
FDV$_TCA

Incorrect number of arguments.
Call was terminated by a CANCL call.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

5-71

SSIGQ
5.55

Set Signal to Quiet Mode
FDV$SSIGQ (sigmd)
sigmd

The signal mode value; (Read. Passed by reference.)

0 =Bell

1 = Reverse video

Description

Specifies the signal mode for the current terminal. If the signal mode is 0, the
terminal bell is rung when you later issue the SIGOP call or the Form Driver
issues any error message. If the mode is 1, the screen video is reversed when
the signal occurs and automatically reverts back to the original video mode
when the operator types the next valid character. See also the description of
SIGOP.
If the signal mode is 1, and the Form Driver does not know what the screen

video attribute of the terminal is, the Form Driver sets the terminal to normal video (white characters on black background). The Form Driver knows
the screen video attribute from then on regardless of any changes caused by
subsequent form displays.
If the terminal is a VT52, the terminal bell is the signali~g mode regardless of

the mode setting. Attempts to specify video reversal as the signal mode for
VT52-compatible terminals are ignored.
Status Codes

FDV$-ARG
FDV$_CAN
FDV$_SUC
FDV$-TCA

5-72

Incorrect number of arguments.
Call was terminated by a CANCL call.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

SSRV
5.56

Specify Status Reporting Variables
FDV$SSRV ([status[,iostat]])
status

The value of the general status. This address becomes the general status reporting
variable. (Written. Passed by reference.)

iostat

The value of the 1/0 status. This address becomes the 1/0 status reporting variable.
(Written. Passed by reference.)

Description
Records the addresses of two variables in the current terminal's TCA:
• The address of a variable in which each subsequent call's 1/0 status is to be
recorded
• The address of a variable in which each subsequent call's normal status is
to be recorded
Following the execution of any call, if either address ·is not location 0, the
appropriate call status is stored in the status variable. You can use this call to
set up automatic status reporting instead of using the STAT call or VMS status returns.
The status variables must be 32-bit integers on all VAX systems.
It is the application program's responsibility to ensure that after it issues this
call, the addresses specified remain valid until the call is issued again specifying zeros for addresses. When you specify zeros as addresses (or when you do
not specify any arguments), further status reporting is discontinued.

Status Codes
FDV$-ARG
FDV$-CAN
FDV$-SUC
FDV$_TCA

Incorrect number of arguments.
Call was terminated by a CANCL call.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

5-73

STAT
5.57

Return Status from Last Call
FDV$STAT (status[,iostat])

status

The value of the general status. (Written. Passed by reference.)

iostat

The value of the I/O status. (Written. Passed by reference.)

Description
Returns the status code for the previous call. Note that a STAT call following
a previous STAT call returns the result of the previous STAT. That result is
almost always success.

Status Codes
FDV$-ARG
FDV$-CAN
FDV$-8UC

5-74

Incorrect number of arguments.
Call was terminated by a CANCL call.
Successful completion of the call.

FORM DRIVER CALLS

STEAM
5.58

Set Current Terminal
FDV$STERM (tea)
tea

The name of a terminal control area. (Modified. Passed by descriptor.)

Description
Makes a specified attached terminal (as indicated by its terminal control
area) the current terminal. Your program must have previously attached the
terminal with an ATERM call with the TCA specified.
Changing the current terminal also causes the current workspace to be
changed to the workspace most recently associated with the new current terminal. If no workspace is attached to that terminal, then after the execution
of this call the current workspace is undefined.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_SUC
FDV$_TCA

Incorrect number of arguments.
Call was terminated by a CANCL call.
Successful completion of the call.
The TCA supplied is not attached or is invalid.

FORM DRIVER CALLS

5-75

STIME
5.59

Set Field Entry Timeout
FDV$STIME (time)

time

The number of seconds the Form Driver waits for the operator to respond to a GETtype call. This parameter is optional, and defaults to 0.(Read. Passed by reference.)

Description
Specifies the number of seconds the Form Driver waits for the operator to
respond to a GET-type call. Execution of this call cancels the effect of any previous STIME call for the current terminal. A negative or zero time value
causes the Form Driver to wait indefinitely for input (the default). A separate
STIME is associated with each terminal.
After an STIME call, the Form Driver resets the timeout value for each character in a field. Thus, if a field has ten characters in it and the timeout value is
15 seconds, the operator has 15 seconds to respond with the first character
and 15 seconds to respond with each of the other nine characters in the field.

Status Codes
FDV$-ARG
FDV$_CAN
FDV$_SUC
FDV$_TCA

l>-76

Incorrect number of arguments.
Call was terminated by a CANCL call.
Successful completion of the call.
No terminal control area (TCA) is defined.

FORM DRIVER CALLS

SWKSP
5.60

Set Current Workspace
FDV$SWKSP (wksp)
wksp

The form workspace location. (Modified. Passed by descriptor.)

Description
Makes the attached workspace you specify the new current workspace. If the
workspace you specify is associated with a different terminal, the current
terminal is changed as well. Your program must have previously attached
the specified workspace to a terminal TCA by issuing an AWKSP call.

Status Codes
FDV$-ARG
FDV$-CAN
FDV$-INI
FDV$_SUC
FDV$_SYS

Incorrect number of arguments.
Call was terminated by a CANCL call.
The workspace specified is not attached or is invalid.
Successful completion of the call.
Form Driver encountered system error response.

FORM DRIVER CALLS

5-77

TC HAN
5.61

Set Terminal Channel
FDV$TCHAN (Channel)
channel

The number of a physical 1/0 channel (not a logical 1/0 channel) to be associated
with the current terminal. (Read. Passed by reference.)

Description
Specifies a physical terminal channel to be used for the current terminal.
When your program issued ATERM, the Form Driver allocated a physical
channel to correspond to the logical channel specified. TCHAN specifies a
physical channel different from the one allocated by ATERM.
TCHAN requires that the TCA be attached before your program issues this
call.
The previous physical channel is released when your program issues this call.
The logical channel number of the previous. channel (the channel number
specified in the ATERM call) is also released.

NOTE
If your program issues TCHAN and later detaches the associated TCA, the terminal is not released. Any channel specified
by means of the TCHAN call must be released by your
program.

Status Codes
FDV$-ARG
FDV$-CAN
FDV$-1CH
FDV$_SUC
FDV$_TCA

5-78

FORM DRIVER CALLS

USER-REFRESH
5.62

Set up User Refresh Routine
FDV$USER_REFRESH([rfr_address])
rfr_address

Address of a user-supplied routine to refresh part of the terminal screen. If
this argument is specified, all subsequent Form Driver refresh operations
will call the user-supplied routine first. If this argument is null or not specified, no user refresh routine will be called on subsequent Form Driver refresh
operations.

Description

Helps a program maintain part of the terminal screen independent of the
Form Driver, when the Form Driver normally overwrites part or all of the
screen. For example, when the Form Driver must perform a refresh operation
for the current terminal, the terminal's screen is first cleared and set to the
proper width and background. Then all the workspaces marked as displayed
are redisplayed. If your program is maintaining part of the screen, the refresh
operation's screen clear automatically deletes your program's part from the
screen.
When the Form Driver refreshes the screen, it calls your refresh routine, if
one has been supplied in a call to USER-REFRESH. Your routine should
clear and write its own part of the screen, call CLEAR_VA, if necessary, and
then return. The Form Driver then redisplays the displayed workspaces. This
allows the refresh function to affect both your program's screen area and the
Form Driver's area.
The Form Driver calls your refresh routine in four circumstances:
• Your program calls RFRSH.
• The operator presses the Refresh key during data entry.
• Help processing or UAR processing caused some part of the Form Driver's
screen to be overlaid. That is, a form marked as displayed was overlaid by a
help form or by a form displayed by a Field Completion UAR, Function Key
UAR, or Pre-Help or Post-Help UAR.
Prior to returning to normal data entry after the help or UAR sequence, the
Form Driver calls your refresh routine and then redisplays the required
forms. If a help form or UAR form does not overlay a displayed form, the
Form Driver does not call your refresh routine. You should design your program so that if a help form or a UAR action overlays your program's screen
area, it should also overlay the Form Driver's screen area.
• The terminal width is changed when a new form is displayed by using a
CDISP, DISP, or DISPW call, or by using a help form display operation.
The Form Driver calls your refresh routine as ifit were a UAR. The refresh
routine behaves exactly like a UAR, except that it must not change the terminal width. The Form Driver restores the current terminal, workspace, and
field.

FORM DRIVER CALLS

5-79

USER-REFRESH (Cont.)
An application program should make a call to USER-REFRESH specifying a
user routine before starting the separate screen display. A second call should
be made to USER-REFRESH without any argument when your program has
completed its separate screen display.

Status codes
FDV$--ARG
FDV$_CAN
FDV$_SUC
FDV$_TCA

5-80

Incorrect number of arguments.
Call was terminated by CANCL.
Success.
No current terminal.

FORM DRIVER CALLS

WAIT
5.63 Wait for Operator
FDV$WAIT ([ftdtrm])
fldtrm

The returned field terminator that the operator entered to terminate the wait condition. (Written. Passed by reference.)

Description
Waits until the operator signals to proceed by pressing any terminator key.
This call allows the Form Driver to synchronize the application program with
the pace of the operator.
If the terminator is a function key not reserved for FMS, and if a form is

loaded in the current workspace and has a function key UAR, the Form
Driver calls that UAR. The function key UAR may suppress the terminator,
ignore it, or change it before subsequent processing occurs. When a terminator is accepted, it is recorded in the workspace as the most recent terminator
entered.

Status Codes
FDV$_ARG
FDV$_CAN
FDV$_INI
FDV$_SUC
FDV$_SYS
FDV$_TCA
FDV$_TMO
FDV$_UAR
FDV$_UDP
FDV$_UNF

Incorrect number of arguments.
Call was terminated by a CANCL call.
No workspace is defined.
Successful completion of the call.
Form Driver encountered system error response.
No terminal control area (TCA) is defined.
Operator took longer to respond than allowed by the timeout
value associated with the current terminal.
UAR returned illegal code.
UAR depth exceeded.
UAR specified but not found.

FORM DRIVER CALLS

5-81

APPENDIX A
VAX FMS Form Driver Calls
A.1

VAX Language-Independent Notation
Form Driver routines are invoked according to rules specified in the VAX
Procedure Calling and Condition Handling Standard (Appendix C of the VAX
Run-Time Library Reference Manual). The complete notation for describing
VAX calls is documented in Appendix C of the VAX Guide to Creating
Modular Library Procedures.
Form Driver routines can be invoked as subroutines or as functions:
As a subroutine

CALL FDV$:xxx (parameter!, parameter2,...)

as a function

VMS_stat. wlc.v = FDV$xxx (parameter!,
parameter2,... )

Access type, data type, passing mechanism, and parameter form are assigned
to each parameter in a prescribed order:
<parameter-name>. <access type><data type>. <passingmechanism><parameter form>

A-1

Example
For the FDV$GET call the fidval, fidtrm, fidnam, and fididx parameters
are described as follows:
FDV$GET (fidval. wt.dxl,fidtrm. wl.r,fidnam.rt.dxl[,fididx.rl.r]
The notation for each parameter is explained below. Note that every Form
Driver call returns a VMS status code in the form VMS_stat.wlc.v.
<passing mechanism>

Parameter

fldval

w Write-only

t Character-coded text d By descriptor

access

fldtrm

w Write-only

access

fldnam

fldidx

A-2

string
I Longword integer
(signed)

xl Fixed-length or
dynamic string
descriptor

r By reference

r Read-only
access

t Character-coded text d By descriptor

r Read-only
access

I Longword integer
(signed)

string

VAX FMS Form Driver Calls

r By reference

xl Fixed-length or
dynamic string
descriptor

A.2

Procedure Parameter Notation For Form Driver Calls
FMS uses a subset of the VAX procedure parameter notation. The following
table explains the notation used for access type, data type, passing mechanism, and parameter form.
Notation

Comments

Read-only access

Parameters for input

Write-only access

Parameters for output

Modify access

Parameters for both input and output

Notation

Virtual address

Longword integer (signed)

Longword return status

Character-coded text string

Aligned bit string

Word integer (signed)

Notation

By descriptor

FMS passing mechanism for character
strings and integer arrays

By reference

FMS passing mechanism

Notation

Comments

Array reference or descriptor

Fixed-length or dynamic string descriptor

VAX FMS Form Driver Calls

A-3

VAX FMS Form Driver Calls
Call

Procedure Parameter Notation

ADLVA

FDV$ADLVA (video.ml.r)
video

video attributes code of data line

Alters the data line video attributes. You can specify Blink, Bold, Reverse,
and/or Underline.
AFCX

FDV$AFCX (insovr.rl.r,curpos.rl.r[,ftdnam.rt.dxl[,ftdidx.rl.r]])
insovr
curpos
ftdnam
ftdidx

Insert/Overstrike mode of field
cursor position within field
field name
field index

Alters the default field context of the specified field. You can specify Insert or
Overstrike mode and cursor position in the field before any GET operation
involving that field.
AFVA

FDV$AFVA (video.ml.r[,ftdnam.rt.dxl[,ftdidx.rl.r]])
video
ftdnam
ftdidx

video attributes code for field
field name
field index

Alters the field video attributes.
ATERM

FDV$ATERM (tca.ml.da,size.rl.r,channel.rl.r[,trmnal.rt.dxl
[,faketrmtyp.rt.dxl[,options.rl.r]]])
or
FDV$ATERM (tca.mt.dxl,size.rl.r,channel.rl.r[,trmnal.rt.dxl
[,faketrmtyp.rt.dxl[,options.rl.r]]])
tea
terminal control area
size
size
channel
logical 1/0 channel number for terminal
trmnal
name of terminal
faketrmtyp name of terminal used for batch processing
options
integer specifying Form Driver options
Attaches a terminal to the Form Driver for processing forms over a specific,
logical 110 channel, names a TCA for that terminal, and specifies the size of
theTCA.

AWKSP

FDV$AWKSP (wksp.ml.da,size.rl.r)
or
FDV$AWKSP (wksp.rt.dxl,size.rl.r)
wksp
size

form workspace
estimate of workspace size

Attaches a form workspace to a list of workspaces associated with the current
TCA, specifies the size in bytes, and establishes that workspace as the current
workspace.

A-4

BELL

FDV$BELL
Rings the terminal bell.

CANCL

FDV$CANCL
Cancels any other call presently being processed on the current terminal.

VAX FMS Form Driver Calls

CDISP

FDV$CDISP (frmnam.rt.dxl[,offset.rl.r])
frmnam
offset

form.name
number controlling placement of form on screen

Clears the screen and displays a form. The display position may be offset from
the original form description.

CLEAR

FDV$CLEAR ([line[,linecnt]])
line
linecnt

line number of first line to clear
number oflines to clear

Clears the entire screen unless otherwise specified with the arguments.

CLEAILVA FDV$CLEAR_VA
Clears the screen video attributes.
DEL

FDV$DEL (frmnam.rt.dxl)
frmnam

form.name

Deletes a form from the list of memory-resident forms.
DFKBD

FDV$DFKBD (detkbd.rw.da,kbdnum.rl.r)
detkbd
kbdnum

array of key functions and key codes
number of pairs of key functions and associated key codes in
defkbd array

Redefines the FMS keypad function keys.

DISP

FDV$DISP (frmnam.rt.dxl[,offset.rl.r])
frmnam
offset

form.name
number controlling placement of form on screen

Clears the portion of the screen specified as the "clear area" in the form
description and displays a form. The display position can be offset from the
original form description.

DISPW

FDV$DISPW ([offset.rl.r])
offset

number controlling placement of form on screen

Clears the portion of the screen specified as the "clear area" in the form
description and displays the form that is already loaded in the workspace. The
display position can be offset from the original form description.

DPCOM

FDV$DPCOM ([dpmode])
dpmode

value defining decimal point in signed-numeric fields

Defines the comma, or redefines the period, as the.decimal point in fields containing signed-numeric field-validation characters.
DTERM

FDV$DTERM (tca.ml.da)
or
FDV$DTERM (tca.rt.dxl)
tea

terminal control area

Detaches a terminal from the Form Driver, and detaches any workspaces associated with the terminal.

VAX FMS Form Driver Calls

A-6

DWKSP

FDV$DWKSP (wksp.ml.da)
or
FDV$DWKSP (wksp.rt.dxl)
wksp

form workspace

Detaches a form workspace from the list of workspaces associated with the
current terminal.
FULSCREEN FDV$FILSCREEN
Repairs overwritten lines on the terminal screen.
GET

FDV$GET (fldval. wt.dxl,fldtrm. wl.r,fldnam.rt.dxl[,fldidx.rl.r])
fldval
fldtrm
fldnam
fldidx

field value
field terminator
field name
field index

Positions the cursor in the initial cursor position of a specific modifiable field
and waits for the operator to enter a value.
(}ETAF

FDV$GETAF (fldval. wt.dxl,fldtrm. wl.r,fldnam. wt.dxl[,fldidx. wl.r])
fldval
fldtrm
fldnam
fldidx

field value
field terminator
ending field name
ending field index

Positions the cursor in the current field in the form and waits for the operator
to enter a value in any field.
GETAL

FDV$GETAL ([fldval. wt.dxl,fldtrm. wl.r[,fldnam.rt.dxl[,fldidx.rl.r]]])
fldval
fldtrm
fldnam
fldidx

returned values of all fields in form
field terminator
starting field name
starting field index

Positions the cursor in the first modifiable field in a form unless otherwise
specified in the fldnam argument and allows you to enter data in all modifiable, nonscrolled fields.
GETDL

FDV$GETDL (value.wt.dxl,fldtrm.wl.r[,line.rl.r[,prompt.rt.dxl]])
value
fldtrm
line
prompt

contents of data line returned from Form Driver
field terminator
line number on which the operator's input is displayed
data line text to serve as a prompt for the operator

Gets a data line from a specified line on the screen.
GETSC

FDV$GETSC (fldnam.rt.dxl,fldval. wt.dxl[,fldtrm. wl.r])
fldnam
fldval
fldtrm

field name that identifies a scrolled area
field values
field terminator

Positions the cursor within the current line in the scrolled area that contains
the specified field and accepts input in modifiable fields within the line.
ILTRM

FDV$1LTRM (trmmod.rl.r)
trmmod

value for illegal terminator :m,ode switch

Specifies the action to take when an illegal field terminator is entered. An illegal field terminator can be rejected by the Form Driver or returned to the program.

A-3

VAX FMS Form Driver Calls

LCHAN

FDV$LCHAN (channel.rl.r)
channel

1/0 channel number for form library

Sets the channel for form library files associated with the c,urrent terminal.
The Form Driver uses the specified channel for any LOPEN or LCLOS call
processing.
LC LOS

FDV$LCLOS
Closes the form library associated with the current library channel for the current terminal.

LEDOF

FDV$LEDOF Oedno.rl.:r)
ledno

terminal LED number

Turns off the light-emitting diode (LED) on the VTlOO keyboard.
LEDON

FDV$LEDON (ledno.rl.r)
ledno

terminal LED number

Turns on the light-emitting diode (LED) on the VTlOO keyboard.
LOAD

FDV$LOAD (frmnam.rt.dxl)
frmnam

formname

Loads a form description into a workspace without displaying the form on the
screen.
LOPEN

FDV$LOPEN (filspc.rt.dxl[,channel.rl.r])
filspc
channel

form library file specification
1/0 channel number for form library

Opens a form library and replaces the current library channel specification if
the 1/0 channel number is supplied.
NDISP

FDV$NDISP
Marks current workspace as not displayed.

PFr

FDV$PFT ([fldtrm.rl.r[,fldnam.rt.dxl[,fldval.rt.dxl
[,nfldnam.wt.dxl[,nfldidx. wl.r]]]]])
fldtrm
fldnam
fldval
nfldnam
nfldidx

field terminator to be processed
field name that identifies a scrolled area
field values to be displayed
current field name after call has been completed
current field index after call has been completed

Processes the field terminator and checks for valid terminator codes.
PUT

FDV$PUT (fldval.rt.dxl,fldnam.rt.dxl[,fldidx.rl.r])
fldval
fldnam
ftdidx

field value to be displayed
field name
field index

Stores the value of the ftdval argument and displays that value in the specified field.
PUTAL

FDV$PUTAL ([frmval.rt.dxl])
frmval

list of field values to be displayed

Outputs values to all fields, stores the frmval argument values in the workspace for nonscroiled fields, and displays these values on the screen.

VAX FMS Form Driver Calls

A-7

PUTD

FDV$PUTD (fldnam.rt.dxl[,fldidx.rl.r])

ftdnam
ftdidx

field name
field index ,

Outputs the default value to a specified field.
PUTDA

FDV$PUTDA

Outputs default values to all fields in the form and displays those values on
the screen.
PUTL

FDV$PUTL (text.rt.dxl[;line.rl.r])

text
line

data line text
line number for displayed data line

Outputs data to the specified line on the screen. If the line number is zero, the
data line is displayed on the last line of the screen.
PUTSC

FDV$PUTSC (fldnam.rt.dxl[,fldval.rt.dxl])

ftdnam
ftdval

field name that identifies a scrolled area
field value

Outputs data to the current line of a scrolled area that contains the specified
field name.
READ

FDV$READ (frmnam.rt.dxl,mloc.ml.da,mlocsiz.rl.r,frmsiz.wl.r)

dr
FDV$READ (frmnam.rt.dxl,mloc.rt.dxl,mlocsiz.rl.r,frmsiz.wl.r)

frmnam
niloc
mlocsiz
frmsiz

form name
form storage area
size of memory buffer that begins with mloc
form size actually used

Extracts a form from the current form library, stores it in a specified memory
area, and adds the name of the form to the list of memory-resident forms.
RET

FDV$RET (fldval.wt.dxl,fldnam.rt.dxl[,fldidx.rl.r])

fldval
fldnam
fldidx

field value
field name
field index

Returns the value for a specified field stored in the workspace.
RETAL

FDV$RETAL (frmval.wt.dxl)

frmval

concatenated values of all fields except those in scrolled areas

Returns the values for all fields except those in scrolled areas stored in the
workspace.

RETCX

FDV$RETCX (atca.wa.r,awksp.wa.r,frmnam.wt.dxl,uarval.wt.dxl,

curpos.wl.r,ftdtrm.wl.r,insovr. wl.r,hlpnum.wl.r)
a tea
awksp
frmnam
uarval
curpos
fldtrm
insovr
hlpnum

terminal control area address
form workspace address
formname
value of the associated text for this UAR
cursor position within field
returned field terminator
Insert/Overstrike mode of field
number of times HELP key pressed for current field

Returns the current context of the Form Driver. You can issue this call in a
UAR to determine the context in which the UAR is called.

A-8

VAX FMS Form Driver Calls

RETDI

FDV$RETDI (nmdidx.rl.r,nmdval.wt.dxl[,nmdnam.wt.dxl])
nmdidx
nmdval
nmdnam

index of Named Data item
text of Named Data item
name of Named Data item

Returns the Named Data text that you specify by its index (rather than by its
name).
RETDN

FDV$RETDN (nmdnam.rt.dxl,nmdval. wt.dxl[,nmdidx.rl.r])
nmdnam
nmdval
nmdidx

name of Named Data item
text of Named Data item
index of Named Data item

Returns the Named Data text that you specify by its name (rather than by its
index).
RETFL

FDV$RETFL (line.rl.r,value. wt.dxl,linlen. wl.r[,type.rl.r])
line
value
linlen
type

line number of form to be returned
value ofrequested line
length of character string returned in value parameter
type of output line requested

Returns the contents of the line that you specify with the line argument. This
is one of the lines displayed by the RFRSH call. This call can also be used for
loaded but undisplayed forms for report formatting.
RETFN

FDV$RETFN (ftdnam.wt.dxl[,ftdidx.wl.r])
ftdnam
ftdidx

field name
field index

Returns the current field name and index from the current workspace. If the
field is not indexed, the index value returned is zero.
RETFO

FDV$RETFO
ftdnum
ftdnam
ftdidx

field number
field name corresponding to ftdnum
field index corresponding to ftdnum

Returns the name and index of the nth field in the form.
RETLE

FDV$RETLE (ftdlen.wl.r,ftdnam~rt.dxl[,ftdidx.rl.r])
ftdlen
ftdnam
ftdidx

field length excluding field-marker characters
field name
field index

Returns the number of data characters in the specified field.
RFRSH

FDV$RFRSH
Refreshes the screen. The RFRSH operation is identical to that initiated by
pressing the CTRL/R keys.

SCR_WIDTH FDV$SCR_WIDTH (width.lr.r)

width

80/132 column screen width

Tells the Form Driver the current screen width.
SIGOP

FDV$SIGOP
Causes the application program to signal the operator.

VAX FMS Form Driver Calls

A-9

SPADA'

FDV$SPADA (mode.rl.r)
mode

numeric/application keypad mode

Sets the alternate keypad mode. Selecting 0 sets the alternate keypad to
numeric mode; selecting 1 sets the keypad to application mode.
SPOFF

FDV$SPOFF
Turns supervisor-only mode off for the current terminal, allowing the operator
to modify fields protected with the Supervisor Only attribute.

SPON

FDV$SPON
Turns supervisor-only mode on for the current terminal, treating fields protected with the Supervisor Only attribute as display-only fields.

SSIGQ

FDV$SSIGQ (sigmd.rl.r)
sigmd

bell/reverse video signaling mode

Sets signal mode for the current terminal. Audio mode (0) rings the terminal
bell. Video mode (1) reverses the VT100NT200 video image.
SSRV

FDV$SSRV ([status.wl.r[,iostat.wl.r]])
status
iostat

general status reporting variable
1/0 status reporting variable

Sets the addresses of the status reporting variables.
STAT

FDV$STAT (status. wl.r[,iostat.wl.r])
status
iostat

general status code
1/0 status code

Returns the status code for the last Form Driver call.
STERM

FDV$STERM (tca.ml.da)
or
FDV$STERM (tca.rt.dxl)
tea

terminal control area

Sets current terminal and the workspace most recently associated with that
terminal to the current workspace. The TCA must have been previously
attached by the FDV$ATERM call.
STIME

FDV$STIME (time.rl.r)

time

timeout period in seconds

Specifies the number of seconds the Form Driver waits for operator response to
a GET-type call.

SWKSP

FDV$SWKSP (wksp.ml.da)
or
FDV$SWKSP (wksp.rt.dxl)
wksp

form workspace

Specifies the workspace that the Form Driver uses for the current workspace.
The workspace must have been previously attached by the FDV$ATERM call.
TCHAN

FDV$TCHAN (channel.rl.r)
channel

physical 1/0 channel number for terminal

Changes the terminal channel associated with the current TCA to the specified value.

A-10

VAX FMS Form Driver Calls

USER_REFRESH FDV$USER_REFRESH([rfr_address.ra.r])
rfr_
address

user-supplied refresh routine

Sets up a user-supplied refresh screen routine.

WAIT

FDV$WAIT ([fldtrm.wl.r])
ftdtrm

field terminator code

Causes the application program to wait until the operator presses a terminator key. This call allows the Form Driver to synchronize the application program to the operator's pace.

VAX FMS Form Driver Calls

A-11

Index

A
ADLVA call, 5-2, 5-3
AFCX call, 5-3, 5-4
AFVA call, 5-4
Alternate keyboard mode, VTlOO,
2-24
Alternate keypad mode, .2-37, 5-69
Area to Clear attribute, 2-4
Asterisk (*), 5-26, 5-6
ATERM call, 2-3, 2-4, 2-6, 5-6
5-78
Attaching terminals, 2-4, 5-6
Attaching workspaces, 5-9
Attributes
Area to Clear, 2-4
Autotab, 2-9
Clear Character, 2-10, 2-11
Date, 2-12
default, 5-50
Display Only, 2-11
fill-character, 2-8, 2-9
fixed-decimal, 2-11, 2-24
Left Justified, 2-8, 2-24
Must Fill, 2-10, 5-26 to 5-30,
5-34
No Echo, 2-11
Response Required, 2-10, 5-26
to 5-30, 5:--34
Right Justified, 2-8, 2-24
Screen Area to Clear, 5-19

Supervisor Only, 2-12
Time, 2-12
default, 5-50
video, 2-9, 5-18, 5-23, 5-48,
5-61, 5-72
altering, 5-2, 5-4
clearing, 5-18, A-5
Zero Fill, 2-10
Autotab attribute, 2-9, 5-9
AWKSP call, 2-3, 2-6, 5-1
5-9

B
BELL call, 5-10

c
Call format, 5-1
Calls 5-2
ADLVA, 5-2, 5-3
AFCX, 5-3, 5-4
AFVA, 5-4, 5-6
ATERM, 2-3, 2-5, 2-6, 5-6,
5-9, 5-78
AWKSP, 2-3, 2-6, 5-1
5-9
BELL, 5-1, 5-10
CANCL, 5-11
and UARs, 2-13, 5-12

Index-I

CDISP, 2-3, 2-6, 5-12, 5-21·
5-11
CLEAR, 5-113, 5-14
CLEAR-VA, 4-3, 5-14, A-5
Control, 1-4, 5-15
DEL, 5-15, 5-16
DFKBD, 2-39, 2-46, 5-16
5-18
DISP, 2-3, 2-6, 5-18
DISPW, 2-3, 2-6, 5-21, 5-22,
5-25, 5-43
DPCOM, 2-25, 5-22, 5-23
DTERM, 2-5, 2-6, 5-23, 5-24
DWKSP, 2-6, 5-24
field-level, 1-5
form-le:vel, 1-5, 5-25
F1x_scREEN' 2-4, 4-3, 5-25,
5-26, A-7
GET, 2-8, 2-18, 5-26
using series of, 2-30 to 2-31
5-28
GETAF, 2-8, 5-28, 5-30
GETAL, 2-8, 5-30
and UARs, 2-13
using, 2-30 to 2-31, 5-32
GETDL, 2-4, 5-2, 5-19, 5-32
5-34
GETSC, 2-8, 5-34
GET-type, 2-4, 2-19, 2-32, 5-43
timeout value for, 5-76
using, 2-30 to 2-31, 5-36
ILTRM, 2-18, 2-37, 5-36, 5-37
LCHAN, 2-3, 5-37, 5-38
LCLOS, 5-37, 5-38, 5-39
LEDOF, 5-39, 5-40
LEDON, 5-40, 5-41
LOAD, 2-3, 2-6, 5-21, 5-41.
5-42
LOPEN, 2-3, 5-37, 5-42
5-43
NDISJP, 2-6, 5-21, 5-43
PFT, 2-32, 2-34 to 2-37, 5-26,
5-34, 5-44
and UARs, 2-13, 5-44
PUT, 2-18, 5-447
PUTAL, 2-8, 5-48
PUT, 5-48, 5-49 ·
PUTD, 5-49
and Date and Time attributes,
2-12, 5-30
PUTDA, 5-30
and Date and Time attributes,
2-12
PUTL, 2-4, 2-18, 2-51, 5-2,
5-19, 5-51, 5-53

Index-2

PUTSC, 2-8, 5-53
PUT-type, 2-4, 5-54
READ, 2-3, 5-15, 5-54, 5-55
RET, 5-55, 5-56
RETAL, 2-8, 5-56, 5-58
RETCX, 2-7, 2-18, 5-58
and UARs, 2-12, 5-59
RETDI, 5-59, 5-60
RETDN, 5-60, 5-61
RETFL, 5-61, 5-63
RETFN, 5-63, 5-64
RETFO, 5-64, 5-65
RETLE, 5-65
RFRSH, 2-4, 2-6, 2-18, 5-19,
5-41, 5-61, 5-66. See also
Refresh operation and Date and
Time attributes, 2-12, 5-67
SCH-WIDTH, 4-3, 5-14, 5-67,
5-68, A-13
SIGOP, 5-68, 5-69
SPADA, 2-24, 2-37, 5-69
5-70
SPOFF, 2-12, 5-70, 5-71
SPON, 2-12, 5-71, 5-72
SSIGQ, 2-22, 5-72, 5-73
SSRV, 2-46, 5-37, 5-74
STAT, 2-46, 5-74, 5-75
STERM, 2-5, 2-6, 5-75
5-76
STIME, 5-76, 5-77
SWKSP, 2-6, 5-77, 5-78
TCHAN, 5-6, -0-23., 5-78
5-79
USER-REFRESH, 5-79
utility, 1-6, 5-81
WAIT, 2-18, 2-20, 5-81
Call status, checking, 2-46
5-11
CANCL call, 5-11
and UARs, 2-13, 5-12
CDISP call, 2-3, 2-6, 5-12, 5-21
Channel, current logical library,
specifying, 5-37
Channel, library, 1-9
Channel, terminal, physical, 5-78
Channel number, 1/0, 5-42
Channel number, logical, specifying,
5-6
Character, deleting a, 2-26
Characters, field-marker, 2-9
Checking operator responses, 2-23

5-la
CLEAR call, 5-13
Clear Character attribute, 2-10,
Clearing screen, 5-13, 5-14

CLEAR._VA, 4-3, 5-14, A-5
Codes
error, RMS, 2-48
VO status, 1-9
key, 2-39 to 2-45
status, 1-9, 2-48
and UARs, 2-13
Codes. See Status codes
Control keys, 2-39 to 2-40
Current field, 5-45
name returned, 5-63
Current logical library channel,
specifying, 5-37
Current scrolled line, 5-45
Current states
field, 1-8
last status code, 1-9
last terminator, 1-9
library channel, 1-9
scrolled line, 1-9
supervisor-only flag, 1-9
terminal, 1-8
timeout value, 2-10
workspace, 1-8
Current terminal, 2-5
setting, 2-5
specifing, 5-75
·Current workspace, 2-5
specifying, 5-77
Cursor
keys to move, 2-27
moving to another field, 2-33
Cursor control keys, 2-39
Cursor position, 2-11, 5-57
initial, 2-23
specifying default, 5-3

Default values output, 5-50, 5-50
Defining keys, 2-46, 5-15, 5-16
DEL call, 5-15
Deleting a character, 2-24
Deleting a field, 2-24
Detaching TCAs, 5-23
Detaching terminals, 2-5, 5-23
Detaching workspaces, 5-16, 5-24, 5-25
DFKBD call, 2-39, 2-46, 5-16
Disk-resident forms, 2-1
and Help function, 2-7, 5-18
DISP call, 2-3, 2-6, 5-18
Displaying forms, 2-2, 5-18 to 5-20,
5-23
Display Only attribute, 2-11
Display-only fields, 5-18, 5-26
to 5-30, 5-35, 5-55
DISPW call, 2-3, 2-6, 5-18,
5-21, 5-22, 5-25,. 5-43
DPCOM call, 2-22, 5-5, 5-23
DTERM call, 2-5, 2-6, 5-23
5-24
DWKSP call, 2-6, 5-24

E
Enter Form key, 2-11
Enter Form terminator, 2-33
ENTER key, 2-18, 2-22
Error codes. See Status codes
Errors, program, signaling
operator 2-51
Exiting Scrolled Area Backward
terminator, 2-36
Exiting Scrolled Area Forward
terminator, 2-36

F
Data line, 5-32, 5-48
Date attribute, 2-12
default, 5-50
Debug mode, 1-7, 2-22, 2-47,
2-49 to 2-50,
Decimal point, 2-11
comma used as, 5-22
in fixed-decimal field, 2-23
in signed-numeric field, 2-25
Default field-editing keys, 2-23
Default field input mode, altering,
5-3
Default field values, 2-10
Default keys, 2-24

Field, current, 1-8, 5-44
Field attributes. See Attributes
Field completion UARs, 2-12, 5-28
to 5-32, 5-34
Field-editing functions, 2-23
Field-editing keys, 2-22
Field input mode, the default
5-3
Field length returned, 5-65
Field-marker characters, 2-9
Field names returned, 5-64, 5-64
Field pictures, 2-9

Index..;.3

Fields, 1-3
default values, 2-10
deleting, 2-24
display only, 5-28 to 5-32,
5-34, 5-55
fixed-decimal, 2-23
highlighting, 5-4
left-justified, 2-9, 2-10
processing, 2-9
processing order, 2-9
right-justified, 2~9, 2-10
signed numeric, 2-25
supervisor-only, 5-28 .to 5-30,
Field terminator, last, 5-57
Field terminators, 2-28, 5-26
processing, 5-44
Field value
read, 5-47, 5-49
written, 5-30, 5-51
Field values, 5-26 to 5-30
written, 5-30
Fill Character attribute, 2-10
Fixed Decimal attribute, 2-11
Fixed Decimal field attribute,
2-11, 2-23, 5-25
F1x_scREEN, 2-4, 4-3, 5-25,
A-7
FMS utilities, 2-2
Form Application Aids, 2-2
Format, call, 5-1
Form complete terminator, 2-33
Form descriptions, 2-2, 2-4
Form Driver calls. See Calls
Form Editor, 2-2, 2-10
and UARs, 2-13
Form Language Translator, 2-2,
2-10
and UARs, 2-13
Form library, 1-7, 2-2, 5-50
closing, 5-38
opening, 5-42
Form line returned, 5-61
Form position offset, 5-21, 5-18,
Forms, 1-2. See also Workspaces
and Form descriptions
accessing, 2-1
context of, 5-58
disk.;resident, 2-1
and Help function, 2-7
displaying, 2-2, 5-18 to 5-20,
5-21
loading, 2-3
loading without display, 5-41
marked as displayed, 5-49, 5-66

Index-4

marked as undisplayed, 5-21,
5-38, 5-41
memory-resident, 1-7, 2-2, 5-50
deleting, 5-15
linking, 4-2
'overlaid, 2-4, 5-19
storing, 2-1, 2-5
Forms, memory:..resident,
deleting, 5-15
Form values, 5-48, 5-56
Form workspaces. See Workspaces
Function key UARs, 2-18, 5-26, .
5-36

G
GET call, 2-8, 2-18, 5-26
using, series of, 2-30 to 2-31
5-28
GETAF call, 5-28, 5-30
GETAL call, 2-8, 5-30
and UARs, 2-13
using, 2-30 to 2-31,
5-32
GETDL call, 2-3, 5-19, 5-32 to 5-33,
5-34
GETSC call, 2-8, 5-34
GET-type calls (GET, GETAF,
GETAL, and GETSC), 2-4, 2-19,
2-32, 5-43
timeout value for, 5-76
using, 2-30
Gold sequences, 2-40 to 2-45

H
Help, 5-32
function, 2-7
key, 2-18
processing, 2-16
statistics, 5-54
Help UARs, 2-15

1/0 channel number, 5-42
1/0 status codes, 1-9
Illegal terminators, 2-18, 2-37,
5-36
ILTRM call, 2-18, 2-37, 5-36

Insert mode, 2-9, 5-3, 5-57
keys, 2-27
setting, 2-27

K
Keyboard mode, VTlOO alternate,
2-23
Key codes, 2-39 to 2-45
Key functions, 1-8, 2-38
Keypad keys, 2-39
Keypad mode, alternate, 2-37,
5-69
Keys
control, 2-39 to 2-40
cursor control, 2-33 to 2-37
default, 2-24
default field-editing, 2-22
defining, 2-39 to 2-45, 5-16
field-editing, 2-22
Insert mode, 2-27
keypad, 2-37
Overstrike mode, 2-27
reserved, 2-45 to 2-46
terminator, 2-37, 5-37

L
LCHAN call, 2-3, 5-37
5-38
LCLOS call, 5-37, 5-38
5-39
LEDOF call, 5-39, 5-40
LEDON call, 5-40
LEDs, terminal, 5-7, 5-39, 5-40
Left-justified field, 2-8, 2-10
Left Justified field attribute,
2-8, 2-23
Library, form, 1-7, 2-2, 2-8,
5-50
opening, 5-42
Library channel, 1-9
Library channel, current logical,
specifying, 5-37
Linking
with a UAR vector, 4-2
with memory-resident forms, 4-2
with the Form Driver
library, 4-2, 5-41
LOAD call, 2-3, 2-6, 5-21, 5-41
Loading forms, 2-3
without display, 5-41

Loading workspaces, 2-3, 2-5
Logical channel number
specifying, 5-6
Logical library channel, current,
specifying, 5-37, 5-42
LOPEN call, 2-3, 5-37, 5-42

M
Memory-resident forms, 1-7, 2-2,
5-50
deleting, 5-15
linking, 4-2
Multiple workspaces, 2-6
Must Fill attribute, 2-10, 5-26
to 5-30, 5-30

N
Named Data, 1-8
returned by index, 5-59
returned by name, 5-43, 5-60
NDISP call, 2-6, 5-21, 5-43
Next Field key, 2-10, 2-11
Next Field terminator, 2-32
No Echo attribute, 2-11
1

0
Offset, form position, 5-18, 5-21
Operator, signaling the, 2-22,
5-8, 5-68, 5-72
Operator responses, checking,
2-23
Overlaid forms, 2-4, 5-19
Overstrike mode, 2-9, 5-57
keys, 2-27
setting, 2-27
specifying default, 5-3

p
PFT call, 2-32, 2-35 to 2-36,
5-26, 5-30, 5-44
and UARs, 2-13
Picture, signed numeric, 2-22,
5-25
Pictures, field, 2-9

Index-5

Point, decimal
comma·used as, 5-22
Previous Field terminator, 2-37
Program errors, signaling
operator, 2-51, 5-47
PUT call, 2-18, 5-47, 5-48
PUTAL call, 2-8, 5-48, 5-49
PUTD call, 5-49
and Date and Time attributes,
2-12, 5-50
PUTDA call, 5-50
and Date and Time attributes,
2-12, 5-53
PUTSC call, 2-8, 5-51, 5-53
PUTL call, 2-4, 2-18, 5-51 to
,..
5-52
PUT-type calls (PUT, PUTAL, PUTD,
and PUTDA, PUTSC), 2-4, 5-54

R
READ call, 2-3, 5-15, 5-54
Refresh operation, 2-6, 2-23,
5-13, 5-43. See also
RFRSH call
Response Required attribute, 2-10,
5-22 to 5-26, 5-30, 5-55
RET call, 5-:-55, 5-56
RETAL call, 2-8, 5-56, 5-57
RETCX call, 2-7, 2-18, 5-57
and UARs, 2-12, 5-59
RETDI call, 5-59, 5-60
RETDN call, 5-60, 5-61
RETFL call, 5-61, 5-63
RETFN call, 5-63, 5-64
RETFO call, 5-64, 5-65
RETLE call, 5-65
Return form context, 5-57
RETURN key, 2-18
RFRSH call, 2-4, 2-6, 2-18, 5-19,
5-40, 5-66. See also
Refresh operation and Date
and Time attributes, 2-12
Right-justified field, 2-9, 2-10
Right Justified field attribute,
2-8, 2-23
RMS system error codes, 2-48

s
Screen, clearing, 5-13
Screen Area to Clear attribute,
5-19, 5-67

Index-6

SCR._WIDTH, 4-3, 5-14, 5-67,
A-13
Screen width attribute, 5-14
Scroll Backward terminator, 2-35
Scrolled areas, 2-12, 5-23, 5-26
Scrolled line, current, 1-9
Scroll Forward terminator, 2-35
Scrolling, 1-7, 2-12, 3-1
Signaling the operator, 2-22, 5-8
5-68, 5-68
signal mode, specifying, 5-72
signed numeric picture, 2-22
5-25, 5-68
SIGOP call, 5-68
Single-character fields, 3-4
5-69
SPADA call, 2-23, 2-37, 5-69
5-70
SPOFF call, 2-12, 5-70
5-71
SPON call, 2-12, 5-71
5-72
SSIGQ call, 2-22, 5-72, 5-73
SSRV call, 2-46, 5-73, 5-74
STAT call, 2-46, 5-74
States, current
last I/0 status code, 1-9
last status code, 1-9
last terminator, 1-9
library channel, 1-9
scrolled line, 1-9
supervisor-only flag, 1-9
terminal, 1-8
workspace, 1-8
Status returned from last call,
5-74
Status, checking call, 2-46, 3-18
Status codes, 1-9
and UARs, 2-13
FMS, 2-48
VMS, 2-48
Status reporting variables,
specifying, 5-73, 5-75
STERM call, 2-5, 5-75, 5-76
STIME call, 5-76
Supervisor Only attribute,. 2-12
Supervisor-only fields, 5-22 to
5-26, 5-30
Supervisor-only flag, 1-9
Supervisor Only mode
off, 5-71
on, 5-70, 5-77
SWKSP call, 2-6, 5-77

T
TCAs, 1-2, 1-3, 5-40, 5-77
See also Terminals
detaching, 5-23
specifying, 5-6 to 5-7
5-78
TCHAN call, 5-6, 5-23, 5-78
Terminal, current, 1-8, 2-5
setting, 2-6
specify, 5-75
Terminal channel, physical, 5-78
Terminal characteristics, 4-1
Terminal control, 2-5
Terminal control areas.
See TCAs
Terminal LEDs, 5-6, 5-39
Terminal output, direct, 4-3
Terminals, 1-2. See also TCAs
attaching, 5-6
detaching, 2-5, 5-23
key functions, 1-8
Terminator, last, 5-57
Terminator keys, 2-37
Terminators, 1-9, 5-26
Enter Form, 2-33
Exit Scrolled Area Backward,
2-36
Exit Scrolled Area Forward,
2-36
field, 2-26
for GET-type calls, 2-30
form complete, 2-33
illegal, 2-18, 2-36, 5-32
Next Field, 2-10, 2-11, 2-33
Previous Field, 2-33
processing, 5-44
Scroll Backward, 2-35
Scroll Forward, 2-35
Time attribute, 2-12
default, 5-49
Timeout, 2-14
Timeout value, specifying
for GET-type call, 5-76

help, 2-15
legal actions in, 2-19
post-help, 2-16
pre-help, 2-15
UAR v_ector, linking with, 4-2
User action routines. See UARs
5-79
USER____REFRESH 5-79
Utilities, FMS, 2-2

v
Video attributes, 2-9, 5-14, 5-23
5-51, 5-61, 5-72
altering, 5-2, 5-4
VTlOO alternate keyboard mode,
2-23, 5-81

w
WAIT call, 2-18, 2-20, 5-81
Workspace, current, 1-8, 2-6
specifying, 5-77
Workspaces, 1-2, 1-3. See
also Forms and Form
descriptions
attaching, 5-7
detaching, 5-23
loading, 2-3, 2-6
multiple, 2-6
Workspace size, estimating, 5-9

z
Zero Fill attribute, 2-10, 2-11

u
UARs, 1-7, 2-12 to 2-19, 5-11,
5-30, 5-43
and RETCX call, 5-57 to 5-58
field completion, 2-13, 5-26 to
5-30
function key, 2-18, 5-22, 5-32

Index-7

VAX FMS
Form Driver
Reference Manual
AA-L319B-TE
READER'S COMMENTS
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.

Please indicate the type of user/reader that you most nearly represent.

O Assembly language programmer
0

Higher-level language programmer

0 Occasional programmer (experienced)
0

User with little programming experience

0 Student programmer
0 Other (please specify)

Organization
Street
State _ _ _ _ _ _ Zip Code - - - - - or Country

DoNotTear-FoldHereandTape -

~amaomn

No Postage
Necessary
if Mai led in the
United States

111111

BUSINESS REPLY MAIL
FIRST CLASS PERMIT N0.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

SSG PUBLICATIONS ZK1-3/J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, NEW HAMPSHIRE 03062-2698

Do Not Tear - Fold Here