HP DECforms software Programmer's Reference Manual
Below you will find brief information for DECforms software. DECforms software is a software product for applications, services, and tools that require a structured, forms-based, or menu-based user interface.
Advertisement
Advertisement
HP DECforms
Programmer’s Reference Manual
Order Number: AA–Q503C–TE
January 2006
HP DECforms is a software product for applications, services, and tools that require a structured, forms-based, or menu-based user interface.
DECforms is the first commercial implementation of an ANSI/ISO standard for forms-based interfaces, the CODASYL Form Interface Management
System (FIMS).
Revision/Update Information:
This is a revised manual.
Operating System:
Software Version:
OpenVMS Alpha Version 7.3-2 or later
OpenVMS I64 Version 8.2 or later
HP DECforms Version 4.0
Hewlett-Packard Company
Palo Alto, California
© Copyright 2006 Hewlett-Packard Development Company, L.P.
Confidential computer software. Valid license from HP required for possession, use, or copying.
Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software
Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendors standard commercial license.
The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.
Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.
Oracle CDD, Oracle/Administrator, Oracle CDD/Repository, Oracle Rdb, and Oracle TRACE are trademarks of Oracle Corporation.
Motif is a registered trademark of the Open Software Foundation, Inc.
ISO is a trademark of the International Organization for Standardization.
PostScript is a registered trademark of Adobe Systems, Incorporated.
Printed in the US
This document was prepared using VAX DOCUMENT Version 2.1.
Contents
Preface
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1 Introduction to Run-Time Processing
1.2
1.3
1.4
1.5
1.1
1.1.1
1.1.2
1.1.3
Overview of DECforms Device Support . . . . . . . . . . . . . . . . . . . .
Support for Character-Cell Terminals . . . . . . . . . . . . . . . . . .
Support for PRINTER Devices . . . . . . . . . . . . . . . . . . . . . . . .
Adding PRINTER Layouts Support to Character-Cell
Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initiating and Controlling Run-Time Communication . . . . . . . . .
Transferring Data Between the Application and the Form . . . . .
Using Responses to Control Run-Time Processing . . . . . . . . . . . .
Using the Activation List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1
2.1.1
2.1.2
2.1.3
2.1.4
2.1.5
2.1.6
2.1.7
2.2
2.2.1
2.2.2
2.2.3
2.3
2.3.1
2.3.2
2 Developing the Application Program
Using DECforms Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Moving Data from a Form to a Program . . . . . . . . . . . . . . . .
Sending Data from a Program to a Form . . . . . . . . . . . . . . . .
Asynchronous SEND Requests . . . . . . . . . . . . . . . . . . . . . . . .
Transceiving Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Disabling Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Canceling Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compiling, Linking, and Running the Application . . . . . . . . . . . .
Compiling an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Linking an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Writing and Calling Escape Routines . . . . . . . . . . . . . . . . . . . . . .
Creating a Form Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Linking Escape Routines Directly with an OpenVMS API
Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ix
2–1
2–3
2–6
2–10
2–13
2–14
2–18
2–18
2–19
2–19
2–20
2–21
2–21
2–22
2–23
1–2
1–2
1–3
1–4
1–5
1–7
1–8
1–9 iii
2.3.3
2.3.4
2.3.5
2.3.6
2.3.7
2.4
2.4.1
2.4.2
2.4.3
2.4.4
2.4.5
2.5
Linking Escape Routines Directly with a Portable API
Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Linking Escape Routines in a Shareable Image . . . . . . . . . . .
Building Applications with Shared Forms or Shared
Procedural Escape Routines on OpenVMS Alpha . . . . . . . . . .
Combining the Direct Link and Shareable Image
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enhancements to Escape Routine Debugging . . . . . . . . . . . .
Using the Trace Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Controlling Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling and Disabling Tracing . . . . . . . . . . . . . . . . . . . . . . .
Exception Conditions During Tracing . . . . . . . . . . . . . . . . . . .
Tracing Command Procedure . . . . . . . . . . . . . . . . . . . . . . . . .
Capturing Additional Tracing Information . . . . . . . . . . . . . . .
Using the Event Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3 Using Oracle Trace Software with DECforms Applications
3.1
3.1.1
3.1.2
3.1.3
3.2
3.2.1
3.2.2
3.3
How to Collect Event Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Describing Events and Items . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling Data Collection . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Create a Report Based on Collected Data . . . . . . . . . . . .
Formatting and Merging Data Files . . . . . . . . . . . . . . . . . . . .
Generating a Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample Oracle Trace Report for DECforms Software . . . . . . . . . .
4.1
4.1.1
4.1.2
4.2
4.2.1
4.2.2
4.2.3
4.2.4
4.2.5
4.3
4.3.1
4.3.2
4.3.3
4.4
4 How the Form Manager Processes Requests
Initialize Request Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initializing Requests (Except ENABLE) . . . . . . . . . . . . . . . . .
Initializing the ENABLE Request . . . . . . . . . . . . . . . . . . . . .
Data Distribution Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Determining Where Values Are Stored . . . . . . . . . . . . . . . . .
How the Data Is Distributed . . . . . . . . . . . . . . . . . . . . . . . . .
Using the DATA TRANSFER Clause . . . . . . . . . . . . . . . . . . .
Shadow Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
External Response Processing Phase . . . . . . . . . . . . . . . . . . . . . .
Performing Control Text Responses . . . . . . . . . . . . . . . . . . . .
Performing Responses to Requests . . . . . . . . . . . . . . . . . . . . .
Response Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accept Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iv
4–1
4–2
4–6
4–12
4–12
4–13
4–14
4–15
4–16
4–18
4–18
4–18
4–19
4–32
2–24
2–25
2–28
2–28
2–29
2–29
2–30
2–32
2–38
2–38
2–39
2–39
3–2
3–2
3–3
3–6
3–7
3–7
3–8
3–9
4.4.1
4.4.2
4.4.3
4.4.4
4.4.5
4.4.6
4.4.7
4.4.8
4.4.9
4.4.10
4.4.11
4.4.12
4.4.13
4.4.14
4.4.15
4.6
4.6.1
4.6.2
4.6.3
4.6.4
4.6.5
4.6.6
4.7
Form Data Assignment Stage . . . . . . . . . . . . . . . . . . . . . . . .
Panel Entry Response Stage . . . . . . . . . . . . . . . . . . . . . . . . .
Group Entry Response Stage . . . . . . . . . . . . . . . . . . . . . . . . .
Field Entry Response Stage . . . . . . . . . . . . . . . . . . . . . . . . . .
Operator Input Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Conversion Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Function Response Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Field Validation Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Field Validation Response Stage . . . . . . . . . . . . . . . . . . . . . .
Field Exit Response Stage . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Validation Response Stage . . . . . . . . . . . . . . . . . . . . .
Group Exit Response Stage . . . . . . . . . . . . . . . . . . . . . . . . . .
Panel Validation Response Stage . . . . . . . . . . . . . . . . . . . . . .
Panel Exit Response Stage . . . . . . . . . . . . . . . . . . . . . . . . . . .
Termination Check Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Altering the Order of Activation Item Processing . . . . . . . . .
4.4.16
4.4.17
4.4.17.1
4.4.17.2
4.4.17.3
4.4.17.4
4.5
Help Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting Help Processing . . . . . . . . . . . . . . . . . . . . . . . . .
How the Help Activation List Works . . . . . . . . . . . . . . . .
Using DECforms Defaults . . . . . . . . . . . . . . . . . . . . . . . .
Customized Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Request Exit Response Phase . . . . . . . . . . . . . . . . . . . . . . . . . . .
Form Data Collection Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How Form Data Is Collected . . . . . . . . . . . . . . . . . . . . . . . . .
Data Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the TRANSFER Clause . . . . . . . . . . . . . . . . . . . . . . . .
Shadow Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receive Shadow Records . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Transfer of Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Request Termination Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5 Using the OpenVMS API
ENABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RECEIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRANSCEIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CANCEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4–45
4–46
4–46
4–48
4–48
4–49
4–49
4–49
4–50
4–51
4–54
4–55
4–39
4–39
4–40
4–40
4–41
4–42
4–44
4–45
4–34
4–35
4–35
4–36
4–36
4–37
4–37
4–37
4–38
4–38
5–2
5–13
5–22
5–32
5–43
5–47 v
6 Using the Portable API
6.1
6.2
6.3
6.4
6.5
6.6
6.7
6.8
6.9
Using the Forms_Record_Data Structure . . . . . . . . . . . . . . . . . . .
Using the Forms_Request_Options Structure . . . . . . . . . . . . . . .
Using Disk-Based Forms or Linked Forms . . . . . . . . . . . . . . . . .
Using Escape Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Error Message Routines . . . . . . . . . . . . . . . . . . . . . . . . . . .
Referencing Error Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C and FORTRAN Request Calling Description . . . . . . . . . . . . . .
ENABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RECEIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRANSCEIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CANCEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Structure Definitions for the C Interface . . . . . . . . . . . . . . . . . . .
Structure Definitions for the Portable API FORTRAN
Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A Elementary Conditions
B Receive Control Text Items
Index
Examples
2–1
2–2
2–3
2–4
2–5
2–6
Enabling a Form from the Advanced FORTRAN Sample
Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RECEIVE Request from the Advanced FORTRAN Sample
Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SEND Request from the Advanced FORTRAN Sample
Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRANSCEIVE Request from the Advanced FORTRAN
Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISABLE Request from the Advanced FORTRAN Sample
Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CANCEL Request from the Advanced FORTRAN Sample
Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6–2
6–5
6–9
6–10
6–11
6–11
6–15
6–16
6–22
6–24
6–29
6–33
6–36
6–38
6–48
2–4
2–7
2–11
2–15
2–18
2–19 vi
Figures
1–1
2–1
2–2
4–1
4–2
2–7
2–8
2–9
2–10
3–1
Tables
4–1
4–2
4–3
5–1
5–2
5–3
5–4
5–5
6–1
6–2
6–3
1
1–1
2–1
2–2
3–1
3–2
3–3
3–4
Portable API C Program that Uses Tracing . . . . . . . . . . . . . .
Using Tracing with the FORMS$ENABLE Call . . . . . . . . . .
Sample DCL Command Procedure Invoking the Trace
Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Event Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample Frequency Report Using Oracle Trace Software . . . .
2–33
2–35
2–39
2–40
3–9
Run-Time Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Control Transfer to a Directly Linked Escape Routine . . . . . .
Control Transfer to an Escape Routine in a Shareable
Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Function of the Form Manager During Data Distribution . . .
Function of the Form Manager During Data Collection . . . . .
1–5
2–24
2–27
4–17
4–53
Conventions Used in This Guide . . . . . . . . . . . . . . . . . . . . . .
DECforms Request Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Request Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Methods for Turning On the Trace Facility . . . . . . . . . . . . . .
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Events and Items Available in the ALL Class . . . . . . . . . . . .
Oracle Trace Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FORMNAME, SESSION, and TERMINAL Values . . . . . . . . .
Default Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Form Manager Message Codes . . . . . . . . . . . . . . . . . . . . . . . .
FORMS$ENABLE Request Options . . . . . . . . . . . . . . . . . . . .
FORMS$DISABLE Request Options . . . . . . . . . . . . . . . . . . .
FORMS$SEND Request Options . . . . . . . . . . . . . . . . . . . . . .
FORMS$RECEIVE Request Options . . . . . . . . . . . . . . . . . . .
FORMS$CANCEL Request Options . . . . . . . . . . . . . . . . . . . .
Portable API Routine Parameters . . . . . . . . . . . . . . . . . . . . .
Forms_Record_Data Elements . . . . . . . . . . . . . . . . . . . . . . . .
Request Options for the Portable API . . . . . . . . . . . . . . . . . .
4–12
4–19
4–27
5–8
5–17
5–27
5–37
5–48
6–1
6–2
6–6 xi
1–7
2–8
2–30
3–4
3–5
3–5
3–8 vii
viii
6–4
6–5
6–6
6–7
6–8
6–9
B–1
Error Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FORMS_ENABLE Request Options . . . . . . . . . . . . . . . . . . . .
FORMS_DISABLE Request Options . . . . . . . . . . . . . . . . . . .
FORMS_SEND Request Options . . . . . . . . . . . . . . . . . . . . . .
FORMS_RECEIVE Request Options . . . . . . . . . . . . . . . . . . .
FORMS_CANCEL Request Options . . . . . . . . . . . . . . . . . . . .
Receive Control Text Items . . . . . . . . . . . . . . . . . . . . . . . . . .
6–12
6–18
6–23
6–26
6–31
6–37
B–1
Preface
This guide contains information about the Form Manager, the run-time component of DECforms software. It describes how to develop application programs to use with the Form Manager, how applications call Form Manager requests, and how the Form Manager processes these requests.
Who Should Use This Guide
This manual is intended for application programmers and those interested in the operation of DECforms software at run time. You are expected to be familiar with a structured programming language, the Independent Form
Description Language (IFDL), and the structure of a form in DECforms software.
Structure of this Guide
This manual consists of the following chapters and appendixes:
Chapter 1
Chapter 2
Chapter 3
Chapter 4
Chapter 5
Chapter 6
Appendix A
Appendix B
Gives an overview of run-time processing.
Gives examples of calling requests from an application program, and explains how to use escape routines and the Form Manager Trace
Utility.
Describes how to use Oracle Trace software with DECforms applications.
Describes how the Form Manager processes external requests.
Describes the syntax of each of the OpenVMS external request calls and arguments.
Describes the portable application programming interface for C and
FORTRAN and how to use each of the external request calls.
Describes the state that causes each of the elementary conditions to be true.
Describes the receive control text items that the Form Manager can return.
ix
x
For More Information
See the online help, the online release notes, or the following documents for more information about DECforms:
• HP DECforms Installation Guide for OpenVMS Systems—Describes how to install DECforms software on VAX and Alpha processors that are running the OpenVMS operating system.
• HP DECforms Guide to Commands and Utilities—Describes the DECforms
forms
commands and utilities.
• HP DECforms IFDL Reference Manual—Describes the DECforms syntax information of the Independent Form Description Language (IFDL).
• HP DECforms Guide to Developing an Application—Part I explains for the beginning DECforms programmer how to create a DECforms application, including both the form and the program. Part II contains additional guidelines and examples for more experienced DECforms programmers.
• HP DECforms Guide to Demonstration Forms and Applications—
Describes how to use various demonstration forms and applications.
This guide is contained in online files named
forms$demo_guide.txt
forms$demo_guide.ps
in the FORMS$EXAMPLES directory.
and
If you cannot find this document, ask your system manager to install it in the appropriate directory.
For information about displaying these forms, see the appendix section of the HP DECforms Guide to Developing an Application.
• HP DECforms Style Guide for Character-Cell Devices—Describes how to develop user interfaces with a Motif style for DECforms applications for character-cell terminals.
• HP DECforms Guide to Converting FMS Applications—Describes how to convert a VAX FMS or DEC FMS application to a DECforms application.
Also of interest to users of DECforms software is the CODASYL Form Interface
Management System Journal of Development (see the Acknowledgment section).
Reader’s Comments
HP welcomes your comments on this manual or any of the DECforms. Please send comments to either of the following addresses:
Internet
Mail [email protected]
Hewlett-Packard Company
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698
How To Order Additional Documentation
For information about how to order additional documentation and for online versions of most DECforms, visit the following World Wide Web address: http://www.hp.com/go/openvms/doc/
Conventions
Table 1 describes the conventions used in this guide:
Table 1 Conventions Used in This Guide
Symbol or Term Meaning
Ctrl/X
KPn
PF1-X
In procedures, a sequence such as Ctrl/X indicates that you must hold down the key labeled Ctrl while you press another key.
Key names that begin with KP indicate keys on the numeric keypad on the right side of the terminal keyboard. For example, KP4 and KPperiod are keys on the numeric keypad.
A sequence such as PF1-X indicates that you must first press and release the key labeled PF1, and then press and release another key.
(continued on next page) xi
Table 1 (Cont.) Conventions Used in This Guide
Symbol or Term Meaning
. . .
In examples, a horizontal ellipsis indicates one of the following possibilities:
• Additional optional arguments in a statement have been omitted.
• The preceding item or items can be repeated one or more times.
• Additional parameters, values, or other information can be entered.
( )
[ ]
{}
$
$
.
.
.
user input
DECforms
A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
In format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses.
In format descriptions, brackets indicate that whatever is enclosed is optional; you can select none, one, or all of the choices.
In format descriptions, braces surround a required choice of options; you must choose one of the options listed.
User input is shown in bold.
The default user prompt is your system name followed by a right angle bracket (>). The dollar sign is used to indicate the DCL prompt on
OpenVMS systems.
References to DECforms throughout this manual refer to HP DECforms software.
Acknowledgment
DECforms is the HP implementation of a Form Interface Management System
(FIMS) ANSI/ISO standard prepared by the CODASYL Form Interface
Management System Committee and ISO/IEC JTC1/SC22 Working Group 18.
The FIMS standard is documented in ISO IS 11730:1994 and can be purchased from the International Organization for Standardization or the American
National Standards Institute.
xii
1
Introduction to Run-Time Processing
A DECforms application has the following components:
• The application program, which contains the data processing algorithms.
• The form, which contains the description of how to display information on the display device and what information to collect from the terminal operator.
• The display device, which displays information and optionally sends input from the operator to the form and program. The display device is not a component of the application; its declaration is a component of the form.
DECforms software supports character-cell (VT) devices, and print output.
For more information about device support, see Section 1.1.
• The Form Manager, which controls run-time processing in DECforms software.
The Form Manager displays information on the display device; accepts input from the terminal operator; and controls communication between the application program, the form, and the display device.
This chapter describes the use and operation of the Form Manager by introducing the following topics:
• Overview of DECforms device support
• How the Form Manager controls run-time communication
• How you can transfer data between the form and the application program
• How you control certain aspects of run-time processing
• How the Form Manager uses the activation list
Introduction to Run-Time Processing 1–1
1.1 Overview of DECforms Device Support
DECforms contains support for character-cell (VT) devices, and print output.
Print output is in DDIF (Digital Document Interchange Format
1
).
1.1.1 Support for Character-Cell Terminals
Character-cell devices include VT devices such as the VT100- through VT500series terminals, and terminal emulators that correctly emulate those VT terminals. DECforms supports these character-cell devices through the definition of viewports, panels, and responses in IFDL layouts having a device type of %VT100, %VT200, %VT300, %VT400, or %VT500. If you specify
%VT100, you can run the layout on all VT devices.
Character-cell layouts support both input and output operations. They allow applications to display panels and data on the display device and also allow the user to enter and modify data through a keyboard. You can specify particular user-defined actions in the character-cell layout for individual function keys on the keyboard.
To choose a character-cell layout as the user interface, the application must pass the device name of a character-cell device as the enable device parameter in the Forms Enable request. Often this name is SYS$INPUT, or
SYS$OUTPUT. When the Form Manager must use a character-cell layout, it selects the layout in the form that best matches the characteristics of the specified device. This layout has a device type of %VTxxx and most closely matches the VT layout according to the type, width, height, and color capabilities of the device.
Character-cell layouts support viewports, panels, panel groups, icons, picture fields, text fields, text literals, polylines, and point literals.
A set of default function responses is defined by the Form Manager for the keyboard function keys. If you choose, you can override these definitions.
User input is validated against the field’s input picture as each character is typed.
Character-cell layouts and their contents can be created and modified by the
Form Development Environment and Panel Editor. Only on Alpha, Migration utilities can be used to aid the conversion of FMS form files to DECforms IFDL form files.
1
DDIF is the standard document format used by CDA, a component of HP Network
Application Support (NAS) architecture that defines standards for compound documents and enables file interchange among all compliant applications.
1–2 Introduction to Run-Time Processing
1.1.2 Support for PRINTER Devices
DECforms supports PRINTER devices through the definition of viewports, panels, and responses in IFDL layouts having a device type of %PRINTER.
The primary use of PRINTER layouts is to generate high quality printable output.
The PRINTER device means an output file in DDIF format. You can convert a DDIF document you produced in DECforms to PostScript® format and print it on a PostScript printer. (To convert the file format, you must have the CDA converters supplied with DECwindows on your system.)
An application program depicts panels with the DISPLAY response step. This display does not actually appear on the terminal or workstation display device when you use a PRINTER layout. The DISPLAY response step instead creates output representing these panels. An application might print a set of invoice or purchase orders by using a PRINTER layout, or an application might simply generate a high-quality, fixed-format printable report by using this feature.
To use a %PRINTER device and choose a PRINTER layout, you must pass the file name as the enable device parameter in the ENABLE request. This layout must have a device type of %PRINTER.
To choose between multiple PRINTER layouts, you can specify an optional selection label within the IFDL file. An application can pass a selection label to the Form Manager to choose a specific layout (the layout with the matching selection label). In the absence of a selection label, the Form Manager chooses the first DDIF layout found. PRINTER layouts cannot be shared with VT layouts.
PRINTER layouts support viewports, panels, panel groups, picture fields, text fields, text literals, polylines, and point literals.
Function keys and function responses can be defined in a PRINTER layout, but are ignored at run-time. Because there is no operator interaction with a
PRINTER layout, all such actions are ignored. However, the Form Manager processes a small subset of response steps (DISPLAY, LET, IF/THEN/ELSE...) in the external request processing phase.
You can create and modify PRINTER layouts by using any Editor.
If your form defines a PRINTER layout, you can create output representing the layout’s panels and panel contents that is suitable for PostScript printing as follows:
Introduction to Run-Time Processing 1–3
1. In the application program, create an ENABLE request that passes the standard arguments:
• Session identification—The session identification string created by the
Form Manager
• Device Name—The name of the display device to be used
For DDIF printing, supply a file name (for example, document_name.doc).
If you are using the DECforms portable Application Programming
Interface (API), this argument is not required. (You can control the display device by using the FORMS$DEFAULT_DEVICE logical name; see step 2.)
• Form File—The name of the form file
• Form Name—The name of the form
• ENABLE request options—Any request options
2. In the form, use external response declarations, such as ENABLE and
SEND, to display each panel to be output, with its application data.
If you do not specify the display device in the ENABLE request, the operator must define a logical name at the system prompt before running the application by using the following command format:
$ DEFINE FORMS$DEFAULT_DEVICE document_name.doc
When the operator runs the application, DECforms creates a file in the format
document_name.doc in the current directory.
The HP DECforms Guide to Developing an Application provides an example of how to support quality printing in an IFDL form and in an application program.
1.1.3 Adding PRINTER Layouts Support to Character-Cell Applications
Adding PRINTER layouts to your application may require you to redesign part of your application. Because PRINTER layout devices are output-only, there is no operator input of data. Therefore, you may choose to define a different set of
DECforms requests, or possibly a different application, that interacts with the
PRINTER layout to produce high quality output. You can create and design the contents of PRINTER layouts by using any Editor.
1–4 Introduction to Run-Time Processing
1.2 Initiating and Controlling Run-Time Communication
During run time, the form, the display device, and the application program send data to and receive data from one another. The Form Manager controls this communication.
Figure 1–1 illustrates these interactions.
Figure 1–1 Run-Time Interaction
Form
Form Records
Application
Program
Form Data
Layout
Panel and
Panel Fields
Display Device
ZK−7896−GE
When the Form Manager initiates run-time processing, it loads a form, which is a data structure that controls a user interface to the application program.
The form is specified as an argument to an ENABLE call and describes the data transfer and all the screen interactions that occur.
You have the following options for the location of forms at run-time:
Application Programming Interface (API) Form Options at Run-time
OpenVMS API
Portable API
Binary (disk-based) file
Object-based (linked) form
Shareable image file
Binary (disk-based) file
Object-based (linked) form
Once the form is loaded, a layout is selected. The layout is the appearance of the form on the display device and is defined within the form. After the layout is selected, the Form Manager creates a session, which is an interaction between the application program and the form that begins when the form is enabled.
Introduction to Run-Time Processing 1–5
Next, the display device is attached to the session, and the form data is initialized. Form data is a set of variables that are associated with a form and a session. Once the form data is initialized, it can be moved between the form, display device, and application program.
The following steps occur during the transfer of data between the form, display device, and application program:
1. The application program sends a request to the Form Manager using a subroutine call. The request contains information specifying the type of request, the name of a record, and points to an area of memory that contains record data.
2. When the request reaches the Form Manager, the data portion of the request exists as a form record. A form record is a structure that controls data transfer between the program and the form. The form record describes the structure of the record data. The Form Manager interprets the form record, which tells the Form Manager in what form data items to store the data received from the application program. Form records do not store form data or application program record data.
3. The Form Manager stores the data that it received from the application program in the appropriate form data items.
4. The Form Manager displays a panel on the operator display device. Panel fields on the panel display form data items. The Form Manager formats the panel and the data according to instructions that it read from the form before displaying the panel.
5. The Form Manager accepts operator input from the keyboard of the display device. The keyboard is used to enter data characters and functions. The
Form Manager has a predefined set of functions that control operator interaction with the form.
The form designer can modify these functions for a form definition. The
Form Manager executes each function response and performs its actions when the function is entered by the operator. Instructions from the form tell the Form Manager in which form data items to store the data that it received from the display device.
6. The Form Manager stores the data that it received from the display device in the appropriate form data items.
7. The Form Manager returns data to the application program. DECforms stores the data in the area of memory pointed to by the request. The
Form Manager uses the data structure defined by the form record. The application program receives a request from the Form Manager.
1–6 Introduction to Run-Time Processing
1.3 Transferring Data Between the Application and the Form
The external interface to the Form Manager consists of six function routines, which are called requests. Requests are used to enable forms, disable forms, transfer data between the form and the application program, or cancel outstanding requests.
When you enable a form, you establish an association between a form and a display device called a session. You also create an instance of the form data declared in the form. When this session is established, the Form Manager assigns a unique identifier to the session called the session-id that allows the
Form Manager and the application program to identify the session.
When you disable a form, the Form Manager discards the association between the form and the display device, and the session-id that identifies the session.
The Form Manager must enable a form before it can transfer data to or from that form. The Form Manager must disable a form before it can end the processing of an application.
You cause the Form Manager to transfer data by calling one of six requests.
The request you call depends on which type of data transfer you want the
Form Manager to perform.
Table 1–1 describes the function of each request:
Table 1–1 DECforms Request Calls
Request Function/Transfer Type
ENABLE
DISABLE
SEND
RECEIVE
TRANSCEIVE
CANCEL
Enables a form.
Disables a form.
Sends data from the application program to the form.
Sends data from the form to the application program.
Combines the actions of a SEND and a RECEIVE in a single request.
Asynchronously stops all previously issued and currently active requests for a given session.
To call a request, write a routine call in your application program. You control what data is passed between the form and the application program by passing arguments in the routine call. For information on how to use routine calls in an application program, see Chapter 2.
Introduction to Run-Time Processing 1–7
When you use the OpenVMS API, DECforms requests will return an OpenVMS condition value to your application program. The condition value is an unsigned longword in which the low-order bit signifies success or failure of the request. The Form Manager returns this condition value to the return status variable in the application program.
When you use the portable API, the value returned is one of the FIMS status values defined in Table 6–4. In either the OpenVMS or portable API, the value indicates the most severe error that the Form Manager encountered while processing a request.
Requests can also return status to your application program by means of
control text. Control text consists of special text codes that the Form
Manager can issue when significant events occur during request processing.
For more information about the format and return values of requests, see
Chapter 5. For more information about receive control text descriptions, see
Appendix B.
1.4 Using Responses to Control Run-Time Processing
The Form Manager responds to a request call by performing a set of predefined actions. For example, each time you call a request, the Form Manager verifies that the arguments in the call are valid. (For more information on these predefined actions, see Chapter 4.)
To control Form Manager processing, you define responses in your IFDL source file. In a response, you list a number of instructions to the Form
Manager called response steps.
These response steps are actions that allow you to control the display of fields, icons, and panels, and change the order of form processing. When you process a request, you can also use response steps to call subroutines (escape routines), define help processing, reset the value of form data, and signal the operator.
(Section 4.3.3 describes the effect of each response step.)
You can define one or more responses for each of the requests. There is no response processing in a cancel request.
The responses correspond to the requests as follows:
1–8 Introduction to Run-Time Processing
Response
ENABLE RESPONSE
DISABLE RESPONSE
SEND RESPONSE
RECEIVE RESPONSE
TRANSCEIVE RESPONSE
Request
ENABLE
DISABLE
SEND
RECEIVE
TRANSCEIVE
For more information on defining responses in your IFDL source file, see the
HP DECforms IFDL Reference Manual.
1.5 Using the Activation List
During the processing of most requests, the Form Manager solicits input from the display device. The Form Manager asks for input from the operator by allowing the operator to enter data into a particular field or panel on the display device. The form controls video attributes that can indicate to the operator which field or panel needs input.
When a field, panel, or icon is available for input, it is said to be active or
activated. An item becomes activated when the Form Manager performs an
ACTIVATE response step. More than one field, panel, or icon can be active at a given time; however, the operator can enter input only into the current active field, panel, or icon.
The Form Manager tracks the current active items by maintaining an ordered internal list called the activation list. At the start of a request the activation list is empty. Each item on the activation list is called an activation item. The activation item into which the operator is currently entering input is called the
current activation item.
For purposes of discussion, activation items can be divided into four groups.
The activation item groups determine what the activation item is associated with and what input the operator must enter to satisfy an activation item.
The four types of activation items are as follows:
• Field activation items are associated with panel fields (picture fields, text fields, and slider fields). The operator enters data and functions to satisfy a field activation item.
• Icon activation items (on character-cell layouts only) are associated with icons. An icon is an element, much like a panel field, that can contain graphics or text, but does not have associated form data items. The operator can only enter functions to satisfy an icon activation item.
Introduction to Run-Time Processing 1–9
• Wait activation items are associated with a panel or with the layout for the currently enabled form. The operator can only enter functions to satisfy a wait activation item.
Response steps, specified within responses, allow you to customize form processing. Responses are the actions that the Form Manager takes when a request is received. For example, when the Form Manager receives a request to enable a form, it executes the ENABLE RESPONSE. You then specify response steps within the ENABLE RESPONSE. For a complete description of response steps, see Chapter 4.
To complete the processing of an activation item, the Form Manager typically performs a function response that contains a POSITION response step. A function response is an action that occurs when an operator enters a function during input (for example, Next Screen or Tab).
The POSITION response steps in the function responses control the order of activation item processing and operator input. The POSITION response step specifies an activation item where the Form Manager should position next. For example, a typical POSITION response step is POSITION TO NEXT ITEM.
This response step causes the Form Manager to begin accepting input for the next activation item on the activation list.
DECforms function responses can be one of two types: built-in or user-defined.
The built-in function responses are predefined by the DECforms software, and provide many standard intrafield editing capabilities, such as:
• Cursor movement
• Field erasure
• Moving to the next or previous field or panel
• Character deletion
The built-in function responses are bound by default to specific keys with
FUNCTION declarations. The keys vary depending on the display device you are using. For more information on built-in functions and field editing, see the
HP DECforms IFDL Reference Manual.
If the function response is not built-in, you specify the function response and associate it with a key or key sequence by using a FUNCTION declaration in your IFDL file.
You create user-defined functions in your form. For examples of user-defined functions, see the HP DECforms Guide to Developing an Application.
1–10 Introduction to Run-Time Processing
A RETURN response step specifies that accept phase (the time when operator input is allowed) should end. You typically terminate operator input by specifying a RETURN response step within a function response.
The following is an example of how the Form Manager controls operator input:
1. The Form Manager encounters an ACTIVATE response step that corresponds to a panel field named FIELD_ONE. It adds an activation item for that field to the activation list.
2. The Form Manager encounters an ACTIVATE response step that corresponds to a panel field named FIELD_TWO. It adds an activation item for that field to the activation list.
3. Because FIELD_ONE is the first item on the activation list, the Form
Manager processes that activation item first when it begins to process the activation list.
4. The operator enters data into FIELD_ONE.
5. The operator uses the built-in NEXT ITEM function. (The built-in NEXT
ITEM function response contains the POSITION TO NEXT ITEM response step.) Input into FIELD_ONE is complete.
6. The Form Manager performs the response step by making FIELD_TWO the current activation item.
7. The operator enters data into FIELD_TWO.
8. The operator uses the TRANSMIT built-in function. (TRANSMIT contains a RETURN response step.)
9. The Form Manager performs the response step by validating FIELD_ONE and FIELD_TWO, terminating accept phase, and returning control to the application program.
For more information on the activation list and how the Form Manager processes each activation item, see Section 4.4.
Introduction to Run-Time Processing 1–11
2
Developing the Application Program
This chapter explains how to call DECforms requests. It also explains compiling, linking, and running an application program and how to use escape routines and the Form Manager trace facility.
The application program performs calculations, file operations, and recordkeeping functions, and maintains the data being manipulated in the application (the data that the terminal operator sees and changes). To maintain the data, the application program must request that the Form
Manager send data to the form or send data from the form to the application program by calling a DECforms request.
Occasionally, the form may initiate a data exchange itself by calling an escape
routine. This process is called a procedural escape. A typical escape routine is a subroutine of the application program. The subroutine is called using a CALL response step. Data can be transferred between the form and the escape routine by means of arguments specified in the CALL response step.
Because of the complex run-time processing that occurs when a request or an escape routine is called, the Form Manager provides a trace facility. The trace facility records processing information that you can use to debug your application program and your form. The Form Manager also provides an event logging mechanism to trap any errors or unusual events during run time.
2.1 Using DECforms Requests
You call DECforms requests from an application program written in one of the programming languages that DECforms supports.
When you use the OpenVMS Application Programming Interface (API),
DECforms conforms to the OpenVMS Calling Standard and supports the following languages:
• ADA
• BASIC
• BLISS
Developing the Application Program 2–1
• C
• COBOL
• DIBOL
• FORTRAN
• Pascal
• PL/1
For more information about the OpenVMS API, see Chapter 5.
The portable API supports the C and FORTRAN binding on the OpenVMS operating system. It uses PASCAL calling conventions and FAR pointers. Any language that can construct argument lists that meet this standard can use this API. For more information about the portable API, see Chapter 6.
When you use a request in an application program, you must format the request as you would any other function call written in the programming language that you use. For example, in FORTRAN you should designate that an argument is omitted from a DECforms request by including a null entry in place of the argument.
This section explains how to use the requests from a FORTRAN application program. The examples are from the advanced FORTRAN sample application program, written using the portable API. This sample application maintains a checking account and a savings account. The program is located in the
FORMS$EXAMPLES directory, which is an option you can choose to install during the DECforms installation procedure.
To view this advanced sample application program, print the following file:
FORMS$EXAMPLES:FORMS$CHECKING_FORTRAN.FOR
Note
The portable API uses header files– formsdef.h (for C) and formsdef.f
(for FORTRAN).
These header files contain definitions of data types that DECforms requires. You need to declare data using the correct data types.
For example, the declaration for a form name called form_name in the
IFDL source form is as follows in the C application program:
Forms_Form_Object form_name;
2–2 Developing the Application Program
The form used for the advanced sample checking application is in
FORMS$EXAMPLES:FORMS$CHECKING_FORM.IFDL.
When the advanced application program is running, the operator can do the following:
• Write checks on the account.
• Deposit money into the account.
• Withdraw cash from the account.
• Transfer money from the checking account to the savings account.
• Transfer money from the savings account to the checking account.
• Review and change account information (for example, the address of the account’s owner).
• Review the history of transactions made on the account.
For more information about the sample programs, see the HP DECforms Guide
to Developing an Application.
2.1.1 Enabling Requests
Before the Form Manager can display information, accept input, or control communication, it must load a form into memory, select a layout, attach a display device, allocate an instance of form data, and create a sessionidentification string. Because the Form Manager performs these tasks during the processing of an ENABLE request, the first request that you call from your application program must be the ENABLE request.
If you are using multiple forms, you do not need to place all enable calls before any other request calls. You need to ensure only that the ENABLE request,
FORMS$ENABLE (OpenVMS API) or forms_enable (portable API), is the first request made for a given display device and form pair.
Example 2–1 contains a portion of the advanced FORTRAN sample application program written for the portable API that calls the ENABLE request.
Developing the Application Program 2–3
Example 2–1 Enabling a Form from the Advanced FORTRAN Sample
Program
IMPLICIT NONE
INCLUDE ’forms_checking_common.f’
INTEGER sample_checking_account
EXTERNAL sample_checking_account
C
C Define data and form file names
C
CHARACTER*200 form_file_name
CHARACTER*200 sample_data_name
1
C Option list. Used to pass special options to forms requests (calls)
RECORD /forms_request_options/ enable_request_options(3)
C Print startup message on console
PRINT *,
1 ’FORTRAN DECforms Sample Checking Account Application starting.’
C Build the data and form file names
CALL forms_checking_getdir( form_file_name, sample_data_name)
C Set up printing to go to the operator’s scratch directory. This involves
C passing a request_options parameter in the enable request.
enable_request_options(1).option = forms_c_opt_print enable_request_options(1).print_file_name = %LOC(print_file_name) enable_request_options(1).print_file_name_length = LEN(print_file_name) enable_request_options(2).option = forms_c_opt_form enable_request_options(2).form_object = %LOC(sample_checking_account) enable_request_options(3).option = forms_c_opt_end
C Initialize the DECforms form & check for errors
3
4
1
2
.
.
.
2
forms_status = forms_enable_for( session_id, device_name_string, form_file_name, form_name_string,
! session id string
! Device name
! Name of form file
! Name of form enable_request_options) ! Request options list
CALL check_forms_status( forms_status )
3
2–4 Developing the Application Program
1
2
3
The INCLUDE statement includes the forms_checking_common file. This file contains the declaration of common areas to be used in this application program.
The ENABLE request call passes the following arguments:
• session_id
Variable that contains the 16-character session-identification string created by the Form Manager. The session-identification string is returned to the application program in this argument upon completion of this ENABLE request.
• device_name_string
Display device to be used for this session.
• form_file_name
Name of the form file to be used for this session.
• form_name_string
Name of the form to be used for this session, as specified in the IFDL file.
• enable_request_options
A list specifying one or more request options used to control the request environment. For more information, see Chapter 6.
In response to this request, the Form Manager loads the form with the specified form file name into memory and selects a layout in the form that is appropriate for the device (if a layout exists). The Form Manager also attaches the display device. After the Form Manager attaches the display device, it creates a session-identification number that it stores in the session_id variable.
For more details on processing that the Form Manager performs for the
ENABLE request, see Chapter 4.
The CALL statement passes the value returned in the forms_status variable to a subroutine that verifies that the ENABLE request was completed. The check_forms_status subroutine specifies that an error message be displayed and that the application program stop executing if the forms_status variable contains a value indicating an error.
Developing the Application Program 2–5
Use the ENABLE request when you want to load a new form into memory, select a new layout, and attach a new display device. Each time that you call the ENABLE request, the Form Manager creates a new session, which is identified by a session-identification string. You can call the ENABLE request as often as you need to create new sessions.
The Form Manager creates a session-identification string for each session that you create. You must pass a session-identification string in all SEND,
RECEIVE, TRANSCEIVE, DISABLE, and CANCEL requests to tell the Form
Manager which session to use while processing the request. Even if you create only one session, you must pass a session-identification string. Sessions are independent of one another; the only way to pass information between sessions is through the application program.
For more information on the ENABLE request and its arguments, see
Chapter 5 and Chapter 6.
2.1.2 Moving Data from a Form to a Program
Use the RECEIVE request to retrieve data stored in form data items and move the data into the record fields of an application program record.
Records defined in your application program control how data is transferred to and from the program. You pass the application program record as a record message argument to a request call. The record message argument is a pointer to an area of memory that stores the fields in the application program record.
When the Form Manager transfers data to the application program during the processing of a request, it copies the data into the area of memory pointed to by the record message. These values are kept in the application program record until the program itself or the processing of another request changes them.
Example 2–2 contains a portion of a subroutine written for the portable API.
This subroutine gets new account information from the operator and moves that new information into the account record stored in the application program.
The new information is moved during the processing of the RECEIVE request.
2–6 Developing the Application Program
Example 2–2 RECEIVE Request from the Advanced FORTRAN Sample
Program
.
.
.
C Get new information for account record. If termination was quit,
C then the operator might have changed a few things that the quit is
C supposed to ignore, so send the original account record back to the
C form and return to menu processing.
.
.
.
record_data.data_length = account_size ! for pre-V5 FORTRAN
C-V5 -> record_data.data_length = SIZEOF(account_temp) ! for VAX FORTRAN V5 record_data.data_record = %LOC(account_temp) record_data.shadow_record = 0 record_data.shadow_length = 0
C Set up to receive control text back from the form request_options(1).option = forms_c_opt_receive_control request_options(1).receive_control_text_count= %LOC(receive_ctl_txt_ct) request_options(1).receive_control_text= %LOC(receive_ctl_txt_string) request_options(2).option = forms_c_opt_end
C Get the record from the form
1
2
3 forms_status = forms_receive_for( session_id,
’account’,
! session id
1
! form record record_data, ! info from the form request_options) ! request option list
CALL check_forms_status( forms_status )
2
.
.
.
1
This statement calls the RECEIVE request. Table 2–1 explains the arguments passed in this request.
Developing the Application Program 2–7
Table 2–1 Request Arguments
Argument Explanation
session_id
’account’ record_data request_options
Variable containing the session-identification string
(from an ENABLE request) that identifies the session to be used during this request.
Name of the form record that contains record fields corresponding to form data items in the form. Each form data item that the application program can receive data from must correspond to a field in the form record. This correspondence allows the form record name to indicate to the Form Manager which form data items from which to move data.
Information received from the form.
A list specifying one or more request options used to control the request environment. For more information, see Chapter 6.
2
The CALL statement calls a subroutine that determines whether the
RECEIVE request was completed. The check_forms_status subroutine specifies that an error message be displayed and that the application program stop executing if the forms_status variable contains a value that indicates an error.
To move the values from form data items to fields in the ACCOUNT application program record (because the form activates fields in the RECEIVE
RESPONSE), the Form Manager must solicit input from the operator. It does so by displaying the set of panel fields corresponding to the form data items associated with the data in the application program record.
The operator enters input to the panel fields, and the Form Manager stores that input in form data items. The Form Manager moves the values stored in the form data items to the fields in the application program record.
The application program record, the form record, the form data items, and the panel fields correspond as follows:
• The application program record is logically equivalent to the form record.
This means that the application program record has the same number of fields as the form record, and that each field in the application program record has the same data type, length, and dimension as the fields in the form record. Any alignment and padding requirements must be the same for both the application program record and the form record.
2–8 Developing the Application Program
• The names of fields in the form record usually correspond to the names of form data items. The form associates each form data item with its corresponding field name in the form record.
• The name of each form data item that requires operator input corresponds to the name of a panel field. The form declares each panel field that has the same name as a form data item that requires input.
This correspondence allows the Form Manager to determine which panel fields need input, which form data items store that input, and into which application program record fields it moves this input during the processing of a RECEIVE request.
This name correspondence is the most common way to specify the transfer of form data to form records, but it is not the only way to transfer information from the form to your program. Another way to specify data transfer is to use the DATA TRANSFER clause. For more information, see the HP DECforms
IFDL Reference Manual.
If errors occur during the processing of this RECEIVE request, the Form
Manager stores receive control text items in the variable for the receive_ control_text request option. For more information about receive control text, see Section 4.7.
Use the RECEIVE request when you need information from the form and, optionally, from the operator in your application program. Not all RECEIVE requests solicit input from the operator, but soliciting input from the operator is part of the default processing that the Form Manager performs for the
RECEIVE request. Section 4.3 describes the default processing.
The statements in the sample application program shown in Example 2–2 are part of a subroutine that is called when the operator chooses to look at and modify data stored in the account record. The account record is maintained in the application program.
This record stores the following data:
• Full name of the owner of the account
• Address of the owner of the account
• Account owner’s work and home telephone numbers
• Date that the account was established
• Password that the operator must enter to change data in the record
Developing the Application Program 2–9
Because the account record is maintained in the application program, the program must receive new values entered by the operator. Therefore, the program calls the RECEIVE request when the operator needs to enter new data into this record. This call ensures that the program receives the new data directly after it is entered.
As another example of using the RECEIVE request, suppose that the purpose of your application program is to maintain a database of employees who work in a particular department. In this application program, you include at least two RECEIVE requests:
• One RECEIVE request causes the Form Manager to solicit input from the operator and pass new information about employees whose records exist in the employee database. The statements before and after this RECEIVE request open an existing employee record and write the new information that was received from the form into that record. The application program then replaces the updated record in the database.
• The other RECEIVE request causes the Form Manager to solicit input from the operator and pass information about new employees who do not have a record in the employee database. The statements before and after this
RECEIVE request create the new employee record and write information about a new employee into that record. These statements create a place for that record and store the record in the database.
For more information on the RECEIVE request and its arguments, see
Chapter 5 and Chapter 6.
2.1.3 Sending Data from a Program to a Form
Use the SEND request to send data to the form. This request causes the Form
Manager to move data from an application program record to form data items.
Example 2–3 contains statements that update account information stored in the form using the SEND request. This example is written for the portable
API.
2–10 Developing the Application Program
Example 2–3 SEND Request from the Advanced FORTRAN Sample Program
C Update the balances, next check number, and room_in_reg flag in the form.
C If there’s no room for more entries in the register, then
C the room_in_reg flag is sent as zero(false), else true(all 1’s in Fortran).
IMPLICIT NONE
INCLUDE ’forms_checking_common.f’
RECORD /update/ update
1
update.checking_balance = checking_balance update.savings_balance = savings_balance update.check_number
update.room_in_reg
= last_check_num
2
= register.number_entries_used .LT. reg_size
C Initialize the descriptor with UPDATE info
.
.
.
record_data.data_length = update_size ! for pre-V5 FORTRAN
C-V5-> record_data.data_length = SIZEOF(update) ! for VAX FORTRAN V5 record_data.data_record = %LOC( update ) record_data.shadow_record = 0 record_data.shadow_length = 0
C Send the update record
1
2
3 forms_status = forms_send_for( session_id,
’update’,
! session id
3
! form record record_data, ! info sent to form
0 ) ! request options list
CALL check_forms_status( forms_status )
4
RETURN
END
1
2
3
The RECORD declaration names the
’ update
’ form record as a data structure.
The assignment statements assign values to fields in the
’ update
’ form record. The values that are assigned to these fields were determined in another part of this program. To see the subroutine that determines the contents of these variables, refer to the full listing of this application program. See Section 2.1 for the location of the advanced sample program.
This statement calls the SEND request. The following list explains the arguments that are unique to this request. For explanations of the others, refer to Table 2–1.
•
’ update
’
Developing the Application Program 2–11
The name of the form record that controls where the data passed in the
SEND request is stored. The data is stored in the form data items that are named the same as the fields of the update form record.
• record_data
The information that is sent to the form.
In response to this request call, the Form Manager updates the values of the form data items associated with the field’s
’ update
’ record. It performs this update by moving the contents of the following record fields into the following form data items:
Record Fields
update.checking_balance
update.savings_balance
update.check_number
update.room_in_reg
Form Data Items
checking_balance savings_balance last_check_num register.number_entries_used
Note that the associated form record fields and form data items do not have to have the same names.
For more information on the description of the DATA TRANSFER clause, see HP DECforms IFDL Reference Manual. For more information on how the Form Manager processes SEND requests, see Chapter 4.
4
The CALL statement calls a subroutine that determines if the SEND request was completed. The check_forms_status subroutine specifies that an error message be displayed and that the application program stop executing if the forms_status variable contains a value that indicates an error.
Use the SEND request when your application program needs to change the values stored in form data items. The statements in Example 2–3 are used in a subroutine in the sample application program. This subroutine is called from other subroutines in the sample application program when the operator changes the account balance.
For example, assume that the application program had previously called a RECEIVE request. During the processing of the RECEIVE request, the operator writes a check on the account, and the amount of that check and the check number are returned to the application program. The application program then calculates a new account balance, assigns a new value to the highest check number, and verifies that the history register it maintains has room for more transactions.
2–12 Developing the Application Program
If the history record has room to store the history record of more transactions, the application program sets the variable room_in_reg to 1. If the history record is full, the application program sets the room_in_reg variable to 0, and the operator cannot enter any more transactions on the account. (In this sample application program, the history record is limited to storing information about 30 transactions. Normally, the history record would not be limited in this way.)
Once the application program has performed these tasks, it calls the subroutine shown in Example 2–3. The SEND request passes the new balance, the highest check number, and the room_in_reg value to the form data items that store them. The contents of these form data items control what transactions the operator can perform. Therefore, it is important that these form data items be updated promptly after each operator action that modifies the account. If this is not done, the operator might be able to write a check for more than the current account balance.
As another example, suppose that the purpose of your application program is to calculate subtotal and total amounts for an invoice. Once these amounts have been calculated, you use the SEND request to pass the subtotal and total to form data items, which are then displayed on a panel. In this type of application program, using the SEND request immediately after the subtotal and total amounts are calculated ensures that incorrect values are not inadvertently displayed on the display device.
For more information on the SEND request and its arguments, see Chapter 5 and Chapter 6.
2.1.4 Asynchronous SEND Requests
In general, DECforms requests cannot be made from asynchronous system trap
(AST) routines because much of DECforms request processing occurs at AST level, and normal request processing is synchronous with respect to the caller.
Form Manager requests from AST level might produce deadlock situations within the process running a DECforms application.
However, it is often useful to communicate with a form from an AST routine.
For example, an application might have a timer AST routine fire periodically to display time-critical data on the screen. DECforms software provides a mechanism by which the SEND request can be used at AST level to send information to the form. Specifically, when an AST routine issues a SEND request, the request executes asynchronously with respect to the calling routine. In addition, only a severely restricted subset of request processing is performed.
Developing the Application Program 2–13
The asynchronous SEND requests perform only the data distribution phase of request processing and then the request is terminated. If the data being sent to the form is currently displayed on a panel, the panel fields are updated normally with the new values. However, because no response processing or accept phase processing is performed, the panel must be displayed by a previous synchronous request.
Because SEND requests at AST level execute asynchronously with respect to the AST routine, the programmer must take care to provide proper synchronization at request completion. DECforms can provide AST notification of request completion, using the FORMS$K_ASTADR and
FORMS$K_ASTPRM item codes in the request-options item list argument in the OpenVMS API.
Hewlett-Packard Company strongly recommends that you use this feature when using asynchronous SEND requests. For more information on the
FORMS$K_ASTADR and FORMS$K_ASTPRM item codes, see Chapter 5. For more information about setting up AST routines, see the OpenVMS System
Services manual.
In the portable API, the FORMS$K_ASTADR and FORMS$K_ASTPRM item codes are referred to as completion routines. You can set up the mechanism by using the completion routine structure in the request option definition.
For examples of using asynchronous send requests, see the following:
FORMS$EXAMPLES:FORMS$DEMO_TIMER.EXE
FORMS$EXAMPLES:FORMS$DEMO_TIMER_AST.COB
FORMS$EXAMPLES:FORMS$DEMO_TIMER_AST_ROUTINE.COB
FORMS$EXAMPLES:FORMS$DEMO_TIMER_CHECK_STATUS.COB
FORMS$EXAMPLES:FORMS$DEMO_TIMER_COMP_ROUTINE.COB
FORMS$EXAMPLES:FORMS$DEMO_TIMER_FORM.IFDL
FORMS$EXAMPLES:FORMS$DEMO_TIMER_SET_TIMER.COB
2.1.5 Transceiving Data
Use the TRANSCEIVE request to send data to the form from the application program and to receive data from the form in the application program.
Example 2–4 contains an example of using the TRANSCEIVE request in the portable API. For this TRANSCEIVE request, the application program is sending and receiving two fields in register_record.
2–14 Developing the Application Program
Example 2–4 TRANSCEIVE Request from the Advanced FORTRAN Sample
Program
C
IMPLICIT NONE
INCLUDE ’forms_checking_common.f’
C Option list. Used to pass special options to forms requests (calls)
RECORD /forms_request_options/ request_options(2)
C Initialize the descriptor with REGISTER info
.
.
.
record_data.data_length = register_record_size ! for pre-V5 FORTRAN
1
C-V5-> record_data.data_length = SIZEOF(register) ! for VAX FORTRAN V5 record_data.data_record = %LOC(register) record_data.shadow_record = 0 record_data.shadow_length = 0
C Set up to receive control text back from the form request_options(1).option = forms_c_opt_receive_control request_options(1).receive_control_text_count=%LOC(receive_ctl_txt_ct) request_options(1).receive_control_text=%LOC(receive_ctl_txt_string) request_options(2).option = forms_c_opt_end
C Transceive the record (send it and ask to get it back)
3
4
1
2
5
CALL check_forms_status( forms_status )
END forms_status = forms_transceive_for(session_id, ! session id
’register_record’, ! send record name
2
record_data, ! the send record
’register_record’, ! Receive record name record_data, ! the recv record request_options) ! request options list
3
1
The values for the size and location of the register record are stored in the record named register_record in a different subroutine in this program.
Developing the Application Program 2–15
2
The next statement calls the TRANSCEIVE request. The following table explains the arguments passed in this request.
Argument
session_id
’register_record’ record_data
’register_record’ record_data request_options
Explanation
Variable containing the session-identification string (from an ENABLE request) that identifies the session to be used during this request.
Name of the form record that controls where the data passed in this request is stored. The data is stored in the form data items that have the same names as the fields of the register_record form record.
Send record.
Name of the form record that controls where data is to be returned to the application program.
Receive record.
A list specifying one or more request options used to control the request environment. For more information, see Chapter 6.
3
In response to the TRANSCEIVE request, the Form Manager sends the value for register_record to the form by moving the data in the register_ record application program record fields into the register_record form data items.
The Form Manager then solicits input from the operator and returns that input to the application program. The Form Manager solicits input into panel fields that correspond to the register_record form data items.
The Form Manager stores the input in these form data items and moves the new values in the form data items to the register_record application program record fields.
The send-record and the receive-record parameter descriptors can refer to different records; you can send data to one record stored in the form, and receive data from a different record stored in the form.
For more information on Form Manager processing of the TRANSCEIVE request, see Chapter 4.
The CALL statement calls a subroutine that determines whether the
TRANSCEIVE request was completed. The check_forms_status subroutine specifies that an error message be displayed and that the application
2–16 Developing the Application Program
program stop executing if forms_status contains a value that indicates an error.
Note
The subroutine shown in this example is a simplified version of a subroutine that transceives a record contained in the sample application program. For information on how the TRANSCEIVE request is actually used in the sample application program, see the documentation of the sample applications in the HP DECforms Guide
to Developing an Application.
Use the TRANSCEIVE request any time information you send to the form could generate new information that you need in your application program.
For example, suppose your application program calculates and stores the values needed to create a balance sheet from your accounting records. This program might contain a TRANSCEIVE request within a loop.
In the TRANSCEIVE request, you send the numbers that were calculated in the application program to the form. These numbers are then displayed on the display device in a completed balance sheet. The operator looks at the balance sheet to see whether it is correct.
If the balance sheet is correct, the operator enters a value in a field that indicates the balance sheet is complete. When this occurs, the Form Manager returns the same values to the application program that it just received from the application program. These values are stored for future reference.
However, if the balance sheet is incorrect, the operator enters a value in a field that indicates the balance sheet is incorrect. The Form Manager then asks the operator for input into each field that affects the totals on the balance sheet.
Once the operator has entered all the changed information, the new data is returned to the application program. The application program recalculates the amounts to be displayed in the balance sheet and returns them to the display by calling the TRANSCEIVE request again. This process continues until the balance sheet is correct.
For more information on the TRANSCEIVE request and its arguments, see
Chapter 5 and Chapter 6.
Developing the Application Program 2–17
2.1.6 Disabling Requests
Call the DISABLE request to terminate the session.
Example 2–5 contains part of a FORTRAN application program that calls the
DISABLE request.
Example 2–5 DISABLE Request from the Advanced FORTRAN Sample
Program
C Clean up, Print ending message on console, leave.
IMPLICIT NONE
INTEGER status
INCLUDE ’forms_checking_common.f’ forms_status = forms_disable_for( session_id , 0 )
1
PRINT *, ’FORTRAN DECforms Sample Checking Account Application ending.’
STOP
END
1
The application program calls the DISABLE request to detach the display device and unload the form. The session_id argument passed in this request tells the Form Manager which display device to detach and which form to unload. The 0 parameter indicates that there are no request options.
For more information on Form Manager processing of the DISABLE request, see Chapter 4.
2.1.7 Canceling Requests
In some situations, you may want to cancel the processing of the current
DECforms requests immediately. Use the CANCEL request to stop processing of the current request.
Example 2–6 contains part of a FORTRAN application program that calls the
CANCEL request.
2–18 Developing the Application Program
Example 2–6 CANCEL Request from the Advanced FORTRAN Sample
Program
forms_status = forms_cancel_for( session_id,0)
1
CALL check_forms_status( forms_status )
2
END
1
2
The application program calls the CANCEL request to cancel the active
DECforms request. The session_id argument passed in this request tells the Form Manager for which session to cancel the request.
Once the request processing is complete, the application program passes the value returned in the forms_status variable to the check_forms_status subroutine. This subroutine specifies that an error message be displayed and that the application program stop executing if forms_status contains a value that indicates an error.
For more information on Form Manager processing of the CANCEL request, see Chapter 4.
2.2 Compiling, Linking, and Running the Application
Once you have written your application program, you can compile, link, and run it. For all the following examples, references to the sample program demonstrate commands using the OpenVMS API, and references to the checking program demonstrate commands using the portable API.
2.2.1 Compiling an Application
To compile your application program in the OpenVMS or portable API, enter the command that invokes the compiler for your programming language. For example, to compile the FORTRAN sample application programs, enter one of the following FORTRAN commands:
$ FORTRAN FORMS$SAMPLE_PROGRAM_FORTRAN (OpenVMS API)
$ FORTRAN FORMS$CHECKING_FORTRAN (portable API)
The command in this example creates an object file that can be input to the OpenVMS Linker. In this example, the object files are named
FORMS$SAMPLE_PROGRAM_FORTRAN.OBJ (OpenVMS API) and
FORMS$CHECKING_FORTRAN.OBJ (portable API). For information about the command that invokes your compiler, see the documentation for your programming language.
The FORTRAN compiler picks up the library file in your working directory, and the C compiler picks up the library file in SYS$INCLUDE.
Developing the Application Program 2–19
To compile the C sample application program in either the OpenVMS or portable API, enter either of the following C commands:
$ CC FORMS$SAMPLE_PROGRAM_C (OpenVMS API)
$ CC FORMS$CHECKING_C (portable API)
2.2.2 Linking an Application
After you compile your program, enter the LINK command to invoke the
OpenVMS Linker. On the command line, specify the file name of the object file that your compiler created. For example, to link the FORTRAN sample application program that uses the OpenVMS API, enter the following command:
$ LINK FORMS$SAMPLE_PROGRAM_FORTRAN
The command in this example creates an executable image that you can execute with the RUN command. In this example, the executable image is named FORMS$SAMPLE_PROGRAM_FORTRAN.EXE. For more information on the LINK command, see the OpenVMS Linker Reference Manual.
To link the advanced FORTRAN sample application program that uses the portable API, enter the following command:
$ LINK FORMS$CHECKING_FORTRAN.OBJ, SYS$INPUT/OPTION -
_$ SYS$SHARE:FORMS$PORTABLE_API/SHARE
Ctrl/Z
If you plan to link escape routines with your application program, you should link the escape routines, your application program, and the form object file on the same command line. Section 2.3 describes using escape routines.
All DECforms entry points for the new portable bindings are in the shareable image, SYS$SHARE:FORMS$PORTABLE_API.EXE. The DECforms run-time system remains in SYS$SHARE:FORMS$MANAGER.EXE.
When you use a linked form in the portable API, you must specify the
/PORTABLE_API qualifier in the FORMS EXTRACT OBJECT command to generate the global form name symbol in the form object.
To obtain the form object file for the OpenVMS API, enter the following command:
$ FORMS EXTRACT OBJECT FORMS$SAMPLE_FORM.FORM
To obtain the form object file for the portable API, enter the following command:
$ FORMS EXTRACT OBJECT /PORTABLE_API FORMS$CHECKING_FORM.FORM
2–20 Developing the Application Program
2.2.3 Running an Application
After you compile and link your application program, you can enter the RUN command to execute it. To execute the program, include the file name of the executable image that the Linker creates on the RUN command line. For example, to run the FORTRAN sample application program, enter one of the following commands:
$ RUN FORMS$SAMPLE_PROGRAM_FORTRAN (OpenVMS API)
$ RUN FORMS$CHECKING_FORTRAN (portable API)
For more information on the RUN command, see the OpenVMS DCL
Dictionary.
2.3 Writing and Calling Escape Routines
An escape routine is an application program subroutine that is called during the processing of a request. In an escape routine, you specify actions that you want performed during request processing. For example, you might write an escape routine that performs a database lookup or a file operation.
You can write an escape routine in any of the programming languages that
DECforms software supports. You can call a request from an escape routine.
However, you cannot call a DISABLE request that terminates the session from which the escape routine was called.
You must call escape routines from responses in your IFDL source file using the CALL response step. The arguments that you pass in the CALL response step name the escape routine and pass values that the escape routine needs.
When the Form Manager encounters the CALL response step, it finds and transfers control to the escape routine. For more information about the CALL response step, see Chapter 4.
If you want more than one application to have access to a set of escape routines, store the escape routines in a separate file. To access the escape routines from several applications, compile the escape routines and either link them in a shareable image (in the OpenVMS API only) or link them with your application program.
Section 2.3.4 describes the effect of storing escape routines in a shareable image. Section 2.3.1 and Section 2.3.2 describe linking escape routines with your application program. You can also store some escape routines in a shareable image and link others with your application program. Section 2.3.6
lists the steps you follow to do this.
Developing the Application Program 2–21
2.3.1 Creating a Form Object
To link an escape routine with your application program or to enable a linked form, you must create a form object. A form object contains a list of the escape routines that are called from the form file you are using. You create the form object using the Extract Object Utility.
To use the Extract Object Utility to create a form object, enter a command similar to the following. Use the /PORTABLE_API qualifier for portable API applications.
$ FORMS EXTRACT OBJECT filename.FORM /OUTPUT=form_obj
In this case, the resulting object file is named specify a destination object file using the /OUTPUT qualifier, the Extract
Object Utility creates a file with the same name as the input file name and a file type of
.obj.
form_obj.obj.
If you do not
For more information on the FORMS EXTRACT OBJECT command, see the HP DECforms Guide to Commands and Utilities.
The Extract Object Utility stores the names of all the escape routines that you call from your form in a form object module. You must link this object with your application program. When you link the form object, the Linker assigns addresses to those escape routines that are linked directly with your application program. If the Linker encounters the names of escape routines that are not linked directly with your application program, it assigns a value of zero to those names.
Note
DECforms does not support shareable images in the portable API bindings. As a result, all escape routines are expected to be linked into the main image. For more information about using linked forms in the portable API, see Section 6.3.
When the Form Manager prepares to transfer control to an escape routine, it searches for the name of the escape routine in FORMS$AR_FORM_TABLE. If the Form Manager finds an address assigned to the name, it transfers control to the subroutine that starts at that address. However, in the portable API, if the Form Manager finds a value of zero assigned in the table, DECforms returns an error indicating that it could not find the escape routine. In the
OpenVMS API, it attempts to activate a shareable image to find the escape routine.
2–22 Developing the Application Program
Once the Form Manager finds the escape routine, it transfers control to the first instruction in that escape routine.
Note
When an escape routine calls another form request on the same session, the built-in form data item PARENTREQUESTID must be passed to the escape routine and subsequently passed as a parameter to the forms request. Failing to pass PARENTREQUESTID as a parameter could result in a deadlock situation. Because multiple requests are active on the same session, the Form Manager does not schedule the request for execution of the second form request until the first request completes unless PARENTREQUESTID is passed for the second request.
By passing PARENTREQUESTID to the second request, the Form
Manager determines that the second request should be scheduled and allowed to execute before the first request completes.
An escape routine which calls another form request on a different session does not need to pass PARENTREQESTID as the two sessions are independent.
2.3.2 Linking Escape Routines Directly with an OpenVMS API Program
To link escape routines directly with your application program, enter the LINK command. For example, to link the FORTRAN sample application program and an escape routine using the OpenVMS API, you might enter the following command:
$ LINK FORMS$CHECKING_FORTRAN, ESC_UNIT, FORM_OBJECT
In this example, the application program, FORMS$CHECKING_FORTRAN.OBJ, is linked with one escape routine, ESC_UNIT.OBJ, and one form object. The form global symbol, FORMS$AR_FORM_TABLE, contains the address of ESC_
UNIT after the Linker finishes processing this command.
Figure 2–1 illustrates how the Form Manager transfers control to an escape routine that has been directly linked with the application program.
Developing the Application Program 2–23
Figure 2–1 Control Transfer to a Directly Linked Escape Routine
.
.
.
.
.
Main Program Form Manager
ENABLE RESPONSE
CALL PROC_ESC
END RESPONSE forms$ar_form_table
"PROC_ESC"
PROC_ESC Address
.
.
.
PROC_ESC
Form
.
.
RETURN
ZK−7897−GE
The following steps describe the process outlined in Figure 2–1.
1. The application program calls the Form Manager with the ENABLE request (FORMS$ENABLE).
2. The Form Manager executes the ENABLE response. The response contains a CALL response step, which includes an escape routine called proc_esc.
3. The Form Manager searches for the proc_esc routine, which it locates in the FORMS$AR_FORM_TABLE table. The Form Manager then transfers control to the proc_esc routine.
2.3.3 Linking Escape Routines Directly with a Portable API Program
To link escape routines directly with a program in the portable API, you need to do the following in your portable program:
1. Declare a global form name as an external integer in FORTRAN or use the predefined type, Forms_Form_Object, in the C language.
2. Specify the form name and a request option list in the ENABLE call.
2–24 Developing the Application Program
3. Set up a form object option by using the global form name in the enable request option list.
For detailed examples on setting up a form object option in the enable request option list, see Section 6.2 and Section 6.3.
To link escape routines with your portable program and form object, enter the following commands:
$ FORMS TRANSLATE MYFORM.IFDL
$ FORMS EXTRACT OBJ /PORTABLE_API MYFORM.FORM /OBJ=MYFORM.OBJ
$ LINK MAIN_PROGRAM, ESC_UNIT, MYFORM.OBJ, SYS$INPUT /OPTION -
_$ SYS$SHARE:FORMS$PORTABLE_API /SHARE
Ctrl/Z
2.3.4 Linking Escape Routines in a Shareable Image
You can link escape routines in a shareable image only if you are using the OpenVMS API. For information on creating a shareable image, see the
OpenVMS Linker Utility Manual.
To resolve escape routine references in your form, you must create a form object file using the forms Extract Object Utility and link it with your escape routines and application program.
After you create a shareable image, you must either define the FORMS$IMAGE logical name or specify the name of the image in the request-options argument of the ENABLE call. If you use the logical name, it must be defined as the name of the shareable image that contains the escape routine you want to use.
For example, the following command defines the FORMS$IMAGE logical name to point to a shareable image name SHAREABLE_IMAGE:
$ DEFINE FORMS$IMAGE DISK1$:[SMITH]SHAREABLE_IMAGE
All routines in the shareable image that you invoke as escape routines must be universal symbols in the shareable image. Escape routines are located at run time with the LIB$FIND_IMAGE_SYMBOL routine. For more information on LIB$FIND_IMAGE_SYMBOL, see the OpenVMS Run-Time
Library documentation.
If you are using more than one shareable image, the FORMS$IMAGE logical name can be a search list. You cannot specify a node name in this logical name definition; however, you can specify a device, directory, and file type. If you omit the device and directory from the logical name definition, the image activator looks for the file in SYS$SHARE. If you omit the file type, the image activator looks for a file with the .EXE type.
If the FORMS$K_IMAGE item code was specified in the request-options argument of the ENABLE request, the FORMS$IMAGE logical name is not used.
Developing the Application Program 2–25
When you specify the item code, the buffer address should contain the name of the shareable image containing the escape routines. You can specify the
FORMS$K_IMAGE item code up to eight times, each referring to a different shareable image. If you specify more than one shareable image, the Form
Manager begins searching with the first shareable image in the request-options list and terminates processing when it finds the procedural escape or it tries all the shareable images in the item list.
If you did not specify a FORMS$K_IMAGE item code in the enable response, or the Form Manager cannot translate FORMS$IMAGE when it attempts to transfer control to an escape routine stored in a shareable image, it returns an error to your application program. If the Form Manager cannot find the shareable image, it also returns an error to your application program. In either case, the request that caused the escape routine to be called terminates processing.
Figure 2–2 illustrates how the Form Manager transfers control to an escape routine that has been stored in a shareable image.
2–26 Developing the Application Program
Figure 2–2 Control Transfer to an Escape Routine in a Shareable Image
.
.
.
.
.
Main Program Form Manager
ENABLE RESPONSE
CALL PROC_ESC
END RESPONSE forms$ar_form_table
"PROC_ESC"
0
.
.
.
LIB$FIND_IMAGE_SYMBOL
Form
PROC_ESC
SUBROUTINE
.
.
.
RETURN
ZK−7898−GE
The following steps describe the process outlined in Figure 2–2:
1. The application program calls the Form Manager with the ENABLE request (FORMS$ENABLE).
2. The Form Manager executes the ENABLE response. The response contains a CALL response step, which includes the proc_esc escape routine.
3. The Form Manager searches for the proc_esc escape routine in the
FORMS$AR_FORM_TABLE table. The Form Manager finds a 0 for the address of the escape routine.
4. Using the RTL routine LIB$FIND_IMAGE_SYMBOL, the Form Manager locates the escape routine and transfers control to the proc_esc escape routine.
Developing the Application Program 2–27
2.3.5 Building Applications with Shared Forms or Shared Procedural
Escape Routines on OpenVMS Alpha
When you build applications that use shared images that contain either forms or procedural escape routines on OpenVMS Alpha, you must specify the following Linker option when building these shared images: symbol_vector=(FORMS$AR_FORM_TABLE=DATA)
For example, to build the DECforms sample application form as a shared image, issue the following command:
$ LINK/SHARE/EXE=FORMS$SAMPLE_FORM FORMS$SAMPLE_FORM, SYS$INPUT/OPT -
_$ SYMBOL_VECTOR=(FORMS$AR_FORM_TABLE=DATA)
The shared image can then be linked with the application program, allowing the form to be accessed through this image.
In addition, if the procedural escape routines are contained in a shared library that does not contain an .obj file that was created by issuing the FORMS
EXTRACT OBJECT or the FORMS EXTRACT OBJECT/NOFORM_LOAD command, each shared procedural escape routine entry point must be declared as well.
For example, if the procedural escape routines (get_deposit, get_check, and print_panel) are in a separate .obj file sample_peus.obj:
$ LINK/SHARE/EXE=SAMPLE_PEUS, SAMPLE_PEUS, SYS$INPUT/OPT -
_$ SYMBOL_VECTOR=(GET_DEPOSIT=PROCEDURE, GET_CHECK=PROCEDURE, -
_$ PRINT_PANEL=PROCEDURE)
2.3.6 Combining the Direct Link and Shareable Image Methods
To link escape routines directly with your program and also use escape routines stored in shareable images use the following procedure:
1. Create the escape routines and the responses that call them.
2. Create the shareable image containing the escape routines.
3. Define the FORMS$IMAGE logical name as the name of the shareable image, or specify the FORMS$K_IMAGE item code in the ENABLE call.
4. Create the form object.
5. Link the application program, the object module, and any escape routines
not stored in the shareable image.
2–28 Developing the Application Program
6. Run your application program.
Note
You can use a combination of the direct link and shareable image methods to link escape routines to your application program only with the OpenVMS API.
2.3.7 Enhancements to Escape Routine Debugging
Debugging DECforms escape routines that exist in shareable images is difficult because the Form Manager dynamically activates the images in the escape routines using the RTL LIB$FIND_IMAGE_SYMBOL routine. You cannot set breakpoints in escape routines until the Form Manager activates the image.
You must signal the SS$_DEBUG condition in routines that are to be debugged as procedural escapes.
To make it less difficult to debug escape routines, you can specify a logical name, FORMS$DEBUG_ESCAPE_ROUTINES, at session-enable time. If you specify the logical name FORMS$DEBUG_ESCAPE_ROUTINES as true, the
Form Manager invokes the Debugger by signaling SS$DEBUG the first time an escape routine is called for a given DECforms session. FORMS$DEBUG_
ESCAPE_ROUTINES is true when it is defined as a character string value that begins with any of the following characters: 1, T, t, Y, or y.
To invoke the Debugger, you must link the executable image that calls the
Form Manager with traceback.
Once the Form Manager invokes the Debugger, you must enter the appropriate
SET IMAGE, SET MODULE, and SET BREAK debug commands to set up a debugging environment. A GO command is also required. The SS$DEBUG condition is signaled as close as possible to the actual CALLG instruction that invokes the escape routine.
2.4 Using the Trace Facility
The Trace facility, supplied in the Form Manager, logs form processing information at run time to help you debug your application program and your form. This facility is useful because a great deal of form processing occurs each time you call a request from your application program.
Developing the Application Program 2–29
Note
Because of the size of the trace files and the overhead incurred in writing the trace files, tracing is not recommended in a production environment. You should be sure to turn tracing off before creating your final run-time environment.
An alternative to tracing, the event log, is described in Section 2.5.
Because event logging does not require much overhead, you might want to keep it on in your final run-time environment.
The Trace facility writes the following information to a file each time a request is called:
• Which request was called
• Responses and response steps performed
• Activation items processed
• Input functions accepted
• Names of panel fields or groups for which entry, exit, or validation responses are performed
• Form Manager logical names translated
• Records transferred to and from the form
• Record message fields transferred to and from the form
2.4.1 Controlling Tracing
Table 2–2 describes the options you have for turning on the tracing facility.
Table 2–2 Methods for Turning On the Trace Facility
Time of Action API Action
Before running the application
OpenVMS API
Portable API
Define the logical name
FORMS$TRACE to T, t, Y, y, or 1.
Define the logical name
FORMS$TRACE_FILE to the name you want for the trace file.
(continued on next page)
2–30 Developing the Application Program
Table 2–2 (Cont.) Methods for Turning On the Trace Facility
Time of Action
Per request during execution of program
API
OpenVMS API
Portable API
Action
Set the request option item code to FORMS$K_TRACE
1
.
Set the request option item code to FORMS$K_TRACEFILE
1
.
Set the request option to forms_c_opt_trace, and set trace.file_name and trace.file_name_length.
2
1
For details on using request options with the OpenVMS API, see Chapter 5.
2
For details on using request options with the portable API, see Chapter 6.
Trace Files
The first time tracing is turned on, the Form Manager opens a trace file specified by either the FORMS$K_TRACEFILE item code or the
FORMS$TRACE_FILE logical name on the OpenVMS API, or the trace.file_
name and trace.file_name_length variable on the portable API. If you specify the item code or option, the logical name is ignored. If you want the trace messages to be written to your display device, you can specify the trace file to be TT:.
If you do not specify the item code, the FORMS$TRACE_FILE logical name, the FORMS_TRACE_FILE file name, or if trace.filename is undefined when the trace facility is turned on, the trace information is written to a file in your current directory.
The file name is the same as the file name of the form file. If the file name is not specified, the form name specified in the form file is used. The file type of the file is .TRACE. For example, if your .FORM file is named
FORM_ONE.FORM, the default trace file name is FORM_ONE.TRACE.
The trace file is defined as a sequential file with variable-length records.
Using the FORMS$TRACE Logical Name
The trace facility sends information to the trace file when the FORMS$TRACE logical name is defined as being on (set to T, t, Y, y, or 1). The trace facility stops writing information to the trace file when FORMS$TRACE is defined as being off. FORMS$TRACE is defined as being off when it is defined as a character string value that begins with any character except T, t, Y, y, or 1, or when it is not defined.
Developing the Application Program 2–31
You can check the validity of the FORMS$TRACE logical name only on an
ENABLE request. If you did not specify the FORMS$K_TRACE item code or the trace.flag field in the request-options parameter, the FORMS$TRACE logical name is translated and tracing is turned on if necessary.
Tracing Multiple Sessions
When you turn on the trace logical name for a process running multiple sessions, the DECforms software opens a trace file with a unique version number to record the progress of each session separately.
Using Request Options for Tracing
You can start and stop tracing by specifying the FORMS$K_TRACE item code in the OpenVMS API, or the trace.flag field in the portable API in the requestoptions parameter for each request. A zero in the buffer address terminates tracing and a nonzero value starts tracing. Tracing remains on or off until you specify a request that changes it.
2.4.2 Enabling and Disabling Tracing
Although it is convenient to enable tracing, there may be occasions where you wish to turn tracing on and off. For example, if you have a very large application, you may wish to trace only one of the requests through the entire application.
You can turn the trace facility on and off by specifying the FORMS$K_TRACE item code in OpenVMS API and the trace.flag field in the portable API in the request-options argument of each request call. Example 2–7 shows an example of a portable API C program that turns tracing on and off.
2–32 Developing the Application Program
Example 2–7 Portable API C Program that Uses Tracing
#include <stdio.h>
#include <formsdef.h>
#define TRACE_FILE_NAME "testdate.trc"
/* Declare the data structure. */ typedef struct _record_message_type { char text_field[15]; long num_field;
} Record_Message_Type;
/* Forms Request Parameters */
Forms_Session_Id
Forms_Record_Data
Forms_Record_Data
Forms_Request_Options
Record_Message_Type
Record_Message_Type
Forms_Status Status;
SessionId;
Send_Message_Desc;
Receive_Message_Desc; forms_request_options[10];
Send_Message;
Receive_Message;
Forms_Control_Text Receive_Ctl_Text;
Forms_Count Receive_Ctl_Text_Count = 5;
Forms_Control_Text Send_Ctl_Text;
Forms_Count Send_Ctl_Text_Count = 5;
Forms_Value Timeout; main(int argc, char **argv)
{ int i;
/* Set up the request options to establish the trace file name. The file*/
/* must be set on enable, but the flag can be passed on any request.
*/ forms_request_options[0].option = forms_c_opt_trace; forms_request_options[0].trace.file_name = TRACE_FILE_NAME; forms_request_options[0].trace.file_name_length = strlen(TRACE_FILE_NAME); forms_request_options[0].trace.flag = 0; /* The flag means "no tracing".*/
(continued on next page)
Developing the Application Program 2–33
Example 2–7 (Cont.) Portable API C Program that Uses Tracing
/* Setup Enable Options List for the Enable call. */ i = 1;
/* receive control text info */ forms_request_options[i].option = forms_c_opt_receive_control; forms_request_options[i].receive_control.text = &Receive_Ctl_Text; forms_request_options[i].receive_control.text_count = &Receive_Ctl_Text_Count; i++;
/* send control text info */ forms_request_options[i].option = forms_c_opt_send_control; forms_request_options[i].send_control.text
= Send_Ctl_Text; forms_request_options[i].send_control.text_count = Send_Ctl_Text_Count; i++; forms_request_options[i].option = forms_c_opt_end;
/* Issue the Forms Enable call to test a bad Enable call */
Status = forms_enable(SessionId,
0,
"sample",
0,
/* Form Session Id ptr*/
/* Terminal Device
/* Form File name
/* Form name forms_request_options); /* Options list if (Status != forms_s_normal) return (1);
*/
*/
*/
*/
/* To enable tracing on this request: */ forms_request_options[0].option = forms_c_opt_trace; forms_request_options[0].trace.flag = 1; forms_request_options[1].option = forms_c_opt_end;
/* Initialize the send record structure. */
Send_Message_Desc.data_record
= &Send_Message;
Send_Message_Desc.data_length
= sizeof(Send_Message);
Send_Message_Desc.shadow_record = NULL;
Send_Message_Desc.shadow_length = 0;
Status = forms_send(SessionId,
"SAMPLE_RECORD",
&Send_Message_Desc, forms_request_options); if (Status != forms_s_normal)
{
Status = forms_disable(SessionId, 0); return (1);
}
(continued on next page)
2–34 Developing the Application Program
Example 2–7 (Cont.) Portable API C Program that Uses Tracing
/* To disable tracing: */ forms_request_options[0].option = forms_c_opt_trace; forms_request_options[0].trace.flag = 0; forms_request_options[1].option = forms_c_opt_end;
/* Initialize the receive structure. */
Receive_Message_Desc.data_record
= &Receive_Message;
Receive_Message_Desc.data_length
= sizeof(Receive_Message);
Receive_Message_Desc.shadow_record = NULL;
Receive_Message_Desc.shadow_length = 0;
Status = forms_receive(SessionId,
"SAMPLE_RECORD",
&Receive_Message_Desc, forms_request_options); if (Status != forms_s_normal)
{
Status = forms_disable(SessionId, 0); return (0);
}
Status = forms_disable(SessionId, /* Form Session Id ptr*/ forms_request_options); /* Options list */ return (0);
}
Example 2–8 shows an example of an ENABLE request that turns tracing on in the OpenVMS API.
Example 2–8 Using Tracing with the FORMS$ENABLE Call
*+
* Sample COBOL syntax that shows how to use the
* request options item list to enable tracing.
*-
IDENTIFICATION DIVISION.
PROGRAM-ID.
EMPLOYEE.
DATA DIVISION.
WORKING-STORAGE SECTION.
*+
* Pull in the FORMS definitions file.
*-
(continued on next page)
Developing the Application Program 2–35
Example 2–8 (Cont.) Using Tracing with the FORMS$ENABLE Call
COPY "sys$share:forms$cob_definitions".
*+
* Information that is transferred between this program and DECforms
*-
01 session_id
01 file_name
01 device_name
01 forms_status
PIC X(16) GLOBAL.
PIC X(9) VALUE "EMPLOYEE_PANEL".
PIC X(9) VALUE "SYS$INPUT".
PIC S9(9) COMP GLOBAL.
*+
* Request options item list.
*-
01 request_options.
03 item_1.
05 buff_len_1
05 item_code_1
05 buff_addr_1
05 ret_len_1
03 item_2.
05 buff_len_2
05 item_code_2
05 buff_addr_2
05 ret_len_2
03 end_of_item_list
*+
* Values for item list.
*-
01 tracefile
01 tracefile_addr
01 tracefile_len
PIC S9(4) COMP.
PIC S9(4) COMP.
PIC S9(9) COMP.
PIC S9(9) COMP.
PIC S9(4) COMP.
PIC S9(4) COMP.
PIC S9(9) COMP.
PIC S9(9) COMP.
PIC S9(9) COMP VALUE 0.
PIC X(9) VALUE "TRACEFILE".
POINTER VALUE IS REFERENCE tracefile.
PIC S9(4) COMP VALUE 9.
2
1
3
4
5
01 trace_off
01 trace_on
PIC S9(9) COMP VALUE 0.
PIC S9(9) COMP VALUE 1.
01 trace_len
PROCEDURE DIVISION.
0.
*+
PIC S9(9) COMP VALUE 4.
* Load first item in request options item list.
* This item causes tracing to be turned on.
*move forms$k_trace to item_code_1.
move trace_len to buff_len_1.
move trace_on to buff_addr_1.
move binary_zero to ret_len_1.
6
7
(continued on next page)
2–36 Developing the Application Program
Example 2–8 (Cont.) Using Tracing with the FORMS$ENABLE Call
*+
* Load second item in request options item list.
* This item specifies the name of the trace file to
* be created.
*move forms$k_tracefile to item_code_2.
move tracefile_len to buff_len_2.
move tracefile_addr to buff_addr_2.
move binary_zero to ret_len_2.
*+
* Enable the form and create the DECforms session.
*-
CALL "forms$enable" USING OMITTED
BY DESCRIPTOR device_name
BY DESCRIPTOR session_id
BY DESCRIPTOR file_name
OMITTED
OMITTED
OMITTED
OMITTED
OMITTED
OMITTED
OMITTED
BY REFERENCE request_options
GIVING forms_status.
*+
* Test the completion status.
*-
IF forms_status IS FAILURE THEN
CALL "LIB$SIGNAL" USING BY VALUE forms_status
STOP RUN
END-IF.
END PROGRAM EMPLOYEE.
1
2
3
8
9
The forms$cob_definitions file contains the declaration of the
FORMS$ENABLE routine name, and the FORMS$K_TRACE and
FORMS$K_TRACEFILE symbols.
The request_options declaration creates a two-dimensional array containing two item lists.
The next set of declarations assigns constant values to be used in the item lists.
Developing the Application Program 2–37
4
5
6
7
8
9
The tracefile constant contains the name of the file that is to contain trace information. The tracefile_addr variable contains the address of the tracefile constant. The tracefile_len variable contains the length of the tracefile constant.
The trace_on and trace_off constants control whether tracing is on or off.
To turn tracing on, pass the trace_on constant. To turn tracing off, pass the trace_off constant.
The trace_len constant contains the length of the trace_on or trace_off constants. The value 4 indicates that the constants are each a VAX longword.
The assignment statements move values into the first item list, which is the item_1 list. The item_1 list controls whether tracing is on or off. In this case, tracing is turned on because the trace_on constant is assigned to the buff_addr_1 variable.
The second set of assignment statements moves values into the item_2 item list. This list controls where trace information is written.
The FORMS$ENABLE call invokes the ENABLE request. The
FORMS$ENABLE call passes a number of empty parameters, the file_name and device_name constants, and the session_id variable. It also passes the request_options item list, containing the tracing information.
2.4.3 Exception Conditions During Tracing
If the Form Manager encounters an exception condition during tracing, it issues a warning message and returns a receive control text item describing the error condition to the application program. If an exception condition occurs, tracing is turned off for the current session.
The following conditions cause the Form Manager to turn off tracing:
• The trace facility cannot open the trace file.
• The trace facility cannot write information to the trace file.
• The trace facility cannot close the trace file.
2.4.4 Tracing Command Procedure
Example 2–9 shows a sample DCL command procedure that invokes the trace facility and specifies the file in which the trace facility writes trace information.
The FORTRAN advanced sample application program is run in this example.
2–38 Developing the Application Program
Example 2–9 Sample DCL Command Procedure Invoking the Trace Facility
$! Turn on tracing
$ DEFINE FORMS$TRACE "T"
$!
$! Define a subdirectory for the output filespec
$ DEFINE FORMS$TRACE_FILE USER:[SMITH.TEST]MY_TEST.TRACE
$!
$ DEFINE/USER SYS$INPUT SYS$COMMAND
$!Run the application program
$ RUN FORMS$CHECKING_FORTRAN
$!
$!Type out the trace file when through processing
$ TYPE USER:[SMITH.TEST]MY_TEST.TRACE
2.4.5 Capturing Additional Tracing Information
If you want to include additional tracing information about data movement, define the OpenVMS logical name FORMS$TRACE_CONVERSIONS to T. The resulting trace file will be much larger than a normal trace file.
2.5 Using the Event Log
Using the trace facility at development time is useful, but it might be inappropriate for a production environment. During development time, you may require detailed information about the actions of the Run-Time Manager.
In a production environment, you might not need to trace every action of the Run-Time Manager, although it may be important to trap any errors or unusual events.
The Event Log file provides a broader scope in capturing error data than the trace file. The Event Log file writes only information pertinent to the logged event. The Event Log file reports all errors within the Form Manager, whereas the trace file reports only errors pertaining to request processing.
You enable Form Manager Event Log files by setting the logical name
FORMS$LOG_EVENTS to 1. If an error occurs in your form sessions, a log file named FORMS$EVENT_LOG.LOG appears in your working directory. You can change the name of the log file by setting the logical name
FORMS$LOG_FILE_NAME. You can set these logical names prior to or during program execution. You can purge, delete, or rename the log file while the program is running. DECforms creates a new version of the log file each time it encounters an error.
This information may be helpful should you submit the error as a problem report to HP. Example 2–10 outlines the information contained in an Event
Log file.
Developing the Application Program 2–39
Example 2–10 Event Log File
DECforms error logged on *date* *time*
Process ID: *process_id*
* Process Name: *process_name*
* Image Name: *program_name*
*error_message_text*
.
.
.
+ Signal Vector [0] : *error_vector_data*
.
.
+ Signal Vector [1] : xxxxxxx
.
+ Mechanism Vector [0] : *error_vector_data*
+ Mechanism Vector [1] : xxxxxxx
+ Mechanism Vector [2] : xxxxxxx
+ Mechanism Vector [3] : xxxxxxx
MGR_form: Terminal Name: *terminal_name*
+ RCB: Address: xxxxxxx
+ RCB: Control Bits: xxxxxxx
+ RCB: Thread Id: xxxxxxx
+ RCB: Additional Control Bits: xxxxxxx
+ SCB: Address: xxxxxxx
+ SCB: Control Bits: xxxxxxx
+ SCB: Scheduling Bits xxxxxxx
+ SCB: Current Request: xxxxxxx
+ SCB: VM Zone Cache: xxxxxxx, Verify status: xxxxxxx
+ SCB: Zone Cache User: xxxxxxx
+ SCB: Error Routine: xxxxxxxx; Error Param: xxxxxxx
Param Block: Request Type: *request_type*
+ Param Block: Request Flags: xxxxxxx
Param Block: Session ID: *session_id*
+ VM Zone: wmg_a_display_zone: xxxxxxx, verify status: xxxxxxx
+ VM Zone: wmg_a_windows_zone: xxxxxxx. verify status: xxxxxxx
+ VM Zone: wmg_a_rectangle_zone: xxxxxxx, verify status: xxxxxxx
+ VM Zone: wmg_a_buffers_zone: xxxxxxx, verify status: xxxxxxx
+ VM Zone: wmg_a_frame_zone: xxxxxxx, verify status: xxxxxxx
*+ *raw_stack_dump_data*
.
.
.
.
*request_type* values:
(continued on next page)
2–40 Developing the Application Program
Example 2–10 (Cont.) Event Log File
forms_enable forms_send
= 1
= 2 forms_receive = 3 forms_transceive = 4 forms_disable forms_cancel
= 5
= 6 forms_send(async) = 7
Legend:
*
+
= OpenVMS only
= DECforms Internal information
*...* = User applicable data
Developing the Application Program 2–41
3
Using Oracle Trace Software with
DECforms Applications
DECforms has many predefined duration and point events that occur during run time. (For a complete list of events, see Table 3–1.) An event can have a start and an end or it can simply occur. Oracle Trace allows events within
DECforms to be defined and DECforms data items to be associated with each event. These data items can be standard resource utilization items or items specific to applications using DECforms.
Oracle Trace records several different pieces of information, called items, for each event. Items can be information about the event itself, such as the name of the event or in what procedure the event is occurring. Items can also include process statistics and performance information, such as the working set size at the time of the event. Section 3.1.2 contains descriptions of DECforms events and items.
To use Oracle Trace commands directly from HP Command Language (DCL), preface them with the keyword COLLECT. For example:
$ COLLECT SHOW VERSION
Oracle Trace Version V2.2
$
You can also enter the Oracle Trace command environment by entering the
COLLECT command with no arguments at the DCL prompt. Oracle Trace software prompts you for commands until you return to DCL command level with the EXIT command.
For example:
$ COLLECT
Trace> SHOW VERSION
Oracle Trace Version V2.2
Trace> EXIT
$
Using Oracle Trace Software with DECforms Applications 3–1
3.1 How to Collect Event Data
To collect event data with Oracle Trace software, you must first create a facility selection and then schedule data collection using that selection.
3.1.1 Creating a Selection
Oracle Trace software can collect event data from a number of layered products and applications. These other products are referred to as facilities, and each has a facility definition registered in the Oracle Trace administration database.
You can use the SHOW DEFINITION command to list the facilities installed on your system.
The following example shows the facility definitions.
$ COLLECT SHOW DEFINITION /FORMAT=NAMES_ONLY
14-APR-1997 14:36
Page 1
Names Only Report
Facility Definition Information
Oracle Trace V2.2
Facility: Version: Creation Date: Class:
-------------------- ---------- ------------------ ------------------
FORMS V2.2
14-APR-1997 04:21 ALL
MONITORING
PERFORMANCE
(D)
V2.1
1-MAR-1997 23:36 ALL
MONITORING
PERFORMANCE
(D)
$
Oracle Trace software can collect data from all the registered facilities or just the ones in which you are interested.
To specify a subset of the available facilities, you use the CREATE
SELECTION command to create a facility selection, which consists of the following items:
• Selection name
• List of facilities for which to collect data
• Class of data to collect for each facility
The basic format for the CREATE SELECTION command is as follows:
$ CREATE SELECTION selection_name /FACILITY=(facility_name[,...])
3–2 Using Oracle Trace Software with DECforms Applications
The following example defines the selection MY_SELECTION to collect the default data for DECforms:
$ COLLECT CREATE SELECTION MY_SELECTION /FACILITY=FORMS
To define a more detailed selection, you should use the OPTIONS qualifier, which takes a file name as an argument. The options file lists each facility and the collection class you want to use. Each facility is described on a separate line. If you specify OPTIONS but do not include a file name, Oracle Trace software prompts you for the options.
The format of the facility description in the options file is as follows:
$ FACILITY facility-name [/VERSION="version-code"] [/CLASS=class-name]
facility-name
The name of the facility for which to collect data.
version-code
A text string identifying the version of the facility. The string must be enclosed in quotation marks ( " " ).
class-name
The class of data that you want collected for the facility.
The following example creates the facility selection SELECT_ALL to collect all the possible data for DECforms software and only the performance-related data from MY_FACILITY:
$ COLLECT CREATE SELECTION SELECT_ALL /OPTIONS
Options> FACILITY FORMS /CLASS=ALL
Options> FACILITY MY_FACILITY/CLASS=PERFORMANCE
Options>
Ctrl/Z
$
3.1.2 Describing Events and Items
Each time a predefined event occurs in a DECforms application, Oracle Trace software records the event items in a data file. You can use this collected data to identify information for a variety of uses, such as how frequently an event occurs, in what order events occur, or how long an event takes to complete.
Using Oracle Trace Software with DECforms Applications 3–3
Note
Oracle Trace software collects all occurrences of each event in your chosen collection class. You cannot choose individual events to record.
However, you can create reports based on specified events, by using the
REPORT command. For information on Oracle Trace reporting, see
Section 3.2.
Table 3–1 describes the events that can occur in your DECforms applications.
Table 3–1 Events
Event
SESSION
ENABLE
SEND
RECEIVE
TRANSCEIVE
DISABLE
CANCEL
DISTRIBUTION
COLLECTION
CALL_RESPONSE
ACCEPT_PHASE
1
PANEL_DURATION
Description
Tracks the length of a DECforms session.
Tracks the length of an ENABLE request.
Tracks the length of a SEND request.
Tracks the length of a RECEIVE request.
Tracks the length of a TRANSCEIVE request.
Tracks the length of a DISABLE request.
Logs the occurrence of a CANCEL request.
Tracks the length of time needed to perform data distribution for a particular record.
Tracks the length of time needed to perform data collection for a particular record.
Tracks the length of time needed to process a CALL response step in IFDL.
Tracks the length of time from the end of the accept phase to the start of the next accept phase (the processing time of a transaction when not accepting user input).
Tracks the length of time spent accepting input within an individual panel.
1
The ACCEPT_PHASE event can be interpreted as the response time of a transaction.
Type of
Event
Duration
Duration
Duration
Duration
Duration
Duration
Point
Duration
Duration
Duration
Duration
Duration
Table 3–2 describes the items, related to the events in the previous table, that are specific to DECforms applications.
3–4 Using Oracle Trace Software with DECforms Applications
Table 3–2 Data Items
Item Description
session id form name send record name receive record name
Name of the DECforms session.
Name of the DECforms form.
Name of the SEND record.
Name of the RECEIVE record.
escape routine name Name of the escape routine.
panel name Name of the panel.
Data type
fixed_ascic fixed_ascic fixed_ascic fixed_ascic fixed_ascic fixed_ascic
The ALL class is composed of the full set of events and items available for collection from DECforms. Table 3–3 lists the events and items that make up the ALL collection class.
Table 3–3 Events and Items Available in the ALL Class
Event Items
SESSION
ENABLE
SEND
RECEIVE
TRANSCEIVE
DISABLE
CANCEL
DISTRIBUTION
COLLECTION
CALL_RESPONSE
ACCEPT_PHASE
1
PANEL_DURATION session id, form name session id, form name session id, form name, send record name session id, form name, receive record name session id, form name, send record name, receive record name session id, form name session id, form name session id, form name, send record name session id, form name, receive record name session id, form name, escape routine name session id, form name session id, form name, panel name
1
The ACCEPT_PHASE event can be interpreted as the response time of a transaction.
Using Oracle Trace Software with DECforms Applications 3–5
3.1.3 Scheduling Data Collection
You must schedule data collection on your system for Oracle Trace software to begin collecting information about DECforms software.
The scheduling criteria include:
• Output file for the collected data
• Start and end times (or alternately, the duration)
• Which facility selection to use
• Whether to collect from your entire cluster or just the local node
Oracle Trace software does not allow you to schedule data collections that overlap or run simultaneously; although you can schedule many data collections on a node, only one collection can be active on a node at any time.
You can schedule data collection either locally or cluster wide, by using the [NO]CLUSTER qualifier. By default, the SCHEDULE COLLECTION command schedules data collection on every node in the cluster. To schedule data collection on a subset of the cluster, you must log in to each node that you want data collection to occur on and schedule local data collection on that node by specifying NOCLUSTER. On a standalone system, the CLUSTER qualifier is ignored.
The following example schedules the collection MY_COLLECTION to begin at 11:00 and end at 12:00 on the current day. The collection uses the facility selection SELECT_ALL and runs on the local node. Oracle Trace software stores the collected data in the file MY_DATA.DAT in your default device and directory.
$ COLLECT SCHEDULE COLLECTION MY_COLLECTION MY_DATA.DAT -
_$ /SELECTION=SELECT_ALL -
_$ /BEGINNING=11:00 /ENDING=12:00 -
_$ /NOCLUSTER
%EPC-I-SCHEDULE, Entry MY_COLLECTION scheduled for 14-APR-1997 11:00
You can use the DURATION qualifier in place of the ENDING qualifier. You must specify the duration as a relative OpenVMS time.
For example:
$ COLLECT SCHEDULE COLLECTION MY_COLLECTION MY_DATA.DAT -
_$ /SELECTION=SELECT_ALL -
_$ /BEGINNING=11:00 /DURATION="+1::" -
_$ /NOCLUSTER
%EPC-I-SCHEDULE, Entry MY_COLLECTION scheduled for 14-APR-1997 11:00
3–6 Using Oracle Trace Software with DECforms Applications
3.2 How to Create a Report Based on Collected Data
You can use Oracle Trace software to produce reports that are based on the data collected from one or more Oracle Trace collections.
There are two steps to producing Oracle Trace reports:
1. Format and merge the data files.
2. Generate the report.
3.2.1 Formatting and Merging Data Files
Before Oracle Trace software can generate a report on the data collected for your collections, you must use the FORMAT command to format the data in the data files into an Oracle Rdb™ database.
1
The following example formats the data in the file MY_DATA.DAT
and stores the formatted data in an Oracle Rdb database named
FORMATTED_DATA.RDB:
$ COLLECT FORMAT MY_DATA.DAT FORMATTED_DATA.RDB
You can also use the FORMAT command to combine the data files from two or more collections into one formatted database. However, these collections must have been scheduled by using the same facility selection.
There are two ways to combine data files: you can format several data files at once into the same Oracle Rdb database, or you can add a data file to an existing formatted database.
The following example combines the data collected from several collections into a new formatted database named WEEK.RDB.
$ COLLECT FORMAT MONDAY.DAT,TUESDAY.DAT,WEDNESDAY.DAT WEEK.RDB
The following example adds the contents of the data file THURSDAY.DAT to the existing formatted database WEEK.RDB:
$ COLLECT FORMAT /MERGE THURSDAY.DAT WEEK.RDB
1
A VAX RMS formatted file is also available for users who plan to create their own reports based on the data. For more information, see the Oracle Trace User’s Guide.
Using Oracle Trace Software with DECforms Applications 3–7
3.2.2 Generating a Report
Oracle Trace software can generate tabular reports based on the data in an
Oracle Rdb formatted database.
Table 3–4 lists the three different types of reports that you can produce.
Table 3–4 Oracle Trace Reports
Type Description
DETAILED
FREQUENCY
SUMMARY (default)
Actual values of the items collected for each event
Event occurrence summary based on a selected time interval
Summary statistics about the collected data
In the simplest case, the REPORT command creates a summary report on all the data in the formatted database and displays the report on your current
SYS$OUTPUT device (usually your terminal).
For example:
$ COLLECT REPORT FORMATTED_DATA.RDB
You can further refine the report with the FACILITY qualifier.
The following example generates a summary report on only DECforms data and writes the report to the file MY_REPORT.TXT:
$ COLLECT REPORT FORMATTED_DATA.RDB /FACILITY=FORMS -
_$ /OUTPUT=MY_REPORT.TXT
You use the STATISTICS qualifier to specify the statistics for the Oracle Trace software to use in the summary report. This feature allows you to create customized reports that present the information in the manner most suitable to your needs.
The valid statistics are as follows:
• ALL (default)
• COUNT
• MAXIMUM
• MEAN
• MINIMUM
• NONE
3–8 Using Oracle Trace Software with DECforms Applications
• STANDARD_DEVIATION
• 95_PERCENTILE
The following example generates a summary report based on the data collected for DECforms software by using the statistics MAXIMUM, MINIMUM, and
MEAN:
$ COLLECT REPORT FORMATTED_DATA.RDB /FACILITY=FORMS -
_$ /TYPE=SUMMARY /STATISTICS=(MAXIMUM,MINIMUM,MEAN) -
_$ /OUTPUT=MY_SUMMARY.TXT
By default, Oracle Trace software reports on the data collected for all the events contained in the formatted database. You can use the EVENTS qualifier to restrict the report to specific events.
The following example generates a report based on the data collected for a subset of the events in DECforms software:
$ COLLECT REPORT FORMATTED_DATA /OUTPUT=MY_REPORT.TXT -
_$ /FACILITY=FORMS -
_$ /EVENTS=(EVENT_1,EVENT_2,EVENT_3)
The BEFORE, INTERVAL, RESTRICTIONS, OPTIONS, and SINCE qualifiers provide additional customization features. For a full description of Oracle
Trace reporting, see the Oracle Trace User’s Guide.
3.3 Sample Oracle Trace Report for DECforms Software
Example 3–1 shows a frequency report produced by Oracle Trace for a
DECforms application.
Example 3–1 Sample Frequency Report Using Oracle Trace Software
14-APR-1997 08:33
Selection: FORMS_EVENTS
Event: ACCEPT_PHASE In Facility: FORMS
Time Period Occurrences
14-APR-1997 08:13:00
14-APR-1997 08:14:00
14-APR-1997 08:15:00
14-APR-1997 08:16:00
14-APR-1997 08:18:00
14-APR-1997 08:19:00
2
1
5
7
2
4
Frequency Report Page 1
Oracle Trace V2.2
Version: V2.2
(continued on next page)
Using Oracle Trace Software with DECforms Applications 3–9
Example 3–1 (Cont.) Sample Frequency Report Using Oracle Trace Software
%EPC-I-NOEND, 3 Start Event Records had no matching End
14-APR-1997 08:33
Selection: FORMS_EVENTS
Frequency Report
Event: CALL_RESPONSE
Time Period
In Facility: FORMS
Occurrences
Page 2
Oracle Trace V2.2
Version: V2.2
14-APR-1997 08:13:00
14-APR-1997 08:14:00
14-APR-1997 08:15:00
14-APR-1997 08:17:00
14-APR-1997 08:18:00
14-APR-1997 08:19:00
14-APR-1997 08:33
Selection: FORMS_EVENTS
4
10
7
9
55
2
Frequency Report
Version: V2.2
Page 3
Oracle Trace V2.2
Event: COLLECTION
Time Period
14-APR-1997 08:13:00
14-APR-1997 08:14:00
14-APR-1997 08:15:00
14-APR-1997 08:16:00
14-APR-1997 08:17:00
14-APR-1997 08:18:00
14-APR-1997 08:19:00
In Facility: FORMS
Occurrences
2
11
2
2
1
3
5
14-APR-1997 08:33
Selection: FORMS_EVENTS
Frequency Report
Event: DISTRIBUTION In Facility: FORMS
Time Period Occurrences
14-APR-1997 08:13:00
14-APR-1997 08:14:00
14-APR-1997 08:15:00
14-APR-1997 08:16:00
14-APR-1997 08:17:00
14-APR-1997 08:18:00
14-APR-1997 08:19:00
5
10
3
1
3
4
8
Page 4
Oracle Trace V2.2
Version: V2.2
14-APR-1997 08:33
Selection: FORMS_EVENTS
Frequency Report
Event: PANEL_DURATION In Facility: FORMS
Page 5
Oracle Trace V2.2
Version: V2.2
(continued on next page)
3–10 Using Oracle Trace Software with DECforms Applications
Example 3–1 (Cont.) Sample Frequency Report Using Oracle Trace Software
Time Period
14-APR-1997 08:13:00
14-APR-1997 08:14:00
14-APR-1997 08:15:00
14-APR-1997 08:16:00
14-APR-1997 08:17:00
14-APR-1997 08:18:00
14-APR-1997 08:19:00
Occurrences
6
35
4
5
10
2
1
%EPC-I-NOEND, 3 Start Event Records had no matching End
%EPC-I-NOSTART, 1 End Event Records had no matching Start
14-APR-1997 08:33
Selection: FORMS_EVENTS
Index
Report Index
Facility Name
FORMS
FORMS
FORMS
FORMS
FORMS
Event Name
ACCEPT_PHASE
CALL_RESPONSE
COLLECTION
DISTRIBUTION
PANEL_DURATION
Page
3
4
1
2
5
Page 6
Oracle Trace V2.2
Using Oracle Trace Software with DECforms Applications 3–11
4
How the Form Manager Processes
Requests
The Form Manager processes each request that you call from an application program by:
1. Initializing the request
2. Distributing form data (SEND and TRANSCEIVE requests only)
3. Processing external responses
4. Accepting input
5. Processing request exit response
6. Collecting form data (RECEIVE and TRANSCEIVE requests only)
7. Terminating the request
The Form Manager returns control to the application program after terminating the request. This chapter explains each phase of the request process.
4.1 Initialize Request Phase
The Form Manager performs the initialize request phase for each request that you call from your application program. During this phase, the Form Manager validates the request call.
How the Form Manager Processes Requests 4–1
4.1.1 Initializing Requests (Except ENABLE)
To initialize any request other than the ENABLE request, the Form Manager performs the following steps:
Step 1: Validating the Argument List
To validate the argument list in a request call, the Form Manager determines that the correct number of arguments was passed in the argument list and that each argument is the correct type. The Form Manager also verifies that it can read information from or write information to the appropriate arguments in the argument list.
Note
Because some programming languages allow you to store variables in either read-only memory, read/write memory (on some operating systems), or on the process stack, you must ensure that where you store a variable does not interfere with the Form Manager’s access to that variable. For information on assigning variables to particular areas of memory, see the documentation for your programming language.
The Form Manager terminates the request and returns an error message to your application program if one of the following is true:
• The argument list contains too few or too many arguments (OpenVMS API only).
• An argument’s data type is incorrect (OpenVMS API only).
• The Form Manager does not have the access it needs to an argument in the argument list.
• An illegal option is specified in the request-options argument.
Step 2: Validating the Session-Identification Argument
Once the Form Manager has determined that the argument list is valid, it validates the session-identification argument. The Form Manager maintains a list of active sessions. To validate the session-identification argument, the
Form Manager compares the value in that argument to the list of active sessions.
If the value in the session-identification argument matches an active session, the argument is valid. The Form Manager uses the form and display device that are associated with the value of the session-identification argument for subsequent operations during this request.
4–2 How the Form Manager Processes Requests
If the session-identification string does not match an active session, the
Form Manager terminates the request and returns an error message to your application program.
Step 3: Validating Record Names
After validating the session-identification argument, the Form Manager validates any record name (either send or receive) argument in the request.
(This validation is not done for the DISABLE or CANCEL requests because you cannot pass a record name argument in either request.)
When the Form Manager validates the record name, it compares the value passed in that argument to the names of records stored in the form. The record name can specify either a single record name, or a list of records.
The record name argument must contain a character string that is the same as a form record name or record list name. For example, if you pass the string
RECORD_ONE in the record name argument, there must be a form record or form record list named RECORD_ONE. (The Form Manager ignores case for form record names, so RECORD_ONE is equivalent to record_one.)
When the Form Manager finds a form record or record list that has the same name as the string passed in the record name argument, it validates the length of the data that is to be passed.
The Form Manager determines the length of that data by looking at the record that you pass in the request call. The Form Manager compares the length specified by the record message argument to the length of the form record in the form specified by the record name. If the length in the record and the length of the form record match, the record length is valid.
If the record name specifies a list, validation is performed the same way that it is performed for a single record for each record in the list. For example, if
RECORD_ONE specifies a record list that contained 25 records, validation is performed 25 times, once for each record.
The Form Manager terminates request processing and returns an error message to your application program if one of the following occurs:
• The record-message-name argument does not match the name of any record defined in the form or record list.
• The length field of the record argument does not match the length of the form record that is named in the record-message-name argument.
How the Form Manager Processes Requests 4–3
Step 4: Validating Control-Text Arguments
Receive control text provides information on the status of a request to the application. The Form Manager passes receive control text to the application and the application passes send control text to the form. A control-text argument can be either receive control text or send control text, specified as a receive-control-text or send-control-text argument in all request types except CANCEL.
The Form Manager tests the send-control-text-count for read access and the receive control text for write access.
The Form Manager validates any control-text arguments during the validation of the argument list. Send control text passes the names of control text responses to the Form Manager. If you pass a control-text argument, either send or receive, you must also pass a control-text-count argument.
To validate a send-control-text argument, the Form Manager verifies that the value in the send-control-text-count argument is less than or equal to the number of send control text items specified in the send control text. (The send control text is a set of five-character items; each item is a five-character string.)
The Form Manager does this by:
1. Reading the value of the send-control-text-count argument.
2. Multiplying this value by five.
3. Comparing the resulting value to the total number of characters in the send control text.
If the value in the send-control-text-count argument is greater than zero and less than or equal to the number of control text items in the send control text, the argument is valid. For example, if the count is 2, and there are 14 characters in the control text, the argument is valid (2 x 5 = 10 and 10 < 14).
If the count is 3 and there are 14 characters in the control text, the argument is not valid.
If the send control text is invalid, the Form Manager terminates request processing and returns an error message to the application program.
The Form Manager ignores those control text items not present in the form.
Step 5: Validating Parent-Request-Ids
To validate a parent-request-id, the Form Manager first verifies that the parent-request-id matches the identification of an existing request.
4–4 How the Form Manager Processes Requests
The Form Manager terminates request processing and returns an error message to your application if one of the following occurs:
• The parent-request-id does not match the identification of an existing request.
• The parent-request-id is not awaiting completion of a procedural escape routine.
The Form Manager then verifies that the parent request awaits completion of a procedural escape routine.
Step 6: Validating Request Options
To validate the request options specified by a request call, the Form Manager matches the specified request options to the request. If the request specifies an option that is invalid for that request, validation of the option fails and the Form Manager returns an error message and returns to the application program. The Form Manager also tests read and write access of the request options.
For more information on request options, see Chapter 5.
Step 7: Validating Shadow Records
Shadow records provide a means of tracking information concerning record fields. There are two kinds of shadow records: send shadow records and receive shadow records.
A send shadow record is sent from the application program to the form. The send shadow record contains an indicator that specifies whether the record fields in the associated send record should change the last known values of associated form data items.
You pass the send shadow record to DECforms by specifying the optional send-shadow-record argument on the SEND and TRANSCEIVE request calls.
A receive shadow record, which is a record returned to the application program, contains information about a record and each record field in the associated receive record. The information specifies whether the record fields in the associated receive record have changed value from the values last known to the program. A receive shadow record contains one character for each record field in the receive record plus one additional character that specifies the modified status of the record.
You pass the receive shadow record to DECforms by specifying the optional receive-shadow-record parameter on the RECEIVE and TRANSCEIVE requests.
You cannot specify shadow records for a CANCEL or DISABLE request.
How the Form Manager Processes Requests 4–5
4.1.2 Initializing the ENABLE Request
To initialize the ENABLE request, the Form Manager performs the following steps:
Step 1: Validating the Argument List
To validate the argument list in an ENABLE request call, the Form Manager determines that the correct number of arguments was passed in the argument list and that each argument is the correct data type. The Form Manager also verifies that it can read information from or write information to the appropriate arguments in the argument list.
Note
Because some programming languages allow you to store variables in either read-only memory, read/write memory (on some operating systems), or on the process stack, you must ensure that where you store a variable does not interfere with the Form Manager’s access to that variable. For information on assigning variables to particular areas of memory, see the documentation for your programming language.
The Form Manager terminates the request and returns an error message to your application program if one of the following is true:
• The argument list contains too few or too many arguments.
• The Form Manager does not have the access it needs to an argument in the argument list.
Step 2: Creating the Session
To create a session, the Form Manager creates a unique, 16-character sessionidentification string. The session-identification string relates the display device that was attached and the form that was loaded into memory to each other.
If the session-identification parameter is not 16 characters long, the Form
Manager returns an error message and terminates request processing. (In the portable API, the 16-character string Forms_Session_Id is defined in the header file.)
Step 3: Loading the Form
Once the Form Manager has validated the argument list in an ENABLE request call, it locates the form and loads it. The Form Manager loads the form based on the parameters specified in the ENABLE request.
4–6 How the Form Manager Processes Requests
To load the form, the Form Manager performs the following tasks:
• If you specify FORMS$AR_FORM_TABLE and the form name parameter in the OpenVMS API, or if you specify form object in the request option of the portable API, the Form Manager checks to see if the form specified by the form name parameter is linked in with the application. If the form is linked in with the application, the Form Manager loads that form.
If the form is not linked in with the application, and you specify both the form name and form file parameters, the Form Manager attempts to activate the file specified in the file name parameter and then looks for the form name specified in the form name parameter. If the Form Manager finds the form, it loads it.
• If you specified the file name and the form is not loaded in either the
OpenVMS API or the portable API, the Form Manager attempts to load the file assuming that it is a valid form file. If a full file specification is not present, the current directory is the default. The default file type is .form.
If the Form Manager cannot find the form specified in the request call, it terminates request processing and returns an error to your application program.
The Form Manager refrains from loading a form file from disk if the file has been loaded by another session for this process. Rather than reloading the form, the Form Manager uses the current memory-resident version of the form for the session to reduce the overall memory requirements for the process.
The form file specifications passed to the ENABLE request must meet the following three criteria for a form to be shared between sessions within the same process:
• The full file specification of the form file must be identical to that of a loaded form.
• The file modification dates of the form files must match.
• The file sizes of the form files must match.
If no loaded memory-resident form meets all three conditions, the Form
Manager reads and loads the form file from disk. The Form Manager deletes a memory-resident form file when no sessions reference it. This form load strategy is especially useful in the ACMS environment and in any environment where multiple instances of the application are used.
How the Form Manager Processes Requests 4–7
Step 4: Selecting the Layout
After the Form Manager loads a form, it selects a layout. To be selected, a layout must meet display device, device type, display size, and natural language requirements.
If the device name indicates a VT-class terminal, then the Form Manager attempts to select a matching VT or character-cell layout. A typical charactercell device name value is "SYS$INPUT".
If the device name indicates a disk file, then the Form Manager attempts to select a matching PRINTER layout. Valid PRINTER device name values are any legal file specification. An example would be "FORMS_OUTPUT.DOC".
To determine which layout in a form meets the display device requirement, the Form Manager first looks at the display device argument in the ENABLE request. In the display device argument, you pass the name of a display device. The Form Manager uses the information in this argument to retrieve information about the attributes of the display device; for example, whether the device is a VT300-series terminal, and if so, if it supports color.
In some cases, the operating system may not provide a way for DECforms to inquire about attributes of the display device. DECforms provides a way to specify default terminal settings.
To specify default terminal settings when you use the portable API, use the forms_c_opt_default_term and the forms_c_opt_default_color options. The fields for these options include: default_color_type default_term_type
Literals are defined in the API library files to simplify the assignment of these fields. The literals are in the format forms_c_dev_[xxx] and forms_c_color_
[xxx]. The Form Manager uses the values you set as default values when it cannot determine the terminal type (or color support) from the operating system.
The layout must specify a display device type that matches the attributes that the Form Manager retrieves. If no layout specifies a display device type that matches the attributes of the physical display device, the Form Manager looks for the layout that most closely corresponds to the physical display device.
To determine whether a layout meets the display size requirement, the Form
Manager compares the display size specified in the layout with the size of the physical display device. To meet the display size requirement, a layout must specify a display size that is valid for the physical display device. For
4–8 How the Form Manager Processes Requests
information on valid display sizes for a particular display device, see the section on device declarations in the HP DECforms IFDL Reference Manual.
To determine whether a layout meets the natural language requirement, the
Form Manager checks if the FORMS$K_LANGUAGE item code or language_ name option is specified. If you do not specify this item code or option, the
Form Manager translates the FORMS$LANGUAGE logical name.
If the translation is successful, the layout is selected based on the value of this translation.
Alternatively, an application program can specify a language clause through the request options of an enable request. Specify item code
FORMS$K_LANGUAGE in the OpenVMS API, and forms_c_opt_language in the portable API.
You cannot define FORMS$LANGUAGE to be a search list.
To meet the natural language requirement, a layout must specify the same natural language clause as is specified in the FORMS$K_LANGUAGE item code, the FORMS$LANGUAGE logical name, or FORMS_LANGUAGE variable. The character string specified in the layout must match either the character string to which FORMS$LANGUAGE or FORMS_LANGUAGE is defined or the FORMS$K_LANGUAGE item code; for example, if you defined
FORMS$LANGUAGE to be ‘‘english’’, the Form Manager would not select a layout that specifies ‘‘eng’’.
When comparing the character string specified in a layout to the character string specified in FORMS$LANGUAGE or FORMS$K_LANGUAGE, the Form
Manager ignores case.
Note
The Form Manager uses FORMS$LANGUAGE and FORMS$K_LANGUAGE to select a layout only. The logical name and item code do not cause the Form Manager to translate information in a layout to a new natural language clause; if literals in the layout are specified in
English, they appear in English even if FORMS$LANGUAGE or
FORMS$K_LANGUAGE and the layout specify German as the natural language clause.
You must provide form literals in the language clause in which you wish them to appear, regardless of whether you specify
FORMS$LANGUAGE and FORMS$K_LANGUAGE.
How the Form Manager Processes Requests 4–9
The Form Manager ignores natural language when selecting a layout if it does not find one of the following:
• A specified FORMS$K_LANGUAGE item code
• A translation for the logical name FORMS$LANGUAGE
The Form Manager searches for a layout by looking at all the layouts specified in the form. If no layouts match the language clause first, then the Form
Manager scans the layouts that do not specify a language clause.
VT Device Layout Selection
The Form Manager selects the layout that specifies the closest compatible device to the device specified in the enable call.
The list of supported VT devices follows in order of compatibility:
• VT100-No AVO
• VT100
• VT200
• VT200 Color
• VT300
• VT300 Color
• VT400
For example, if the enable device is a VT300 terminal and the form contains layouts for both the VT100 and VT400 terminals, the Form Manager selects the
VT100 terminal because it is more closely compatible to the VT300. The Form
Manager does not select the VT400 terminal because the VT400 capabilities are not compatible with terminals below the enable device, in this case the
VT300 terminal.
To have only one layout to service all terminals above and including a VT100, specify a VT100 as the enable device. This layout is not compatible with the
VT100-No AVO terminal.
The Form Manager evaluates VT layouts in the following order:
1. Vertical length—closest to without exceeding the vertical height of the enable device
2. Width—closest to without exceeding the width of the enable device
4–10 How the Form Manager Processes Requests
If more than one layout specifies the same device type, the Form Manager uses the vertical height (page size) of the enable device to resolve the conflict and selects the layout that specifies a vertical height closest to without exceeding that of the enable device.
If more than one layout specifies the same vertical height, the Form Manager uses the width of the layout to resolve the conflict.
If more than one layout equally satisfies all these criteria, the Form Manager selects the first such layout as defined in the IFDL.
PRINTER Layout Selection
When the Form Manager selects a PRINTER layout, it scans all %PRINTER layouts with a matching language clause for a SELECTION_LABEL match.
If it finds no match, the Form Manager scans the set of %PRINTER layouts that do not specify a language clause for a SELECTION_LABEL match. If no match is found, the Form Manager chooses the first %PRINTER layout without a language clause in the form.
Step 5: Attaching the Display Device
Once the Form Manager has selected a layout, it attempts to attach the display device specified in the display device specification argument to the ENABLE request call. If the Form Manager cannot attach the specified display device, it terminates request processing and returns an error to your application program.
Step 6: Initializing Form Data Items
During the initialization of an ENABLE request, the Form Manager assigns initial values to all form data items, including built-in form data items.
Built-in form data items are form data items to which only the Form Manager has write access.
During the initialization of an ENABLE request, the Form Manager stores the following values in the FORMNAME, SESSION, and TERMINAL built-in form data items (if they are declared in the form) as seen in Table 4–1.
How the Form Manager Processes Requests 4–11
Table 4–1 FORMNAME, SESSION, and TERMINAL Values
Form Data Item Contents
FORMNAME
SESSION
TERMINAL
The character string name of the form in the IFDL file.
The session identification string, which the Form Manager creates.
The character string name of the display device that you specified in an ENABLE request or the translation if that string is a logical name.
The Form Manager sets all other built-in form data items to spaces.
If you declare built-in form data items in your IFDL source file, you can read values from them. You must declare built-in form data items to be
CHARACTER or CHARACTER VARYING data types; you can specify any length for the data items and they can be character null-terminated.
If the value to be stored in any built-in form data items exceeds the length you declared for the form data item, the Form Manager truncates the value from the right.
If the value is shorter than the length you declared for the form data item and you declared the form data item to be the CHARACTER data type, the Form
Manager pads the value on the right with spaces.
If you declared the built-in form data item to be CHARACTER VARYING, the length of the form data item becomes the length of the value, for as long as that value is stored in the item.
4.2 Data Distribution Phase
For SEND and TRANSCEIVE requests, the second phase of request processing is the data distribution phase. During this phase, the Form Manager copies data from application program record fields to form data items. This phase is not performed for any other request.
4.2.1 Determining Where Values Are Stored
The data passed in a SEND request or the send part of a TRANSCEIVE request comes from fields in an application program record. Therefore:
• Any application program record containing data that you want to pass to the form must be logically equivalent to a form record.
• The application program record must be the same length as a form record, and it must have the same number of fields as a form record.
4–12 How the Form Manager Processes Requests
• The fields in the application program record must have the same data type, length, and dimension as the corresponding fields in the form record.
Note
All program record data is expected by the Form Manager to be byte aligned.
The Form Manager determines which application program record and form record are logically equivalent by looking at the record name argument passed in a SEND or TRANSCEIVE request call. The order of the descriptors specified in the request call must match the order of the records in the record name.
The character string in this argument must name the form record or records
(specified in a record list) that are logically equivalent to the application program record storing the values that you are passing in the request.
The correspondence between the application program record and the form record allows the form record to act as a table of contents to the application program record. The form record does not store the values passed in a request.
The values are stored in form data items. Therefore, fields in the form record must, in turn, correspond to form data items.
4.2.2 How the Data Is Distributed
When the Form Manager distributes form data, it moves the values from the application program record fields into form data items. If these form data items are displayed in panel fields, or used as panel object labels, or referenced in WHEN or FIRST clauses, the Form Manager also updates the values on the panel. (These form data items must have the same qualified names as their associated panel fields.)
If the form data items are not referenced in currently displayed panel fields, the Form Manager does not change the display.
More than one form record can be associated with each form.
Each form record consists of named record fields. A direct association is made between a record field and a form data item with the same qualified name. You associate the name of a record field with a form data item.
You can also define a panel field with the same name as the form data item to enable the operator to view the content of the record field. When no such panel field declaration exists, the application program sends and retrieves information that the operator cannot view.
How the Form Manager Processes Requests 4–13
You can override the default name association between record field and form data item by using the TRANSFER clause. This allows associations between form data and record fields other than by name. For more information on the
TRANSFER clause, see the HP DECforms IFDL Reference Manual.
If no association is established between a record field and a form data item, either by the default name association, or by use of the TRANSFER clause, the Form Manager performs a default action. For a send record, the Form
Manager ignores the contents of a record field with no association.
Note
The fields in the application program record must have the same data type, length, and dimension as the corresponding fields in the form record. When data is distributed, the Form Manager distributes record field data to a form data item by converting data. During this conversion, if the data does not match, the Form Manager returns a data conversion error.
4.2.3 Using the DATA TRANSFER Clause
You use the DATA TRANSFER clause to specify that the name of a record field in a form record should be treated as if it had a different name (which must be the same as a form data item). The DATA TRANSFER clause acts as a bridge between convenient names for record fields and convenient names for form data items.
The SOURCE clause declares that the value of the record field is to be set from a form data item when the application program requests the given form record.
The form data item can then broadcast its value to several record fields in the same form record.
The DESTINATION clause can specify that the record field value is to be copied to one or more form data items when the record is sent from the application program to the form, broadcasting its value to several form data items.
A record can have SOURCE and DESTINATION clauses pointing to different form data items to achieve special effects.
You can also use the DATA TRANSFER clause to move data and record field arrays. For more information on the DATA TRANSFER clause, see the HP
DECforms IFDL Reference Manual.
4–14 How the Form Manager Processes Requests
4.2.4 Shadow Records
In addition to the data contained within a form record, you can optionally have applications pass additional information that is associated with and describes special attributes of the record fields of the form record. The information is passed in a shadow record whose structure is directly related to the form record.
The special information is of two varieties, depending on the direction of the data transfer. Information about the modified status of the record fields can be returned to the application in a receive record, and the application can supply information as to whether last known values for modified field information should be updated.
Modified Fields
The Form Manager tracks the modified status of form data and returns this data to the application program if the program requests it in a shadow record.
You might find this data useful in deciding whether certain actions must take place based on the data returned from the form.
Because keeping track of the modified status of form data will probably degrade performance, and because you may not need to know the modified status of all form data, you can track form data items individually, or track all the form data items in a data group, or all form data items in a form. The Form
Manager saves the last known values of tracked form data items only.
Tracked data is associated with form data, which is directly connected to the record fields that are sent from and received into the program. The meaning of modified data depends upon the last known value of a form data item. The program expects a certain value for a form data item: the program knows what it has sent out to the form or what it received back from the form in a previous request. If the value being returned to the program in a receive record differs from this last known value, the value is marked as modified.
Modified data is maintained between requests. The program can send out a record field in a send request and ask for that record field back in a receive request later (perhaps several requests later).
If the value of the form data item that is associated with that record field returned has changed because of form activity (operator input, form procedural statements), the returned data states that the record field has changed.
If the value changed more than once, but the record retains its original value, the program receives data that the record field has not changed, because the value is associated with the last known value of the associated form data item.
How the Form Manager Processes Requests 4–15
Send Shadow Record
A send shadow record is a record that is sent from the application program to the form. The send shadow record contains an indicator specifying whether the record fields in the associated send record should change the last known values of form data items that were changed by the send record and are being tracked.
The send shadow record is passed by specifying the optional send-shadowrecord argument on the SEND and TRANSCEIVE request calls. In the
OpenVMS API, the shadow record must be passed by descriptor. In the portable API, use the Forms_Record_Data structure to set up the send shadow record.
There is no send-shadow-record-length argument in the OpenVMS API. The length is specified in the shadow descriptor. In the portable API, use the length field in the structure Forms_Record_Data.
The send shadow record consists of a single character. The length of the send shadow record must be 1. If the character is N (either uppercase or lowercase), the last known values of tracked form data items are not set when the form data items receive data from their associated form record fields during data distribution. If the first character is anything but N, or if a send shadow record is not specified on a SEND or TRANSCEIVE call, the last known values of form data items are set.
If a form data item is not specified as tracked, there are no associated last known values to be updated.
4.2.5 Data Conversion
If the data type of a program record field does not match the data type of its corresponding form data item, the Form Manager must convert the data in the program record field to the data type of the form data item. The Form Manager must also perform data conversion when a form data item is displayed in a panel field, and the form data item and panel field have the same qualified name during data distribution.
The Form Manager terminates request processing and returns an error to your application program if one of the following is true:
• The Form Manager cannot convert the data in a program record field to the data type of the form data item in which it attempts to store that data.
• The Form Manager cannot convert the form data item to a data type that can be displayed in a panel field.
4–16 How the Form Manager Processes Requests
• The data does not fit into the destination. In this case, a nonfatal conversion error is returned after the request has completed.
To distinguish the different conversion errors, set event logging or tracing and examine the output.
Figure 4–1 shows an exchange of information that might occur during a SEND request.
Figure 4–1 Function of the Form Manager During Data Distribution
Application Program
RECORD EMP
NAME="SMITH"
STATUS="AVAIL" retstat=FORMS$SEND(...
’EMP’,EMP...)
Form Manager Display Device
Name: SMITH
Status: AVAIL
Form
FORM RECORD EMP
NAME CHARACTER (17)
STATUS CHARACTER (17)
END RECORD
Form Data Items
SMITH
AVAIL
Name
Status
ZK−7899−GE
The following steps describe the process outlined in Figure 4–1:
1. The SEND request tells the Form Manager to move the record data defined in the EMP program record to the EMP form record. The Form Manager looks in the form for a form record named EMP, and sees that EMP is composed of the form record fields NAME and STATUS.
2. The Form Manager moves the data to the NAME and STATUS form data items. If necessary, the Form Manager converts the data to the data type of the NAME and STATUS form data items.
3. The Form Manager takes the information in the form data items NAME and STATUS and displays it on the panel fields on the display device.
How the Form Manager Processes Requests 4–17
4.3 External Response Processing Phase
The third phase of request processing for SEND and TRANSCEIVE requests, and the second phase for other requests, is the external response processing phase. The Form Manager performs this phase for each request you call from your application program. During this phase, the Form Manager processes responses and control text responses.
Section 4.3.3 explains the action that the Form Manager takes when it encounters each response step.
4.3.1 Performing Control Text Responses
One of the arguments that you can pass in a request call is send control text.
Send control text can be composed of up to five send control text items.
Each send control text item names one control text response stored in the form.
Each send control text item has a fixed five-character length. If a send control text item name is less than five characters, you must pad it with spaces. The number of valid send control text items is passed in a send control text item count argument or request option.
If a send control text item matches the name of a control text response stored in the form, the Form Manager performs that control text response. If there is no match in the form, that control text item has no effect.
You can use control text responses to cause the Form Manager to perform actions immediately before it performs the response to the request you called.
By passing a send control text item, you can directly perform a particular response. For example, you could define a send control text response that applies a highlight to a set of fields that are about to be activated for input from the operator.
4.3.2 Performing Responses to Requests
Once the Form Manager completes any control text responses that you specify, it performs the response to the request. The Form Manager performs either a default response or a response you define.
Table 4–2 explains the default responses that the Form Manager performs in response to requests.
4–18 How the Form Manager Processes Requests
Table 4–2 Default Responses
Request Default Form Manager Response
ENABLE
DISABLE
SEND
RECEIVE
TRANSCEIVE
None.
None.
None.
Perform the ACTIVATE CORRESPONDING RECEIVE
ALL response step.
If a RECEIVE RESPONSE is defined for the record name in which the Form Manager stores data from the form, that response is performed as the default
TRANSCEIVE response. If a RECEIVE RESPONSE is not defined for that record name, the Form
Manager performs the ACTIVATE CORRESPONDING
RECEIVE ALL response step.
If you want the Form Manager to perform actions other than those specified by the default response to an external request, you can declare an external response in your IFDL source file. Any response you declare overrides the default response.
For more information on defining responses, see the HP DECforms IFDL
Reference Manual.
4.3.3 Response Steps
Each response that you define consists of a set of one or more response steps.
Each response step that you include in a response causes the Form Manager to perform a particular action. This section explains the processing that each response step causes the Form Manager to perform.
ACTIVATE Response Step
The ACTIVATE response step causes the Form Manager to add one or more activation items to the activation list for subsequent input processing. The
ACTIVATE response step can specify the activation item as any of the following:
A field
A field array (or array element)
An icon
An icon array
A group
A group array (or array element)
A panel
How the Form Manager Processes Requests 4–19
All help panels for a field
A specific panel as a wait item
A wait without a panel
All panel fields
For more information about clauses you can specify with this response step to control what the Form Manager adds to the activation list, see the HP
DECforms IFDL Reference Manual.
If the Form Manager encounters the ACTIVATE response step during external response processing, it adds the necessary activation items to the bottom, or end, of the activation list. If the Form Manager encounters the ACTIVATE response step during the accept phase of processing, it inserts the necessary activation items in the activation list immediately following the current activation item.
For example, an activation list that consists of activation items for three fields might appear as follows:
1
2
3
Activation Item
Number Field Name
FIELD_A
FIELD_B
FIELD_C
If the Form Manager encountered an activate response step for a field named
FIELD_D during the processing of the activation item for FIELD_B, the activation list would appear as follows:
1
2
3
4
Activation Item
Number Field Name
FIELD_A
FIELD_B
FIELD_D
FIELD_C
The Form Manager does not add two activation items for the same panel field, panel field array element, or wait to the activation list; each panel field or panel can correspond to only one activation item. (This also holds true for icons.) However, the activation list can contain any number of unique activation items.
4–20 How the Form Manager Processes Requests
When the Form Manager activates whole panels or groups within panels, then panel fields and icons are added to the activation list in the order in which they are defined in the panel definition (not the order in which the fields and icons appear on the display device).
If all the panel fields are stored in a single panel, the Form Manager adds activation items in the order in which the panel fields are stored in the definition of that panel. If the panel fields appear on more than one panel, the Form Manager adds activation items for all the panel fields stored in the first panel in the form.
Then it adds activation items for all the panel fields stored in the second panel in the form, and so on, until all the necessary activation items have been added.
For example, suppose that the following response step appears in your IFDL source file:
ACTIVATE FIELD CLIENT ON PANEL_ONE
GROUP EMPLOYEE_INFO ON PANEL_TWO
Now suppose that CLIENT is a panel field on panel ONE and that
EMPLOYEE_INFO is a panel group on panel TWO. The EMPLOYEE_INFO group contains panel fields named STATUS, ID_NUMBER, and PHONE (in that order).
The following table shows how the Form Manager would add activation items to the activation list in response to the ACTIVATE response step shown in the preceding example:
1
2
3
4
Activation Item
Number Panel Field Name
CLIENT
EMPLOYEE_INFO.STATUS
EMPLOYEE_INFO.ID_NUMBER
EMPLOYEE_INFO.PHONE
Panel Name
CLIENT_PANEL
STATUS_PANEL
NUMBER_PANEL
PHONE_PANEL
CALL Response Step
The CALL response step causes the Form Manager to transfer control to an escape routine. You can use the following mechanisms to specify arguments in the response step to pass to the escape routine:
• BY REFERENCE
• BY DESCRIPTOR
How the Form Manager Processes Requests 4–21
• BY VALUE
• BY DEFAULT
The CALL response step uses copy-in, copy-back semantics for passing arguments. When you pass a form data item BY REFERENCE, you do not pass the address of the form data item itself: a copy of the form data item is created and that address is passed to the escape routine. This temporary data item is copied back to the form data item when the escape routine returns.
If the escape routine modifies an argument that corresponds to a form data item, the Form Manager modifies the form data item upon return to the Form
Manager from the escape routine. When control returns from the escape routine, the Form Manager continues processing the request.
For more information on the call response step and form data items, see the
HP DECforms IFDL Reference Manual. For information on writing and calling escape routines, see Chapter 2.
DEACTIVATE Response Step
The DEACTIVATE response step causes the Form Manager to remove one or more activation items from the activation list. The DEACTIVATE response step can specify the activation item as any of the following:
A field
A field array (or array element)
An icon
An icon array
A group
A group array (or array element)
An entire panel
All fields on the activation list
A wait for a specific panel
A wait without a panel.
For more information about the optional clauses you can specify with this response step, see the HP DECforms IFDL Reference Manual.
If the activation item being removed is not the current activation item, it is immediately removed from the activation list.
If the activation item that is removed is the current activation item, the Form
Manager completes the processing of that activation item by processing any field, group, or panel exit responses. Only after the applicable exit responses have been performed does the Form Manager remove the activation item from the activation list.
4–22 How the Form Manager Processes Requests
If the Form Manager does not find a specified activation item on the activation list, it ignores this item, but puts a message in the trace file (if tracing is turned on) and continues processing the response step.
DISPLAY Response Step
The DISPLAY response step causes the Form Manager to display the specified panels on the display device.
For PRINTER devices this response step causes the Form Manager to display the DDIF representation of a panel to the output DDIF document.
If you specify a viewport in the response step, the Form Manager displays the panel in that viewport.
If a panel has already been displayed, but becomes obscured or covered up, the
DISPLAY response step redisplays the panel.
If you do not specify a viewport in the response step, the Form Manager uses the viewport specified in the panel definition.
If you did not specify a viewport in either the response step or the panel definition, the Form Manager displays the panel in the default viewport for the selected layout.
On PRINTER layouts, the DISPLAY response step with the IMMEDIATE clause specifies that the currently open DDIF file be closed after the panels are downloaded to the DDIF file. The IMMEDIATE clause with the DISPLAY response step has no meaning in character-cell layouts.
ENTER HELP Response Step
The ENTER HELP response step initiates help processing. The current location on the main activation list is saved, and the help activation list is created.
After the help activation list is created, accept phase processing restarts on that list. The HELP ACTIVE elementary condition is set to true. The values of the CURRENTITEMHELPED and CURRENTPANELHELPED built-in form data items are set to the names of the current activation item (if a field or icon) and its panel.
EXIT HELP Response Step
The EXIT HELP response step sets the HELP ACTIVE elementary condition to false and switches from the help activation list to the main activation list. It does not change the current position on the main activation list. If
IMMEDIATE is specified, validation is not performed on the current HELP field.
How the Form Manager Processes Requests 4–23
The EXIT HELP response step causes the Form Manager to terminate accept phase processing for the help activation list. The Form Manager continues processing of the current activation item on the help activation list. When the current activation item passes validation, the Form Manager begins the termination check stage of accept processing.
Once the termination check is complete, accept phase processing for the help activation list finishes. The Form Manager resumes processing on the main activation list.
The IF Response Step
The IF/THEN/ELSE response step allows optional response steps to be performed based on the value of the conditional expression specified in the IF clause. When the condition is true, the Form Manager performs the response steps specified in the THEN clause. When the condition is false, the Form
Manager performs the response steps specified in the ELSE clause. When the condition is false and no ELSE clause exists, the response step has no effect.
For more information on conditional expressions, see the HP DECforms IFDL
Reference Manual.
INCLUDE Response Step
The INCLUDE response step names an internal response that is to be performed as part of the processing for the current response. The Form
Manager invokes internal responses only when it encounters an INCLUDE response step.
Use internal responses to define response steps that are used in several places in the form. Defining internal responses to perform common processing functions can result in smaller forms and improved performance.
INVALID Response Step
When the Form Manager performs accept responses (entry, exit, function, and validation responses), the INVALID response step causes the validation for the current activation item to fail. This response step also negates any POSITION response step and causes the Form Manager to perform an implicit POSITION
IMMEDIATE TO CURRENT response step.
If the Form Manager is not in the accept input phase of processing, it ignores the INVALID response step.
4–24 How the Form Manager Processes Requests
LET Response Step
The LET response step causes the Form Manager to assign a value to a form data item. The value assigned can be a literal, or the value of another form data item.
The operands that you specify must conform to the data type conversion rules specified in the HP DECforms IFDL Reference Manual. If you specify an operand that does not conform to these rules, the Form Manager terminates the request and returns an error message to your application program.
MESSAGE Response Step
The MESSAGE response step causes the Form Manager to display a character string in the message panel. If the message panel is not displayed, the
Form Manager performs an implicit DISPLAY PANEL response step before it displays the character string in the message panel.
The Form Manager supports a single message panel for each layout in a form.
This message panel has no panel fields or literals defined. The panel’s width and height are the width and height of its associated viewport. It is used by the Form Manager to display information from MESSAGE and MESSAGE
HELP response steps and from operator entry errors.
The Form Manager creates a default message panel in a default message viewport at form load time if none is defined for the selected layout. For character-cell layouts, the default viewport for the message panel is the width of the layout. The height is one line.
PRINTER layouts do not support message panels, therefore no default message panel is created.
The Form Manager treats the message panel like a scrolled region. The message panel is divided into lines and columns based on the size of the message panel and the size of the font assigned for that message panel.
Each message character string is written to the bottom of the message panel in a left-to-right direction on the bottom line of the panel and in a right-to-left direction in Hebrew layouts.
On character-cell devices, if the message character string is longer than the width of the panel, the string is word-wrapped to the next line. The current line in the message panel is scrolled up one line. The remaining characters in the message string are then written to the message panel using wordwrapping.
A word is any group of contiguous characters that lies between two word boundary characters. The word boundary characters are:
• SPACE
How the Form Manager Processes Requests 4–25
• LINE_FEED
• VERTICAL_TAB
• FORM_FEED
• CARRIAGE_RETURN
These characters are displayed, not interpreted, as control characters in this environment. If no boundary characters are found in the string, the string is broken at the length boundary of the line. The remaining characters, including the boundary character, are displayed on the next line using the previously discussed rules.
Word-wrapping of messages is supported only in character-cell layouts.
New messages are displayed at the left margin of the bottom line. Messages are displayed at the right margin in Hebrew layouts. If the bottom line is not blank, the contents of the message panel are shifted up as previously described.
You can specify the contents of the message that you want to display in the following ways:
• Pass an application program record field called MESSAGEPANEL. The contents of the record field are displayed in the message panel on the display device as soon as the Form Manager receives the record field.
The application program record field must be declared to be either the
CHARACTER, CHARACTER VARYING, or CHARACTER NULL STRING data type.
• Include a string literal in the MESSAGE response step.
• Include the name of a form data item in the MESSAGE response step. This causes the Form Manager to display the value of the form data item.
• Specify the HELP keyword. The Form Manager displays a help message associated with the current activation item. This help message may be declared at the panel field, panel group, panel, or layout level of the form.
• Include one of the Form Manager Message Codes, shown in the Table 4–3.
4–26 How the Form Manager Processes Requests
Table 4–3 Form Manager Message Codes
%CANTMOVELEFT
%CANTMOVERIGHT
%MIN_LEN_FAILS
%NODOWNOCC
%DATA_CONVERSION %NOLEFTOCC
%ENTRY_REQ_FAILS %NORIGHOCC
%FIELD_FULL
%FUNCTIONS_ONLY
%HELP_INACTIVE
%INVALID_DATE
%NOUPOCC
%NO_DOWN_ITEM
%NO_HELP_AVAIL
%NO_LEFT_ITEM
%NO_MORE_HELP
%NO_NEXT_ITEM
%NO_PREV_ITEM
%NO_RIGHT_ITEM
%NO_UP_ITEM
%RANGE_FAILS
%REQUIRE_FAILS
%SEARCH_FAILS
Online help contains explanations of these codes.
To read these explanations, enter a command in the following format:
$ HELP FORMS ERRORS message-ident
Message-ident is the abbreviation of the message. For example:
$ HELP FORMS ERRORS NO_UP_ITEM
POSITION Response Step
The POSITION response step designates which item in the activation list the Form Manager will process after completing the current activation item.
Neither the activation list nor the current activation item is modified by this response step; only the designation of the next activation item is modified.
If the Form Manager cannot find an activation item that meets the requirements of a POSITION response step, it does nothing. The Form
Manager does not return an error message. For example, if you specify
POSITION TO FIRST_FIELD and FIRST_FIELD does not correspond to any activation item, the Form Manager does nothing. If tracing is enabled, the
Form Manager puts a message in the trace file stating that it cannot find the specified activation item.
How the Form Manager Processes Requests 4–27
A relative POSITION response step is any POSITION response step that does not name:
A specific panel
A specific field
A specific icon
A specific group
FIRST ITEM
LAST ITEM
FIRST PANEL
LAST PANEL
If you are specifying a relative POSITION response step, and there is no active item, the Form Manager ignores the POSITION response step and puts a message in the trace file. This result commonly occurs if you specify relative
POSITION response steps inside an external request response before the accept phase begins.
IMMEDIATE specifies that the Form Manager not complete the current item’s validation response for the current activation item before moving to the specified activation item. However, the Form Manager does complete the processing of the response that contains the POSITION IMMEDIATE response step and any exit responses for the current activation item. You can use the
IMMEDIATE clause with any other POSITION response step clause.
For more information about the optional clauses you can specify with this response step, see the HP DECforms IFDL Reference Manual.
If you specify a POSITION response step followed by another POSITION or
POSITION IMMEDIATE response step, the latter response step overrides the former. When you specify the POSITION IMMEDIATE response step, subsequent POSITION response steps are ignored: the POSITION response step can be overridden by subsequent POSITION and POSITION IMMEDIATE response steps, but the POSITION IMMEDIATE response step can be overridden only by subsequent POSITION IMMEDIATE response steps.
PRINT Response Step
The PRINT response step causes the Form Manager to print the display contents of the specified panels. If no panels are specified in the response step, all panels displayed by the current session are printed. Each PRINT response step causes a separate page to be printed. Panel fields and all form literals are sent as part of the panels. If a panel name is specified, the specified panel or panels are downloaded to a file for printing.
4–28 How the Form Manager Processes Requests
The PRINT response step with the IMMEDIATE clause specifies that the currently open output file be closed after the panels are downloaded to the print file. The file specification of the print file is specified by the
FORMS$PRINT_FILE logical name or the FORMS$K_PRINTFILE item code in the OpenVMS API and forms_c_opt_print option in the portable API. (For more information, see Chapter 5 and Chapter 6.) This response step is valid only in character-cell layouts. To print panels in PRINTER layouts, use the
DISPLAY clause.
The PRINT response step is independent of the application program; this response step allows the form to print a panel directly without interacting with the application program. For an example of printing the current panel, see the
HP DECforms Guide to Developing an Application.
REFRESH Response Step
The REFRESH response step specifies that a designated viewport or viewports on the display be repainted.
You can specify two options for the REFRESH response step. ALL designates that all viewports for the current layout be refreshed on the display, and
Viewport-name designates that the specified viewport or viewports be refreshed on the display.
If you do not specify one of the preceding options, the Form Manager designates that the contents of the default viewport for this layout are to be refreshed.
REMOVE Response Step
The REMOVE response step causes the Form Manager to delete the specified viewports from the display. This removes the contents of panels displayed on the viewport.
You can specify any of the following optional clauses when you use the
REMOVE response step:
• ALL specifies that all viewports for the current session be deleted. The
Form Manager clears the display when REMOVE ALL is specified.
• Viewport-name specifies that the named viewport be removed from the display.
• HELP specifies that all viewports displayed during help processing be removed.
If you do not specify one of the preceding options, the Form Manager deletes the default viewport for this layout. If your layout is a framed layout, the Form
Manager deletes the Frame viewport.
How the Form Manager Processes Requests 4–29
RESET Response Step
The RESET response step causes the Form Manager to set the values of the specified form data items to their initial values. The initial value of a form data item is the value specified in the FORM DATA declaration: spaces if the form data item is a character data type, or zeros if the form data item is a numeric data type.
You can specify that a particular form data item, a group of form data items, or all form data items be reset. If any of the form data items that the Form
Manager modifies correspond to currently displayed panel fields, the Form
Manager also updates the display.
RETURN Response Step
The RETURN response step causes the Form Manager to terminate accept phase processing. The Form Manager continues processing the current activation item as normal. If the current activation item fails validation, the Form Manager begins the operator input stage of accept processing again.
When the item is validated, the Form Manager begins the termination check stage of accept phase processing. Once the termination check stage finishes, the Form Manager completes processing of the accept phase.
If you specify the IMMEDIATE clause with the RETURN response step, the
Form Manager terminates the accept phase without performing validation at the field, icon, group, or request levels. It does not perform any remaining entry responses for the current activation item. However, the Form Manager does perform exit responses at the field, icon, group, and panel levels.
You can specify a receive control text item with the RETURN response step that will be returned to your application program as part of the receive control message. Section 4.7 describes the format of receive control text messages.
If you specify a RETURN response step followed by another RETURN or
RETURN IMMEDIATE response step, the latter response step is performed.
However, when you specify the RETURN IMMEDIATE response step, all subsequent RETURN or RETURN IMMEDIATE response steps are ignored: the RETURN response step can be overridden by subsequent response steps, but the RETURN IMMEDIATE response step can never be overridden by subsequent response steps.
SIGNAL Response Step
The SIGNAL response step causes the Form Manager to send a signal to the display device. Depending on your display device and the type of signal specified, the SIGNAL response step causes the Form Manager to ring the terminal bell or put the screen into reverse video.
4–30 How the Form Manager Processes Requests
VALIDATE Response Step
The VALIDATE response step causes the Form Manager to validate the specified items on the activation list. If an item specified is not on the activation list, it is ignored.
If any named item is a grouping (array, group, panel), only those elements of the grouping on the activation list are validated. The validation response associated with the grouping is also executed. The validations performed are all declared validation clauses for the relevant items. VALIDATE response steps for those items are not executed.
The VALIDATE response step is ignored if one of the following response steps has been executed in the current context. These response steps turn off validation:
POSITION IMMEDIATE
RETURN IMMEDIATE
EXIT IMMEDIATE
INVALID
The Form Manager performs the validation as if it had validated the item during the accept phase. If the Form Manager detects a validation failure or a POSITION IMMEDIATE at the end of a field validation or at the end of any validation response, it stops further validation. A response can determine that validation failed by determining that the elementary-condition IMMEDIATE is true.
The Form Manager ignores recursive validate steps. If the Form Manager encounters a validate step during the execution of another validate step, the
Form Manager ignores the second validate step.
During validation of an activation item, the Form Manager temporarily sets certain data items to values they would hold if the Form Manager were conducting validation of the item. After the completion of the validation step, the Form Manager restores such data items to the values they held prior to execution of the validate step. The data items affected are as follows:
• CURRENTITEM, CURRENTPANEL, FIELDVALUE, FIELDIMAGE,
LOCATORITEM, and LOCATORPANEL
• The CURRENT data items for arrays
The Form Manager performs validation for activation items depending on their types. For fields, the Form Manager executes the field property validations and then zero or more validation responses. For icons, the Form Manager executes only the validation response for the object.
How the Form Manager Processes Requests 4–31
The Form Manager also executes one or more validation responses for each validation step. The Form Manager always executes an icon or field validation response for icons or fields.
If the validate step specifies an entire grouping of items, rather than a selection of items from a grouping, the Form Manager also a executes validation response for the grouping.
For more information about the VALIDATE response step, see the HP
DECforms IFDL Reference Manual.
4.4 Accept Phase
The fourth phase of request processing for SEND and TRANSCEIVE requests, and the third phase for other requests, is the accept phase. During the accept phase, the Form Manager processes the activation list. The Form Manager performs this phase for each external request you call that requires operator input. An external request requires operator input when items are activated.
If no items are placed on the activation list, no accept phase processing is done.
The activation list is composed of activation items, which are satisfied by operator input.
The four types of activation items and the operator entries that satisfy them are as follows:
• Field activation items, which correspond to panel fields, are satisfied by both data input and function input from the operator.
• Icon activation items, which correspond to icons, are satisfied by function input from an operator. An icon is an element, much like a panel field, that can contain graphics or text; however, the operator cannot enter data in an icon.
• Wait activation items, which may or may not correspond to panels that are to be displayed, are satisfied by function input from the operator.
Activation items can be added to the activation list before or during accept phase processing.
If the current activation item is a wait or icon, the Form Manager accepts only function entry from the operator. No data characters are accepted.
If the current activation item is a panel field, the Form Manager accepts input and functions from the operator:
4–32 How the Form Manager Processes Requests
• For slider fields, the input is in the form of locator actions or keyboard functions that modify the value of the slider field. A locator is a device, such as a mouse, that the operator can use to navigate the form.
• For picture fields, the data characters are validated against the input picture defined for the panel field.
• For text fields, the data is entered into the field with no picture character validation.
Text fields can contain multiple lines of data.
Each input picture is composed of one or more edit picture characters. These edit picture characters define the character range permitted for the particular data position in the field. Validation of input is performed differently for different layouts:
• Character-cell layouts
Character-by-character validation is performed; the operator’s input is validated against the edit picture character as each character is typed.
Insertion literals need not be typed. If the character is not acceptable, an error is signaled and a message is displayed in the message panel.
For more information about edit picture characters, see the HP DECforms
IFDL Reference Manual.
• PRINTER layouts
Because PRINTER layouts are output only, the Form Manager never enters the accept phase when processing PRINTER layouts.
The Form Manager starts the accept phase by determining which activation item it should process first. Usually, the Form Manager processes the first item on the activation list. However, if you specify POSITION response steps that are performed during the external response processing phase, these response steps control which activation item the Form Manager processes first.
When the Form Manager encounters POSITION response steps during the external response phase, it begins the accept phase by processing the item specified in the last POSITION response step performed during the external response processing phase.
The POSITION response step does not modify the order of items on the activation list. The POSITION response step controls only which activation item is processed first.
How the Form Manager Processes Requests 4–33
The Form Manager continues the accept phase by processing each activation item on the activation list. The POSITION response steps that the Form
Manager encounters during the accept phase control the order of activation item processing.
Each function that the operator invokes to satisfy an activation item should contain a POSITION response step. These response steps indicate to the Form
Manager into which item the operator will enter input next. Certain conditions can alter the order in which the Form Manager processes the activation list.
Section 4.4.16 discusses these conditions.
4.4.1 Form Data Assignment Stage
The first stage in activation item processing is the form data assignment stage.
During this stage, the Form Manager assigns values to the following built-in form data items:
• CURRENTITEM
• CURRENTPANEL
• FIELDIMAGE
• FUNCTIONNAME
• LOCATORITEM
• LOCATORPANEL
If the Form Manager is processing a field or icon, it stores the name of the item for which input is needed in the CURRENTITEM and LOCATORITEM built-in form data items. It also sets the FIELDIMAGE built-in form data item for picture and text fields to the value that is displayed in the field.
If the Form Manager is processing a wait activation item, it stores the name of the panel to be displayed in the CURRENTITEM, LOCATORITEM,
LOCATORPANEL, and CURRENTPANEL built-in form data items and sets the FIELDIMAGE and FUNCTIONNAME built-in form data items to spaces.
If the Form Manager is processing a wait activation item that is not associated with a panel, it sets the CURRENTITEM, LOCATORITEM, LOCATORPANEL, and CURRENTPANEL built-in form data items to spaces.
4–34 How the Form Manager Processes Requests
4.4.2 Panel Entry Response Stage
If the current activation item is a panel, field or icon on a panel, the Form
Manager looks for a panel entry response for that panel.
The Form Manager performs any panel entry response you declared for that panel if one of the following is true:
• The accept phase is just beginning.
• The current activation item is a panel other than the panel that is associated with the previous activation item.
• The current activation item is contained in a panel that is different from the panel that contains the previous activation item processed.
For example, suppose the previous activation item is a panel field on panel
ONE. If the current activation item is a panel field on panel TWO, the
Form Manager performs the panel entry response stage for panel TWO.
If you do not declare a panel entry response, the Form Manager skips this stage of activation item processing.
4.4.3 Group Entry Response Stage
If the current activation item is a member of a group, the Form Manager performs any entry response you declared for that group when one of the following is true:
• The accept phase is just beginning.
• The item that is the current activation item belongs to a different group than the item that is the previous activation item.
For example, suppose the previous activation item is a panel field in group
A. The Form Manager performs the group entry response for group B when the current activation item is a panel field in group B.
• The previous activation item does not belong to this group.
If you do not declare a group entry response, or if the current activation item is not in a group, the Form Manager skips this stage of activation item processing.
Fields, and icons can be nested within up to two levels of groups. When processing group entry responses, the Form Manager executes entry responses for each group that is being entered relative to the previous activation item.
The order of execution of entry responses is from outermost group to innermost group.
How the Form Manager Processes Requests 4–35
4.4.4 Field Entry Response Stage
If the current activation item is a panel field for which you declared an entry response, the Form Manager performs that response immediately before soliciting input from the operator.
If you do not declare an entry response for the field or icon, the Form Manager skips this stage of activation item processing. If you are performing input on the same item as the previous item (as is the case if validation fails), the Form
Manager also skips this stage of activation item processing.
4.4.5 Operator Input Stage
During the operator input stage, the Form Manager accepts operator input to satisfy the activation item.
If the Form Manager is processing a field activation item, the operator can enter data in the panel field and issue functions to satisfy the activation item.
As the operator enters data, the Form Manager validates the data.
On character-cell devices, the Form Manager interprets picture strings and the editing clause for numeric data items as the operator enters data. If the user enters a character that does not match that specified by the picture string, the
Form Manager outputs a message to the message panel indicating an error.
The Form Manager then continues to accept input data.
After operator input, the FIELDIMAGE built-in form data item is modified to reflect the operator input.
When the operator enters a function to complete entry into the panel field or icon that is the field activation item, the Form Manager stores the name of the function in the FUNCTIONNAME built-in form data item.
The Form Manager does not change the values in the FIELDIMAGE built-in form data item when it is processing a wait or an icon.
Any error messages generated by data or functions that the operator enters are displayed in the message panel on the display device; these errors do not terminate request processing.
Before the Form Manager can exit from the operator input stage, the operator must enter a valid function other than one of the following intrafield editing functions:
• CURSOR LEFT
• CURSOR RIGHT
• CURSOR UP
4–36 How the Form Manager Processes Requests
• CURSOR DOWN
• DELETE CHARACTER
• INSERT OVERSTRIKE
• ERASE FIELD
For information about editing functions, see the HP DECforms IFDL Reference
Manual.
4.4.6 Data Conversion Stage
If the activation item being processed is a field activation item, the Form
Manager attempts to convert the field’s value displayed in the panel field to the data type of its corresponding form data item.
If the conversion is unsuccessful, the Form Manager displays a message on the message panel. The operator input stage begins again unless the IMMEDIATE clause has been specified with a RETURN or POSITION response step.
If the IMMEDIATE clause has been specified, the Form Manager does one of the following:
• Returns control to the application program, as specified by the RETURN
IMMEDIATE response step
• Begins processing the activation item specified in the POSITION
IMMEDIATE response step
If the current activation item is not a field activation item, the Form Manager skips this stage of activation item processing.
4.4.7 Function Response Stage
During the function response stage, the Form Manager performs the default response steps specified for the function the operator entered. You can specify actions other than this by defining a special function response. The HP
DECforms IFDL Reference Manual describes special function responses.
4.4.8 Field Validation Stage
During the field validation stage, the Form Manager performs any validation that you specified for the item in the item declaration of your IFDL source file. For example, you may have specified that the Form Manager checks that the picture field is of a specified minimum length, that the data and function entry meet the requirements of the panel field, and so on. If any validation clause fails, the Form Manager displays a message on the message panel and performs an implicit INVALID response step.
How the Form Manager Processes Requests 4–37
If the current activation item is not a field or icon activation item, the Form
Manager skips this stage of activation item processing.
4.4.9 Field Validation Response Stage
During the field validation response stage, the Form Manager performs any validation response that you declared for the field. In a validation response, you can specify validation beyond that specified in the field declaration. If the
Form Manager encounters an INVALID response step when it is processing a validation response, it does not perform any further validation responses.
However, it does process any exit responses for the field.
When the Form Manager is processing a field or icon activation item, it performs the field validation response stage if one of the following is true:
• The operator has entered a function that contains a POSITION response step that indicates another activation item as the next activation item to be processed.
• Accept phase processing is being terminated.
If the Form Manager does not encounter an INVALID response step while processing this stage, it assumes that the item is valid.
If you did not declare a validation response, if the current activation item is not a field or icon activation item, or if the next activation item is the same as the current activation item, the Form Manager skips this stage of activation item processing.
4.4.10 Field Exit Response Stage
When the Form Manager is processing a field, or an icon activation item, it performs the field exit response stage if one of the following is true:
• The operator has entered a function that contains a POSITION response step that indicates another activation item as the next activation item to be processed.
• Accept phase processing is being terminated.
The Form Manager performs the exit response even if it is processing a
POSITION IMMEDIATE or RETURN IMMEDIATE response step.
If the Form Manager is not processing a field or icon activation item, or if you did not declare an exit response for the item, the Form Manager skips this stage of activation item processing.
4–38 How the Form Manager Processes Requests
4.4.11 Group Validation Response Stage
During the group validation response stage, the Form Manager performs any validation response you declared for a group if one of the following is true:
• The next activation item is in a group other than the group that contains the current activation item.
For example, suppose the current activation item is a panel field in group
A. The Form Manager performs the group validation stage for group A when the next activation item to be processed is a panel field in group B.
• The next activation item is an entity that is not in a group.
• The Form Manager is terminating accept phase processing.
If the Form Manager encounters an INVALID response step when it is processing a group validation response, it does not perform any further validation responses. However, it does process any exit responses that you declared for the item.
If the Form Manager does not encounter an INVALID response step while processing this stage, it assumes that the group is valid.
If you did not declare a group validation response or if the current activation item is not in a group, the Form Manager skips this stage of activation item processing.
4.4.12 Group Exit Response Stage
If the current activation item is a field or icon that is a member of a group, the
Form Manager performs any exit response you declared for that group if one of the following is true:
• The next activation item is an item in a group other than the group that contains the current activation item.
For example, suppose the current field activation item is a panel field in group A. The Form Manager performs the group exit response for group
A when the next field activation item to be processed is a panel field in group B.
• The next activation item is an item that is not in a group.
• The Form Manager is terminating accept phase processing.
The Form Manager performs the group exit response even if it is processing a
POSITION IMMEDIATE or RETURN IMMEDIATE response step.
For nested groups, group validation and group exit responses execute in turn, inner group first, then outer group, for each level of nested group being exited.
How the Form Manager Processes Requests 4–39
If you did not declare a group exit response or if the Form Manager is not processing an item in a group, the Form Manager skips this stage of activation item processing.
4.4.13 Panel Validation Response Stage
During the panel validation response stage, the Form Manager performs any validation response you declared for a panel if both of the following are true:
• The current activation item is active.
• No INVALID, POSITION IMMEDIATE, EXIT IMMEDIATE, or RETURN
IMMEDIATE was executed.
If any of the following are true, the Form Manager interprets the panel validation response of the panel of the current activation item:
• The next item is on another panel.
• The next item is not associated with a panel (it is a wait without a panel).
• An EXIT IMMEDIATE or a RETURN IMMEDIATE response step was executed.
• An EXIT or RETURN response step without IMMEDIATE has been executed previously and no INVALID step has been executed since.
If the Form Manager encounters an INVALID response step when it is processing a panel validation response, it does not perform any further validation responses. However, it does process any exit responses that you declared for the item.
If the Form Manager does not encounter an INVALID response step while processing this stage, it assumes that the panel is valid.
If you did not declare a panel validation response or if the current activation item is not in a panel, the Form Manager skips this stage of activation item processing.
After interpreting the response, the Form Manager goes to the next activation item.
4.4.14 Panel Exit Response Stage
During the panel exit response stage, the Form Manager performs the exit response you declared for the panel associated with the current activation item if one of the following is true:
• The next activation item is a panel other than the panel that is the current activation item.
4–40 How the Form Manager Processes Requests
• The next activation item is on a different panel than the panel that contains the item that is the current activation item.
For example, suppose the current activation item is a panel field on panel
ONE. The Form Manager performs the panel exit response stage for panel
ONE when the next activation item is a panel field on panel TWO.
• The Form Manager is terminating accept phase processing.
The Form Manager performs the panel exit response even if it is processing a
POSITION IMMEDIATE or RETURN IMMEDIATE response step.
If you did not declare a panel exit response, the Form Manager skips this stage of activation item processing.
4.4.15 Termination Check Stage
The Form Manager performs the termination check stage if both of the following are true:
• A RETURN response step was executed in a previous response.
• There are items on the activation list.
During the termination check stage, the Form Manager validates each item on the activation list. This process includes performing field validation clauses, and performing validation responses for fields, icons, groups, and panels.
Validation clauses and validation responses can be performed multiple times for each item on the activation list, because each item can be validated while it is active and when the accept phase is terminated.
During this stage, the Form Manager also performs any validation response that you defined in the REQUEST VALIDATION external response. If the activation list is empty, no validation checks are performed.
If any validation check fails, the request termination is canceled and the accept phase continues with the next activation item.
The next activation item is determined as follows:
• If the failure is due to a field validation clause, there is an implicit
INVALID for the field that failed validation, which causes a POSITION
IMMEDIATE TO CURRENT ITEM to occur.
• If the failure is due to a validation response, the INVALID and POSITION steps in the response determine the next item.
If all validation checks succeed, the Form Manager resets the contents of the
CURRENTITEM, FUNCTIONNAME, and FIELDIMAGE built-in form data items to spaces and terminates the accept phase.
How the Form Manager Processes Requests 4–41
4.4.16 Altering the Order of Activation Item Processing
Usually, the Form Manager processes activation items as indicated by
POSITION response steps. However, some conditions can cause this general order of activation item processing to be modified.
The Form Manager performs special processing if one of the following is true:
• A function response does not specify a POSITION response step.
If a function response does not specify or imply a POSITION response step, the Form Manager begins processing the current activation item again.
When this occurs, the Form Manager returns to the operator input stage.
The Form Manager continues processing this activation item until the operator enters a function that contains a POSITION response step.
• A function response contains a POSITION IMMEDIATE or RETURN
IMMEDIATE response step.
When the Form Manager encounters a POSITION IMMEDIATE or
RETURN IMMEDIATE response step, it skips the validation stages for the current activation item. However, the Form Manager does perform any field, group, icon, or panel exit responses.
Only after the exit responses have been performed does the Form
Manager begin processing the next current activation item (POSITION
IMMEDIATE) or return control to your application program (RETURN
IMMEDIATE).
• The Form Manager encounters a RETURN or EXIT HELP response step.
When the Form Manager encounters a RETURN response step, it returns control to your application program after completing validation successfully.
The Form Manager stops processing the current activation list, even though it may not have processed some activation items on the current activation list.
The Form Manager continues processing the current activation item as normal. If the item associated with the current activation item fails validation, the Form Manager begins the operator input stage of accept processing again. When the item is validated, the Form Manager begins the termination check stage of accept phase processing. Once the termination check stage completes, the Form Manager terminates request processing and returns control to your application program.
• The Form Manager cannot validate input because of an operator entry error or an INVALID response step.
4–42 How the Form Manager Processes Requests
If the Form Manager cannot complete processing because of an operator input error or an INVALID response step, it returns to the operator input stage of activation item processing and continues processing the current activation item.
• The Form Manager encounters a DEACTIVATE response step.
If it encounters the DEACTIVATE response step, the Form Manager alters the activation list. The DEACTIVATE response step removes activation items from the activation list.
If the activation item being removed is not the current activation item, the
Form Manager immediately removes it from the activation list.
If the activation item that is removed is the current activation item, the Form Manager completes the processing of that activation item by processing any field, group, icon, or panel exit responses. Only after the applicable exit responses have been performed does the Form Manager remove the activation item from the activation list.
• The PROTECTED WHEN attribute of an item has become true.
If an item becomes protected because the PROTECTED WHEN attribute for that item is true, the Form Manager cannot process that activation item until it is unprotected. Therefore, it skips the activation item that is the protected item. The Form Manager determines which activation item to process next by searching the activation list for an item that is not protected.
When the Form Manager looks through the activation list for an activation item that is eligible for input, it begins with the activation item immediately following the one it could not process. If that activation item is eligible for input, the Form Manager processes that item. Otherwise, it searches forward through the activation list until it encounters either an activation item that is eligible for input or the end of the activation list.
If the Form Manager reaches the end of the activation list without finding an activation item that is eligible for input, it begins to look backward in the list. Starting from the point at which it began its forward search, the
Form Manager searches backward until it encounters either an activation item that is eligible for input or the beginning of the activation list.
If the Form Manager reaches the beginning of the activation list without finding an activation item that is eligible for input, it processes any field, group, icon, or panel exit responses for the current activation item, and terminates accept phase processing. The Form Manager terminates accept phase processing by performing the termination check stage of activation item processing.
How the Form Manager Processes Requests 4–43
The activation item that is a protected item is not removed from the activation list. It may become unprotected, and therefore eligible for input, later during activation list processing. If the Form Manager encounters the activation item after the item is unprotected, it processes the activation item.
4.4.17 Help Processing
DECforms software provides you with two ways to provide help for your users.
Both ways use response steps and the activation list. The first, and simpler way of specifying help, is to use the DECforms defaults. The second method is to use customized help.
If you use the DECforms defaults, you can specify two levels of help by declaring help messages and help panels in your form that the Form Manager displays at specified times during form processing. These declarations do not apply to PRINTER layouts.
You can declare help messages on panels, fields, groups, icons, and layouts within your form by using the USE HELP message clause. When you declare a USE HELP message clause within your form, the clause that you specify is displayed in the message panel when a MESSAGE HELP response step is executed.
By default, a MESSAGE HELP response step is executed when the user presses the function key defined as the Help key. (Different keys can be specified as Help keys. Depending on which terminal you have, DECforms software provides a default key as the Help key. For more information, see the appendix section of the HP DECforms IFDL Reference Manual.)
The help message is the first level of help. You can also specify a help panel for a form element, which gives the user another level of assistance after the help message has been displayed. You specify a help panel on a form element by declaring the USE HELP PANEL clause within a field, group, icon, layout, or panel declaration, and by declaring a help panel.
In a HELP PANEL declaration, you can specify the viewport in which the help panel is to be displayed, the display attributes for the help panel, and the responses that occur when functions are invoked. You can also specify a help message for the help panel. You cannot specify a USE HELP PANEL clause within a HELP PANEL declaration. For more information on how to declare a help panel, see the HP DECforms IFDL Reference Manual
4–44 How the Form Manager Processes Requests
4.4.17.1 Starting Help Processing
With the DECforms defaults, when the user presses the Help key the first time, the Form Manager starts help processing by executing the NEXT HELP builtin function response. The NEXT HELP built-in function response specifies that if a help message is available for this form element, execute the MESSAGE
HELP response step. The MESSAGE HELP response step displays the help message (the message clause you specified in your form as the USE HELP message clause) in the message panel.
The next time a user presses the Help key, the NEXT HELP built-in function response executes, and because the help message has already been displayed, an ENTER HELP response step is executed. The ENTER HELP response step sets the elementary condition HELP ACTIVE to true and creates a help activation list.
If after exiting help the user presses the Help key a third time, the Form
Manager displays a "No help available" message.
4.4.17.2 How the Help Activation List Works
The help activation list is similar in some ways to the main activation list. The help activation list is created when an ENTER HELP response step is executed and is deleted when help is exited.
When the Form Manager processes the ENTER HELP response step, it checks to see if a help panel exists for the current help activation item. The Form
Manager starts searching up the form hierarchy for help.
If the current help activation item is a field or icon and you have help specified at the panel level, the Form Manager displays that higher level help, unless the form item is explicitly declared as having NO HELP.
If NO HELP is omitted, the Form Manager continues searching upward until it reaches the top level of the hierarchy. If it reaches the top level and finds no help, the Form Manager displays the message, "No help available".
If the help panel has no fields, or if all the fields on the help panel are protected, the Form Manager will either activate a wait on the help panel or display the help panel depending on the display device.
If there are any unprotected items on the help panel, the Form Manager activates the panel, and then activates the items in the order specified in the
PANEL declaration.
How the Form Manager Processes Requests 4–45
4.4.17.3 Using DECforms Defaults
Suppose you have a form that contains panel ACCOUNT. Field WITHDRAW is on panel ACCOUNT. There is a help panel associated with WITHDRAW and another associated with ACCOUNT. When the user asks for help on Field
WITHDRAW, he gets a help message, and then the help panel associated with WITHDRAW. If he presses the Help key a third time, the Form Manager displays the message, "No help available".
If there is no help specified for field WITHDRAW, when the operator presses the Help key, the Form Manager checks to see if help is declared at this level in the form. The Form Manager finds no help message for WITHDRAW. The
Form Manager begins searching up the form hierarchy for help, and when it encounters the help panel for panel ACCOUNT, it displays that help panel.
After the Form Manager displays the panel ACCOUNT help panel, it returns you to the place in the form where you were before help processing began.
4.4.17.4 Customized Help
If the default method of help processing does not provide you with the help you want, use response steps, elementary conditions, the main activation list, and the help activation list to create your own help processing. Appendix A provides information on help conditions.
The HP DECforms IFDL Reference Manual describes built-in help responses.
The following example illustrates customized help processing.
Field DATA_TYPE
Line 4
Column 18
Output Picture X(50)
Use Help Message
"Enter the VAX data type for the field’s data" -
" item. Press HELP for a list of valid data " -
" types or SELECT to choose from a list."
Use Help Panel
CREATE_FIELD_HELP_DT_PANEL
End Field
.
.
.
Help Panel CREATE_FIELD_HELP_DT_PANEL
Viewport HELP_VP
Display
%Keypad_Application
4
5
1
2
3
4–46 How the Form Manager Processes Requests
1
2
3
4
5
6
7
8
9
1 0
1 1
Entry Response
Activate
Panel CREATE_FIELD_HELP_PANEL
Panel CREATE_FIELD_HELP_PIC_PANEL
Panel FUNCTION_KEY_HELP_PANEL
Position To Icon DISMISS_ICON On
CREATE_FIELD_HELP_DT_PANEL
End Response
Picture field DATA_TYPE is declared.
6
7
8
9
1 0
1 1
A help message for field DATA_TYPE is specified in the Use Help Message.
Use Help Panel specifies a help panel, CREATE_FIELD_HELP_DT_
PANEL.
Panel CREATE_FIELD_HELP_DT_PANEL is declared.
CREATE_FIELD_HELP_DT_PANEL is displayed in Viewport HELP_VP.
Up to this point, this is standard DECforms help processing.
An entry response within CREATE_FIELD_HELP_DT_PANEL is declared.
An ACTIVATE response step is declared, specifying additional panels to be activated on the help activation list while help is active.
CREATE_FIELD_HELP_PANEL is activated.
CREATE_FIELD_HELP_PIC_PANEL is activated.
FUNCTION_KEY_HELP_PANEL is activated. When these help panels are activated, they are placed on the help activation list. Within each help panel, you can specify other responses, if desired.
Position To Icon DISMISS_ICON on CREATE_FIELD_HELP_DT_PANEL returns you to an icon in the help panel.
In the previous example, entry responses were used to activate additional items on the help activation list other than those declared on the initial help panel. While the help activation list is active, all ACTIVATE, DEACTIVATE, and POSITION response steps take place on the help activation list.
To customize your form’s help processing, you must begin with a response, from which you can specify response steps. Within the response steps, you can check the elementary conditions that directly affect help.
These conditions are:
• HELP ACTIVE
• HELP MESSAGE EXISTS
How the Form Manager Processes Requests 4–47
• HELP PANEL EXISTS
• HELP MESSAGE AVAILABLE
For more information on responses and response steps, see the HP DECforms
IFDL Reference Manual. For more information on elementary conditions, see
Appendix A.
4.5 Request Exit Response Phase
During this phase of processing, the Form Manager executes the exit response declared as a REQUEST EXIT RESPONSE in the external response for the current request.
A REQUEST EXIT RESPONSE is useful when request completion activities need to be done in the form. For example, a REQUEST EXIT RESPONSE can reset the values of certain form data items that are used within the request, so that they are in a known state when the next request is issued.
4.6 Form Data Collection Phase
The sixth phase of request processing for TRANSCEIVE requests, and the fifth phase for RECEIVE requests, is the form data collection phase. (The Form
Manager performs this phase only for RECEIVE and TRANSCEIVE requests.)
During this phase, the Form Manager moves data from form data items to record fields. (You can think of this phase as being the opposite of the data distribution phase explained in Section 4.2.)
For a receive record, the Form Manager supplies values for record fields with no associated form data: blanks for alphanumeric record fields and zeros for numeric record fields.
If the data type of a form data item does not match the data type of its corresponding record field, the Form Manager must convert the data in the form data item to the data type of the record field.
If the data in the form data items cannot be converted to the data type of the record fields, the Form Manager terminates the request and returns an error to your application program. If a fatal data conversion error occurs, the Form
Manager does not alter the data in the record field in which the error occurred.
4–48 How the Form Manager Processes Requests
4.6.1 How Form Data Is Collected
When the Form Manager collects form data, it moves the values from the form data items into the application program record fields. During data collection, any record field or record field array element that does not receive data from a form data item or form data array element is set to a default.
Record fields and form record field array elements that are defined to contain alphanumeric data are set to spaces by default during data collection.
Record fields and record field array elements that are defined to contain numeric data are set to zeros during data collection. Record fields and record field array elements that are defined to contain date/time data are set to appropriate fields from midnight on November 17, 1858, the Smithsonian base date.
Note
The fields in the form record must have the same data type, length, and dimension as the corresponding fields in the application program record.
4.6.2 Data Conversion
If the data type of a form data item does not match the data type of its corresponding program record field, the Form Manager must convert the data in the form data item to the data type of the program record field.
If the Form Manager cannot do this, it terminates request processing and returns an error to your application program.
4.6.3 Using the TRANSFER Clause
Use the TRANSFER clause to specify that the name of a form data item should be treated as if it had a different name (which must be the same as a record field in a form record). The TRANSFER clause acts as a bridge between convenient names for record fields and convenient names for form data items.
The TRANSFER clause has other special uses. The SOURCE clause declares that the value of the record field is to be set from a form data item when the application program requests the given form record. The form data item can then broadcast its value to several record fields in the same form record. A record can have SOURCE and DESTINATION clauses pointing to different form data items to achieve special effects.
How the Form Manager Processes Requests 4–49
You can also use the TRANSFER clause to move data and record field arrays.
For more information on the TRANSFER clause, see the HP DECforms IFDL
Reference Manual.
4.6.4 Shadow Records
In addition to the data contained within a form record, applications can optionally pass additional information that is associated with and describes special attributes of the record fields of the form record. When this information is used, it is passed in a shadow record whose structure is directly related to the form record.
The special information is of two varieties, depending on the direction of the data transfer. The application can get information about the modified status of the record fields returned in a receive record and it can supply information as to whether the last known values for modified field information should be updated.
Modified Fields
The Form Manager tracks the modified status of form data and returns this data to the application program if the program requests it in a shadow record.
The application program may find this data useful in deciding whether certain actions must take place based on the data returned from the form.
Because keeping track of the modified status of form data might degrade performance in most implementations, and because you may not need to know the modified status of all form data, you can track form data items individually, or track all the form data items in a data group, or track all the form data items in a form. The Form Manager saves the last known values of tracked form data items only.
Modified data is associated with form data, which is directly connected to the record fields that are sent from and received into the program. What modified data means depends upon the last known value of a form data item. The program has an expectation of the value of a form data item: the program knows what it has sent out to the form or what it received back from the form in a previous request. If the value being returned to the program in a receive record is different from this last known value, the value is marked as modified.
Modified data is maintained between requests. The program can send out a record field in a send request and later ask for that record field back in a receive request (perhaps several requests later). If the value of the form data item that is associated with that record field returned has changed because of any form activity (operator input, form procedural statements, data transfer) the returned data states that the record field has changed. If the value changed, the program receives data that the record field has not
4–50 How the Form Manager Processes Requests
changed, because it is associated with the last known value of the associated form data item.
4.6.5 Receive Shadow Records
You may wish to track modified data in your application. During form data collection, the receive shadow record can be used to track such data.
The receive shadow record consists entirely of characters, and its length is
1 plus the number of record fields that the form record contains. The first character of the shadow record specifies the modified status of the entire record. If any record field in the record has been modified, the first character indicates that the record has been modified; if no record field has been modified, the first character indicates that the record has not been modified.
After the first character, the shadow record contains a single character for every record field in the record being returned. The correspondence between the shadow record and the received record is by ordinal position of record fields in the received record and ordinal position of characters in the shadow record, with an offset of 1, because of the additional character at the start of the shadow record.
A character returned in the field part of a shadow record is either 0 (record field not modified), X (the form did not request that modified data be kept for the record field, so the Form Manager has no status to report), or 1 (record field modified). If all field characters are 0, the first character of the shadow record (status for the entire record) is 0. If all field characters are either 0 or
X, the first character is X. If any field character is 1, the first character is 1.
For example:
FORM DATA
B CHARACTER(15) TRACKED
C INTEGER (1) TRACKED
D INTEGER (2) TRACKED
END DATA
FORM RECORD ELVIS
B CHARACTER(15)
C INTEGER (1)
D INTEGER (2)
END RECORD
The record ELVIS is 18 bytes long. Its shadow record is 4 bytes: 1 for the entire record and 1 for each of the record fields.
How the Form Manager Processes Requests 4–51
FORM DATA TRACKED
A INTEGER(4)
GROUP G1 OCCURS 5
GROUP G2 OCCURS 3
END GROUP
B CHARACTER(15)
END DATA
D INTEGER(2)
END GROUP
FORM RECORD ELVIS2
A INTEGER(4) IMPLICIT SIGN
GROUP G1 OCCURS 5
GROUP G2 OCCURS 3
D INTEGER(2)
END GROUP
END GROUP
B CHARACTER(15)
END RECORD
The record ELVIS2 has 49 data bytes. Its shadow record has 20 bytes: 1 for the entire record, 1 for A, 15 for the two-dimensional array G1.G2.D, 1 for B, and 2 for the sign character.
To see if record fields have been changed, a program can look at particular parts of a record by defining an appropriate shadow record structure in the program and asking the appropriate question on that structure.
For example, in COBOL:
01 ELVIS2-SHADOW
03 A
03 G1
05 G2
03 B
07 D
PIC X.
OCCURS 5.
OCCURS 3.
PIC X.
PIC X.
In the COBOL procedure section, the programmer could then write:
IF D(3,2) OF ELVIS2-SHADOW = "1" THEN
<change code for element D(3,2)>.
IF G1(3) OF ELVIS2-SHADOW NOT = "000" THEN
<change code for row 3>.
For some requests, the program might not affect the last known value of form data, especially in a program that is an escape routine making recursive requests on the Form Manager. Values passed to and from the form by the escape routine can effect form data, which would cause the last known value to be updated. If you choose not to change the last known value in the OpenVMS
API, the escape routine can run transparently to the main requester.
4–52 How the Form Manager Processes Requests
If no receive shadow record is supplied on a request, the Form Manager does not assume that the program knows about the change in a form data item’s value; specifically, the Form Manager does not update the last known value in the form for the record fields in a receive record unless it also passes a receive shadow record.
Similarly, a request may specify, in the first character of a send shadow record, that it does not want the values in the receive record to update the last known values in the form. If an N (either uppercase or lowercase) is specified in the first byte of the shadow record, the Form Manager does not update the last known value; if any other character is specified in the first byte, the last known value is updated. Figure 4–2 shows the exchange of information that can occur during a RECEIVE request.
Figure 4–2 Function of the Form Manager During Data Collection
Form Manager Application Program
RECORD EMP
NAME="SMITH"
STATUS="AVAIL" retstat=FORMS$RECEIVE(...
’EMP’,EMP...)
Form Data Items
SMITH
AVAIL
Name
Status
Form
FORM RECORD EMP
NAME CHARACTER (17)
STATUS CHARACTER (17)
END RECORD
ZK−7900−GE
The following steps describe the process outlined in Figure 4–2:
1. The RECEIVE request asks that data stored in the form data items that correspond to the EMP form record be returned to the application program.
2. The Form Manager looks in the form for a form record EMP, and sees that
EMP is composed of the form record fields NAME and STATUS.
3. The Form Manager moves the values in the form data items NAME and
STATUS to the NAME and STATUS application program record fields. If necessary, the Form Manager converts the data in the form data items to the data type of the record fields.
How the Form Manager Processes Requests 4–53
4.6.6 Data Transfer of Arrays
When data transfer takes place during data distribution and data collection; and the record fields, or form data items, or both are arrays; the amount of data that is transferred depends on the dimensions of the record fields and form data items involved.
The following rules explain how data is transferred between a record field and a form data item during data distribution and data collection, when one or both are arrays:
• When either the record field or the form data item that takes part in a data transfer is a whole array (as opposed to an array element), only a single data value is transferred between the record field and the form data item.
The Form Manager uses the lowest subscripted member of the array in the transfer. The remaining members of the array are not transferred.
For example, if record field G1.A is not an array and it transfers to or from form data item G1.A, which is a one-based array that occurs five times, only element G1.A (1) of the form data array is transferred to and from record field G1.A. The other four elements of the form data array G1.A are not transferred.
• When both the record field and the form data item are arrays of the same dimension and contain the same number of array elements in each dimension, elements are transferred directly from one array to the other.
The element with the lowest subscript of each array is transferred first, the element with the second lowest subscript is transferred second, and so forth.
• When both the record field and the form data item arrays are twodimensional but the size of the two arrays is different (the OCCURS clauses specify a different number of occurrences), the number of elements that are transferred is the minimum of the number of occurrences in each dimension for each array, independent of all other dimensions.
Given that DECforms arrays are always in row major order, the Form
Manager transfers rows of the record field and form data arrays as if they were one-dimensional arrays:
1. The Form Manager transfers the first row of the record field and form data arrays until one of the arrays has no more elements in its row.
2. The Form Manager transfers the second row of each array until one of the arrays has no more elements in its second row.
4–54 How the Form Manager Processes Requests
3. The Form Manager continues transferring rows of the record field and form data arrays in this manner until one of the arrays has no more rows to transfer.
If the form data array is shorter than the form record array, the remainder is filled with default characters.
• When one of the arrays (either the record field array or the form data array) is one-dimensional and the other is two-dimensional, the Form
Manager treats the one-dimensional array as a two-dimensional array, with the first dimension being of size 1 (as if OCCURS 1 were specified for the outermost group of two nested, multiply occurring groups). The Form
Manager proceeds as if both arrays are two-dimensional but the size of the two arrays is different.
For example, if record field G1.A is a one-dimensional array and form data item G1.G2.A is a two-dimensional array, the Form Manager treats the first row of the form data array G1.G2.A as a one-dimensional array and proceeds as if both are one-dimensional arrays. The transfer is made to or from only one row of the two-dimensional form data array G1.G2.A, with no wraparound to the beginning of the next row.
Because of the way the Form Manager performs data transfer of arrays, not all elements of a record field array may actually be transferred to or from a form data array during data distribution or data collection.
4.7 Request Termination Phase
The last phase of external request processing for all requests is the terminate request phase. The Form Manager performs this phase of processing for each external request that you call, although the Form Manager performs special termination processing on a DISABLE call. This phase completes the request and returns control to your application program.
The Form Manager returns a value to the return status variable for the external request. This value is the OpenVMS condition value of the most severe error that the Form Manager encountered during processing in the
OpenVMS API. In the portable API, the Forms Manager returns a FIMS error number representing the most severe error.
The Form Manager performs special termination processing on a DISABLE call. First, the Form Manager unloads the form. After it unloads the form, the
Form Manager detaches the display device. The session is then terminated, along with the existing form data.
How the Form Manager Processes Requests 4–55
If you passed receive control text in your request call, the Form Manager also returns other exception conditions and informational messages in this receive control text. The receive control text is composed of individual receive
control text items, each of which is five characters.
The number of receive control text items that a receive control message contains depends on the length of the receive control text and the number of exceptions encountered and messages that must be returned. In the portable
API, the receive control message text must be 25 bytes long, while in the
OpenVMS API, the length of the text is user-specified. Appendix B lists the receive control text items.
You can define application-specific receive control text items in a RETURN response step. For information on defining receive control text items, see the
RESPONSE STEP syntax in the HP DECforms IFDL Reference Manual.
Receive control text items have the following defined format:
WSXXX
W
W indicates whether an exception occurred. The letter ‘‘E’’ in this position indicates that an exception occurred. A space indicates that no exception occurred; the control text item is informational.
S
The letter S in the second position indicates the source of the receive control text item depending on which character appears in this position. The characters that can appear are as follows:
I
S
Character
F
Receive Control Text Item Source
Indicates that the form designer defined the receive control text item in the form.
Indicates that the receive control text item was defined by DECforms software.
Indicates that the receive control text item was defined by the FIMS standard.
XXX
The XXX designation contains the control code as specified in Appendix B.
4–56 How the Form Manager Processes Requests
For example, in the receive control text ES004, the E signals an exception that was defined by the FIMS standard (S); the 004 control code indicates that the Form Manager could not establish a session with session-id specified in the argument of an ENABLE request. Appendix B lists this and other control codes in numeric order.
How the Form Manager Processes Requests 4–57
5
Using the OpenVMS API
DECforms software supports both an OpenVMS application programming interface (API), and a portable API that supports C and FORTRAN bindings.
This chapter describes each DECforms request for users of the OpenVMS API.
For similar information about the portable API, see Chapter 6.
Each DECforms request is described in a structured format that provides the following information:
• The name of the request and a sentence describing its purpose.
• The format of the request. Optional arguments are enclosed in square brackets ( [ ] ).
• A list that provides information on the return status variable, which describes the information returned by the program to the Form Manager.
This information includes what data type the return status variable should be, the access that the Form Manager needs to the return status variable, and the passing mechanism of the return status variable.
• A description of each argument. A list at the beginning of each argument description indicates what the data type of the argument should be, the access that the Form Manager needs to the argument, and the passing mechanism of the argument.
• A complete description of the request.
• The possible return values for the request, listed in alphabetical order.
• One or more examples of using each request in the FORTRAN programming language.
The Form Manager ignores case in arguments that you pass. For example, the Form Manager considers the name RECORD_ONE to be equivalent to the name record_one.
For examples of how to include requests in an application program, see
Chapter 2. For information on how the Form Manager processes requests, see
Chapter 4.
Using the OpenVMS API 5–1
ENABLE
ENABLE
Initializes a DECforms session.
Format
ret-status=FORMS$ENABLE
( form-object-address, display-device-specification, session-id,
[file-specification,]
[form-specification, receive-control-text, receive-control-text-count],
)
[send-control-text, send-control-text-count],
[timeout],
[parent-request-id],
[request-options]
Returns
OpenVMS usage: type: access: mechanism: cond_value longword (unsigned) write only by value
Arguments
form-object-address
OpenVMS usage: longword (unsigned) type: access: mechanism: longword (unsigned) read only by value
Required argument that is either the FORMS$AR_FORM_TABLE symbol name or 0. The FORMS$AR_FORM_TABLE symbol is defined in an object module stored in a system library. This symbol is a pointer to the address of a special object module, called a form object.
The form object module contains the addresses of escape routines and forms that are linked with the application.
5–2 Using the OpenVMS API
ENABLE
If no form object module is needed for the session, you can pass 0 in form-
object-address.
display-device-specification
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Required argument that is a character-string name for the device to be used as the display device during this session.
You can define a logical name for the device name and pass that logical name in display-device-specification.
session-id
OpenVMS usage: char_string type: access: mechanism: character-coded text string write only by descriptor
Required argument that is filled by the Form Manager; the Form Manager returns a 16-byte character session identification string.
Session-id associates the display device with the form that was loaded into memory. You must pass this session identification string in subsequent request calls to tell the Form Manager which display device and form you want the
Form Manager to use.
The string you specify must be 16 bytes long.
file-specification
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Optional argument that specifies the character-string file specification of the form file to be used during this session. The file specification can include node name, device name, directory specification, file name, file type, and file version number.
If you omit the node name, device name, or directory specification, the Form
Manager uses the node you are logged in to, the current default device, and the current default directory, respectively.
Using the OpenVMS API 5–3
ENABLE
If you omit the file type, the Form Manager looks for a file with the .form or
.exe type. If you omit the file version number, the Form Manager uses the latest version (highest version number) of the specified file.
You can define a logical name for the file specification and pass that logical name in file-specification.
If you do not specify this argument, you must specify form-specification. If your form is linked into a shareable image, you must specify this argument and
form-specification.
The following table shows what you must specify for a form name or a form file when specifying file-specification. The X designates what you must supply.
file-specification form-specification
.FORM
X
.EXE
X
X
Linked In
X
form-specification
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Optional argument that specifies the name of the form in the IFDL source file. The Form Manager first looks for a .form file, then searches for a
file-specification.
If you do not specify this argument, you must specify file-specification. If the form specified in file-specification is a .form file, form-specification is ignored.
If your form is linked into a shareable image, you must specify this argument and the file-specification.
receive-control-text
OpenVMS usage: char_string type: access: mechanism: character-coded text string write only by descriptor
Optional argument that returns status information from the Form Manager to the application program when the request is terminated. The status information is divided into a maximum of five receive control text items.
5–4 Using the OpenVMS API
ENABLE
Each receive control text item is five single-byte characters long, so the variable you pass in this argument must be able to store a string that is a multiple of five characters long. If you pass this argument, you must also pass
receive-control-text-count.
If the length specified in the OpenVMS descriptor for receive-control-text is too short to hold all the receive control text items that the Form Manager attempts to return, the Form Manager discards those receive control text items that do not fit.
receive-control-text-count
OpenVMS usage: longword_unsigned type: access: mechanism: longword (unsigned) write only by reference
Optional argument that specifies the number of receive control text items returned by the Form Manager (each of which is five characters long) in the receive control text. This number indicates the number of receive control text items returned by the Form Manager to the application.
When the Form Manager terminates the request, it stores the number of receive control text items that it is returning in this argument. This argument is set to 0 at the start of each request. If you pass receive-control-text, you must pass this argument.
send-control-text
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Optional argument in which you can pass zero to five send control text items to the Form Manager from the application program. Each send control text item must be one to five single-byte characters long and should name a control text response stored in the form. If you pass this argument, you must also pass the
send-control-text-count argument.
You can pass a send control text item that is less than five characters long.
However, if you are specifying an additional send control text item, the Form
Manager requires you to pad the send control text with blanks to five 1-byte characters.
Using the OpenVMS API 5–5
ENABLE
If you omit this argument, the Form Manager will not execute any control text response. If a send control text item specifies a control text response that does not exist, the Form Manager either processes the next send control text item or proceeds to the next request phase.
send-control-text-count
OpenVMS usage: longword_unsigned type: access: mechanism: longword (unsigned) read only by reference
Optional argument in which you specify the number of control text items in send-control-text. You can specify zero to five control text items in this argument. If you pass send-control-text, you must pass this argument.
timeout
OpenVMS usage: word_unsigned type: access: mechanism: word (unsigned) read only by reference
Optional argument in which you specify a timeout value for the entry timer.
The entry timer controls the maximum number of seconds that can elapse between each operator keystroke.
The timeout value you pass in this argument supersedes any timeout value declared in the form.
If you omit this argument, the operator has unlimited time between each keystroke, unless you specify a timeout value in the form. If the timeout value is set to 0, the operator has unlimited time between each keystroke.
parent-request-id
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Optional argument specifying the parent request of the new request. When a request that is currently executing invokes an escape routine that invokes another DECforms request, parent-request-id specifies the original request that called the escape routine.
This argument is intended only for using DECforms calls from within an escape routine. There can be no parent-request-id argument for a request called from a nonprocedural escape routine called from within the application.
5–6 Using the OpenVMS API
ENABLE
You can make parent-request-id available within an escape routine by passing the built-in form data item PARENTREQUESTID as one of the arguments to the escape routine within the CALL response step.
This argument is 24 bytes long.
Note
When an escape routine calls the current session or another session, the calling request hangs unless:
1. A built-in form data item of PARENTREQUESTID is declared as a form data item declaration.
2. The declared form data item is passed as a descriptor to the escape routine.
3. The escape routine passes the descriptor as a parameter to the request.
Once the built-in form data item declaration is declared and the
PARENTREQUESTID is passed to the escape routine, the DECforms request being called from the escape routine is processed while the parent request completes.
request-options
OpenVMS usage: item_list_2 type: access: mechanism: longword (unsigned) read only by reference
Optional item list containing request-specific arguments that control the environment of the request.
Request-options is the address of an OpenVMS item list containing zero or more request arguments. Each item consists of three longwords.
The first longword consists of two fields: a 1-word field that contains the length of the application buffer, and a 1-word field containing the item code value.
The second longword contains the address of the application buffer that either contains or will receive the data.
The third longword contains the address of a word to receive the length of the data written into the buffer. (The third longword is optional and is useful when the specified item code indicates that data will be returned to the application.)
Using the OpenVMS API 5–7
ENABLE
The item list is terminated by a longword containing a 0.
Certain item codes correspond to logical names that the Form Manager translates during request processing. If you specify an item code, the Form
Manager reads the item code directly and does not attempt to translate the corresponding logical names.
Table 5–1 contains the item codes that can be specified and their explanations.
Table 5–1 FORMS$ENABLE Request Options
Item Code Description
FORMS$K_ASTADR
FORMS$K_ASTPRM
FORMS$K_EFN
FORMS$K_IMAGE
The asynchronous system trap (AST) service routine to be executed when the request is complete. The buffer address field of the item contains the address of the entry mask for this routine.
The AST argument to be passed to the AST service routine. The buffer address field of the item contains the address of a longword value containing the value to be passed.
Event flag the Form Manager sets when it completes the request. The buffer address field of the item contains the event flag number.
The Form Manager clears the specified event flag at the beginning of the request.
File specification of a shareable image that is searched for procedural escapes. This item code can appear up to eight times in the item list: the order of appearance specifies the order in which the images will be searched for procedural escapes.
The buffer address field of the item contains the address of a string that contains the image file specification.
(continued on next page)
5–8 Using the OpenVMS API
ENABLE
Table 5–1 (Cont.) FORMS$ENABLE Request Options
Item Code Description
FORMS$K_LANGUAGE
FORMS$K_PRINTFILE
FORMS$K_RSB
FORMS$K_TRACE
FORMS$K_TRACEFILE
Natural language to use when selecting a layout to enable. The buffer address field of the item contains the address of a string that contains a language type.
The string attempts to match the language description in the foreign layout. If it does not find a match, it selects the next best fit.
File specification of the file to be printed using the PRINT response step. The buffer address field of the item contains the address of a string that contains the print file specification.
The quadword request status block to receive the completion status of the request. The buffer address field of the item contains the address of a DECforms quadword status block where the Form Manager writes the return status of the request.
The Form Manager returns the final condition value of the request in the first longword of the status block. The second longword is reserved for future use.
Tracing indicator for the session. The buffer address field of the item can be specified as zero or any nonzero value. A value of zero indicates that trace is disabled. Any nonzero value indicates that trace is enabled.
File specification of the file to be used to trace the execution of the session. The buffer address field of the item contains the address of a string that contains the trace file specification.
If another request on this session opens the trace file, this item code is ignored.
Using the OpenVMS API 5–9
ENABLE
Description
The ENABLE request loads the specified form file into memory, selects an appropriate layout, and attaches the specified display device. The Form
Manager also returns a unique session-identification string and initializes all form data items. For more information about initializing an ENABLE request, see Section 4.1.2.
You can include more than one ENABLE request call in your application program (the Form Manager supports multiple synchronous requests to display devices). For example, the operator’s terminal can be enabled for two different sessions. The Form Manager can perform operations in any enabled session.
You cannot enable an executable form image located on a remote node due to a restriction in LIB$FIND_IMAGE_SYMBOL.
Return Values
FORMS$_BADARG
FORMS$_CANCELLED
FORMS$_CANTOPENDIC
FORMS$_INVDEVICE
FORMS$_LOADFORM
FORMS$_NOLAYOUT
FORMS$_NOLICENSE
FORMS$_NORMAL
FORMS$_OPENFORM
FORMS$_READFORM
FORMS$_TIMEOUT
Bad argument or incorrect argument format for the request.
Request processing interrupted by arrival of
CANCEL request.
The Form Manager could not open the Kana to Kanji dictionary.
The device specified on the ENABLE call was invalid.
The Form Manager could not load the specified form.
No layout in this form fits the terminal type, language, and display size.
No DECforms software license is active.
FORMS$ENABLE was successfully completed.
The Form Manager could not open the form file for input.
The Form Manager could not read the form file.
Input was not completed in the time specified.
5–10 Using the OpenVMS API
ENABLE
Examples
1.
1
2
CHARACTER*16 session_id
INTEGER forms_status ! check status
.
.
.
forms_status = forms$enable ( FORMS$AR_FORM_TABLE, ! form object address
3
’sys$input:’, session_id,
! Device name
! return from forms$
’forms$sample_form’) ! Name of form file
CALL check_forms_status( forms_status )
.
.
.
The request call in this example causes the Form Manager to perform the following tasks: a. Enable form file on the device specified by SYS$INPUT.
b. Validate the arguments in the request.
c. Attach the display device named by SYS$INPUT.
d. Create a session-identification string and store it in session_id.
e. Load the forms$sample_form.form form file into memory from the current default device and directory.
f. Process the ENABLE response, if defined.
g. Return control to the application program.
2.
1
2
3
CHARACTER*16 session_id
INTEGER forms_status
.
.
.
forms_status = forms$enable ( , ! form object address
’sys$input:’, ! Device name session_id, ! return from forms$enable
’my_form.form’) ! Name of form file
.
.
.
CALL check_forms_status( forms_status )
Using the OpenVMS API 5–11
ENABLE
By taking the following steps, the request call in this example causes the
Form Manager to load a form file where there are no procedural escapes being called: a. Validate the arguments in the request.
b. Attach the display device named by SYS$INPUT.
c. Create a session-identification string and store it in session_id.
d. Load the my_form.form form file into memory from the current default device and directory.
e. Process the ENABLE response, if defined.
f. Return control to the application program.
5–12 Using the OpenVMS API
DISABLE
DISABLE
Terminates a session.
Format
ret-status = FORMS$DISABLE
( session-id,
[receive-control-text, receive-control-text-count],
[send-control-text, send-control-text-count],
[timeout],
[parent-request-id],
)
[request-options]
Returns
OpenVMS usage: type: access: mechanism: cond_value longword (unsigned) write only by value
Arguments
session-id
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Required argument that contains a unique session-identification string. The
Form Manager returns the session-identification string to your application program during the processing of an ENABLE request.
You must pass session-id because the session-identification string specifies which display device and session you want the Form Manager to use during this request.
The string you specify must be 16 bytes long.
Using the OpenVMS API 5–13
DISABLE receive-control-text
OpenVMS usage: char_string type: access: mechanism: character-coded text string write only by descriptor
Optional argument that returns status information from the Form Manager to the application program when the request is terminated. The status information is divided into a maximum of five receive control text items.
Each receive control text item is five characters long, so the variable you pass in this argument must be able to store a string that is a multiple of five characters long. If you pass this argument, you must also pass the
receive-control-text-count argument.
If the length specified in the OpenVMS descriptor for receive-control-text is too short to hold all the receive control text items that the Form Manager attempts to return, the Form Manager discards those receive control text items that do not fit.
receive-control-text-count
OpenVMS usage: longword_unsigned type: access: mechanism: longword (unsigned) write only by reference
Optional argument that specifies the number of receive control text items returned by the Form Manager (each of which is five characters long) in the receive control text.
When the Form Manager terminates the request, it stores the number of receive control text items that it is returning in this argument. This argument is set to 0 at the start of each request. If you pass receive-control-text, you must pass this argument.
send-control-text
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Optional argument in which you can pass zero to five send control text items to the Form Manager from the application program. Each send control text item must be one to five single-byte characters long and should name a control text response stored in the form. If you pass this argument, you must also pass
send-control-text-count.
5–14 Using the OpenVMS API
DISABLE
You can pass a send control text item that is less than five characters long.
However, if you are specifying an additional send control text item, the Form
Manager requires you to pad the send control text with blanks to five 1-byte characters.
If you omit this argument, the Form Manager will not execute any control text response. If a send control text item specifies a control text response that does not exist, the Form Manager either processes the next send control text item or proceeds to the next request phase.
send-control-text-count
OpenVMS usage: longword_unsigned type: access: mechanism: longword (unsigned) read only by reference
Optional argument in which you specify the number of control text items in send-control-text. You can specify zero to five control text items in this argument. If you pass send-control-text, you must pass this argument.
timeout
OpenVMS usage: word_unsigned type: access: mechanism: word (unsigned) read only by reference
Optional argument in which you specify a timeout value for the entry timer.
The entry timer controls the maximum number of seconds that can elapse between each operator keystroke.
The timeout value you pass in this argument supersedes any timeout value declared in the form.
If you omit this argument, the operator has unlimited time between each keystroke, unless you specify a timeout value in the form. If the timeout value is set to 0, the operator has unlimited time between each keystroke.
parent-request-id
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Optional argument specifying the parent request of the new request. When a request that is currently executing invokes an escape routine that invokes
Using the OpenVMS API 5–15
DISABLE
another DECforms request, parent-request-id specifies the original request that called the escape routine.
This argument is intended only for when you issue DECforms calls from within an escape routine. There can be no parent-request-id argument for a request called from a nonprocedural escape routine called from within the application.
You can make parent-request-id available within an escape routine by passing the built-in form data item PARENTREQUESTID as one of the arguments to the escape routine within the CALL response step.
This argument is 24 bytes long.
Note
When an escape routine calls the current session or another session, the calling request hangs unless:
1. A built-in form data item of PARENTREQUESTID is declared as a form data item declaration.
2. The declared form data item is passed as a descriptor to the escape routine.
3. The escape routine passes it as a parameter to the request.
Once the built-in form data item declaration is declared and the
PARENTREQUESTID is passed to the escape routine, the DECforms request being called from the escape routine is processed while the parent request completes.
request-options
OpenVMS usage: item_list_2 type: access: mechanism: longword (unsigned) read only by reference
Optional item list containing request-specific arguments that control the environment of the request.
Request-options is the address of an OpenVMS item list containing zero or more request arguments. Each item consists of three longwords.
The first longword consists of two fields: a 1-word field that contains the length of the application buffer, and a 1-word field containing the item code value.
5–16 Using the OpenVMS API
DISABLE
The second longword contains the address of the application buffer that either contains or will receive the data.
The third longword contains the address of a word to receive the length of the data written into the buffer. (The third longword is optional and is useful when the specified item code indicates that data will be returned to the application.)
The item list is terminated by a longword containing a 0.
Certain item codes correspond to logical names that the Form Manager translates during request processing. If you specify an item code, the Form
Manager reads the item code directly and does not attempt to translate the corresponding logical names.
Table 5–2 shows the request options that you can specify.
Table 5–2 FORMS$DISABLE Request Options
Item Code Description
FORMS$K_ASTADR
FORMS$K_ASTPRM
FORMS$K_EFN
The asynchronous system trap (AST) service routine to be executed when the request is complete. The buffer address field of the item contains the address of the entry mask for this routine.
The AST argument to be passed to the AST service routine. The buffer address field of the item contains the address of a longword value containing the value to be passed.
Event flag the Form Manager sets when it completes the request. The buffer address field of the item contains the event flag number.
The Form Manager clears the specified event flag at the beginning of the request.
(continued on next page)
Using the OpenVMS API 5–17
DISABLE
Table 5–2 (Cont.) FORMS$DISABLE Request Options
Item Code Description
FORMS$K_NO_TERM_IO
FORMS$K_PRINTFILE
FORMS$K_RSB
Item code to permit a multiterminal application to disable its sessions without the risk that a terminal that is not accepting output will hang the shutdown process.
If this item code is present and its value is nonzero, the disable request will not perform terminal I/O. Any output normally sent to the terminal during this request is discarded. The accept phase, which is the only phase during which input from the operator is accepted, is bypassed.
If a session is disabled with NO_TERM_IO and another session remains open to that terminal, the other session can continue to be used normally. The first request made to the other session causes the screen to be refreshed if any terminal output from the first session was discarded.
File specification of the file to be printed using the PRINT response step. The buffer address field of the item contains the address of a string that contains the print file specification.
The quadword request status block to receive the completion status of the request. The buffer address field of the item contains the address of a DECforms quadword status block where the Form Manager writes the return status of the request.
The Form Manager returns the final condition value of the request in the first longword of the status block. The second longword is reserved for future use.
(continued on next page)
5–18 Using the OpenVMS API
DISABLE
Table 5–2 (Cont.) FORMS$DISABLE Request Options
Item Code Description
FORMS$K_TRACE
FORMS$K_TRACEFILE
Tracing indicator for the session. The buffer address field of the item can be specified as zero or any nonzero value. A value of zero indicates that trace is disabled. Any nonzero value indicates that trace is enabled.
File specification of the file to be used to trace the execution of the session. The buffer address field of the item contains the address of a string that contains the trace file specification.
If another request on this session opens the trace file, this item code is ignored.
Description
The DISABLE request terminates the specified session. The Form Manager detaches the display device and the form that are associated with the sessionidentification string. Once the Form Manager completes the processing of this request, the session specified by the session-identification string no longer exists. The values of all form data items in the form are disabled last.
Return Values
FORMS$_BADARG
FORMS$_CANCELLED
FORMS$_INUSE
FORMS$_NORMAL
FORMS$_NOSESSION
FORMS$_TIMEOUT
Bad argument or incorrect argument format for request.
Request processing interrupted by arrival of
CANCEL request.
The program attempted to disable a form that is in current use.
FORMS$DISABLE was successfully completed.
The session-identification string passed in
session-id does not match an existing session.
Input was not completed in the specified time.
Using the OpenVMS API 5–19
DISABLE
Examples
1.
CHARACTER*16 session_id
INTEGER forms_status,
1 count/1/
.
.
.
forms_status = FORMS$DISABLE( session_id )
CALL check_forms_status( forms_status )
The request call in this example causes the Form Manager to perform the following tasks: a. Validate the arguments in the request.
b. Verify that session_id names a valid session.
c. Perform the DISABLE response, if defined.
d. Unload the form specified by session_id.
e. Detach the display device specified by session_id.
f. Return control to the application program.
2.
CHARACTER*16 session_id
CHARACTER*25 rec_ctrl_txt, send_ctrl_txt
INTEGER forms_status, reccount, sendcount, timeout
.
.
.
forms_status =
FORMS$DISABLE(session_id,rec_ctrl_txt,reccount,send_ctrl_txt,sendcount,,,)
CALL check_forms_status( forms_status )
The request call in this example causes the Form Manager to perform the following tasks: a. Validate the arguments in the request.
b. Verify that session_id names a valid session.
c. Perform the control text responses named in send_ctrl_txt.
d. Perform the DISABLE response, if defined.
e. Unload the form specified by session_id.
5–20 Using the OpenVMS API
f. Detach the display device specified by session_id.
g. Store any receive control text items in rec_ctrl_txt.
h. Return control to the application program.
DISABLE
Using the OpenVMS API 5–21
SEND
SEND
Copies data from an application program record to form data items.
Format
ret-status = FORMS$SEND
( session-id, send-record-name, send-record-count,
[receive-control-text, receive-control-text-count],
[send-control-text, send-control-text-count],
[timeout],
[parent-request-id],
[
[request-options],
[send-record-message],
[send-shadow-record],
)
] . . .
Returns
OpenVMS usage: type: access: mechanism: cond_value longword (unsigned) write only by value
Arguments
session-id
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Required argument that contains a unique session-identification string. The
Form Manager returns the session-identification string to your application program during the processing of an ENABLE request.
5–22 Using the OpenVMS API
SEND
You must pass session-id because the session-identification string identifies which DECforms session and form you want the Form Manager to use during this request.
The string you specify in this argument must be 16 bytes long.
send-record-name
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Required argument that is a single-byte character string name of the form record (for single record transfers) or record list (for multiple record transfers) to which the Form Manager is passing data. send-record-name is used to search for and trigger a send response within the form file.
The character string you pass in this argument must match a record name, or record list name, in the form.
send-record-count
OpenVMS usage: longword_unsigned type: access: mechanism: longword (unsigned) read only by reference
Required argument that contains the number of send record items passed to the form. (A send record item is made up of two parts: send-record-message and send-shadow-record. You cannot specify send-shadow-record unless you also specify send-record-message.) This number must also match the number of records in the form specified for send-record-name.
This value must be greater than or equal to 0. If send-record-count is 0, then
send-record-name must correspond to an empty record definition in the IFDL.
receive-control-text
OpenVMS usage: char_string type: access: mechanism: character-coded text string write only by descriptor
Optional argument that returns status information from the Form Manager to the application program when the request is terminated. The status information is divided into a maximum of five receive control text items.
Using the OpenVMS API 5–23
SEND
Each receive control text item is five single-byte characters long, so the variable you pass in this argument must be able to store a string that is a multiple of five characters long. If you pass this argument, you must also pass
receive-control-text-count.
If the length specified in the descriptor for receive-control-text is too short to hold all the receive control text items that the Form Manager attempts to return, the Form Manager discards those receive control text items that do not fit.
receive-control-text-count
OpenVMS usage: longword_unsigned type: access: mechanism: longword (unsigned) write only by reference
Optional argument that specifies the number of receive control text items
(each of which is five characters long) in the receive control message. This number indicates the number of receive control text items returned by the
Form Manager to the application.
When the Form Manager terminates the request, it stores the number of receive control text items that it is returning in this argument. This argument is set to 0 at the start of each request. If you pass receive-control-text, you must pass this argument.
send-control-text
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Optional argument in which you can pass zero to five send control text items to the Form Manager from the application program. Each send control text item must be one to five single-byte characters long and should name a control text response stored in the form. If you pass this argument, you must also pass the
send-control-text-count argument.
You can pass a send control text item that is less than five characters long.
However, if you are specifying an additional send-control-text item, the Form
Manager requires you to pad send-control-text with blanks to five 1-byte characters.
5–24 Using the OpenVMS API
SEND
If you omit this argument, the Form Manager will not execute any control text response. If a send control text item specifies a control text response that does not exist, the Form Manager either processes the next send control text item or proceeds to the next request phase.
send-control-text-count
OpenVMS usage: longword_unsigned type: access: mechanism: longword (unsigned) read only by reference
Optional argument in which you specify the number of control text items in send-control-text. You can specify zero to five control text items in this argument. If you pass send-control-text, you must pass this argument.
timeout
OpenVMS usage: word_unsigned type: access: mechanism: word (unsigned) read only by reference
Optional argument in which you specify a timeout value for the entry timer.
The entry timer controls the maximum number of seconds that can elapse between each operator keystroke.
The timeout value you pass in this argument supersedes any timeout value declared in the form.
If you omit this argument, the operator has unlimited time between each keystroke, unless you specify a timeout value in the form. If the timeout value is set to 0, the operator has unlimited time between each keystroke.
parent-request-id
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Optional argument specifying the parent request of the new request. When a request that is currently executing invokes an escape routine that involves another DECforms request, parent-request-id specifies the original request that called the escape routine.
This argument is intended only for when you send DECforms calls from within an escape routine. There can be no parent-request-id argument for a request called from a nonprocedural escape routine called from within the application.
Using the OpenVMS API 5–25
SEND
You can make parent-request-id available within an escape routine by passing the built-in form data item PARENTREQUESTID as one of the arguments to the escape routine within the CALL response step.
This argument is 24 bytes long.
Note
When an escape routine calls the current session or another session, the calling request hangs unless:
1. A built-in form data item of PARENTREQUESTID is declared as a form data item declaration.
2. The declared form data item is passed as a descriptor to the escape routine.
3. The escape routine passes it as a parameter to the request.
Once the built-in form data item declaration is declared and the
PARENTREQUESTID is passed to the escape routine, the DECforms request being called from the escape routine is processed while the parent request completes.
request-options
OpenVMS usage: item_list_2 type: access: mechanism: longword (unsigned) read only by reference
Optional item list containing request-specific arguments that control the environment of the request.
Request-options is the address of an OpenVMS item list containing zero or more request arguments. Each item consists of three longwords.
The first longword consists of two fields: a 1-word field that contains the length of the application buffer, and a 1-word field containing the item code value.
The second longword contains the address of the application buffer that either contains or will receive the data.
The third longword contains the address of a word to receive the length of the data written into the buffer. (The third longword is optional and is useful when the specified item code indicates that data will be returned to the application.)
The item list is terminated by a longword containing a 0.
5–26 Using the OpenVMS API
SEND
Certain item codes correspond to logical names that the Form Manager translates during request processing. If you specify an item code, the Form
Manager reads the item code directly and does not attempt to translate the corresponding logical names.
Table 5–3 contains the item codes that you can specify.
Table 5–3 FORMS$SEND Request Options
Item Code Description
FORMS$K_ASTADR
FORMS$K_ASTPRM
FORMS$K_EFN
FORMS$K_PRINTFILE
FORMS$K_RSB
The asynchronous system trap (AST) service routine to be executed when the request is complete. The buffer address field of the item contains the address of the entry mask for this routine.
The AST argument to be passed to the AST service routine. The buffer address field of the item contains the address of a longword value containing the value to be passed.
Event flag the Form Manager sets when it completes the request. The buffer address field of the item contains the event flag number.
The Form Manager clears the specified event flag at the beginning of the request.
File specification of the file to be printed using the PRINT response step. The buffer address field of the item contains the address of a string that contains the print file specification.
The quadword request status block to receive the completion status of the request. The buffer address field of the item contains the address of a DECforms quadword status block where the Form Manager writes the return status of the request.
The Form Manager returns the final condition value of the request in the first longword of the status block. The second longword is reserved for future use.
(continued on next page)
Using the OpenVMS API 5–27
SEND
Table 5–3 (Cont.) FORMS$SEND Request Options
Item Code Description
FORMS$K_TRACE
FORMS$K_TRACEFILE
Tracing indicator for the session. The buffer address field of the item can be specified as zero or any nonzero value. A value of zero indicates that trace is disabled. Any nonzero value indicates that trace is enabled.
File specification of the file to be used to trace the execution of the session. The buffer address field of the item contains the address of a string that contains the trace file specification.
If another request on this session opens the trace file, this item code is ignored.
send-record-message
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Optional argument pointing to application data that is to be passed to the form. The form record is the description of this data to the Form Manager.
send-shadow-record
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Optional argument that is an OpenVMS string descriptor that contains an indicator specifying whether to update last known values of form data items.
The send shadow record argument consists of a single 1-byte character. This character controls whether the Form Manager uses the data in the send record to update the last known values of the corresponding tracked form data items in the form.
If the character is N (either uppercase or lowercase), the Form Manager does not do the update; if the character is anything else, or if no send shadow record appears, the Form Manager does the update.
The length of send-shadow-record must be 1 byte.
5–28 Using the OpenVMS API
SEND
If you do not pass send-shadow-record, the last known values of tracked form data items are updated.
For more information on shadow records, see Chapter 4.
Description
The SEND request causes the Form Manager to pass data from the application program record to form data items. The Form Manager can then display the form data items on the display device. Optionally, the Form Manager executes the SEND RESPONSE for the record or record list.
Return Values
FORMS$_BADARG
FORMS$_BADRECCNT
FORMS$_BADRECLEN
FORMS$_BAD_
SSHDWRECLEN
FORMS$_CANCELLED
FORMS$_INVRECDES
FORMS$_NORECORD
FORMS$_NORMAL
FORMS$_NOSESSION
FORMS$_PENDING
FORMS$_TIMEOUT
Bad argument or incorrect argument format for request.
The number specified in record-count in the request call does not match the number of records in the record list.
The length of the program record and the form record do not match. Either the program record descriptor length or the form record length is incorrect.
The request specified a length for send-
shadow-record other than 1.
FORMS$SEND processing interrupted by arrival of CANCEL request.
One of the record message descriptors passed in FORMS$SEND is invalid.
FORMS$SEND specified a record identifier that is not in this form.
FORMS$SEND was completed.
The session-identification string you passed in
session-id does not match an existing session.
An asynchronous operation you started has not yet completed.
Input was not completed in the specified time.
Using the OpenVMS API 5–29
SEND
Examples
1.
5
6
3
4
7
8
1
2
CHARACTER*16 session_id
INTEGER forms_status,
.
.
.
forms_status = forms$send ( session_id,
9
’account’, count,
,
,
,,
,,
,
)
CALL check_forms_status( forms_status )
! session id
! form record
! number of records sent
! receive ctl text msg/ct
! send ctl text msg/ct
! timeout
! parent request id
! request options item list descriptor1, ! info sent to form
! shadow rec
The external request call in the preceding example causes the Form
Manager to perform the following tasks: a. Validate the arguments in the request.
b. Verify that session_id names a valid session.
c. Copy the values stored in application program record fields to the form data items that correspond to the
’ account
’ form record.
d. Perform the SEND response, if defined.
e. Return control to the application program.
2.
CHARACTER*25 rec_ctrl_txt, send_ctrl_txt
8
9
6
7
4
5
2
3
INTEGER status, reclength, reccount, sendcount, timeout, one
.
.
.
forms_status = forms$send ( session_id,
1
10
’one_record’, one, reccount,sendcount send_ctrl_txt, rec_ctrl_txt, timeout,
,
, descriptor1,
)
CALL check_forms_status( forms_status )
! session id
! form record
! number of records sent
! receive ctl text msg/ct
! send ctl text msg/ct
! rec ctl text msg/ct
! timeout
! parent request id
! request options item list
! info sent to form
! shadow rec
5–30 Using the OpenVMS API
SEND
The external request call in the preceding example causes the Form
Manager to perform the following tasks: a. Validate the arguments in the request.
b. Verify that session_id names a valid session.
c. Copy the values stored in application program record fields to the form data items that correspond to the
’ one_record
’ form record. The address of the application program record from which data is moved is specified by descriptor1.
d. Perform the control text responses named in send_ctrl_txt.
e. Perform the SEND response, if defined.
f. Store any receive control text items in rec_ctrl_txt.
g. Return control to the application program.
Using the OpenVMS API 5–31
RECEIVE
RECEIVE
Copies data from form data items to an application program record.
Format
ret-status=FORMS$RECEIVE
( session-id, receive-record-name, receive-record-count,
[receive-control-text, receive-control-text-count],
[send-control-text, send-control-text-count],
[timeout],
[parent-request-id],
[
[request-options],
[receive-record-message],
[receive-shadow-record],
)
] . . .
Returns
OpenVMS usage: type: access: mechanism: cond_value longword (unsigned) write only by value
Arguments
session-id
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Required argument that contains a unique session-identification string. The
Form Manager returns the session-identification string to your application program during the processing of an ENABLE request.
5–32 Using the OpenVMS API
RECEIVE
You must pass session-id because the session-identification string identifies which DECforms session and form you want the Form Manager to use during this request.
The string you specify in this argument must be 16 bytes long.
receive-record-name
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Required argument that is a single-byte character-string name of a form record
(for single record transfers) or a form record list (for multiple record transfers).
Receive-record-name is used to search for a form record or record list to use during data collection and trigger a RECEIVE RESPONSE within the form file.
receive-record-count
OpenVMS usage: longword_unsigned type: access: mechanism: longword (unsigned) read only by reference
Required argument that contains the number of receive record items for this call. (A receive record item is made up of two parts: receive-record-message and receive-shadow-record. You cannot specify receive-shadow-record unless you also specify receive-record-message.)
Receive-record-count must match the number of records specified by receive-
record-name. This value must be greater than 0.
receive-control-text
OpenVMS usage: char_string type: access: mechanism: character-coded text string write only by descriptor
Optional argument that returns status information from the Form Manager to the application program when the request is terminated. The status information is divided into a maximum of five receive control text items.
Each receive control text item is five characters long, so the variable you pass in this argument must be able to store a string that is a multiple of five characters long. If you pass this argument, you must also pass receive-control-
text-count.
Using the OpenVMS API 5–33
RECEIVE
If the length specified in the OpenVMS descriptor for receive-control-text is too short to hold all the receive control text items that the Form Manager attempts to return, the Form Manager discards those receive control text items that do not fit.
receive-control-text-count
OpenVMS usage: longword_unsigned type: access: mechanism: longword (unsigned) write only by reference
Optional argument that specifies the number of receive control text items
(each of which is five characters long) in the receive control message. This number indicates the number of receive control text items returned by the
Form Manager to the application.
When the Form Manager terminates the request, it stores the number of receive control text items that it is returning in this argument. If you pass
receive-control-text, you must pass this argument. This argument is set to 0 at the start of each request.
send-control-text
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Optional argument in which you can pass zero to five send control text items to the Form Manager from the application program. Each send control text item must be one to five single-byte characters long and should name a control text response stored in the form. If you pass this argument, you must also pass the
send-control-text-count argument.
You can pass a send control text item that is less than five characters long.
However, if you are specifying an additional send control text item, the Form
Manager requires you to pad the send-control-text with blanks to five 1-byte characters.
If you omit this argument, the Form Manager will not execute any control text response. If a send control text item specifies a control text response that does not exist, the Form Manager either processes the next send control text item or proceeds to the next request phase.
5–34 Using the OpenVMS API
RECEIVE send-control-text-count
OpenVMS usage: longword_unsigned type: access: mechanism: longword (unsigned) read only by reference
Optional argument in which you specify the number of control text items in send-control-text. You can specify zero to five control text items in this argument. If you pass send-control-text, you must pass this argument.
timeout
OpenVMS usage: word_unsigned type: access: mechanism: word (unsigned) read only by reference
Optional argument in which you specify a timeout value for the entry timer.
The entry timer controls the maximum number of seconds that can elapse between each operator keystroke.
The timeout value you pass in this argument supersedes any timeout value declared in the form.
If you omit this argument, the operator has unlimited time between each keystroke, unless you specify a timeout value in the form. If the timeout value is set to 0, the operator has unlimited time between each keystroke.
parent-request-id
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Optional argument specifying the parent request of the new request. When a request that is currently executing invokes an escape routine that invokes another DECforms request, parent-request-id specifies the original request that called the escape routine.
This argument is intended only for when you issue DECforms calls from within an escape routine. There can be no parent-request-id argument for a request called from a nonprocedural escape routine called from within the application.
You can make parent-request-id available within an escape routine by passing the built-in form data item PARENTREQUESTID as one of the arguments to the escape routine within the CALL response step.
Using the OpenVMS API 5–35
RECEIVE
This argument is 24 bytes long.
Note
When an escape routine calls the current session or another session, the calling request hangs unless:
1. A built-in form data item of PARENTREQUESTID is declared as a form data item declaration.
2. The declared form data item is passed as a descriptor to the escape routine.
3. The escape routine passes it as a parameter to the request.
Once the built-in form data item declaration is declared and the
PARENTREQUESTID is passed to the escape routine, the DECforms request being called from the escape routine is processed while the parent request completes.
request-options
OpenVMS usage: item_list_2 type: access: mechanism: longword_unsigned read only by reference
Optional item list containing request-specific arguments that control the environment of the request.
Request-options is the address of an OpenVMS item list containing zero or more request arguments. Each item consists of three longwords.
The first longword consists of two fields: a 1-word field that contains the length of the application buffer, and a 1-word field containing the item code value.
The second longword contains the address of the application buffer that either contains or will receive the data.
The third longword contains the address of a word to receive the length of the data written into the buffer. (The third longword is optional and is useful when the specified item code indicates that data will be returned to the application.)
The item list is terminated by a longword containing a 0.
5–36 Using the OpenVMS API
RECEIVE
Certain item codes correspond to logical names that the Form Manager translates during request processing. If you specify an item code, the Form
Manager reads the item code directly and does not attempt to translate the corresponding logical names.
Table 5–4 contains the item codes that can be specified and their explanations.
Table 5–4 FORMS$RECEIVE Request Options
Item Code Description
FORMS$K_ASTADR
FORMS$K_ASTPRM
FORMS$K_EFN
FORMS$K_PRINTFILE
FORMS$K_RSB
The asynchronous system trap (AST) service routine to be executed when the request is complete. The buffer address field of the item contains the address of the entry mask for this routine.
The AST argument to be passed to the AST service routine. The buffer address field of the item contains the address of a longword value containing the value to be passed.
Event flag the Form Manager sets when it completes the request. The buffer address field of the item contains the event flag number.
The Form Manager clears the specified event flag at the beginning of the request.
File specification of the file to be printed using the PRINT response step. The buffer address field of the item contains the address of a string that contains the print file specification.
The quadword request status block to receive the completion status of the request. The buffer address field of the item contains the address of a DECforms quadword status block where the Form Manager writes the return status of the request.
The Form Manager returns the final condition value of the request in the first longword of the status block. The second longword is reserved for future use.
(continued on next page)
Using the OpenVMS API 5–37
RECEIVE
Table 5–4 (Cont.) FORMS$RECEIVE Request Options
Item Code Description
FORMS$K_TRACE
FORMS$K_TRACEFILE
Tracing indicator for the session. The buffer address field of the item can be specified as zero or any nonzero value. A value of zero indicates that trace is disabled. Any nonzero value indicates that trace is enabled.
File specification of the file to be used to trace the execution of the session. The buffer address field of the item contains the address of a string that contains the trace file specification.
If another request on this session opens the trace file, this item code is ignored.
receive-record-message
OpenVMS usage: char_string type: access: mechanism: character-coded text string write only by descriptor
Optional argument pointing to form data that is to be passed to the application.
The form record is the description of this data to the Form Manager. The Form
Manager copies the values of corresponding form data items into this area of memory at the completion of the RECEIVE request.
If an exception condition occurs during processing of this request, the Form
Manager does not move data to the application program.
receive-shadow-record
OpenVMS usage: char_string type: access: mechanism: character-coded text string write only by descriptor
Optional argument that is a descriptor where the Form Manager writes modified field information that is returned to the application program from the form.
5–38 Using the OpenVMS API
RECEIVE
Receive-shadow-record contains information about each record field in the associated receive record message. The information specifies whether values in the record fields in the associated receive record message have changed from the values last known to the program. Receive-shadow-record contains one character for each record field in the receive record message, plus one additional character.
The length of receive-shadow-record is 1 plus the number of fields contained in the shadow record’s associated form record. Receive-shadow-record contains a single character for every field in the record being returned.
The correspondence between the shadow record and the received record is by ordinal position of characters in the shadow record, with an offset of 1 because of the additional character at the start of the shadow record.
When the application program passes the RECEIVE request to the form, the the first byte of receive-shadow-record can contain a character that specifies the following:
• N—The last known values are not updated.
• Any other character—The last known values are updated.
A character returned from the form to the program in the first byte of receive-
shadow-record can be one of the following:
• 0—No fields in the record have been modified.
• X—Modified status was not requested for one field; all fields were either not tracked or not modified.
• 1—At least one field in the record has been modified.
Each subsequent character receive-shadow-record corresponds to a field in
receive-record-message in the same relative position in the record.
The character is set as follows:
• 0—The corresponding field has not been modified.
• X—The field was not tracked by the Form Manager.
• 1—The corresponding field has been changed from its last known value.
Description
The RECEIVE request copies values from form data items to application program record fields. Optionally, the Form Manager executes the RECEIVE
RESPONSE for the record or record list.
Using the OpenVMS API 5–39
RECEIVE
Return Values
FORMS$_BADARG
FORMS$_BADRECCNT
FORMS$_BADRECLEN
FORMS$_BAD_
RSHDWRECLEN
FORMS$_CANCELLED
FORMS$_INVRECDES
FORMS$_NORECORD
FORMS$_NORMAL
FORMS$_NOSESSION
FORMS$_PENDING
FORMS$_TIMEOUT
Bad argument or incorrect argument format for request.
The number specified in record-count in the request call does not match the number of records specified in the form.
The length of the program record and the form record do not match. Either the program record descriptor length or the form record length is incorrect.
The request call specified a length for receive-
shadow-record that does not match the length of receive-shadow-record in the form.
FORMS$RECEIVE processing was interrupted by arrival of CANCEL request.
Invalid record message descriptor. One of the record message descriptors passed in
FORMS$RECEIVE is invalid.
FORMS$RECEIVE specified a record identifier that is not in this form.
FORMS$RECEIVE was completed successfully.
The session-identification string you passed in
session-id does not match an existing session.
An asynchronous operation that you started has not yet been completed.
Input was not completed in the specified time.
5–40 Using the OpenVMS API
RECEIVE
Examples
1.
7
8
5
6
9
3
4
1
2
CHARACTER*16 session_id
.
.
.
descriptor1.reclen = 4 + len(get_check.check_payto) + len(get_check.check_memo) descriptor1.address = %loc(get_check)
.
.
.
forms_status = forms$receive( session_id,
’get_check’,
%ref(count),
,,
,,
,
,
, descriptor1,
! session id
! form record
! # of records received
! receive ctl msg/ct
! send ctl msg/ct
! timeout
! parent request id
! request options item
)
! info received from form
! shadow record
CALL check_forms_status( forms_status )
The external request call in this language example causes the Form
Manager to perform the following tasks: a. Validate the arguments in the request.
b. Verify that session-id names a valid session.
c. Perform the RECEIVE response.
d. Copy the values stored in form data items that correspond to the
’ get_check
’ record to the application program record. The address of the application program record is specified by descriptor1.
e. Return control to the application program.
Using the OpenVMS API 5–41
RECEIVE
2.
CHARACTER*16 session_id
CHARACTER*25 rec_ctrl_txt, send_ctrl_txt
4
5
2
3
8
9
6
7
INTEGER status, reclength, reccount, sendcount, timeout
.
.
.
forms_status = forms$receive (session_id,
1 ’one_record’, one, ! number of records received rec_ctrl_txt,reccount, ! receive ctl text msg/ct send_ctrl_txt,sendcount, ! send ctl text msg/ct timeout,
,
, descriptor1,
)
! session id
! form record
! timeout
! parent request id
! request options item list
! info received from form
! shadow rec
CALL check_forms_status( forms_status )
The external request call in the preceding example causes the Form
Manager to perform the following tasks: a. Validate the arguments in the request.
b. Verify that session_id names a valid session.
c. Perform the control text responses named in send_ctrl_txt.
d. Perform the RECEIVE RESPONSE.
e. Copy the values stored in form data items that correspond to the
’ one_record
’ record to the application program record. The address of the application program record is specified by descriptor1.
f. Store any receive control text items in rec_ctrl_txt.
g. Return control to the application program.
5–42 Using the OpenVMS API
TRANSCEIVE
TRANSCEIVE
Combines the functionality of the SEND and RECEIVE requests in a single request.
Format
ret-status=FORMS$TRANSCEIVE
( session-id, send-record-name, send-record-count, receive-record-name, receive-record-count,
[receive-control-text, receive-control-text-count],
[send-control-text, send-control-text-count],
[timeout],
[
[parent-request-id],
[request-options],
[
] . . .
[send-record-message],
[send-shadow-record],
)
] . . .
[receive-record-message],
[receive-shadow-record],
Returns
OpenVMS usage: type: access: mechanism: cond_value longword (unsigned) write only by value
Using the OpenVMS API 5–43
TRANSCEIVE
Arguments
See the sections on the SEND and RECEIVE requests for descriptions of the
TRANSCEIVE arguments.
Description
The TRANSCEIVE request causes the Form Manager to combine the functionality of a SEND request and a RECEIVE request. First, the Form
Manager moves data from application program record fields to form data items. When the request completes, the Form Manager then moves data from form data items to application program record fields.
Return Values
FORMS$_BADARG
FORMS$_BADRECCNT
FORMS$_BADRECLEN
FORMS$_BAD_
RSHDWRECLEN
FORMS$_BAD_
SSHDWRECLEN
FORMS$_CANCELLED
FORMS$_INVRECDES
FORMS$_NORECORD
Bad argument or incorrect argument format for request.
The number specified in the record-count argument in the request call does not match the number of records specified in the form.
The length of the program record and the form record do not match. Either the program record descriptor length or the form record length is incorrect.
The request call specified a length for the
receive-shadow-record argument that does not match the length of the receive-shadow-record argument in the form.
The request specified a length for the
send-shadow-record argument other than
1.
FORMS$TRANSCEIVE processing was interrupted by arrival of CANCEL request.
Invalid record message descriptor. One of the record message descriptors passed in
FORMS$TRANSCEIVE is invalid.
FORMS$TRANSCEIVE specified a record identifier that is not in this form.
5–44 Using the OpenVMS API
TRANSCEIVE
FORMS$_NORMAL
FORMS$_NOSESSION
FORMS$_PENDING
FORMS$_TIMEOUT
FORMS$TRANSCEIVE was completed successfully.
The session-identification string you passed in
session-id does not match an existing session.
An asynchronous operation that you started has not yet been completed.
Input was not completed in the specified time.
Example
8
9
6
7
4
5
2
3
3
4
1
2
CHARACTER*16 session_id
.
.
.
forms_status = forms$transceive(session_id,
1 ’update’,
%ref(count),
%ref(count),
,,
,,
,
! session id
! send form record
! number of records sent
’operator_choice’, ! receive form record
,
, descriptor1,
, descriptor2,
)
! number of records received
! receive ctl txt/count
! send ctl txt/count
! timeout
! parent request id
! request options
! program record data sent to form
! send shadow record
! program record data from form
! recv shadow record
CALL check_forms_status( forms_status )
The request call in this language example causes the Form Manager to perform the following tasks: a. Validate the arguments in the request.
b. Verify that session-id names a valid session.
c. Copy the values stored in application program record fields to the form data items that correspond to the
’ update
’ form record. Descriptor1 specifies the address of the application program record from which data is copied.
d. Perform the TRANSCEIVE response, if defined. If no TRANSCEIVE response is defined, perform the RECEIVE response for the receive record message,
’ operator_choice
’
.
Using the OpenVMS API 5–45
TRANSCEIVE
e. Copy the values stored in form data items that correspond to the
’ operator_choice
’ form record to the application program record.
Descriptor2 specifies the address of the application program record.
f. Return control to the application program.
5–46 Using the OpenVMS API
CANCEL
CANCEL
Cancels the current request and all outstanding requests for the specified session.
Format
ret-status = FORMS$CANCEL
(session-id [,request-options] )
Returns
OpenVMS usage: type: access: mechanism: cond_value longword (unsigned) write only by value
Arguments
session-id
OpenVMS usage: char_string type: access: mechanism: character-coded text string read only by descriptor
Required argument that contains a unique session-identification string. The
Form Manager returns the session-identification string to your application program during the processing of an ENABLE request.
You must pass session-id because the session-identification string identifies which session you want the Form Manager to cancel.
The string you specify must be 16 bytes long.
request-options
OpenVMS usage: item_list_2 type: access: mechanism: longword (unsigned) read only by reference
Optional item list containing request-specific arguments that control the environment of the request.
Using the OpenVMS API 5–47
CANCEL
Request-options is the address of an OpenVMS item list containing zero or more request arguments. Each item consists of three longwords.
The first longword consists of two fields: a 1-word field that contains the length of the application buffer, and a 1-word field containing the item code value.
The second longword contains the address of the application buffer that either contains or will receive the data.
The third longword contains the address of a word to receive the length of the data written into the buffer. (The third longword is optional and is useful when the specified item code indicates that data will be returned to the application.)
The item list is terminated by a longword containing a 0.
Certain item codes correspond to logical names that the Form Manager translates during request processing. If you specify an item code, the Form
Manager reads the item code directly and does not attempt to translate the corresponding logical names.
Table 5–5 contains the item codes that can be specified and their explanations.
Table 5–5 FORMS$CANCEL Request Options
Item Code Description
FORMS$K_ASTADR
FORMS$K_ASTPRM
FORMS$K_EFN
The asynchronous system trap (AST) service routine to be executed when the request is complete. The buffer address field of the item contains the address of the entry mask for this routine.
The AST argument to be passed to the AST service routine. The buffer address field of the item contains the address of a longword value containing the value to be passed.
Event flag the Form Manager sets when it completes the request. The buffer address field of the item contains the event flag number.
The Form Manager clears the specified event flag at the beginning of the request.
(continued on next page)
5–48 Using the OpenVMS API
CANCEL
Table 5–5 (Cont.) FORMS$CANCEL Request Options
Item Code Description
FORMS$K_RSB The quadword request status block to receive the completion status of the request. The buffer address field of the item contains the address of a DECforms quadword status block where the Form Manager writes the return status of the request.
The Form Manager returns the final condition value of the request in the first longword of the status block. The second longword is reserved for future use.
Description
The CANCEL request causes the Form Manager to cancel the processing of any request that is in progress for the specified session and any outstanding request for that session. The cancelled requests end with the status
FORMS$_CANCELLED.
CANCEL executes asynchronously with respect to the requests that it cancels;
CANCEL returns to the routine that called it before it cancels the specified request.
Calling FORMS$CANCEL directs the Form Manager to terminate the current request as quickly as possible. No additional input or output to the screen is started nor is any data returned to the program.
Because a cancelled request may have been outputting data to the screen at the time it was cancelled, the contents of the display may not accurately reflect the current values of form data as stored in the form.
To ensure that the screen is correct after you cancel a request, issue the
REFRESH response step or press Ctrl/W to refresh the screen.
FORMS$CANCEL should be restricted to cases where the operator has clear and unmistakable feedback from the form that a request has been cancelled.
Using the OpenVMS API 5–49
CANCEL
Return Values
FORMS$_BADARG
FORMS$_CANINPROG
FORMS$_NOACTREQ
FORMS$_NORMAL
FORMS$_NOSESSION
Bad argument or incorrect argument format for request.
A previous CANCEL request is in progress.
No active request to cancel.
FORMS$CANCEL was completed successfully.
No session was active.
Example
CHARACTER*16 session_id
INTEGER forms_status
.
.
.
forms_status = FORMS$CANCEL(session_id,)
The request call in the preceding example would cause the Form Manager to perform the following tasks: a. Validate the arguments in the request.
b. Verify that session_id names a valid session.
c. Cancel the request.
d. Return control to the application program.
5–50 Using the OpenVMS API
6
Using the Portable API
This chapter describes the DECforms application programming interface (API) for C and FORTRAN.
The portable API interface supports the following languages:
• DEC C
• HP FORTRAN
When you convert large applications from the OpenVMS API to either the C or FORTRAN API syntax, you may need to use portions of both interfaces temporarily. However, for applications running in a production environment, you should avoid mixing the two interfaces because signal handling, parameter validations, and other functions are designed differently to solve different problems.
The portable API bindings are designed to provide a simple DECforms interface.
Table 6–1 contains a list of the available routine parameters.
Table 6–1 Portable API Routine Parameters
Routine Parameter Request
Form Name
Form File Name
Device Name
Session Id
Send Record Name
Send Record Structure
Receive Record Name
Receive Record Structure
Request Option Structure
ENABLE
ENABLE
ENABLE
All requests
SEND and TRANSCEIVE
SEND and TRANSCEIVE
RECEIVE and TRANSCEIVE
RECEIVE and TRANSCEIVE
All requests
Using the Portable API 6–1
The definitions for the Form Name, Form File Name, Device Name, Session Id, and Send and Receive Record Name parameters remain unchanged from the
DECforms OpenVMS API; however, the data types are different.
In the portable API, you pass records by using a predefined structure named
Forms_Record_Data. You specify optional parameters by using a predefined structure named Forms_Request_Options.
A DECforms portable library file defining all the literals and type definitions is provided for DECforms portable application programs that use the C and
FORTRAN languages:
• formsdef.h—for C programs
• formsdef.f—for FORTRAN programs
These files contain external routine declarations for the bindings, type definitions for C binding users, literal definitions, and structure definitions for
Forms_Record_Data and Forms_Request_Options.
A copy of these files exists in SYS$LIBRARY.
6.1 Using the Forms_Record_Data Structure
Forms_Record_Data is a structure containing four elements. These elements are listed in Table 6–2.
Table 6–2 Forms_Record_Data Elements
Element Required or Optional
Data_record
Data_length
Shadow_record
Shadow_length
Required
Required
Optional
Optional
Forms_Record_Data stores either send or receive data record information and shadow record information. This structure is a required parameter for the
RECEIVE and TRANSCEIVE request calls.
To pass records, record parameters such as send record and receive record in a request call are used to pass the address of a single structure or an array structure of Forms_Record_Data. To pass a single record, you do not need to specify the record count to DECforms. DECforms sets the record count to 1 by default. If you pass zero or more than one record, you must specify
6–2 Using the Portable API
the record count representing the actual number of records being passed in
Forms_Request_Options.
For example, to pass two records, declare and use the array as follows:
C Binding
#include <formsdef.h> void sample_send( Forms_Session_Id session_id )
{
Forms_Request_Options request_options[2];
Forms_Record_Data
Forms_Status struct_record { int a; int b; send_records[2]; forms_status;
} record1 = {1,2}; struct_record2 { int a; int b; int c;
} record2 = {3,4,5}; char shadow2[1];
/*
/* Setting up send records
/*
*/
*/
*/ send_records[0].data_record
= &record1; send_records[0].data_length
= sizeof (record1); send_records[0].shadow_record = NULL; send_records[0].shadow_length = 0; send_records[1].data_record
= &record2; send_records[1].data_length
= sizeof(record2); send_records[1].shadow_record = &shadow2; send_records[1].shadow_length = 4;
/* */
/* Specifying record count in request option */
/* */ request_options[0].option = forms_c_opt_send_record; request_options[0].send_record.count= 2; request_options[1].option = forms_c_opt_end;
Using the Portable API 6–3
forms_status = forms_send( session_id, record_list_name, send_records, request_options); check_forms_status (forms_status)
}
FORTRAN Binding
SUBROUTINE sample_send (session_id)
INCLUDE ’formsdef.f’
C
C Declare record1 and record2
C
Character*16 session_id
RECORD /Forms_Record_Data/ send_records(2)
RECORD /Forms_Request_Options/ request_options(2)
STRUCTURE /r1/
INTEGER a
INTEGER b
END STRUCTURE
STRUCTURE /r2/
INTEGER a
INTEGER b
INTEGER c
END STRUCTURE
RECORD /r1/ record1
RECORD /r2/ record2
CHARACTER*1 shadow2
INTEGER forms_status
C
C Init record1 and record2
C record1.a = 1 record1.b = 2 record2.a = 3 record2.b = 4 record2.c = 5
C
C Set up send record
C send_records(1).data_length
= 8 send_records(1).data_record
= %LOC (record1) send_records(1).shadow_length = 0 send_records(1).shadow_record = 0
6–4 Using the Portable API
send_records(2).data_length
= 12 send_records(2).data_record
= %LOC (record2) send_records(2).shadow_length = 4 send_records(2).shadow_record = %LOC (shadow2)
C
C Set up record count
C request_options(1).option = forms_c_opt_send_record request_options(1).send_record_count = 2
+
+
+
+ request_options(2).option = forms_c_opt_end forms_status = forms_send_for ( session_id, record_list_name, send_records, request_options)
CALL check_form_status (forms_status)
END
6.2 Using the Forms_Request_Options Structure
Forms_Request_Options is a union that contains groups of small structures and a special element named option. To set up a request option list, you declare an array of at least two elements of type Forms_Request_Options and specify the name for the structure to be used in the option variable. To end a request option list, assign the symbolic constant, forms_c_opt_end, to the option variable in the last array element.
For example, to specify a print file name, declare the following:
C Binding
# define PRINT_FILE_NAME "MY_FORM.TXT"
Forms_Request_Options enable_request_options[2]; enable_request_options[0].option = forms_c_opt_print; enable_request_options[0].print.file_name = PRINT_FILE_NAME; enable_request_options[0].print.file_name_length = strlen(PRINT_FILE_NAME); enable_request_options[1].option = forms_c_opt_end;
Using the Portable API 6–5
FORTRAN Binding
CHARACTER*(*) print_file_name
PARAMETER (print_file_name=’SYS$SCRATCH:FORMS$CHECKING_FORM.TXT’)
RECORD /Forms_Request_Options/ enable_request_options(2) enable_request_options(1).option = forms_c_opt_print enable_request_options(1).print_file_name = %LOC (print_file_name) enable_request_options(1).print_file_name_length = LEN(print_file_name) enable_request_options(2).option = forms_c_opt_end
Certain option codes correspond to logical names that the Form Manager translates during request processing. If you specify an option code, the Form
Manager reads the option code directly and does not attempt to translate the corresponding logical names. Table 6–3 lists the request options that you can use in the portable API requests. The names in the leftmost column (Option
Type Code) are used in the format forms_c_opt_code to describe the name of the request option and in the format .code in the option declaration. The names in the next column (Field) are elements for each option structure. (To see how the options are declared, see the examples in this section.)
Table 6–3 Request Options for the Portable API
Option Type Code Field Request Type Description
send_record send_control receive_record receive_control count text text_count count text
SEND
TRANSCEIVE
SEND
TRANSCEIVE
SEND
TRANSCEIVE
RECEIVE
TRANSCEIVE
RECEIVE
TRANSCEIVE
Number of data records to be passed from the application program to the form
Control text to be passed to the form
Number of control text items to be passed to the form
Number of data records to be passed from the form to the application program
Control text to be returned by the form
(continued on next page)
6–6 Using the Portable API
Table 6–3 (Cont.) Request Options for the Portable API
Option Type Code Field Request Type Description
trace print language timeout text_count file_name file_name_length flag file_name file_name_length name name_length period completion_routine address completion_status parameter address
RECEIVE
TRANSCEIVE all all all all all
ENABLE
ENABLE all all all all
Number of control text items to be returned by the form
Name of trace file that receives output trace logging
Length of trace file name (number of characters)
Flag to turn trace on or off
Name of print file that receives output text
Length of print file name (number of characters)
Name of language to match during layout selection
Length of language name (number of characters)
Describes timeout period; limits to 32767 seconds or less
Address of completion routine—equivalent to
FORMS$K_ASTADR and FORMS$K_
ASTPRM in the
OpenVMS API
Completion routine parameter
Address of completion status—equivalent to
FORMS$K_RSB in the
OpenVMS API
(continued on next page)
Using the Portable API 6–7
Table 6–3 (Cont.) Request Options for the Portable API
Option Type Code Field Request Type Description
parent_request form no_term_io id object flag all
ENABLE
Session id of parent request—used in call to escape routine
Form object for linked form and table
Suppresses terminal I/O selection_label name
DISABLE
SEND
RECEIVE
TRANSCEIVE
ENABLE name_length ENABLE
Label name for a
PRINTER layout
Length of label name string (number of characters)
You must pass all character string elements in Forms_Request_Options by reference. Each string element, except for parent_request_id, send_control_text and receive_control_text, has a corresponding string length element. You must specify the length of each string element either by using the string length element corresponding to it or by terminating the string with a null. If you terminate a string with a null and specify the corresponding string length to a nonzero value, DECforms uses the corresponding string length.
Parent_request_id and receive_control_text are pointers to fixed length elements in Forms_Request_Options. Parent_request_id should be a pointer to a string of 24 characters, and receive_control_text must be a pointer to a string of 25 characters. DECforms assumes that you have allocated enough memory to store information in these elements.
The receive control text count in Forms_Request_Options indicates how many control text items are written into the receive control text string. Each control text item is five characters in length. Use send_control_text_count to specify how many control text items are passed to DECforms.
In Forms_Request_Options, timeout is defined as type integer. However, due to a restriction in the OpenVMS terminal driver, the timeout value for any request is limited to the range between 0 and 32,767 seconds.
6–8 Using the Portable API
6.3 Using Disk-Based Forms or Linked Forms
With the DECforms portable API bindings, your program must enable a separate disk-based binary form. With the OpenVMS API, you can either enable a disk-based form or link the form in with your program.
The portable API binding does not support the use of shareable forms because the use of shareable images is not a portable concept.
To enable a disk-based form, specify your binary form name in the ENABLE request call in the program. (If you leave out the file type, the Form Manager looks for .form.)
For example:
C Binding
status = forms_enable (session_id,
NULL,
"my_form_file",
,
);
FORTRAN Binding
/* session ID */
/* current device */
/* name of form file */
/* no form name specified*/
/* no request options */
+
+
+
+ status = forms_enable_for (session_id,, device_name,
’my_form_file’,
,
);
To enable a linked form, do the following:
1. Use the DECforms Extract Object Utility to create a form object file from your binary form file.
Specify the /PORTABLE_API qualifier in the FORMS EXTRACT OBJECT command to convert form files into form object files for the DECforms API bindings.
2. Declare an external global variable using the name of your form.
Do this by using the name of the form with the type Forms_Form_Object in the C binding or EXTERNAL INTEGER in the FORTRAN binding.
The Linker resolves the value of this global variable by using information produced by the DECforms Extract Object Utility.
3. Set up in Forms_Request_Options a form object option that uses the global variable.
Using the Portable API 6–9
4. Specify your form name and the request option in the ENABLE request call in the program.
For example:
C Binding
Forms_Form_Object
Forms_Session_Id my_form_name; session_id;
Forms_Request_Options enable_options[2]; enable_options[0].option = forms_c_opt_form; enable_options[0].form.object = my_form_name; enable_options[1].option = forms_c_opt_end; status = forms_enable (session_id,, device_name,
,
"my_form_name", enable_options);
FORTRAN Binding
INTEGER
EXTERNAL my_form_name my_form_name
CHARACTER*(16) session_id
RECORD /Forms_Request_Options/ enable_options(2) enable_options(1).option = forms_c_opt_form enable_options(1).form_object = %LOC (my_form_name) enable_options(2).option = forms_c_opt_end;
+
+
+
+ status = forms_enable_for (session_id, device_name,
,
’my_form_name’, enable_options);
6.4 Using Escape Routines
You must link escape routines with the application program when you use the
DECforms portable API. To resolve escape routine references in your form, you must create a form object file by using the Forms Extract Object Utility. The form object file resolves the escape routine references when escape routines are linked in. You then link the form object file with your escape routines and application program.
If you plan to use a disk-based form, you should use the /NOFORM_LOAD qualifier with the FORMS EXTRACT OBJECT command. If you plan to use a linked form, use the /FORM_LOAD qualifier when you create your form object.
6–10 Using the Portable API
For more information about escape routines, see Section 2.3. For an example of linking escape routines with your application program, see the HP
DECforms Guide to Developing an Application. For a description of the
FORMS EXTRACT OBJECT command, see the HP DECforms Guide to
Commands and Utilities.
6.5 Using Error Message Routines
DECforms provides an error message routine named forms_errormsg( ) for
C and forms_errormsg_for( ) for FORTRAN. These routines translate return values from a DECforms request into meaningful message text. These routines require a request status number and a string pointer pointing to pre-allocated memory large enough to store up to 256 characters. DECforms stores the message text in the location specified by the given string pointer.
The following examples show routine descriptions for both C and FORTRAN bindings.
Routine Description for C
char msg_text_ptr[256]; void forms_errormsg ( Forms_Status errno,
Forms_Text_Ptr msg_text_ptr);
Routine Description for FORTRAN
SUBROUTINE forms_errormsg_for ( INTEGER errno,
CHARACTER*(256) msg_text_ptr)
6.6 Referencing Error Numbers
There are three types of errors that can occur during a call to the portable C or
FORTRAN interface:
• FIMS-defined errors
• DECforms defined errors
• User-defined errors
User-defined errors are passed using the control text fields in the Forms_
Request_Options union structure. Errors related to the FIMS standard and to DECforms software are passed as status values returned by the request calls. The status values are also called FIMS error numbers. Each number is a unique integer associated with some request condition.
An error number is a positive or negative decimal number. Positive numbers represent a status defined by FIMS. Negative numbers represent a status specific to DECforms.
Using the Portable API 6–11
Successfully processed requests receive a status value of 0. Literals are defined in the formsdef.h and formsdef.f header file for referring to these status numbers; for example, forms_s_normal = 0. You can find the meaning of each status number in the header files.
Table 6–4 lists the error numbers, definitions, corresponding control texts, and matching symbolic constants. Table 6–4 should only be used as reference. For the most up-to-date list, refer to the formsdef.h or formsdef.f header file that ships in your kit.
Table 6–4 Error Numbers
Definition
Error
Number
Control
Text
forms_s_normal forms_s_timeout
0
1
S000
ES001 forms_s_formerror forms_s_nolayout forms_s_invdevice forms_s_hangup forms_s_norecord forms_s_badreclen forms_s_inuse forms_s_nosession forms_s_return_immed forms_s_nodecpt forms_s_bad_rshdwreclen 15
12
14 forms_s_bad_sshdwreclen 16
2
3
4
5
7
8
10
11
ES002
ES003
ES004
ES005
ES007
ES008
ES010
ES011
ES012
ES014
ES015
ES016
Description
Request calls completed successfully.
Input was not completed in the specified time.
Encountered problem when using form file.
No layout fit terminal type, language, and display size.
Invalid device specified in ENABLE.
Data set hangup; session disabled.
Specified record identifier not in form.
Record length argument does not match length of record in form.
Attempted to disable a form still in use.
session_id does not match existing session.
Request terminated due to REQUEST
IMMEDIATE.
Decimal or comma decimal point positioned incorrectly in record field.
Length of receive-shadow-record does not match length specified in form.
Length of send-shadow-record is something other than 1.
(continued on next page)
6–12 Using the Portable API
Table 6–4 (Cont.) Error Numbers
Definition
Error
Number
Control
Text
forms_s_cancelled 17 ES017 forms_s_noactreq forms_s_invlobound forms_s_invhibound forms_s_illdtcvt forms_s_badreccnt forms_s_converr forms_s_aborted forms_s_badarg forms_s_baditmlstcode forms_s_baditmlstcomb forms_s_blocked_by_ast forms_s_bad_devhlr forms_s_caninprog forms_s_cantopendic forms_s_closetrace forms_s_deverr forms_s_disinprog forms_s_exprevalerr forms_s_fatinterr forms_s_illctltxtcnt forms_s_illfldvaluectx forms_s_illvpuse
–3
–4
–5
–6
–7
19
24
25
–1
–2
–8
–9
–10
–46
–11
–12
–13
–14
–15
–16
–17
–18
ES019
ES024
ES025
EI001
EI002
EI003
EI004
EI005
EI006
EI007
EI008
EI009
EI010
EI046
EI011
EI012
EI013
EI014
EI015
EI016
EI017
EI018
Description
Request interrupted by arrival of
CANCEL.
No active requests to CANCEL.
Subscript reference less than base.
Subscript reference greater than array dimension defined.
Illegal DATE, TIME, ADT conversion.
Number of records does not match number specified in record list.
Error while converting from one data type to another.
Session ended abnormally due to severe error in another request.
Bad argument or incorrect format.
Invalid item code found in item list.
Invalid combination of item codes found in item list.
Cannot process request; block by application AST.
Invalid device handler.
Previous CANCEL is in progress.
Cannot open dictionary.
Cannot close trace file.
Device I/O error.
Previous DISABLE is in progress.
Cannot convert operands into common data type.
Fatal internal error.
Illegal control text count argument.
Illegal FIELDVALUE context.
Illegal use of print viewport.
(continued on next page)
Using the Portable API 6–13
Table 6–4 (Cont.) Error Numbers
Definition
Error
Number
Control
Text
forms_s_intdatcor forms_s_invrange forms_s_invreccnt forms_s_invrecdes forms_s_nohandler forms_s_nolicense
–19
–20
–21
–22
–23
–24
EI019
EI020
EI021
EI022
EI023
EI024 forms_s_noparent forms_s_no_read_access forms_s_openout forms_s_opentrace forms_s_paramovrflow forms_s_procesc_not_ found forms_s_proc_escape_ error forms_s_recvrecitems forms_s_reqdarg forms_s_sendrecitems
–33
–34 forms_s_strtooshort forms_s_writetrace
–35
–36 forms_s_no_write_access –37 forms_s_bckgrndio –38 forms_s_timeract –39
–30
–31
–32
–25
–26
–27
–28
–29
EI025
EI026
EI027
EI028
EI029
EI030
EI031
EI032
EI033
EI034
EI035
EI036
EI037
EI038
EI039
Description
Database consistency check failed.
Invalid subscript range.
Invalid record count value.
Invalid record message descriptor.
No device handler for such device.
No DECforms software license is active.
Specified parent request does not exist.
No read access to user argument.
Cannot open specified output file.
Cannot open trace file for output.
Escape routine parameter has overflowed.
Cannot find address of procedural escape.
Request ended due to severe error in escape routine.
Number of receive record items does not match record count value.
Required argument missing.
Number of send record items does not match record count value.
Length of string is too small.
Cannot write to trace file.
No write access to user argument.
Attempted read or write I/O from background process.
Attempted timed field input while alarm active.
(continued on next page)
6–14 Using the Portable API
Table 6–4 (Cont.) Error Numbers
Definition
Error
Number
Control
Text
forms_s_blkbyreq –40 EI040 forms_s_imgmismatch forms_s_nyi
–41
–42
EI041
EI042
Description
Attempted synchronous request while another request active.
Shareable image mismatch.
Requested operation is not yet implemented.
6.7 C and FORTRAN Request Calling Description
This section describes each DECforms C and FORTRAN request in a structured format that provides the following information:
• The name of the request and a sentence describing its purpose
• The syntax of the request
• A description of each argument
• A complete description of the request
• An example of using each request in the FORTRAN and C bindings
For examples of how to include requests in an application program, see
Chapter 2. For information on how the Form Manager processes requests, see
Chapter 4.
Using the Portable API 6–15
ENABLE
ENABLE
Initializes a DECforms session.
C Binding
#include <formsdef.h>
Forms_Status forms_enable (
Forms_Session_Id
Forms_Text_Ptr
Forms_Text_Ptr
Forms_Text_Ptr
Forms_Request_Options session_id, device_name, form_file_name, form_name, request_options[ ] );
FORTRAN Binding
INCLUDE ’FORMSDEF.F’
INTEGER*4 FUNCTION forms_enable_for ( session_id, device_name, form_file_name, form_name, request_options )
CHARACTER*16
CHARACTER*(*)
CHARACTER*(*)
CHARACTER*(*) session_id device_name form_file_name form_name
RECORD /Forms_Request_Options/ request_options
Arguments
session_id
type: access: character-coded text string write only mechanism: by reference
Required argument that is filled by the Form Manager. In this argument, the Form Manager returns a 16-byte character session identification string.
Session_id associates the display device with the form that was loaded into memory.
You must pass this session identification string in subsequent request calls to tell the Form Manager which display device and form you want the Form
Manager to use.
6–16 Using the Portable API
ENABLE device_name
type: access: character-coded text string read only mechanism: by reference
Required argument that is a character string name for the device to be used as the display device during this session.
You can define a logical name for the device name and pass that logical name in device_name: you can specify SYS$INPUT or a file name as the device name to use a terminal or a DDIF output file, respectively.
When you do not specify device_name or you specify device_name as NULL in the forms_enable call, a FORMS$DEFAULT_DEVICE logical name is available for specifying device_name. If device_name is omitted or NULL and
FORMS$DEFAULT_DEVICE is undefined, SYS$INPUT is used.
form_file_name
type: access: character-coded text string read only mechanism: by reference
Specifies the character string file specification of the form file to be used during this session. This argument is optional. The file specification can include: node name device name directory specification file name file type file version number
If you omit the node name, device name, or directory specification, the Form
Manager uses the node you are logged into, the current default device, and the current default directory, respectively.
Using the portable API:
• You can define a logical name for the file specification and pass that logical name in form_file_name.
• If you do not specify form_file_name, you must specify form_name.
• If you omit the file version number, the Form Manager uses the latest version (highest version number) of the specified file.
• If you omit the file type, the Form Manager looks for a file with the .form
type.
Using the Portable API 6–17
ENABLE form_name
type: access: character-coded text string read only mechanism: by reference
Specifies the name of the form in the IFDL source file.
If you do not specify form_name, you must specify form_file_name.
request_options
type: access:
Forms_Request_Options read only mechanism: by reference
Optional item list containing request-specific arguments that control the environment of the request.
For more information about request options, see Section 6.2.
Table 6–5 contains the Request Option codes that can be specified and their explanations.
Table 6–5 FORMS_ENABLE Request Options
Item Code Description
forms_c_opt_selection_label forms_c_opt_default_color forms_c_opt_default_term forms_c_opt_no_term_io forms_c_opt_form forms_c_opt_trace forms_c_opt_print forms_c_opt_language forms_c_opt_completion_status forms_c_opt_completion_routine forms_c_opt_end forms_c_opt_parent_request
Selection label value for PRINTER layout
Default color type
Default terminal type
Suppress terminal IO
DECforms Form Object
Name of trace file and flag
Name of print file to use
Name of language to match
Location of store completion status
Completion routine and parameter
End of Request Options
Specifies parent_request_id
(continued on next page)
6–18 Using the Portable API
ENABLE
Table 6–5 (Cont.) FORMS_ENABLE Request Options
Item Code Description
forms_c_opt_receive_control forms_c_opt_send_control forms_c_opt_timeout
Receive control text information
Send control text information
Timeout period
Description
The ENABLE request loads the specified form file into memory, selects an appropriate layout, and attaches the specified display device. The Form
Manager also returns a unique session-identification string and initializes all form data items. For more information about initializing an ENABLE request, see Section 4.1.2.
You can include more than one ENABLE request call in your application program because the Form Manager supports multiple synchronous requests to display devices. For example, the operator’s device can be enabled for two different sessions. The Form Manager can perform operations in any enabled session.
Examples
1.
status = forms_enable( session_id,
NULL,
"myform",
NULL,
NULL);
/* Session id returned */
/* Current device */
/* Name of form file */
/* Name of the form */
/* No request Options */
This C binding example enables a form, provides the form file name, specifies a NULL device name, and uses no request options.
2.
#include <formsdef.h>
#include <stdio.h>
#define PRINT_FILE_NAME "monthly_report"
#define OTHER_PRINT_FILE "weekly_report" main()
{
Forms_Session_Id session_id;
Forms_Request_Options enable_options[3];
Forms_Status status;
/* To generate the monthly report: */
Using the Portable API 6–19
ENABLE
enable_options[0].option = forms_c_opt_selection_label; enable_options[0].selection_label.name = PRINT_FILE_NAME; enable_options[0].selection_label.name_length = strlen(PRINT_FILE_NAME); enable_options[1].option = forms_c_opt_end; status = forms_enable(session_id,
"printed_form.doc",
"myform",
NULL, enable_options); if (status != forms_s_normal)
{ return;
} forms_disable(session_id, 0);
/* To generate the weekly report: */ enable_options[0].option = forms_c_opt_selection_label; enable_options[0].selection_label.name = OTHER_PRINT_FILE; enable_options[0].selection_label.name_length = strlen(OTHER_PRINT_FILE); enable_options[1].option = forms_c_opt_end; status = forms_enable(session_id,
"printed_form.doc",
"myform",
NULL, enable_options); if (status != forms_s_normal)
{ return;
} forms_disable(session_id, 0);
}
6–20 Using the Portable API
ENABLE
Written in the C binding, this example:
• Enables a form.
• Provides the form file name.
• Specifies the DDIF output file name printed_form.doc.
• Specifies the name of the form file.
• Specifies a NULL form name.
• Uses request options to select between two PRINTER layouts with LAYOUT SELECTION clauses labeled "monthly_report" and
"weekly_report" in the IFDL source file.
3.
print_file = ’forms_checking_form.txt’ request_options(1).option = forms_c_opt_print request_options(1).print_file_name = %LOC (print_file) request_options(1).print_file_name_length = 23 request_options(2).option = forms_c_opt_end
+
+
+
+ status = forms_enable_for(
+ session_id,
,
’my_forms’,
, request_options)
! session id
! current device
! name of form file
This FORTRAN example shows how to set a request option in the print file name by using a file whose name is in a string variable.
Using the Portable API 6–21
DISABLE
DISABLE
Terminates a session.
C Binding
#include <formsdef.h>
Forms_Status forms_disable (
Forms_Session_Id
Forms_Request_Options session_id, request_options[ ] );
FORTRAN Binding
INCLUDE ’FORMSDEF.F’
INTEGER*4 FUNCTION forms_disable_for ( session_id, request_options )
CHARACTER*16 session_id
RECORD /Forms_Request_Options/ request_options
Arguments
session_id
type: access: character-coded text string read only mechanism: by reference
Required argument that contains a unique session-identification string. The
Form Manager returns the session-identification string to your application program during the processing of an ENABLE request.
You must pass this argument because the session-identification string identifies which display device and session you want the Form Manager to use during this request.
request_options
type: access:
Forms_Request_Options read only mechanism: by reference
Optional item list containing request-specific arguments that control the environment of the request.
For more information about request options, see Section 6.2.
6–22 Using the Portable API
DISABLE
Table 6–6 shows the request options that you can specify.
Table 6–6 FORMS_DISABLE Request Options
Item Code Description
forms_c_opt_trace forms_c_opt_completion_status forms_c_opt_completion_routine forms_c_opt_end forms_c_opt_receive_control forms_c_opt_send_control forms_c_opt_timeout
Name of trace file and options
Location of store completion status
Completion routine and parameter
End of request options
Receive control text information
Send control text information
Timeout period
Description
The DISABLE request terminates the specified session. The Form Manager detaches the display device and the form that are associated with the sessionidentification string. Once the Form Manager completes the processing of this request, the session specified by the session-identification string no longer exists. The values of all form data items in the form are disabled last.
Example
status = forms_disable ( session_id, NULL);
This C example disables a form and does not pass any request options.
Using the Portable API 6–23
SEND
SEND
Copies data from an application program record to form data items.
C Binding
#include <formsdef.h>
Forms_Status forms_send (
Forms_Session_Id
Forms_Text_Ptr session_id, send_record_name,
Forms_Record_Data send_record[ ],
Forms_Request_Options request_options[ ] );
FORTRAN Binding
INCLUDE ’FORMSDEF.F’
INTEGER*4 FUNCTION forms_send_for ( session_id, send_record_name, send_record, request_options )
CHARACTER*16
CHARACTER*(*)
RECORD /Forms_Record_Data/
RECORD /Forms_Request_Options/ session_id send_record_name send_record request_options
Arguments
session_id
type: access: character-coded text string read only mechanism: by reference
Required argument that contains a unique session-identification string. The
Form Manager returns the session-identification string to your application program during the processing of an ENABLE request.
You must pass this argument because the session-identification string identifies which DECforms session and form you want the Form Manager to use during this request.
6–24 Using the Portable API
SEND send_record_name
type: access: character-coded text string read only mechanism: by reference
Required argument that is a single-byte character string name of the form record (for single record transfers) or record list (for multiple record transfers) to which the Form Manager is passing data. Send_record_name is used to search for and trigger a send response within the form file.
The character string you pass in this argument must match a record name or record list name in the form.
send_record
type: access:
Forms_Record_Data read only mechanism: by reference
Required argument that contains information about the data to be passed from the application program to the form. This argument is a data structure that includes the following:
• Length of the actual record data
• Pointer to the actual record data
• Length of the shadow record data
• Pointer to the shadow record data
The number of send records passed must match the number of records specified in the form for send_record_name. This value must be greater than or equal to 0. If the record count is not equal to 1, the count must be passed using the
send_record request option.
request_options
type: access:
Forms_Request_Options read only mechanism: by reference
Optional item list containing request-specific arguments that control the environment of the request.
For more information about request options, see Section 6.2.
Using the Portable API 6–25
SEND
Table 6–7 contains the Request Option codes that you can specify.
Table 6–7 FORMS_SEND Request Options
Item Code Description
forms_c_opt_trace forms_c_opt_completion_status forms_c_opt_completion_routine forms_c_opt_end forms_c_opt_parent_request forms_c_opt_send_record forms_c_opt_send_control forms_c_opt_timeout
Name of trace file and options
Location of store completion status
Completion routine and parameter
End of Request Options
Specifies parent_request_id
Number of records being passed
Send control text information
Timeout period
Description
The SEND request causes the Form Manager to pass data from the application program record to form data items. If the form data items to which the Form
Manager moves the data are displayed, the Form Manager displays the data on the display device.
Optionally, the SEND RESPONSE for the record or record list can be executed, and various stages of form processing are invoked at the discretion of the form designer.
Examples
#define FIRST_NAME_SIZE 15
#define LAST_NAME_SIZE 20
#define CITY_SIZE
.
.
.
20
6–26 Using the Portable API
SEND
struct account_str { unsigned long account_number; sys_time unsigned long char char char char char char char char char date_established; zip_code; last_name[LAST_NAME_SIZE]; first_name[FIRST_NAME_SIZE];
}; middle_name[15]; street[30]; city[CITY_SIZE]; state[2]; home_phone[10]; work_phone[10]; password[12];
#define ACCOUNT_SIZE sizeof (struct account_str)
.
.
.
Forms_Record_Data record_data; /* Declare record data structure */ struct account_str account; char* account_name_string = "account"; record_data.data_record
= &account; record_data.data_length
= ACCOUNT_SIZE; record_data.shadow_record = NULL; record_data.shadow_length = 0; status=forms_send (session_id, account_name_string, record_data,
)
This C example, from the advanced sample checking application, distributes data for the ACCOUNT record to the form. There is no shadow record and no request options.
STRUCTURE account
INTEGER balance
END STRUCTURE
RECORD /account/ my_account
RECORD /Forms_Record_Data/ old_account
CHARACTER*16 session_id my_account.balance = 1000; old_account.data_record = %LOC(my_account) old_account.data_length = 4 old_account.shadow_record = 0 old_account.shadow_length = 0
Using the Portable API 6–27
SEND
+
+
+ status = forms_send_for(
+ session_id,
’old_account’, old_account,
0 )
This FORTRAN example sends one record named old_account to the form.
There is no shadow record and no request options.
6–28 Using the Portable API
RECEIVE
RECEIVE
Copies data from form data items to an application program record.
C Binding
#include <formsdef.h>
Forms_Status forms_receive (
Forms_Session_Id
Forms_Text_Ptr session_id, receive_record_name,
Forms_Record_Data receive_record[ ],
Forms_Request_Options request_options[ ] );
FORTRAN Binding
INCLUDE ’FORMSDEF.F’
INTEGER*4 FUNCTION forms_receive_for ( session_id, receive_record_name, receive_record, request_options )
CHARACTER*16
CHARACTER*(*) session_id receive_record_name
RECORD /Forms_Record_Data/ receive_record
RECORD /Forms_Request_Options/ request_options
Returns
type: access: longword (unsigned) write only mechanism: by value
Arguments
session_id
type: access: character-coded text string read only mechanism: by reference
Required argument that contains a unique session-identification string. The
Form Manager returns the session-identification string to your application program during the processing of an ENABLE request.
Using the Portable API 6–29
RECEIVE
You must pass this argument because the session-identification string identifies which DECforms session and form you want the Form Manager to use during this request.
receive_record_name
type: access: character-coded text string read only mechanism: by reference
Required argument that is a character-string name of a form record (for single record transfers) or a form record list (for multiple record transfers).
Receive_record_name is used to search for a form record or record list to use during data collection and trigger a RECEIVE RESPONSE within the form file.
receive_record
type: access:
Forms_Record_Data write only mechanism: by reference
Required argument that contains information about the data to be passed from the form to the application program. This argument is a data structure that includes the following:
• Length of the actual record data
• Pointer to the actual record data
• Length of the shadow record data
• Pointer to the shadow record data
The number of receive records passed must match the number of records specified in the form for receive_record_name. This value must be greater than 0. If the record count is not equal to 1, it must be passed by using the
receive_record request option.
request-options
type: access:
Forms_Request_Options read only mechanism: by reference
Optional list containing request-specific arguments that control the environment of the request.
For more information about request options, see Section 6.2.
6–30 Using the Portable API
RECEIVE
Table 6–8 contains the Request Option codes that can be specified and their explanations.
Table 6–8 FORMS_RECEIVE Request Options
Item Code Description
forms_c_opt_trace forms_c_opt_completion_status forms_c_opt_completion_routine forms_c_opt_end forms_c_opt_parent_request forms_c_opt_receive_record forms_c_opt_receive_control forms_c_opt_send_control forms_c_opt_timeout
Name of trace file and options
Location of store completion status
Completion routine and parameter
End of Request Options
Specifies parent_request_id
Number of records being passed
Receive control text information
Send control text information
Timeout period
Description
The RECEIVE request copies values from form data items to application program record fields. Optionally, the Form Manager executes the RECEIVE
RESPONSE for the record or record list.
Example
#define print_file_name "new_account.lis" struct _new_account { int balance;
} new_account = {0};
Forms_Request_Options request_option [2];
Forms_Record_Data account_record;
Forms_Session_Id session_id; account_record.data_length = sizeof (new_account); account_record.data_record = &new_account; account_record.shadow_record = NULL; account_record.shadow_length = 0; request_option[0].option = forms_c_opt_print; request_option[0].print.file_name = print_file_name; request_option[0].print.file_name_length = strlen (print_file_name); request_option[1].option = forms_c_opt_end;
Using the Portable API 6–31
RECEIVE
status = forms_receive( session_id
"new_account",
&account_record, request_option);
/* session_id
/* record name in form
*/
*/
/* send record structure */
/* printfile request option */
This C request call receives one record named account_record from the form.
There is no shadow record and a print file is specified in Forms_Request_
Options.
6–32 Using the Portable API
TRANSCEIVE
TRANSCEIVE
Combines the functionality of the SEND and RECEIVE requests in a single request.
C Binding
#include <formsdef.h>
Forms_Status forms_transceive (
Forms_Session_Id
Forms_Text_Ptr
Forms_Record_Data
Forms_Text_Ptr
Forms_Record_Data
Forms_Request_Options session_id, send_record_name, send_record[ ], receive_record_name, receive_record[ ], request_options[ ] );
FORTRAN Binding
INCLUDE ’FORMSDEF.F’
INTEGER*4 FUNCTION forms_transceive_for ( session_id, send_record_name, send_record, receive_record_name, receive_record, request_options )
CHARACTER*16
CHARACTER*(*)
RECORD /Forms_Record_Data/
CHARACTER*(*)
RECORD /Forms_Record_Data/
RECORD /Forms_Request_Options/ session_id send_record_name send_record receive_record_name receive_record request_options
Returns
type: access: longword (unsigned) write only mechanism: by value
Using the Portable API 6–33
TRANSCEIVE
Arguments
See the SEND and RECEIVE sections for descriptions of individual arguments.
Note
On a TRANSCEIVE, the send_record_count cannot be 0.
Description
The TRANSCEIVE request causes the Form Manager to combine the functions of a SEND request and a RECEIVE request. First, the Form Manager moves data from application program record fields to form data items. When the request completes, the Form Manager then moves data from form data items to application program record fields.
Example
#define print_file_name "new_account.lis" struct _new_account { int balance;
} new_account = {0};
Forms_Request_Options request_option [2];
Forms_Record_Data account_record;
Forms_Session_Id session_id; account_record.data_record = &new_account; account_record.data_length = sizeof (new_account); account_record.shadow_record = NULL; account_record.shadow_length = 0; request_option[0].option = forms_c_opt_print; request_option[0].print.file_name = print_file_name; request_option[0].print.file_name_length = strlen (print_file_name); request_option[1].option = forms_c_opt_end; status = forms_transceive( session_id
"new_account",
&account_record,
"new_account",
&account_record, request_option);
/* session_id
/* send record name in form
/* send record structure
/* receive record name in form */
/* receive record structure
/* request options
*/
*/
*/
*/
*/
6–34 Using the Portable API
TRANSCEIVE
This C request call transceives one record named account_record from the form. There is no shadow record and a print file is specified in Forms_
Request_Options.
Using the Portable API 6–35
CANCEL
CANCEL
Cancels the current request and all outstanding requests for the specified session.
C Binding
#include <formsdef.h>
Forms_Status forms_cancel (
Forms_Session_Id
Forms_Request_Options session_id, request_options[ ] );
FORTRAN Binding
INCLUDE ’FORMSDEF.F’
INTEGER*4 FUNCTION forms_cancel_for ( session_id, request_options )
CHARACTER*16
RECORD /Forms_Request_Options/ session_id request_options
Arguments
session_id
type: access: character-coded text string read only mechanism: by reference
Required argument that contains a unique session-identification string. The
Form Manager returns the session-identification string to your application program during the processing of an ENABLE request.
You must pass this argument because the session-identification string identifies which session you want the Form Manager to cancel.
request_options
type: access:
Forms_Request_Options read only mechanism: by reference
Optional item list containing request-specific arguments that control the environment of the request.
For more information about request options, see Section 6.2.
6–36 Using the Portable API
CANCEL
Table 6–9 contains the Request Option codes that can be specified and their explanations.
Table 6–9 FORMS_CANCEL Request Options
Item Code Description
forms_c_opt_completion_status forms_c_opt_completion_routine forms_c_opt_end
Location of store completion status
Completion routine and parameter
End of Request Options
Description
The CANCEL request causes the Form Manager to cancel the processing of any request that is in progress for the specified session and any outstanding request for that session. The cancelled requests end with the status forms_s_cancelled.
CANCEL executes asynchronously with respect to the requests that it cancels;
CANCEL returns to the routine that called it before it cancels the specified request.
The CANCEL request directs the Form Manager to terminate the current request as quickly as possible. No additional input or output to the screen is started nor is any data returned to the program.
Because a cancelled request may have been outputting data to the screen at the time it was cancelled, the contents of the display may not accurately reflect the current values of form data as stored in the form. To ensure that the screen is correct after you cancel a request, issue the REFRESH response step or press Ctrl/W (on VT devices) to refresh the screen.
The CANCEL request should be restricted to cases where the operator has clear and unmistakable feedback that a request has been cancelled.
Example
status = forms_cancel (session_id, NULL );
This C example cancels any requests that are in progress and does not pass any request options.
Using the Portable API 6–37
6.8 Structure Definitions for the C Interface
The file included in this section contains the structure definitions for Forms_
Request_Options and other predefined types for various DECforms requests.
These definitions are part of the C header file, formsdef.h, for the DECforms C request interface.
If you are using the C binding in the portable API to write your application, be sure to include this formsdef.h file.
This listing should only be used as a reference. For the most up-to-date list, refer to the formsdef.h file that is contained in your kit.
#if !defined (_FORMS_DEFINED)
#define _FORMS_DEFINED
/*
** ++
** FACILITY:
**
DECforms **
**
** ABSTRACT:
**
Include file for the DECforms API.
**
**
**
**
**
** --
*/
NOTE: This file must remain both C and C++ compatible.
Do not use C++ style comments or commands in this file.
/*
*
*
*
COPYRIGHT (c) 1993, 1997 BY
HEWLETT-PACKARD COMPANY, CALIFORNIA, MASS.
* THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED
* ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE
* INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER
* COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY
* OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY
* TRANSFERRED.
*
* THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
* AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY HP.
*
*
* HP ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS
* SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY HP.
*
*/
6–38 Using the Portable API
/* Possible values for the default terminal type option */
/* These are used in the Forms_Request_Options, for
/* the forms_c_opt_default_term option (below) typedef enum { forms_c_dev_vt100 = 0, forms_c_dev_vt100_noavo = 1,
*/
*/ forms_c_dev_vt200 forms_c_dev_vt300
= 2,
= 3, forms_c_dev_vt400 = 4, forms_c_dev_mswindows = 5
} Forms_Default_Term_Values; typedef long int Forms_Default_Term_Type;
/* Possible values for the default color type option
/* These are used in the Forms_Request_Options, for
/* the forms_c_opt_default_color option (below) typedef enum { forms_c_color_mono forms_c_color_regis
= 0,
= 4, forms_c_color_ansi
} Forms_Default_Color_Values;
= 8 typedef long int Forms_Default_Color_Type;
*/
*/
*/
/*
* Define Forms_Form_Object, which points to the global symbol created by the commands:
*
*
"forms extract object" (on OpenVms and Ultrix)
"forms object" (on Windows)
*/
#ifdef vms
#define Forms_Form_Object globalref void *
#elif defined (_WIN32) && defined (__cplusplus)
#define Forms_Form_Object extern "C" void *
#elif defined (_WIN32) && !defined (__cplusplus)
#define Forms_Form_Object extern void *
#elif defined (MSDOS) && defined (__cplusplus)
#define Forms_Form_Object extern "C" void __far *
#elif defined (MSDOS) && !defined (__cplusplus)
#define Forms_Form_Object extern void __far *
#elif !defined (MSDOS) && defined (__cplusplus)
/* OpenVms */
/* _WIN32, C++ */
/* _WIN32, C */
/* MSDOS, C++ */
/* MSDOS, C */
/* Ultrix, C++ */
#define Forms_Form_Object extern "C" void *
#elif !defined (MSDOS) && !defined (__cplusplus)
#define Forms_Form_Object extern
#endif void *
/* Ultrix, C */
Using the Portable API 6–39
/*
* Define Forms_Callback for PEU routine declarations
*
* If your PEU routine is NOT returning a value, you can declare it as:
*
* void Forms_Callback peu_routine(...);
*
* If your PEU routine IS returning a value, you can declare it as:
*
* long Forms_Callback peu_routine(...);
*/
#if defined(vms)
#define Forms_Callback
#elif defined (MSDOS)
#define Forms_Callback __far __pascal __export
#elif defined (_WIN32)
#define Forms_Callback __declspec(dllexport)
#else
#define Forms_Callback
#endif
/* OpenVms
/* MSDOS
/* WIN32
/* Ultrix
*/
*/
*/
*/
/* Define the pointer and routine linkages -- only used internally to this .H file */
#if defined (MSDOS)
#define _Mem_Access_ __far
#define _Rtn_Access_ __far __pascal __export
#elif defined (_WIN32)
#define _Mem_Access_
#define _Rtn_Access_
#else
#define _Mem_Access_
#define _Rtn_Access_
#endif
/*
* Define datatypes which are referenced in the structures, parameters,
* and calls of the DECforms requests.
*/
6–40 Using the Portable API
typedef long int
/* a request call
/* value
Forms_Status;
*/ typedef long int _Mem_Access_ * Forms_Status_Ptr;
*/
Forms_Session_Id[16]; typedef void _Mem_Access_ * Forms_Generic_Ptr;
/* type definition for status of */
/* Pointer to Forms_Status return*/ typedef char
/* characters */ typedef char typedef char
/* in 4 bytes */
Forms_Control_Text_Item[5]; /* Control text item of 5 characters*/
Forms_Control_Text[5][5]; /* Control text array of */
/* 5 Control_Text_Items */ typedef Forms_Control_Text _Mem_Access_ * Forms_Control_Text_Ptr; /* Pointer to typedef long int
/* in 4 bytes typedef long int typedef long int
*/
Forms_Data_Length;
Forms_Shadow_Length;
Forms_Count; typedef long int _Mem_Access_ * Forms_Count_Ptr;
/* Session id text string of 16 */
*/
/* Forms_Control_Text */
/* Data record length contained */
/* Shadow record length contained */
/* in 4 bytes */
/* Count of objects contained */
/* Pointer to Forms_Count, a 4
/* byte value
*/
*/
/* General pointer to an object */
/* contained in 4 bytes */
/*Data value contained in 4 */
/* element of ANSI struct */ typedef long int typedef long int
/* tm (see time.h) typedef long int typedef char typedef long int typedef char typedef void typedef void
Forms_Value;
Forms_Time_Value;
*/
Forms_Flags;
Forms_Text;
Forms_Text_Length;
_Mem_Access_ * Forms_Text_Ptr;
_Mem_Access_ * Forms_Routine_Arg_Ptr;
/* 4 bytes of binary flags value */
/* Text character */
/* Count of text characters */
/* in a string */
/* Pointer to Forms_Text, one or */
/* more text characters
/* routine argument
(_Rtn_Access_ * Forms_Routine_Ptr)(Forms_Routine_Arg_Ptr); /* Pointer to */
*/
*/
/* Pointer (any type) to Completion */ typedef void typedef char typedef char
_Mem_Access_ * Forms_Form_Object_Ptr;
Forms_Request_Id[24];
_Mem_Access_ * Forms_Request_Id_Ptr;
/*Completion routine returning Void */
/* Pointer to linked in Form file */
/* Parent request id text string of 24 */
/* characters */
/* Pointer to Forms_Request_Id */
/***********************************************************************************************/
/*
/* Structure for passing send and receive record data and shadow record data
/*
*/
*/
*/
/***********************************************************************************************/ typedef struct {
Forms_Data_Length
Forms_Generic_Ptr
Forms_Generic_Ptr
} Forms_Record_Data; data_length; data_record;
Forms_Shadow_Length shadow_length; shadow_record;
/* length of the actual record data area
/* pointer to the actual record data area
/* length of the shadow record data area
/* pointer to the shadow record data area
*/
*/
*/
*/
Using the Portable API 6–41
/***********************************************************************************************/
/*
/* Structure for building a field in a record message which maps to a record field
/* of IFDL data type TM. ANSI C doesn’t say how long the tm data type is, only that
/* it contains certain "int" fields. The DECforms TM data type is an implementation of the
*/
*/
*/
*/
/* ANSI C data type, but your C compiler may have a different (but still standard-conforming) */
/* definition of TM. Hence this structure can be used to load and unload the record message */
/* even if your C compiler’s implementation of tm contains additional fields.
/*
*/
*/
/***********************************************************************************************/ typedef struct
{
Forms_Time_Value
Forms_Time_Value
Forms_Time_Value
} Forms_Tm; tm_sec, tm_min, tm_hour; tm_mday, tm_mon, tm_year; tm_wday, tm_yday, tm_isdst;
/***********************************************************************************************/
/*
/* Option names for Forms_Request_Options
/*
*/
*/
*/
/***********************************************************************************************/ typedef enum { forms_c_opt_selection_label = -10, forms_c_opt_default_color = -9, forms_c_opt_default_term = -8, forms_c_opt_no_term_io = -7, forms_c_opt_form = -6, forms_c_opt_trace = -5, forms_c_opt_print = -4, forms_c_opt_language = -3, forms_c_opt_completion_status = -2, forms_c_opt_completion_routine = -1, forms_c_opt_end = 0, forms_c_opt_parent_request = 1, forms_c_opt_receive_record = 2, forms_c_opt_send_record = 3, forms_c_opt_receive_control = 4, forms_c_opt_send_control = 5, forms_c_opt_timeout = 6
} Forms_Request_Options_Values;
/* selection label value
/* default color type
/* default terminal type
/* suppresses terminal I/O
*/
*/
*/
*/
*/
*/
*/
*/
/* DECforms form Object */
/* name of the trace file and options */
/* name of printfile to use
/* name of language to match
/* indicates end of request options */
/* specifies parent request id */
*/
/* receive control text info
/* send control text info
/* describes timeout period
*/
*/
/* location to store completion status */
/* completion routine and parameter */
/* number of records being passed
/* number of records being passed typedef long int Forms_Request_Options_Type;
/***********************************************************************************************/
/*
/* Forms_Request_Options for API request calls
/*
*/
*/
*/
/***********************************************************************************************/ typedef union {
/* Discriminate Tag */
Forms_Request_Options_Type option;
6–42 Using the Portable API
struct {
Forms_Request_Options_Type option;
Forms_Text_Ptr name;
Forms_Text_Length name_length;
} selection_label; struct {
Forms_Request_Options_Type option;
Forms_Default_Color_Type type;
} default_color; struct {
Forms_Request_Options_Type option;
Forms_Default_Term_Type type;
} default_term; struct {
Forms_Request_Options_Type option;
Forms_Flags flag;
} no_term_io; struct {
Forms_Request_Options_Type option;
Forms_Form_Object_Ptr object;
} form; struct {
Forms_Request_Options_Type option;
Forms_Text_Ptr file_name;
Forms_Text_Length file_name_length;
Forms_Flags flag;
} trace; struct {
Forms_Request_Options_Type option;
Forms_Text_Ptr file_name;
Forms_Text_Length file_name_length;
} print; struct {
Forms_Request_Options_Type option;
Forms_Text_Ptr name;
Forms_Text_Length name_length;
} language; struct {
Forms_Request_Options_Type option;
Forms_Status_Ptr address;
} completion_status;
/* forms_c_opt_selection_label */
/* Name of layout to choose */
/* length of name */
/* forms_c_opt_default_color */
/* when runtime can’t detect whether */
/* you have color, set this value */
/* forms_c_opt_default_term */
/* when runtime can’t detect the */
/* terminal type, set this value */
/* forms_c_opt_no_term_io */
/* forms_c_opt_form */
/* Pointer created by Forms_Form_Object, */
/* in application program */
/* forms_c_opt_trace */
/* Name of trace file */
/* length of name */
/* forms_c_opt_print */
/* Name of file or device that */
/* the PRINT step uses */
/* length of name */
/* forms_c_opt_language */
/* Name to use when selecting a */
/* layout, matches the LANGUAGE clause */
/* length of name */
/* forms_c_opt_completion_status */
/* Address to load completion */
/* status when request completes */
Using the Portable API 6–43
struct {
Forms_Request_Options_Type option;
Forms_Routine_Ptr address;
Forms_Routine_Arg_Ptr parameter;
} completion_routine; struct {
Forms_Request_Options_Type option;
} end; struct {
Forms_Request_Options_Type option;
Forms_Request_Id_Ptr id;
} parent_request; struct {
Forms_Request_Options_Type option;
Forms_Count count;
} receive_record; struct {
Forms_Request_Options_Type option;
Forms_Count count;
} send_record; struct {
Forms_Request_Options_Type option;
Forms_Count_Ptr text_count;
Forms_Control_Text_Ptr text;
} receive_control; struct {
Forms_Request_Options_Type option;
Forms_Count text_count;
Forms_Control_Text_Ptr text;
} send_control; struct {
Forms_Request_Options_Type option;
Forms_Value period;
} timeout; struct {
Forms_Request_Options_Type option; char forms_reserved_bytes[28];
} forms_reserved_struct;
} Forms_Request_Options;
/* forms_c_opt_completion_routine */
/* Address of routine to call when */
/* request completes */
/* Address of parameter to pass */
/* to completion routine */
/* forms_c_opt_end */
/* forms_c_opt_parent_request */
/* Pointer to parent request id, for */
/* calls to DECforms while a */
/* DECforms request is still active */
/* (such as from an Escape Routine) */
/* forms_c_opt_receive_record */
/* Number of unique receive records in the request */
/* forms_c_opt_send_record */
/* Number of unique send records in the request */
/* forms_c_opt_receive_control */
/* Pointer to Number of control text items returned by */
/* DECforms - write only */
/* Receive control text must be an array of 25 bytes */
/* forms_c_opt_send_control */
/* Number of control text being sent to DECforms */
/* - read only */
/* Send control text could be up to 25 bytes, in */
/* multiples of 5 */
/* forms_c_opt_timeout */
/* Timeout value is limited to the range 0 to */
/* 32767 seconds on VMS. */
/* This structure is placed here to ensure */
/* extensibility.
*/
/* Please do not use this structure.
*/
6–44 Using the Portable API
/*
/*
/*
/*
/*
/*
/*
/*
/*
/* FIMS specified status value
/*
/* Note: S000 and ESnnn are corresponding FIMS control texts.
Severity of each status is indicated by:
(E) - Fatal error(s) occurred during request. Must be fixed before continuing.
(W) - Warning error(s) occurred during request. Should fix before continuing.
(I) - Informational event(s) occurred during request.
(S) - Request processed successfully.
typedef enum { forms_s_normal forms_s_timeout forms_s_formerror forms_s_nolayout forms_s_invdevice forms_s_hangup forms_s_norecord forms_s_badreclen forms_s_inuse forms_s_nosession forms_s_return_immed forms_s_nodecpt forms_s_bad_rshdwreclen forms_s_bad_sshdwreclen forms_s_cancelled forms_s_noactreq forms_s_invlobound forms_s_invhibound
= 0, /* S000: (S) Request calls completed successfully */
= 1, /* ES001: (E) Input did not complete in the time specified */
= 2, /* ES002: (E) Encountered problem when using form file
= 3, /* ES003: (E) No layout fit terminal type, language and
/* display size
= 4, /* ES004: (E) Invalid device specified in ENABLE
= 5, /* ES005: (E) Data set hangup; session disabled
= 7, /* ES007: (E) Specified record identifier not in form
*/
*/
= 8, /* ES008: (E) Record length argument did not match length */
/*
*/
*/
*/
*/ of record in form
= 10, /* ES010: (E) Attempted to disable a form still in use
= 14, /* ES014: (E) Decimal or comma decimal point positioned
/* session
*/
*/
= 11, /* ES011: (E) Session id in argument did not match existing */
/*
= 12, /* ES012: (S) Request completed due to REQUEST IMMEDIATE incorrectly in record field
= 15, /* ES015: (E) Receive-shadow-record-length did not match
/* length specified in form
*/
*/
= 16, /* ES016: (E) Send-shadow-record-length is something other */
*/
*/
*/
*/
/* than 1
= 17, /* ES017: (E) Request interrupted by arrival of CANCEL
= 19, /* ES019: (E) No active requests to CANCEL
= 24, /* ES024: (E) Subscript reference less than base
= 25, /* ES025: (E) Subscript reference greater than array
/* dimension defined
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/* DECforms specific status values
*/
*/
/* */
/* Note: EInnn are corresponding DECforms control texts. Any status relating to parameter checking */ of DECforms request calls or license checking of DECforms will not have a corresponding */ control text.
*/
*/
Severity of each status is indicated by:
(E) - Fatal error(s) occurred during request. Must be fixed before continuing.
(W) - Warning error(s) occurred during request. Should fix before continuing.
(I) - Informational event(s) occurred during request.
(S) - Request processed successfully.
*/
*/
*/
*/
*/
*/
*/
Using the Portable API 6–45
forms_s_illdtcvt forms_s_badreccnt forms_s_converr forms_s_aborted
= -1,
= -2,
= -3,
= -4, forms_s_badarg forms_s_baditmlstcode forms_s_baditmlstcomb forms_s_blocked_by_ast
= -5,
= -6,
= -7,
= -8, forms_s_bad_devhlr forms_s_caninprog forms_s_closetrace forms_s_deverr forms_s_disinprog forms_s_exprevalerr
= -9,
= -10,
= -11,
= -12,
= -13,
= -14, forms_s_fatinterr forms_s_illctltxtcnt forms_s_illfldvaluectx forms_s_illvpuse forms_s_intdatcor forms_s_invrange forms_s_invreccnt forms_s_invrecdes
= -15,
= -16,
= -17,
= -18,
= -19,
= -20,
= -21,
= -22, forms_s_nohandler forms_s_nolicense forms_s_noparent forms_s_no_read_access
= -23,
= -24,
= -25,
= -26, forms_s_openout forms_s_opentrace
= -27,
= -28, forms_s_paramovrflow = -29, forms_s_procesc_not_found = -30, forms_s_proc_escape_error = -31, forms_s_recvrecitems forms_s_reqdarg forms_s_sendrecitems
= -32,
= -33,
= -34, forms_s_strtooshort forms_s_writetrace forms_s_no_write_access forms_s_bckgrndio forms_s_timeract forms_s_blkbyreq forms_s_imgmismatch forms_s_nyi forms_s_cantopendic
= -35,
= -36,
= -37,
= -38,
= -39,
= -40,
= -41,
= -42,
= -46
} Forms_Status_Values;
/* EI001: (W) Illegal DATE, TIME, ADT conversion
/* EI002: (E) number of records did not match number
*/
*/
/* specified in record list */
/* EI003: (I) Error while converting from one data type */
/* to another
/* EI004: (E) Session aborted due to severe error in
/*
/* another request
: (E) Bad argument or incorrect format
: (E) Invalid item code found in item list */
: (E) Invalid combination of item codes found in */
*/
*/
*/
*/
/*
/*
/* item list
/* EI008: (E) Cannot process request; block by
/* application AST
/* EI009: (E) Invalid device handler
/* EI010: (E) A previous CANCEL is still in progress
/* EI011: (W) Cannot close trace file
/* EI012: (E) Device I/O error
/* EI013: (E) A previous DISABLE is still in progress
/* EI014: (E) Cannot convert operands into common data */
/* type
/* EI015: (E) Fatal Internal error
/* : (E) Illegal control text count argument
/* EI017: (E) Illegal FIELDVALUE context
*/
*/
*/
*/
*/
*/
*/
*/
/* EI018: (E) Illegal use of print viewport
/* EI019: (E) Database consistency check failed
/* EI020: (E) Invalid subscript range
/* EI021: (E) Invalid record count value
/* EI022: (E) Invalid record message descriptor
/* EI023: (E) No device handler for such device
/* : (E) No DECforms software license is active
/* EI025: (E) Specified parent request did not exist
/* : (E) No read access to user argument */
/* EI027: (E) The specified output file cannot be opened */
/* EI028: (W) Cannot open trace file for output */
/* EI029: (E) An escape routine parameter has overflowed */
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
/* EI030: (E) Address of procedural escape not found */
/* EI031: (E) Request terminated due to severe error in */
/*
/*
PEU
: (E) # of receive record items did not match record count value
: (E) Required argument missing
*/
*/
*/
*/
: (E) # of send record items did not match record*/ count value */
*/
/*
/*
/*
/*
/* EI035: (E) length of string is too small
/* EI036: (W) Cannot write to trace file
/* : (E) No write access to user argument
*/
*/
/* EI038: (E) Attempted read or write I/O from background*/
/* process
/* EI039: (E) Attempted timed field input while alarm
*/
*/
/* active */
/* EI040: (E) Attempted synchronous request while another*/
/*
/*
/* EI042: (E) Requested operation is not yet implemented */
/* EI046: (E) Can’t open the Kana-Kanji conversion
/* request active
: (E) Shareable image mismatch dictionary
*/
*/
*/
*/
6–46 Using the Portable API
/* Prevent the name mangling that C++ does, so that we keep these external names */
#if defined (__cplusplus) extern "C"
{
#endif
/*************************************************************************/
/*
/* Define the function prototypes for the 6 DECforms calls
/*
/* These are the definitions for those compilers that DO
/* support function prototypes with parameter definitions
*/
*/
/*
/*************************************************************************/
*/
*/
*/
*/
#if defined(__STDC__) || defined (vaxc) || defined (MSDOS) || defined (__cplusplus)
Forms_Status _Rtn_Access_ forms_enable
(char
Forms_Text_Ptr
Forms_Text_Ptr
Forms_Text_Ptr
_Mem_Access_ * session_id, device_name, form_file_name, form_name,
Forms_Request_Options _Mem_Access_ request_options[]);
Forms_Status _Rtn_Access_ forms_send
(char
Forms_Text_Ptr
Forms_Record_Data
_Mem_Access_ * session_id, send_record_name,
_Mem_Access_ send_record[],
Forms_Request_Options _Mem_Access_ request_options[]);
Forms_Status _Rtn_Access_ forms_receive
(char
Forms_Text_Ptr
Forms_Record_Data
_Mem_Access_ * session_id, receive_record_name,
_Mem_Access_ receive_record[],
Forms_Request_Options _Mem_Access_ request_options[]);
Forms_Status _Rtn_Access_ forms_transceive
(char
Forms_Text_Ptr
Forms_Record_Data
Forms_Text_Ptr
Forms_Record_Data
_Mem_Access_ * session_id, send_record_name,
_Mem_Access_
_Mem_Access_ send_record[], receive_record_name, receive_record[],
Forms_Request_Options _Mem_Access_ request_options[]);
Forms_Status _Rtn_Access_ forms_disable
(char _Mem_Access_ * session_id,
Forms_Request_Options _Mem_Access_ request_options[]);
Forms_Status _Rtn_Access_ forms_cancel
(char _Mem_Access_ * session_id,
Forms_Request_Options _Mem_Access_ request_options[]);
#else
Using the Portable API 6–47
/*************************************************************************/
/*
/* Define the function prototypes for the 6 DECforms calls
/*
/* These are the definitions for those compilers that do NOT
/* support function prototypes with parameter definitions
*/
*/
/*
/*************************************************************************/
*/
*/
*/
*/
Forms_Status forms_enable();
Forms_Status forms_send();
Forms_Status forms_receive();
Forms_Status forms_transceive();
Forms_Status forms_disable();
Forms_Status forms_cancel();
#endif /* End of "if defined STDC, etc" */
/* End of "Prevent the name mangling that C++ does, so that we keep these external names" */
#if defined (__cplusplus)
}
#endif
#undef _Rtn_Access_
#undef _Mem_Access_
#endif /* if !defined _FORMS_DEFINED */
6.9 Structure Definitions for the Portable API FORTRAN
Interface
The file included in this section contains the structure definitions for Forms_
Record_Data, as well as the name tag constants and union/map structure declaration for Forms_Request_Options. These declarations are part of the
FORTRAN file, formsdef.f, for the DECforms FORTRAN portable binding.
If you are using the FORTRAN binding in the portable API for your program, be sure to include the formsdef.f file in your subprograms and main program.
This listing should only be used as a reference. For the most up-to-date information, refer to the formsdef.f file that ships in your kit.
C
C
C
C
C
C ++
FACILITY:
DECforms
C
C
C
C
C --
C
ABSTRACT:
Include file for the DECforms API.
6–48 Using the Portable API
C ++
C
C structure for passing send and receive record data and shadow record data
C
C --
STRUCTURE /Forms_Record_Data/ integer integer integer integer
END STRUCTURE data_length data_record shadow_length shadow_record
C
C
C ++
C
C --
Declaration for literals
INTEGER forms_c_dev_vt100
INTEGER forms_c_dev_vt100_noavo
INTEGER forms_c_dev_vt200
INTEGER forms_c_dev_vt300
INTEGER forms_c_dev_vt400
INTEGER forms_c_color_mono
INTEGER forms_c_color_regis
INTEGER forms_c_color_ansi
C ++
C
C --
Possible value for the default terminal type option.
PARAMETER (forms_c_dev_vt100 = 0)
PARAMETER (forms_c_dev_vt100_noavo = 1)
PARAMETER (forms_c_dev_vt200 = 2)
PARAMETER (forms_c_dev_vt300 = 3)
PARAMETER (forms_c_dev_vt400 = 4)
C ++
C
C --
Possible value for the default color type option.
PARAMETER (forms_c_color_mono = 0)
PARAMETER (forms_c_color_regis = 4)
PARAMETER (forms_c_color_ansi = 8)
Using the Portable API 6–49
C
C
C ++
C
C --
Type declaration for option names
INTEGER forms_c_opt_selection_label
INTEGER forms_c_opt_default_color
INTEGER forms_c_opt_default_term
INTEGER forms_c_opt_no_term_io
INTEGER forms_c_opt_form
INTEGER forms_c_opt_trace
INTEGER forms_c_opt_print
INTEGER forms_c_opt_language
INTEGER forms_c_opt_completion_status
INTEGER forms_c_opt_completion_routine
INTEGER forms_c_opt_end
INTEGER forms_c_opt_parent_request
INTEGER forms_c_opt_receive_record
INTEGER forms_c_opt_send_record
INTEGER forms_c_opt_receive_control
INTEGER forms_c_opt_send_control
INTEGER forms_c_opt_timeout
C
C
C ++
C
C --
Option names for Forms_Request_Options
PARAMETER (forms_c_opt_selection_label = -10)
PARAMETER (forms_c_opt_default_color = -9)
PARAMETER (forms_c_opt_default_term = -8)
PARAMETER (forms_c_opt_no_term_io = -7)
PARAMETER (forms_c_opt_form = -6)
PARAMETER (forms_c_opt_trace = -5)
PARAMETER (forms_c_opt_print = -4)
PARAMETER (forms_c_opt_language = -3)
PARAMETER (forms_c_opt_completion_status = -2)
PARAMETER (forms_c_opt_completion_routine = -1)
PARAMETER (forms_c_opt_end = 0)
PARAMETER (forms_c_opt_parent_request = 1)
PARAMETER (forms_c_opt_receive_record = 2)
PARAMETER (forms_c_opt_send_record = 3)
PARAMETER (forms_c_opt_receive_control = 4)
PARAMETER (forms_c_opt_send_control = 5)
PARAMETER (forms_c_opt_timeout = 6)
C
C
C ++
C
C --
Forms_Request_Options for API request calls
STRUCTURE /Forms_Request_Options/ integer option
6–50 Using the Portable API
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
UNION forms_c_opt_selection_label
MAP integer selection_label integer selection_label_length
END MAP forms_c_opt_default_color (forms_c_color_mono,forms_c_color_regis,forms_c_color_ansi)
MAP integer default_color_type
END MAP forms_c_opt_default_term i.e. forms_c_dev_vt100, forms_c_dev_vt200, etc.
MAP integer default_term_type
END MAP forms_c_opt_no_term_io
MAP integer no_term_io_flag
END MAP forms_c_opt_form
MAP integer form_object
END MAP forms_c_opt_trace
MAP integer trace_file_name integer trace_file_name_length integer trace_flag
END MAP forms_c_opt_print
MAP integer print_file_name integer print_file_name_length
END MAP forms_c_opt_language
MAP integer language_name integer language_name_length
END MAP forms_c_opt_completion_status
Using the Portable API 6–51
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
MAP integer completion_status_address
END MAP forms_c_opt_completion_routine
MAP integer completion_routine_address integer completion_routine_parameter
END MAP forms_c_opt_parent_request
MAP integer parent_request_id
END MAP forms_c_opt_receive_record
MAP integer receive_record_count
END MAP forms_c_opt_send_record
MAP integer send_record_count
END MAP forms_c_opt_receive_control
Number of control text returned by DECforms - write only receive control text must be an array of 25 bytes
MAP integer receive_control_text_count integer receive_control_text
END MAP forms_c_opt_send_control
Number of control text being sent to DECforms - read only send control text could be up to 25 bytes
MAP integer send_control_text_count integer send_control_text
END MAP
6–52 Using the Portable API
C
C
C
C
C forms_c_opt_timeout timeout value is limited to the range between 0 to 32767 seconds on VMS.
MAP integer timeout_period
END MAP
C
C
C
C This structure is placed here to ensure extensibility.
Please do not use this structure.
MAP
CHARACTER*28 forms_reserved_bytes
END MAP
END UNION
END STRUCTURE
C
C
C ++
C
C --
Type declaration for error numbers
INTEGER forms_s_normal
INTEGER forms_s_timeout
INTEGER forms_s_formerror
INTEGER forms_s_nolayout
INTEGER forms_s_invdevice
INTEGER forms_s_hangup
INTEGER forms_s_norecord
INTEGER forms_s_badreclen
INTEGER forms_s_inuse
INTEGER forms_s_nosession
INTEGER forms_s_return_immed
INTEGER forms_s_nodecpt
INTEGER forms_s_bad_rshdwreclen
INTEGER forms_s_bad_sshdwreclen
INTEGER forms_s_cancelled
INTEGER forms_s_noactreq
INTEGER forms_s_invlobound
INTEGER forms_s_invhibound
INTEGER forms_s_illdtcvt
INTEGER forms_s_badreccnt
INTEGER forms_s_converr
INTEGER forms_s_aborted
INTEGER forms_s_badarg
INTEGER forms_s_baditmlstcode
INTEGER forms_s_baditmlstcomb
INTEGER forms_s_blocked_by_ast
INTEGER forms_s_bad_devhlr
INTEGER forms_s_caninprog
INTEGER forms_s_closetrace
INTEGER forms_s_deverr
INTEGER forms_s_disinprog
INTEGER forms_s_exprevalerr
INTEGER forms_s_fatinterr
INTEGER forms_s_illctltxtcnt
Using the Portable API 6–53
INTEGER forms_s_illfldvaluectx
INTEGER forms_s_illvpuse
INTEGER forms_s_intdatcor
INTEGER forms_s_invrange
INTEGER forms_s_invreccnt
INTEGER forms_s_invrecdes
INTEGER forms_s_nohandler
INTEGER forms_s_nolicense
INTEGER forms_s_noparent
INTEGER forms_s_no_read_access
INTEGER forms_s_openout
INTEGER forms_s_opentrace
INTEGER forms_s_paramovrflow
INTEGER forms_s_procesc_not_found
INTEGER forms_s_proc_escape_error
INTEGER forms_s_recvrecitems
INTEGER forms_s_reqdarg
INTEGER forms_s_sendrecitems
INTEGER forms_s_strtooshort
INTEGER forms_s_writetrace
INTEGER forms_s_no_write_access
INTEGER forms_s_bckgrndio
INTEGER forms_s_timeract
INTEGER forms_s_blkbyreq
INTEGER forms_s_imgmismatch
INTEGER forms_s_nyi
INTEGER forms_s_cantopendic
CC ++
CC
CC FIMS specified status value
CC
CC Note: S000 and ESnnn are corresponding FIMS control texts.
CC
Severity of each status is indicated by: CC
CC
CC
CC
CC
CC
CC --
C
(E) - Fatal error(s) occurred during request. Must be fixed before continuing.
(W) - Warning error(s) occurred during request. Should fix before continuing.
(I) - Informational event(s) occurred during request.
(S) - Request processed successfully.
C S000: (S) Request calls completed successfully
C
PARAMETER (forms_s_normal = 0000)
C
C ES001: (E) Input did not complete in the time specified
C
PARAMETER (forms_s_timeout = 0001)
C
C ES002: (E) Encountered problem when using form file
C
PARAMETER (forms_s_formerror = 0002)
C
C ES003: (E) No layout fit terminal type, language and display size
C
PARAMETER (forms_s_nolayout = 0003)
C
6–54 Using the Portable API
C ES004: (E) Invalid device specified in ENABLE
C
PARAMETER (forms_s_invdevice = 0004)
C
C ES005: (E) Data set hangup; session disabled
C
PARAMETER (forms_s_hangup = 0005)
C
C ES007: (E) Specified record identifier not in form
C
PARAMETER (forms_s_norecord = 0007)
C
C ES008: (E) Record length argument not match length of record in form
C
PARAMETER (forms_s_badreclen = 0008)
C
C ES010: (E) Attempted to disable a form still in use
C
PARAMETER (forms_s_inuse = 0010)
C
C ES011: (E) Session id in argument not match existing session
C
PARAMETER (forms_s_nosession = 0011)
C
C ES012: (S) Request completed due to REQUEST IMMEDIATE
C
PARAMETER (forms_s_return_immed = 0012)
C
C ES014: (E) Decimal or comma decimal point positioned incorrectly in record field
C
PARAMETER (forms_s_nodecpt = 0014)
C
C ES015: (E) Receive shadow record length not match length specified in form
C
PARAMETER (forms_s_bad_rshdwreclen = 0015)
C
C ES016: (E) Send-shadow-record-length is something other than 1
C
PARAMETER (forms_s_bad_sshdwreclen = 0016)
C
C ES017: (E) Request interrupted by arrival of CANCEL
C
PARAMETER (forms_s_cancelled = 0017)
C
C ES019: (E) No active requests to CANCEL
C
PARAMETER (forms_s_noactreq = 0019)
C
C ES024: (E) Subscript reference less than base
C
PARAMETER (forms_s_invlobound = 0024)
C
C ES025: (E) Subscript reference greater than array dimension defined
C
PARAMETER (forms_s_invhibound = 0025)
Using the Portable API 6–55
CC
CC
CC
CC
CC
CC
CC
CC
CC ++
CC
CC DECforms specific status values
CC
CC Note: EInnn are corresponding DECforms control texts. Any status relating
CC to parameter checking of DECforms request calls or license checking of DECforms will have not a corresponding control text.
Severity of each status is indicated by:
CC
CC
CC
CC --
(E) - Fatal error(s) occurred during request. Must be fixed before continuing.
(W) - Warning error(s) occurred during request. Should fix before continuing.
(I) - Informational event(s) occurred during request.
(S) - Request processed successfully.
C
C EI001: (W) Illegal DATE, TIME, ADT conversion
C
C
C
C
PARAMETER (forms_s_illdtcvt = -0001)
C
C EI002: (E) number of records not match number specified in record list
C
PARAMETER (forms_s_badreccnt = -0002)
C
C EI003: (I) Error while converting from one data type to another
C
PARAMETER (forms_s_converr = -0003)
C
C EI004: (E) Session aborted due to severe error in another request
C
PARAMETER (forms_s_aborted = -0004)
: (E) Bad argument or incorrect format
PARAMETER (forms_s_badarg = -0005)
C
C
C
: (E) Invalid item code found in item list
C
C
C
PARAMETER (forms_s_baditmlstcode = -0006)
: (E) Invalid combination of item codes found in item list
PARAMETER (forms_s_baditmlstcomb = -0007)
C
C EI008: (E) Cannot process request; block by application AST
C
PARAMETER (forms_s_blocked_by_ast = -0008)
C
C EI009: (E)Invalid device handler
C
PARAMETER (forms_s_bad_devhlr = -0009)
C
C EI010: (E) A previous CANCEL is still in progress
C
6–56 Using the Portable API
PARAMETER (forms_s_caninprog = -0010)
C
C EI011: (W) Cannot close trace file
C
PARAMETER (forms_s_closetrace = -0011)
C
C EI012: (E) Device I/O error
C
PARAMETER (forms_s_deverr = -0012)
C
C EI013: (E) A previous DISABLE is still in progress
C
PARAMETER (forms_s_disinprog = -0013)
C
C EI014: (E) Cannot convert operands into common data type
C
PARAMETER (forms_s_exprevalerr = -0014)
C
C EI015: (E) Fatal Internal error
C
PARAMETER (forms_s_fatinterr = -0015)
C
C
C
: (E) Illegal control text count argument
PARAMETER (forms_s_illctltxtcnt = -0016)
C
C EI017: (E) Illegal FIELDVALUE context
C
PARAMETER (forms_s_illfldvaluectx = -0017)
C
C EI018: (E) Illegal use of print viewport
C
PARAMETER (forms_s_illvpuse = -0018)
C
C EI019: (E) Database consistency check failed
C
PARAMETER (forms_s_intdatcor = -0019)
C
C EI020: (E) Invalid subscript range
C
PARAMETER (forms_s_invrange = -0020)
C
C EI021: (E) Invalid record count value
C
PARAMETER (forms_s_invreccnt = -0021)
C
C EI022: (E) Invalid record message descriptor
C
PARAMETER (forms_s_invrecdes = -0022)
C
C EI023: (E) No device handler for such device
C
PARAMETER (forms_s_nohandler = -0023)
Using the Portable API 6–57
C
C
C
: (E) No DECforms software license is active
PARAMETER (forms_s_nolicense = -0024)
C
C EI025: (E) Specified parent request not exist
C
PARAMETER (forms_s_noparent = -0025)
C
C
C
: (E) No read access to user argument
PARAMETER (forms_s_no_read_access = -0026)
C
C EI027: (E) The specified output file cannot be opened
C
C
C
C
PARAMETER (forms_s_openout = -0027)
C
C EI028: (W) Cannot open trace file for output
C
PARAMETER (forms_s_opentrace = -0028)
C
C EI029: (E) An escape routine parameter has overflowed
C
PARAMETER (forms_s_paramovrflow = -0029)
C
C EI030: (E) Address of procedural escape not found
C
PARAMETER (forms_s_procesc_not_found = -0030)
C
C EI031: (E) Request terminated due to severe error in PEU
C
PARAMETER (forms_s_proc_escape_error = -0031)
: (E) # of receive record items not match record count value
PARAMETER (forms_s_recvrecitems = -0032)
C
C
C
: (E) Required argument missing
C
C
C
PARAMETER (forms_s_reqdarg = -0033)
: (E) # of send record items not match record count value
PARAMETER (forms_s_sendrecitems = -0034)
C
C EI035: (E) length of string is too small
C
C
C
C
PARAMETER (forms_s_strtooshort = -0035)
C
C EI036: (W) Cannot write to trace file
C
PARAMETER (forms_s_writetrace = -0036)
: (E) No write access to user argument
PARAMETER (forms_s_no_write_access = -0037)
C
6–58 Using the Portable API
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C EI038: (E) Attempted read or write I/O from background process
C
PARAMETER (forms_s_bckgrndio = -0038)
C
C EI039: (E) Attempted timed field input while alarm active
C
PARAMETER (forms_s_timeract = -0039)
C
C EI040: (E) Attempted synchronous request while another request active
C
PARAMETER (forms_s_blkbyreq = -0040)
C
C
C
: (E) Shareable image mismatch
PARAMETER (forms_s_imgmismatch = -0041)
C
C EI042: (E) Requested operation is not yet implemented
C
PARAMETER (forms_s_nyi = -0042)
C
C EI046: (E) Can’t open the Kana-Kanji dictionary
C
PARAMETER (forms_s_cantopendic = -0046)
DECforms F77 entry points forms_status = forms_enable_for ( session_id, device_name, form_file_name, form_name, request_options )
CHARACTER*16 session_id
CHARACTER*(*) device_name
CHARACTER*(*) form_file_name
CHARACTER*(*) form_name
RECORD /Forms_Request_Options/ request_options() forms_status = forms_send_for ( session_id, send_record_name, send_record, request_options )
CHARACTER*16 session_id
CHARACTER*(*) send_record_name
RECORD /Forms_Record_Data/ send_record()
RECORD /Forms_Request_Options/ request_options() forms_status = forms_receive_for ( session_id, receive_record_name, receive_record, request_options )
CHARACTER*16 session_id
CHARACTER*(*) receive_record_name
RECORD /Forms_Record_Data/ receive_record()
RECORD /Forms_Request_Options/ request_options() forms_status = forms_transceive_for ( session_id, send_record_name, send_record, receive_record_name, receive_record, request_options )
CHARACTER*16 session_id
CHARACTER*(*) send_record_name
Using the Portable API 6–59
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
RECORD /Forms_Record_Data/ send_record()
CHARACTER*(*) receive_record_name
RECORD /Forms_Record_Data/ receive_record()
RECORD /Forms_Request_Options/ request_options() forms_status = forms_disable_for ( session_id, request_options )
CHARACTER*16 session_id
RECORD /Forms_Request_Options/ request_options() forms_status = forms_cancel_for ( session_id, request_options )
CHARACTER*16 session_id
RECORD /Forms_Request_Options/ request_options()
INTEGER forms_enable_for
EXTERNAL forms_enable_for
INTEGER forms_send_for
EXTERNAL forms_send_for
INTEGER forms_receive_for
EXTERNAL forms_receive_for
INTEGER forms_transceive_for
EXTERNAL forms_transceive_for
INTEGER forms_disable_for
EXTERNAL forms_disable_for
INTEGER forms_cancel_for
EXTERNAL forms_cancel_for
6–60 Using the Portable API
A
Elementary Conditions
Elementary conditions are predefined accept phase conditions. During accept phase processing, the Form Manager stores either true or false in elementary conditions to indicate the status of activation list processing. You can use elementary conditions in conditional expressions in your IFDL source file.
The following table explains what state causes each of the elementary conditions to be true.
Elementary
Condition
ACCEPT PHASE
CONVERTED
EMPTY FIELD
FIRST DISPLAYED
HORIZONTAL
1
FIRST DISPLAYED
VERTICAL
1
FIRST ITEM
True or
False
True
True
True
False
True
True
True
State
When the Form Manager is performing accept phase processing.
When the contents of a panel field have been converted to the data type of the form data item that corresponds to the panel field.
When the panel field that corresponds to the current activation item is empty (when a numeric field contains only zeros or a nonnumeric field contains only spaces).
For text fields, sliders, waits, and icons.
If the active item has the smallest horizontal subscript of all currently displayed occurrences of that item.
If the active item has the smallest vertical subscript of all currently displayed occurrences of that item.
When the current activation item is the first item on the activation list.
1
All geographical elementary conditions are evaluated as false when the condition is compared against a WAIT item such as WAIT on PANEL.
Elementary Conditions A–1
Elementary
Condition
FIRST OCCURRENCE
HORIZONTAL
FIRST OCCURRENCE
VERTICAL
FULL FIELD
GROUP FIRST ITEM
True or
False
True
True
True
False
True
State
If the active item has the smallest horizontal subscript of all occurrences of that item on the activation list.
If the active item has the smallest vertical subscript of all occurrences of that item on the activation list.
When each character position in the active input field has been filled. This means:
• Format 1 picture fields (alphanumeric)— no spaces (blank characters)
• Format 2 picture fields (fixed decimal)— no leading zeros before and no trailing zeros after the decimal point
For:
• Format 3 picture fields (floating point)
• Format 4 picture fields (date and time)
• Text fields, sliders, icons, and waits
The presence or absence of a sign or a currency symbol does not affect FULL FIELD.
When:
• Accept phase is just beginning.
• The current activation item corresponds to an item in a different group than the previous item processed.
• The previous activation item corresponded to an entity that was not a member of a group.
The current item must be a member of a group.
A–2 Elementary Conditions
Elementary
Condition
GROUP LAST ITEM
GROUP OTHER ITEM
HELP ACTIVE
HELP MESSAGE
AVAILABLE
HELP MESSAGE EXISTS
HELP PANEL EXISTS
IMMEDIATE
LAST ITEM
True
True
True
True
True or
False
True
False
True
True
True
State
When:
• The current activation item corresponds to an item that is in a different group than the next item to be processed.
• The next activation item corresponds to an entity that is not a member of a group.
The current item must be a member of a group.
When GROUP FIRST ITEM and GROUP
LAST ITEM are both false.
When the help activation list is being processed.
When HELP MESSAGE EXISTS is true and the operator has not seen the help message.
When:
• There is help message text for the current activation item.
• The current activation item is a field, or icon activation item, when there is message help for the corresponding panel field, or for any of the groups or panels that contain this corresponding item.
If the current activation item is a wait activation item, unless the item is a wait on panel and there is a help message at the panel level.
When there is a help panel referenced at any level of form definition (field, icon, group, panel, or layout) for the current activation item.
After the Form Manager encounters a
POSITION IMMEDIATE, EXIT HELP
IMMEDIATE, or RETURN IMMEDIATE response step.
When the current activation item is the last item on the activation list.
Elementary Conditions A–3
Elementary
Condition
LAST DISPLAYED
HORIZONTAL
VERTICAL
1
1
LAST DISPLAYED
LAST OCCURRENCE
HORIZONTAL
LAST OCCURRENCE
VERTICAL
LEFTMOST ITEM
1
LOWERMOST ITEM
OTHER DISPLAYED
HORIZONTAL
OTHER DISPLAYED
VERTICAL
1
OTHER ITEM
1
1
OTHER OCCURRENCE
HORIZONTAL
True or
False
True
True
True
True
True
True
True
True
True
True
State
If the active item has the largest horizontal subscript of all occurrences of the current item displayed.
If the active item has the largest vertical subscript of all occurrences of the current item displayed.
If the active item has the largest horizontal subscript of all occurrences of that item on the activation list.
If the active item has the largest vertical subscript of all occurrences of the item on the activation list.
If there is no active item on the current panel to the geographic left of the currently active item.
If there is no active item on the current panel geographically below the currently active item.
If the active item has neither the smallest nor the largest horizontal subscript of all occurrences of the current item displayed.
If the active item has neither the smallest nor the largest vertical subscript of all occurrences of the current item displayed.
When the current activation item is neither the first nor the last activation item on the activation list.
If the active item has neither the smallest nor the largest horizontal subscript of all occurrences of the item on the activation list.
OTHER OCCURRENCE
VERTICAL
True If the active item has neither the smallest nor the largest vertical subscript of all occurrences of the item on the activation list.
1
All geographical elementary conditions are evaluated as false when the condition is compared against a WAIT item such as WAIT on PANEL.
A–4 Elementary Conditions
Elementary
Condition
PANEL FIRST ITEM
PANEL LAST ITEM
PANEL OTHER ITEM
RIGHTMOST ITEM
UPPERMOST ITEM
VALIDATED
1
1
VALIDATION STARTED
True or
False
True
True
True
True
True
True
True
State
When the current activation item either is the first item on the activation list or corresponds to an item that is on a different panel than the previous item processed.
When the current activation item either is the last item on the activation list or corresponds to an item that is on a different panel than the next item to be processed.
When the current activation item corresponds to an item that is neither the first nor the last item of a contiguous set of panel items.
A contiguous set of panel items is two or more panel items that correspond to two or more adjacent activation items; the second activation item immediately follows the first, the third activation item immediately follows the second, and so on.
If there is no active item on the current panel to the geographic right of the currently active item.
If there is no active item on the current panel geographically above the currently active field.
After a RETURN response step (without
IMMEDIATE) has been executed and after all items on the activation list have been validated.
After the Form Manager begins validating a field activation item. This elementary condition is never true when the Form
Manager is processing a wait activation item.
1
All geographical elementary conditions are evaluated as false when the condition is compared against a WAIT item such as WAIT on PANEL.
Elementary Conditions A–5
B
Receive Control Text Items
Receive control text items return status information from the Form Manager to your application program. If you pass a receive control text item in your
DECforms request, the Form Manager stores it in the receive control text.
Table B–1 lists and explains the receive control text items.
EI009
EI010
EI011
EI012
EI013
EI014
EI015
Table B–1 Receive Control Text Items
Control
Text Item Description
EI001
EI002
EI003
EI004
EI008
An error occurred during a DATE, TIME, or ADT data type conversion.
These data types can be converted only to the DATE, DATETIME, TIME,
ADT, CHARACTER NULL TERMINATE, or CHARACTER VARYING data types.
The number of records specified does not match the number specified in the record list.
The Form Manager could not convert a value from one data type to another data type, or data truncation occurred during the conversion.
The session was ended abnormally due to a severe error in another request.
DECforms software cannot process the request. An application AST is blocking the request.
Invalid device handler.
A previous CANCEL request is in progress.
Cannot close trace file.
Device I/O error.
A previous DISABLE request is in progress.
Cannot convert operands into common data type.
Fatal internal error.
(continued on next page)
Receive Control Text Items B–1
EI027
EI028
EI029
EI030
EI031
EI035
EI036
EI018
EI019
EI020
EI021
EI022
EI023
EI025
EI040
EI041
EI042
ES000
ES001
Table B–1 (Cont.) Receive Control Text Items
Control
Text Item Description
EI017
ES002
ES003
ES004
Illegal FIELDVALUE context. Reference to FIELDVALUE outside of
ACCEPT phase.
Illegal use of print viewport.
Database consistency check failed.
Invalid subscript range.
Invalid record count value.
Invalid record message descriptor.
No device handler exists for such device.
Specified parent request does not exist.
Specified output file cannot be opened.
Cannot open trace file for output.
Escape routine parameter has overflowed.
Address of the procedural escape was not found.
Request was terminated due to a severe error in an escape routine.
Length of the string is too small.
Cannot write to the trace file.
Attempted synchronous request while another request was active.
Shareable image mismatch.
Requested operation is not yet implemented.
Request calls completed.
External request ended abnormally because the timeout value specified in either the form or an external request argument expired before the operator finished giving input.
In an ENABLE request, the Form Manager was unable to find the form.
In an ENABLE request, either the Form Manager was not able to find a form that fit the display device or no layout was defined to match the definition of the FORMS$LANGUAGE logical name or
FORMS$K_LANGUAGE item code.
In an ENABLE request, the Form Manager could not establish a session with session-id specified in the argument.
(continued on next page)
B–2 Receive Control Text Items
Table B–1 (Cont.) Receive Control Text Items
Control
Text Item Description
ES005
ES006
ES007
ES008
ES009
ES010
ES011
ES012
ES014
ES015
ES016
ES017
ES019
ES024
ES025
In a SEND, RECEIVE, TRANSCEIVE, or DISABLE request, the Form
Manager lost the terminal connection, causing the previously established session to become lost.
In a SEND or TRANSCEIVE request, send-record-name specified a record name unknown in the form.
In a RECEIVE or TRANSCEIVE request, the receive-record-name specified a record name unknown in the form.
In a SEND or TRANSCEIVE request, the length specified in send-record-
message (OpenVMS API) or in send-record (portable API) did not match the length of the record in the form.
In a RECEIVE or TRANSCEIVE request, the length specified in receive-
record-message (OpenVMS API) or in receive-record (portable API) did not match the length of the record in the form.
Attempted to disable a session while a procedural escape was outstanding for that session.
Value specified by session-id of a request specifies a session unknown to the
Form Manager.
The request was terminated using a RETURN IMMEDIATE response step.
Record in send-record-name, sent by the application program to the form, contains invalid information.
The length specified in receive-shadow-record during a RECEIVE or
TRANSCEIVE request did not match the length of the shadow record in the form.
In a SEND or TRANSCEIVE request, the length of send-shadow-record was not 1.
Request interrupted by arrival of a CANCEL request.
No active requests to cancel.
Subscript reference is less than the base.
Subscript reference is greater than the defined array dimension.
Receive Control Text Items B–3
Index
A
Accept phase, 4–32 to 4–41 definition, 1–10 elementary condition, A–1 processing, A–1 status of processing, A–1 to A–5
ACTIVATE response step clauses, 4–20 example, 4–21
Form Manager actions, 4–19 to 4–21 for panel fields on different panels, 4–21
Activation items definition, 4–20 processing, 4–33 to 4–41
Activation lists altering processing, 4–42 to 4–44 definition, 1–9 first current activation item, 4–33 processing, 4–33 to 4–41 searching, 4–43 status of processing, A–1 to A–5
Application program records, 2–16 copying data from, 4–12 correspondence to form records, 4–12 definition, 2–6 during data collection, 4–49 restrictions, 4–14 using with RECEIVE request, 2–8
Applications converting to portable API, 6–1
Argument
CALL response step passing mechanisms,
4–21
Arrays data transferring, 4–54
Asynchronous SEND request, 2–13
B
Building applications, 2–19
Built-in form data items
See also specific built-in form data items assignment during activation item processing, 4–34 declaring, 4–12 padding and truncating, 4–12 required data type, 4–12
C
CALL response step argument passing mechanism, 4–21 definition, 2–21
Form Manager actions, 4–21 to 4–22
CANCEL request example, 2–18 to 2–19 purpose of return status variable, 2–19
CANCEL request (OpenVMS API), 5–47 to
5–50 example, 5–50
CANCEL request (portable API), 6–36 to
6–37 example, 6–37
Character-cell devices description, 1–2
Index–1
Compiling, 2–19
Condition
See Elementary conditions
Control text
See Receive control text
See Send control text definition, 1–8
Control text item
See Receive control message
See Send control message
Control text items length, 6–8
Control text responses when performed, 4–18 when to use, 4–18
CONVERTED elementary condition, A–1
Converting file formats, 1–3
Current activation item definition, 1–9
CURRENTITEM built-in form data item initial value, 4–12 resetting, 4–41 value assigned during accept phase, 4–34
D
Data
See also Form data distribution by Form Manager, 4–13
Database for Oracle Trace, 3–7
Data transfer arrays, 4–54
DATA TRANSFER clause use, 4–14
Data types conversion during collect form data phase,
4–48 conversion during distribute form data phase, 4–16 conversion during receive form data phase, 4–49 of application program record fields, 4–13 of form record fields, 4–13
DEACTIVATE response step altering activation list processing, 4–43
Form Manager actions, 4–22 to 4–23
Debugging escape routines, 2–29
Defaults terminal settings default_color_type, 4–8 default_term_type, 4–8
DISABLE request example, 2–18 no default response, 4–19 processing, 4–1 to 4–57 purpose of return status variable, 2–18
DISABLE request (OpenVMS API), 5–13 to
5–21 example, 5–20
DISABLE request (portable API), 6–22 to
6–23 example, 6–23
Disk-based forms, 6–9 enabling, 6–9
Display device request argument, 4–8 when attached, 4–11
DISPLAY response step
Form Manager actions, 4–23
Display size in layout selection, 4–8
Display type in layout selection, 4–8
E
Elementary conditions when true, A–1 to A–5
EMPTY FIELD elementary condition, A–1
ENABLE request creating multiple sessions with, 2–6 default response, 4–19 processing, 4–6 to 4–57 using, 2–3 to 2–6
Index–2
ENABLE request (OpenVMS API), 5–2 to
5–12 example, 5–11
ENABLE request (portable API), 6–16 to
6–21 examples, 6–19
ENTER HELP response step, 4–23
Error message routines description, 6–11 examples, 6–11
Error messages returning to application program, 4–55
Error numbers listed, 6–12 referencing, 6–11
Errors transferring to escape routine (shareable image), 2–26 with POSITION response step, 4–27
Escape routines calling request from, 2–21 control transfer illustration (direct linking), 2–23 control transfer illustration (shareable image), 2–26 debugging, 2–29 definition, 2–1, 2–21 direct linking, 2–23 to 2–24 direct linking and storing in shareable image, 2–28 effect of error status, 2–25
FORMS$IMAGE logical name, 2–25 linking with applications, 6–10 storing in a shareable image, 2–25 to
2–28 using, 2–21 using Extract Object Utility, 2–22 to
2–23 using in portable API, 2–22, 6–10
Event Log file, 2–39
Event logging, 2–39
Events definition, 3–1
Examples
CANCEL request (OpenVMS API), 5–50
CANCEL request (portable API), 6–37
FORTRAN, 2–19
DISABLE request (OpenVMS API), 5–20
DISABLE request (portable API), 6–23
FORTRAN, 2–18
ENABLE request (OpenVMS API), 5–11
ENABLE request (portable API), 6–19 enabling a form (portable API)
FORTRAN, 2–4 event log file, 2–39 portable C program, 2–33
RECEIVE request (OpenVMS API), 5–41
RECEIVE request (portable API), 6–31
FORTRAN, 2–7 request options (OpenVMS API) control text, 5–41 request options (portable API) print file, 6–31, 6–34 print file (for PRINT response step),
6–21 selection labels, 6–19
SEND request (OpenVMS API), 5–30
SEND request (portable API), 6–26
FORTRAN, 2–11 tracing
DCL command procedure, 2–38
OpenVMS API, 2–35 portable C program, 2–33
TRANSCEIVE request (OpenVMS API),
5–45
TRANSCEIVE request (portable API),
6–34
FORTRAN, 2–15
Exception condition returning to application program, 4–55
EXIT HELP response step, 4–23 altering activation list processing, 4–42
External requests accept input phase, 4–32 to 4–41 collect form data phase, 4–48 to 4–55 receive control text, 4–56 return value, 4–55 terminate request phase, 4–55
Index–3
External routine declarations for portable API, 6–2
Extract Object Utility
See also Form objects example, 2–22 name of file created, 2–22
Extract vectors what they store in the form object, 2–22
F
Field activation item, 4–32 definition, 1–9
FIELDVALUE built-in form data item initial value, 4–12
FIMS (Form Interface Management System) error numbers, 4–55
FIRST DISPLAYED HORIZONTAL elementary condition, A–1
FIRST DISPLAYED VERTICAL elementary condition, A–1
FIRST ITEM elementary condition, A–1
FIRST OCCURRENCE HORIZONTAL elementary condition, A–1
FIRST OCCURRENCE VERTICAL elementary condition, A–2
Form data collection phase, 4–48 to 4–55 definition, 1–6 distributing, 4–12 to 4–17
Form data items
See also Built-in form data items definition, 1–6, 4–11, 4–13 initial value, 4–11
Form files loading, 4–6
Form Manager
See also Activation lists
See also External requests adding activation items, 4–20 creating a session, 4–6 interaction with other components, 4–1 list of processing phases, 4–1 list of receive control text items, B–1 to
B–3
Form Manager (cont’d) processing requests, 4–1 to 4–57 request calling description (OpenVMS
API), 5–1 to 5–50 request calling description (portable API),
6–15 selecting a layout, 4–8 using a form object, 2–22
FORMNAME built-in form data item initial value, 4–12 resetting, 4–41 validating, 4–12
Form objects
See also Extract Object Utility creating, 2–22 to 2–23 effect of linking, 2–22 name of, 2–22 using, 2–22
Form records correspondence to application program records, 4–12 correspondence to form data items, 4–13 definition, 1–6, 4–13 purpose, 4–13
Forms definition, 1–5
FORMS$DEBUG_ESCAPE_ROUTINES logical name, 2–29
FORMS$DEFAULT_DEVICE logical name,
1–4 description, 6–17
FORMS$EVENT_LOG.LOG file, 2–39
FORMS$IMAGE logical name defining, 2–25 purpose, 2–25 search list allowed, 2–25
FORMS$K_IMAGE item code, 2–25
FORMS$K_LANGUAGE item code, 4–9
FORMS$K_PRINTFILE logical name using, 4–28
FORMS$K_TRACEFILE item code, 2–31
FORMS$K_TRACEFILE request option item code, 2–31
Index–4
FORMS$K_TRACE request option item code,
2–30
FORMS$LANGUAGE logical name effect, 4–9 using, 4–9
FORMS$LOG_EVENTS logical name, 2–39
FORMS$LOG_FILE_NAME logical name,
2–39
FORMS$PRINT_FILE logical name using, 4–28
FORMS$TRACE logical name, 2–30 defining, 2–31
FORMS$TRACE_CONVERSIONS logical name, 2–39
FORMS$TRACE_FILE logical name, 2–30 defining, 2–31 formsdef.f file, 6–48 formsdef.h file, 6–38 forms_c_opt_trace request option, 2–31
Forms_Record_Data structure, 6–2 to 6–5
Forms_Request_Options structure, 6–2 to
6–5
FORMS_TRACE variable, 2–30
FORMS_TRACE_CONVERSIONS variable,
2–39
FORMS_TRACE_FILE variable, 2–30 form_obj.obj file, 2–22
FULL FIELD elementary condition, A–2
FUNCTIONNAME built-in form data item initial value, 4–12 modifying, 4–36 resetting, 4–41 value assigned during accept phase, 4–34
Function responses definition, 1–10 with POSITION response step, 1–10
G
GROUP FIRST ITEM elementary condition,
A–2
GROUP LAST ITEM elementary condition,
A–2
GROUP OTHER ITEM elementary condition,
A–3
H
Header files for portable API, 6–2
Help customizing, 4–46 default behavior, 4–46
Help activation list, 4–45
HELP ACTIVE elementary condition, A–3
HELP MESSAGE AVAILABLE elementary condition, A–3
HELP MESSAGE EXISTS elementary condition, A–3
HELP PANEL EXISTS elementary condition,
A–3
Help processing, 4–44
I
Icon activation item, 1–9
IF/THEN/ELSE response step
Form Manager actions, 4–24
IFDL (Independent Form Description
Language) conditional expression elementary condition in, A–1 to A–5
IMMEDIATE elementary condition, A–3
Include files for portable API, 6–2
INCLUDE response step
Form Manager actions, 4–24
INVALID response step altering activation list processing, 4–43
Form Manager actions, 4–24
L
Languages supported for programming, 2–1
Languages supported, 6–1
Index–5
LAST DISPLAYED HORIZONTAL elementary condition, A–3
LAST DISPLAYED VERTICAL elementary condition, A–4
LAST ITEM elementary condition, A–3
LAST OCCURRENCE HORIZONTAL elementary condition, A–4
LAST OCCURRENCE VERTICAL elementary condition, A–4
Layouts definition, 1–5 searching for, 4–10 selecting, 4–8 to 4–10 selection by Form Manager, 2–5
LEFTMOST ITEM elementary condition,
A–4
LET response step
Form Manager actions, 4–25
LIB$FIND_IMAGE_SYMBOL routine, 2–25
Linked forms, 6–9 enabling, 6–9
Linking, 2–20 escape routines (OpenVMS API), 2–23 escape routines (portable API), 2–24 escape routines (shareable image), 2–25,
2–28
Logical names
FORMS$DEFAULT_DEVICE, 1–4
LOWERMOST ITEM elementary condition,
A–4
M
Message panels how Form Manager handles, 4–25
MESSAGE response step
Form Manager actions, 4–25 to 4–27
HELP clause, 4–27 specifying message contents, 4–26
Messages specifying contents, 4–26
N
Natural language in layout selection, 4–9
O
Operator input effect of errors, 4–36
Oracle Rdb database with Oracle Trace, 3–7
Oracle Trace software creating facility selection, 3–2 description, 3–1 facilities, 3–2 invoking, 3–1 items, 3–1
OTHER DISPLAYED HORIZONTAL elementary condition, A–4
OTHER DISPLAYED VERTICAL elementary condition, A–4
OTHER ITEM elementary condition, A–4
OTHER OCCURRENCE HORIZONTAL elementary condition, A–4
OTHER OCCURRENCE VERTICAL elementary condition, A–4
P
PANEL FIRST ITEM elementary condition,
A–4
PANEL LAST ITEM elementary condition,
A–5
PANEL OTHER ITEM elementary condition,
A–5
Panels definition, 1–6
Portable C program example, 2–33
POSITION response step
Form Manager actions, 4–27 to 4–28
IMMEDIATE clause altering activation list processing,
4–42
Index–6
POSITION response step (cont’d) precedence of POSITION IMMEDIATE response step, 4–28 result of not specifying, 4–42
Printer
See Display device
PRINTER devices description, 1–3
PRINTER layouts device name, 6–17 program example, 6–19 selecting, 4–8 label, 4–11 language, 4–11 steps for creating output, 1–3
PRINT response step
Form Manager actions, 4–28 to 4–29
Procedural escape definition, 2–1
Programming languages supported, 2–1
PROTECTED WHEN attribute altering activation list processing, 4–43
R
Receive control message format, 4–56 validating, 4–2 when invalid, 4–2, 4–6
Receive control text
See also Send control text contents, 4–56 example, 4–57 in RETURN response step, 4–56 purpose, 2–9
Receive control text item
See also Send control text item
See Receive control message list of, B–1 to B–3 specifying in RETURN IMMEDIATE response step, 2–9
RECEIVE request default response, 4–19 processing, 4–1 to 4–57
RECEIVE request (cont’d) using, 2–6 to 2–8, 2–9 to 2–10
RECEIVE request (OpenVMS API), 5–32 to
5–42 example, 5–41
RECEIVE request (portable API), 6–29 to
6–32 examples, 6–31
Receive shadow records defining, 4–5, 4–51 using, 4–15, 4–50, 4–51 validating, 4–5
Record validating, 4–3
Record message when invalid, 4–3
Record message name request argument use in distributing data, 4–13
Records application program, 2–6
REFRESH response step, 5–49, 6–37
Form Manager actions, 4–29
REMOVE response step clauses, 4–29
Form Manager actions, 4–29
Request
See also specific request arguments distributing form data phase, 4–12 to
4–17 list of processing phases, 4–1 processing external responses, 4–18 to
4–32 session-identification string validating, 4–2 when invalid, 4–3 validating, 4–1 to 4–12 validating arguments, 4–2 to 4–6 validating records, 4–3
Request argument list when invalid, 4–2, 4–6
Request arguments validating, 4–2
Index–7
Request calling description (portable API),
6–1 to 6–60
REQUEST EXIT RESPONSE processing phase, 4–48
Requests calling, 2–1 to 2–19 description, 1–6
REQUEST VALIDATION external response, 4–41
RESET response step
Form Manager actions, 4–30
Responses default, 4–18 defining, 4–19 definition, 1–8 when performed, 4–18
Response steps, 4–19 to 4–32
See also specific response steps definition, 1–8
RETURN IMMEDIATE response step specifying receive control text in, 2–9
RETURN response step altering activation list processing, 4–42
Form Manager actions, 4–30
IMMEDIATE clause, 4–30 altering activation list processing,
4–42 precedence of RETURN IMMEDIATE,
4–30 receive control text item in, 4–30
Return value from external request, 4–55
RIGHTMOST ITEM elementary condition,
A–5
Routine parameters for portable API, 6–1
Running applications, 2–21
Run-time processing, 4–1 to 4–57 description, 1–6 introduction, 4–1 list of processing phases, 4–1
S
Send control message contents, 4–18
Send control text validating, 4–4 when invalid, 4–4
Send control text item
See also Receive control text item purpose, 4–18
SEND request default response, 4–19 example of using, 2–10 to 2–12 processing, 4–1 to 4–57 using an asynchronous SEND, 2–13
SEND request (OpenVMS API), 5–22 to
5–31 example, 5–30
SEND request (portable API), 6–24 to 6–28 examples, 6–26
Send shadow records defining, 4–5, 4–16 using, 4–15, 4–50 validating, 4–5
Session creating, 2–5, 4–6 definition, 1–5 purpose of session-identification string,
4–6 referencing multiple sessions, 2–6
SESSION built-in form data item initial value, 4–12 resetting, 4–41 validating, 4–12
Session ID creating, 4–6 definition, 1–7 purpose, 4–2 validating, 4–2 when invalid, 4–3
SIGNAL response step
Form Manager actions, 4–30
Index–8
Storage values in a request, 4–13
T
Terminal
See Display device
TERMINAL built-in form data item initializing, 4–12 resetting, 4–41 validating, 4–12
Timeout value for requests, 6–8 trace.file_name variable defining, 2–31
Trace facility
See also FORMS$TRACE logical name controlling, 2–30 creating trace file, 2–31 definition, 2–29 example command procedure, 2–38 what it records, 2–30
Tracing capturing additional information, 2–39 command procedure, 2–38 example (portable C program), 2–33 exception conditions, 2–38 multiple sessions, 2–32 turning on and off, 2–32 with request options, 2–32
TRANSCEIVE request default response, 4–19 example, 2–15 processing, 4–1 to 4–57 referencing two different records, 2–16 using, 2–14 to 2–17
TRANSCEIVE request (OpenVMS API),
5–43 to 5–46 example, 5–45
TRANSCEIVE request (portable API), 6–33 to 6–35 example, 6–34
Type definitions for portable API, 6–2
U
UPPERMOST ITEM elementary condition,
A–5
V
VALIDATED elementary condition, A–5
VALIDATE response step
Form Manager actions, 4–31 to 4–32
Validation of data input, 4–33
VALIDATION STARTED elementary condition, A–5
W
Wait activation item definition, 1–9, 4–32
Word-wrapping in messages, 4–26
Index–9
Download
Advertisement
Key features
Structured, forms-based, or menu-based user interface
First commercial implementation of CODASYL FIMS
Support for character-cell (VT) devices and print output
Provides run-time processing control
Enables data transfer between application and form
Offers customizability through responses
Manages activation list for input focus
Supports DDIF (Digital Document Interchange Format) for print output
Provides tracing facility for debugging
Leverages Oracle Trace software for event monitoring
Frequently asked questions
DECforms software is a software product designed for building applications, services, and tools requiring structured, forms-based, or menu-based user interfaces. It's the first commercial implementation of the CODASYL Form Interface Management System (FIMS) standard.
DECforms supports both character-cell (VT) devices, like VT100- through VT500-series terminals and emulators, and print output in DDIF (Digital Document Interchange Format).
DECforms allows you to transfer data between your application program and the form. This process involves using requests, which are subroutine calls to the Form Manager. You can use these requests to enable forms, disable forms, send data from your program to the form, receive data from the form back into your program, and even combine sending and receiving in a single request.
Responses are defined in your IFDL source file. They provide a list of instructions to the Form Manager, called response steps, which allow you to control the display of fields, icons, and panels, change the processing order, call subroutines, define help processing, reset form data values, and send signals to the operator.
The activation list is an ordered internal list managed by the Form Manager. It keeps track of the currently active items, such as fields, panels, and icons, that the operator can interact with. An item becomes active when the Form Manager performs an ACTIVATE response step, and the operator can only enter input into the currently active item.