HP DECforms Guide to Developing an Application Order Number: AA–Q0T3C–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: OpenVMS Alpha Version 7.3-2 or later OpenVMS I64 Version 8.2 or later Software Version: 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 ..................................................... xv Part I Getting Started 1 Introduction 1.1 DECforms Purpose . ................................... 1–1 1.2 DECforms Architecture ................................ 1–2 1.2.1 The Form ........................................ 1–2 1.2.2 The Program . ................................... 1–6 1.2.2.1 Requests . ................................... 1–7 1.2.2.2 Calls to Escape Routines ......................... 1–8 1.2.2.3 Phases in Processing Requests . ................... 1–8 1.3 DECforms Utilities and Facilities ........................ 1–10 1.4 Developing a DECforms Application . ................... 1–12 1.5 What Comes Next . ................................... 1–14 2 Planning the Application 2.1 The Paper Form . ................................... 2–1 2.2 Planning the Data to Capture ........................... 2–3 2.3 Planning the Platforms and Layouts for the Application ....... 2–4 2.4 Planning the User Interface . ........................... 2–4 2.4.1 Planning Panel Size ................................ 2–4 2.4.2 Planning Panel Relationships ........................ 2–5 2.4.3 The Header Panel ................................. 2–6 2.4.3.1 The Header Panel Data .......................... 2–7 2.4.3.2 Operator Interaction with the Header Panel .......... 2–7 iii 2.4.4 The Trips Panel . ................................ 2–10 2.4.4.1 Organizing the Trip Data . ........................ 2–10 2.4.4.2 Operator Interaction with the Trips Panel ............ 2–11 2.4.4.3 Understanding User-Defined Functions ............. 2–12 2.4.4.4 Functions for the Trips Panel ...................... 2–13 2.4.5 Support for Printing ................................ 2–14 2.4.6 Message and Help Panels . ........................ 2–15 2.5 Planning the Program Style ............................. 2–18 2.6 What Comes Next .................................... 2–19 3 Creating the Character-Cell Layout 3.1 Creating the Form Using the Form Development Environment ........................................ 3–1 3.2 Modifying the Default Layout . ........................ 3–5 3.3 Creating Panels ...................................... 3–6 3.4 Modifying the Help Panel .............................. 3–8 3.5 Choosing Panels ...................................... 3–8 3.6 Creating the Appearance of the First Panel . ................ 3–9 3.6.1 Invoking the Panel Editor CCPED .................... 3–12 3.6.2 Specifying Text Display Attributes ..................... 3–13 3.6.3 Creating a Graphic Literal . ........................ 3–14 3.6.4 Specifying Text Literals and Picture Fields for User Input . ........................................ 3–15 3.6.5 Specifying a Text Literal and Text Field for User Input ..... 3–17 3.6.6 Specifying More Text Literals and a Picture Field . ....... 3–19 3.6.7 Creating Informational Text on the Header Panel . ....... 3–20 3.6.8 Modifying Text Display Attributes ..................... 3–20 3.6.9 Creating a Rectangle Literal . ........................ 3–21 3.7 Creating the Appearance of the Second Panel ............... 3–21 3.7.1 Creating Background Text and Graphics ................ 3–22 3.7.2 Specifying a Group . ................................ 3–23 3.7.3 Specifying Picture Fields for the Group . ................ 3–23 3.7.4 Completing the Form Data . ........................ 3–28 3.7.5 Specifying Picture Fields for the Totals . ................ 3–30 3.7.6 Creating a Rectangle Literal for the TRIP Group . ....... 3–31 3.7.7 Creating Text Literals and the Final Picture Field for the Totals . ........................................ 3–32 3.7.8 Specifying Icons . ................................ 3–32 3.8 Creating the Appearance of the Help Panels ................ 3–33 3.9 Testing the Appearance of the Panels ..................... 3–35 3.10 What Comes Next .................................... 3–36 iv 4 Adding Functions, Responses, Display Actions, and Validations to the IFDL File 4.1 Understanding User-Defined Functions and Function Responses ........................................... 4–1 4.2 Creating User-Defined Functions and Function Responses . 4–2 4.2.1 Declaring the Functions in the Layout .................. 4–3 4.2.2 Where to Declare Function Responses ................. 4–5 4.2.3 Creating Function Responses at the Layout Level ......... 4–5 4.2.4 Creating Function Responses at the Panel Level .......... 4–6 4.2.5 Creating Function Responses at the Group Level ......... 4–7 4.2.6 Creating Function Responses at the Icon Level . .......... 4–7 4.3 Creating Other Responses . ........................... 4–9 4.3.1 Summary of Responses and Response Steps . .......... 4–9 4.3.2 Order of Functions and Responses . ................... 4–12 4.3.3 Creating the Other Responses at the Layout Level ........ 4–12 4.3.4 Creating Responses at the Panel Level ................. 4–14 4.3.5 Creating Exit Responses at the Field Level .............. 4–15 4.4 Declaring a Built-In Function Response . ................... 4–16 4.5 Creating Active Highlighting ........................... 4–17 4.6 Validating Data . ................................... 4–18 4.7 What Comes Next . ................................... 4–19 5 Specifying Form Records and Program Data 5.1 Comparing the Portable and OpenVMS APIs ............... 5–1 5.2 Understanding Form Record Descriptions .................. 5–2 5.2.1 Form Records . ................................... 5–2 5.2.2 Form Record Fields and Groups ....................... 5–3 5.3 Forms_Record_Data Structure ........................... 5–3 5.4 Creating the Form Record Descriptions . ................... 5–4 5.5 Creating Header Information and Data Declarations for the Program . ........................................... 5–7 5.5.1 Creating the Data Declarations and Header Information for the C Program . ................................... 5–8 5.5.2 Creating the Data Declarations and Header Information for the FORTRAN Program . ........................... 5–9 5.6 What Comes Next . ................................... 5–10 v 6 Completing the Application Program for the Character-Cell Layout 6.1 Enabling the Form .................................... 6–1 6.1.1 Creating the C ENABLE Request and Request Options Structure ........................................ 6–3 6.1.2 Creating the FORTRAN ENABLE Request and Request Options Structure . ................................ 6–3 6.2 Receiving the Form Data ............................... 6–4 6.2.1 Creating the C RECEIVE Requests and Form Record Data Definitions ....................................... 6–5 6.2.2 Creating the FORTRAN RECEIVE Requests and Form Record Data Definitions ............................. 6–6 6.3 Disabling the Form . ................................ 6–7 6.3.1 Creating the C DISABLE Request ..................... 6–7 6.3.2 Creating the FORTRAN DISABLE Request .............. 6–7 6.4 Creating the Escape Routines . ........................ 6–7 6.4.1 Creating the Escape Routines for the C Program . ....... 6–9 6.4.2 Creating the Escape Routines for the FORTRAN Program . ........................................ 6–11 6.5 What Comes Next .................................... 6–12 7 Building and Testing the Application for Character-Cell Devices 7.1 Translating the Form and Extracting an Object File . ....... 7–1 7.2 Building the Portable API Program ...................... 7–3 7.3 Testing the Application ................................ 7–4 7.4 What Comes Next .................................... 7–7 Part II More Guidelines and Examples 8 Form Structure 8.1 Form Elements ...................................... 8–1 8.1.1 Form Data ......................................