CONTENTS Title Page Copyright Page Preface Part I The RALLY Definition System 1 Introduction to RALLY Application Development 1.1 Importance of Planning RALLY Applications 1.2 Selecting a Development Method 1.3 Sample RALLY Applications 1.3.1 RALLY$SALES_INFO: The Sales Information System 1.3.2 RALLY$COMMERCE: Salespeople, Products, Customers, Orders 1.4 RALLY as a Productivity Tool 1.4.1 Simple Applications 1.4.2 Prototyping 1.4.3 3GL and ACMS Integration 1.5 Development Method 1.5.1 Concept Phase 1.5.2 Analysis Phase 1.5.3 Design Phase 1.5.3.1 Creating Logical Data Flow Diagrams 1.5.3.2 Designing the Data Source 1.5.3.3 Addressing Form/Report Design Considerations 1.5.3.3.1 Form/Report Layouts 1.5.3.3.2 Data Validation 1.5.3.3.3 Frequency of Access 1.5.3.3.4 Access Rights 1.5.3.4 Creating Control Flow Diagrams 1.5.3.5 Addressing Data Source Definition Design Considerations 1.5.3.6 Writing Formal Specifications 1.5.4 Implementation Phase 1.5.4.1 Writing the Detailed Design Specification 1.5.4.2 Preparing for Development 1.5.4.3 Managing a Multi-Developer Application 1.5.4.3.1 Using RALLY Object Naming Conventions 1.5.4.3.2 Merging Applications 1.5.4.3.3 Using DEC/MMS to Manage Application Files 1.5.4.3.4 Using DEC/CMS to Store Application Files 1.5.4.4 Developing the Application 1.5.4.4.1 DSD Considerations 1.5.4.4.2 Form/Report Considerations 1.5.4.4.3 Menu Considerations 1.5.4.4.4 Further Enhancements 1.5.4.4.5 Debugging the Application 1.5.4.5 Testing the Application Using DEC Test Manager 1.5.4.6 Verifying Adherence to the Design Specification 1.5.4.7 Writing End-User Documentation 1.5.5 Installation Phase 1.5.6 Operation Phase 1.6 Developing Portable Applications 1.6.1 Restrictions for Portable Applications 1.6.2 Design Considerations for Microsoft Windows Environments 1.6.2.1 ``Look and Feel'' 1.6.2.2 Application Logic 1.6.2.3 Commands Not Implemented in RALLY for Windows 2 Concepts 2.1 Data Sources 2.1.1 Relational Database Tables 2.1.2 RMS Files 2.1.3 DATATRIEVE Domains 2.1.4 FIX Files 2.1.5 Other Data Sources Using ODI 2.2 RALLY Objects 2.2.1 Introducing the SALESPERSON_FORM Form/Report 2.2.2 Data Source Definitions 2.2.3 Form/Reports 2.2.3.1 Groups 2.2.3.2 Form/Report Fields and Text Areas 2.2.3.3 Form/Report Packets 2.2.4 Menus 2.2.5 Tasks 2.2.6 ADL Procedures 2.2.7 Naming Conventions 2.2.8 External Objects 2.2.8.1 Creating a Reference to an External Object 2.2.8.2 Editing an External Object Reference 2.2.8.3 Other Operations 2.2.8.4 Usage and Implementation 2.2.9 How to Create, Edit, Delete, Rename, Copy Objects 2.2.9.1 Edit Application Menu (Object/Operation Menu) 2.2.9.2 Direct Object Manipulation 2.2.9.3 Placeholders 2.2.9.4 Effects of Renaming an Object 2.2.9.5 Dynamic Editing (GOLD-DO) 2.2.9.6 Dynamic Tracing (GOLD-D) 2.3 Actions and Tasks 2.3.1 Action Stacks 2.3.2 Tasks 2.3.3 Using Action Sites 2.3.3.1 Action Sites Listed by Application Object 3 Defining a Data Source and Its Components 3.1 Defining an Oracle Rdb Database 3.1.1 Creating a Database 3.1.1.1 Defining Oracle Rdb Domains 3.1.1.1.1 Listing Required Domains 3.1.1.1.2 Listing Domain Characteristics 3.1.1.2 Creating Domain Definitions 3.1.1.3 Defining Oracle Rdb Tables 3.1.1.4 Defining Oracle Rdb Indexes 3.1.2 Editing a Database 3.1.3 Deleting a Database 3.2 Creating Customized Messages for Oracle Rdb Error Conditions 3.2.1 Column Valid-If Constraint Errors 3.3 Accessing RMS Data Sources 3.4 Accessing DATATRIEVE Data Sources 3.5 Defining FIX Data Sources 4 Creating and Editing Data Source Definitions 4.1 What Is a Data Source Definition? 4.1.1 Relationship Between the Data Source and the Data Source Definition 4.1.2 Where Is a DSD Used? 4.2 Elements Common to All Data Source Definitions 4.2.1 Fields 4.2.1.1 Ordering and Reordering Fields 4.2.1.2 Creating a DSD Field 4.2.1.3 Deleting a DSD Field 4.2.1.4 Editing a Field 4.2.1.5 Changing a DSD Field to Reflect Data Source Changes 4.2.1.6 Specifying Formats for a Data Source Definition Field 4.2.1.7 Specifying Initial and Null Values for a Field 4.2.1.8 Specifying Validation for a Field 4.2.1.9 Specifying Input Options 4.2.1.10 Responding to Changes in the Data Source 4.2.2 Editing Record Operation Options 4.3 Creating a Data Source Definition 4.4 Deleting a Data Source Definition 4.5 Rdb Data Source Definitions 4.5.1 Editing an Oracle Rdb Data Source Definition 4.5.2 Record Selection Expressions 4.5.2.1 OR Capability of Oracle Rdb RSEs 4.5.2.2 Run-Time Parameters for Record Selection Expression (RSE) 4.5.3 Using SQL/Services 4.5.3.1 Attachments to the Database 4.5.3.2 Location of the Databases Used by the RALLY Application 4.5.3.3 Using Database Class Servers 4.5.3.4 Using TCP/IP Instead of DECnet 4.5.3.5 Database Access and Server Security 4.5.4 Record Locking Options 4.5.5 Lock Timing Options 4.5.6 Creating a DSD Using Several Tables 4.5.7 Multischema Database Support 4.5.8 Accessing Nondefault Version in Multiversion Rdb Environment (RALLY_SQL_CLASS) 4.5.9 Accessing Data from DEC DB Integrator Gateway Products 4.5.9.1 Defining a DSD Based on an RMS File 4.5.9.2 Defining a DSD Based on a DB2 Database 4.6 Oracle7 Data Source Definitions 4.7 RMS Data Source Definitions 4.7.1 Creating an RMS Database in CDD/Repository 4.7.2 Creating an RMS DSD 4.7.3 RMS DSD Fields 4.8 DATATRIEVE Data Source Definitions 4.8.1 General Guidelines for Creating a DATATRIEVE DSD 4.8.2 Creating a DATATRIEVE DSD Using an RMS File 4.8.3 Creating a DATATRIEVE DSD Based on an Oracle CODASYL DBMS Database 4.8.4 DSDs Using DATATRIEVE OCCURS Clauses 4.9 FIX Data Source Definitions 4.9.1 Creating a FIX DSD 4.9.2 Defining the FIX Data Source File 4.9.3 Creating FIX DSD Fields 4.10 ODI Data Source Definitions 5 Working with Form/Reports 5.1 Using the Screen Editor 5.1.1 Text Areas 5.1.1.1 Ensuring Display of Fields Within Text Area Boundaries 5.1.2 Commands for Screen Editing 5.1.3 Screen Editor Options 5.1.3.1 Location Coordinates and Options: Page Layout Control for Groups, Text Areas, and Fields 5.1.3.2 Change How the Screen Editor Displays Groups 5.1.3.3 Edit a Text Area 5.1.3.4 Edit an LOV or Pop-Up Subform Group 5.2 Types of Groups 5.2.1 Main Group 5.2.2 Data Groups 5.2.3 List of Values Group 5.2.4 Format Group 5.2.5 Position of Groups 5.2.6 Visualizing Form/Report Groups 5.3 Form/Report Types 5.3.1 Form/Reports Based on DSD Joins or Form/Report Joins 5.3.1.1 Creating Form/Reports: Builder Tools Versus Edit Application Menu 5.3.1.2 Simple Multi-Group Reports 5.3.1.3 Complex Multi-Group Reports 5.3.1.3.1 Parent Group 5.3.1.3.2 Child Group 5.3.1.3.3 Overall Structure 5.3.1.4 Multi-Group Reports Using DATATRIEVE 5.3.1.5 Defining Sibling Groups 5.3.1.5.1 Creating the Data Source Definitions 5.3.1.5.2 Creating the Parent Group 5.3.1.5.3 Creating the Sibling Groups 5.3.1.5.4 Aligning the Sibling Groups Side by Side 5.3.1.5.5 Adding Aggregate Fields Based on Sibling Groups 5.3.1.5.6 Making Sibling Groups Invisible 5.3.1.5.7 Creating Sequential Sibling Reports 5.3.2 Form/Report Based on a Control Break 5.3.2.1 Creating the DSD for the Control Break Report 5.3.2.2 Creating the Control Break Report 5.3.3 Updatable Alternative to Control Breaks 5.4 Form/Report Features 5.4.1 Form/Report Packet Options 5.4.1.1 Form/Report to Call and Initial Mode 5.4.1.2 Auto Insertion Options 5.4.1.3 Commit Options 5.4.1.4 Attributes 5.4.2 Action Sites 5.4.3 Local Functions 5.4.4 Visitation Order 5.4.4.1 ' Next Record ' Preserves Current Field 5.4.4.2 Conditional Next Field Definition 5.4.4.3 Pop-Up Subforms 5.4.5 Group-Related Features 5.4.5.1 Format Groups 5.4.5.2 Formatting Options 5.4.5.3 Fields, Text Areas, and Child Groups 5.4.5.4 DSD Substitution 5.4.5.5 Record Operation Options 5.4.5.6 Links to Parent and Child Groups 5.4.5.7 Designing a Title Page 5.4.6 Field-Related Features 5.4.6.1 Types of Fields 5.4.6.2 Data Fields 5.4.6.3 Aggregate Fields 5.4.6.4 Computed Fields 5.4.6.5 Variable Fields 5.4.6.6 Copy Fields 5.4.6.7 Floating Totals 5.4.6.8 Input and Output Formats 5.4.6.9 Field Display and Visitation Attributes 5.4.7 Validation and Limitations 5.4.7.1 Query By Example (QBE) Options 5.4.7.2 Highlighting Fields, Text Areas, or Groups Conditionally 5.4.8 Defining a List of Values 5.4.8.1 Creating a Table and Data for the LOV 5.4.8.2 Creating a Data Source Definition for the LOV 5.4.8.3 Creating a Form/Report for the LOV 5.4.8.4 Editing the Field That Brings Up the LOV 5.4.8.5 Testing the LOV 5.4.8.6 Using an LOV to Do Lookups 5.4.8.7 Using Conditional Lists of Values 5.5 Form/Report Formatting (FML States) 5.5.1 Conceptual Model of Form/Report Layout 5.5.2 Implementation of Form/Report Layout at Run Time 6 Using Date and Number Formats 6.1 Date Format Objects 6.1.1 Changing Default Formats for Date Fields 6.1.2 Using a Date Format Object for a Form/Report Field 6.1.3 Editing Global Date Strings 6.2 Number Format Objects 6.2.1 Creating Number Format Objects 6.2.1.1 Specifying the Maximum Number of Displayable Characters 6.2.1.2 Specifying Scale Factors 6.2.1.3 Specifying Number Character Sets 6.2.1.4 Associating Number Format Objects with Fields 6.2.1.5 Specifying Conditional Actions 6.2.2 Specifying Number Pictures 7 Creating and Editing Menus 7.1 Defining a Menu Using the Builder Tools 7.2 Defining a Menu Outside the Builder Tools 7.3 Using the Screen Editor with a Menu 7.4 Specifying Global Information for Menus 8 Messages 8.1 Defining Help and Error Messages Interactively 8.2 Creating Legends 8.3 Using ' Local_Function ' from Message Sites 8.4 Copying Messages 8.5 Deleting Messages 8.6 Reading and Writing a Text File 8.7 Help and Error Message File Chains 8.7.1 Adding a Message Application File to a Help Message Chain 8.7.2 Adding a Message Application File to an Error Message Chain 8.8 Modifying Global Information for Help and Error Messages 8.8.1 Modifying Global Characteristics of Help Messages 8.8.1.1 Modifying Help Message Options 8.8.2 Modifying Global Characteristics of Error Messages 8.9 Load Messages and Unload Messages Utilities 8.10 Using Messages with External Program Links 8.11 Internationalization 8.11.1 Customizing RALLY Help and Error Message Files 9 Using Tasks, Application Commands, and Macros 9.1 Overview of RALLY Tasks 9.1.1 Creating a Task 9.1.2 Using Task Windows Effectively 9.1.3 Using Tasks in the Definition System 9.1.4 Starting a New Task Versus Calling an Action in the Same Task 9.2 Using Application Commands 9.3 Using Macros 9.3.1 Defining Macros 9.3.2 Using Numbered Macros 9.3.3 Saving Numbered Macros 9.3.4 Reading a Numbered Macro File 9.3.5 Creating Named Macros from Numbered Macros 9.3.6 Using Named Macros 9.3.7 Creating Numbered Macros from Named Macros 10 Maintaining Applications 10.1 Application Security 10.1.1 Reasons for Using Security 10.1.2 Creating and Deleting Password Objects 10.1.3 Protecting Applications from Modification 10.1.4 Protecting Specific Objects in the Application 10.1.5 Controlling the Number of Attempts at a Password 10.1.6 Other RALLY Security-Related Options 10.1.7 Protecting Application Files with Operating System Protection 10.1.8 Using Database Management System Protection 10.2 Using Utilities 10.2.1 Report Utility 10.2.2 Verify Utility 10.2.3 Compact Utility 10.2.3.1 Removing the Symbol Table from the Application File 10.2.4 Merge Utility 10.2.5 Update Utility 10.2.6 Integrate Utility 10.2.7 Load Messages and Unload Messages 10.2.7.1 Unloading Messages from Application Files into Text Files 10.2.7.2 Help and Error Window Start and End Flags 10.2.7.3 Help and Error Option Flags 10.2.7.4 Error and Help Message File Flags 10.2.7.5 Help and Error Message Flags 10.2.7.6 Legend Flags 10.2.7.7 Editing the Message Text File 10.2.7.7.1 Modifying Message Text 10.2.7.7.2 Adding Help Messages 10.2.7.7.3 Adding Error Messages 10.2.7.7.4 Adding Legends 10.2.7.7.5 Deleting Messages 10.2.7.8 Loading Message Files into Existing Application Files 10.2.7.9 Creating Message Application Files 10.2.8 Load Data and Unload Data 10.2.8.1 Transferring Data 10.2.8.2 Transferring Data Using ADL 10.2.9 Define Keys Utility 10.2.9.1 Creating Key Definition Files 10.2.9.2 Changing a Key Mapping 10.2.9.3 Disabling Commands in RALLY for Windows 10.2.9.4 Processing Key Definition Files 10.2.9.5 Using a Key Definition File at Run Time 10.2.9.6 Terminal Options 10.3 RALLY Session Settings 10.3.1 Automatic Fill Mode 10.3.2 Case Sensitive Search 10.3.3 Clear Field 10.3.4 Find Remain 10.3.5 Find to End 10.3.6 Overstrike 10.3.7 Scroll Percent 10.3.8 Word Wrap 10.4 Debugging and Tracing Activity in an Application 10.4.1 Examining Application Values 10.4.2 Using the OpenVMS Debugger for External Program Links 10.4.3 Screen Editing and the Report Writer 10.4.4 Process of Elimination 10.4.5 Using Error Messages as ADL Breakpoints 10.4.6 Testing 10.4.7 Acceptance Testing 10.4.8 Tracing Activity in Applications 10.4.8.1 Debugging Options for Actions and Tasks 10.4.8.2 Debugging Options for Data Operations 10.4.8.3 Running an Application with the /TRACE_LOG Qualifier 10.4.8.4 Dynamic Tracing and Debugging (GOLD-D) 10.4.8.5 Using the /TRACE_LOG Qualifier with Two Terminals 10.5 Performance Considerations 10.5.1 Improving Form/Report Performance 10.5.1.1 Avoid Certain Features in On-Screen Form/Reports 10.5.1.1.1 Scrolling Regions 10.5.1.1.2 Total Page Fields on Each Page 10.5.1.1.3 Aggregates on Each Page or the First Page 10.5.1.2 Use READ ONLY DSDs for Oracle Rdb Data Sources 10.5.1.3 Choose Between Database Joins and Form/Report Joins 10.5.1.4 Use Oracle Rdb Statistical Operators Rather than RALLY Aggregates 10.5.1.5 Avoid Storing Aggregate Values in a Database 10.5.1.6 Reduce the Number of Database Attaches 10.5.1.7 Avoid Refresh on Form/Report Insert and Update 10.5.2 Improving ADL and External Program Performance 10.5.2.1 Use ADL Only When Necessary 10.5.2.2 Open ADL DSDs at the Beginning of a Session 10.5.2.3 Avoid Multiple References to Form/Report Fields 10.5.3 Improving Oracle Rdb Performance 10.5.3.1 Assess Memory Allocation 10.5.3.2 Adjust System Parameters for Lock Usage 10.5.3.3 Assign Sufficient Resources to Each RALLY User 10.5.3.4 Distribute I/O Load on the Database 10.6 Using Oracle TRACE with RALLY Applications 10.6.1 Overview of TRACE 10.6.2 How to Collect Event Data for RALLY 10.6.2.1 Describing RALLY Events and Items 10.6.2.2 Creating a Selection 10.6.2.3 Scheduling Data Collection 10.6.3 Registration IDs 10.6.4 Collecting Workload Information for Oracle Expert 10.6.5 How to Create a Report Based on Collected Data 10.6.5.1 Formatting and Merging Data Files 10.6.5.2 Generating a Report 10.6.5.3 Creating a Customized Report 10.6.6 Using RALLY to Create TRACE Reports 10.6.6.1 Running the Application 10.6.6.2 Description of the Application 10.6.7 RALLY Database Tables Part II Procedural Programming with Oracle RALLY 11 Introduction to Procedural Programming with RALLY 12 External Program Links 12.1 External Program Link Attributes 12.2 Screen Controls 12.3 Parameters 12.3.1 RALLY Internal Information 12.3.2 Passing Mechanism 12.3.2.1 Read/Write Designation Field 12.3.3 Data Description 12.4 Using Parameter Packets with External Links and ADL Procedures 12.4.1 Creating Parameter Packets 12.4.2 Defining ADL Procedures That Accept Parameters 12.4.3 Defining External Program Links That Accept Parameters 12.5 Portability of EPL Routines 12.6 Defining an External Program Link on OpenVMS Systems 12.6.1 Creating the External Routines 12.6.1.1 Writing the Source Code for the External Routine 12.6.1.1.1 External Routine CONDITION_CODE 12.6.1.1.2 External Routine FUNCTION_VALUE 12.6.1.1.3 External Routine VRD 12.6.1.2 Compiling External Routines 12.6.1.3 Placing Routines in a Shareable Image 12.6.1.4 Defining Logical Names to Point to Shareable Images 12.6.1.5 Using OpenVMS Facilities 12.6.2 Creating External Program Links 12.6.3 Assigning External Program Links to Action Sites 12.6.4 The BUFFER Type External Program Link (OpenVMS Only) 12.6.4.1 Parameters for an External Link Program of BUFFER Type 12.7 Digital UNIX External Program Link Support 12.7.1 Language Support 12.7.2 Data Types Supported 12.7.3 Floating Point External Data Type Support 12.7.4 C Naming Convention 12.7.5 C Calling Convention 12.7.6 Building Shared Libraries 12.7.7 Locating Shared Libraries 12.7.8 Loading/Unloading Shared Libraries 12.7.9 External Date Format 12.7.10 Routine Names When Using Multiple Shared Libraries 12.7.11 Hints for Debugging 12.8 Microsoft Windows External Program Link Support 12.8.1 Language Support 12.8.2 Data Types Supported 12.8.3 Floating Point External Data Type Support (G_FLOAT) 12.8.4 C Naming Convention 12.8.5 C Calling Convention 12.8.6 Building Dynamic Link Libraries (DLLs) 12.8.7 Windows Prolog/Epilog Code 12.8.8 Locating DLLs 12.8.9 Loading/Unloading DLLs 12.8.10 External Date Format 12.8.11 Sharing Dynamic Link Libraries 12.8.12 Sharing File Handles with RALLY 12.8.13 Function Prototypes and Include Files 12.8.14 Hints for Debugging 12.9 MS-DOS External Program Link Support 12.9.1 Overview 12.9.2 Language Support 12.9.3 Data Types Supported 12.9.4 Floating Point External Data Type Support (G_FLOAT) 12.9.5 Pascal Naming Convention 12.9.6 Pascal Calling Convention 12.9.7 Math Library Support 12.9.8 Restrictions on C Run-Time Library Support 12.9.9 Building Dynamic Link Libraries 12.9.9.1 Creating Object and/or Library Files 12.9.9.2 Module Definition Files 12.9.9.3 LLIBCDLL.LIB, LLIBCA.LIB 12.9.9.4 Installing the Standard C and Alternate Math Libraries 12.9.10 Locating DLLs with RALLY_PATH 12.9.11 External Date Format 12.9.12 Sharing DLLs 12.9.13 Sharing File Handles with RALLY 12.9.14 Segment Fix-Up Errors 12.9.15 Function Prototypes and Include Files 12.9.16 Hints for Debugging 13 Callable Interface to RALLY 13.1 Simplified Callable Interface 13.2 Full Callable Interface 13.3 Handling User-Requested Interrupts 13.4 Reusability and Re-entrancy 13.5 Passing Parameters to Callable RALLY Routines 13.5.1 Item Lists 13.5.2 Bound Procedure Values 13.5.3 Message Vector 13.5.4 Testing for Condition Codes 13.6 Callable Interface Routines RALLY$CLEANUP RALLY$CLI_PARSE RALLY$CONTROL RALLY$INITIALIZE RALLY$PARSEINFO RALLY$RALLY RALLY$SPAWN 14 Open Data Interface (ODI) 14.1 Open Data Interface Routines 14.1.1 Organizational Routines 14.1.2 Routines for Reading Data from a Data Source 14.1.3 Routines for Writing Data to a Data Source 14.2 Error Handling 14.3 DECdtm Support 14.4 SQL Record Selection Expression 14.5 Data Structures 14.5.1 User_defined_info 14.5.2 Value Buffers 14.5.3 Field_array 14.5.4 Record_id 14.5.5 Query_array 14.6 Typical Call Sequences 14.7 Using the RALLY Open Data Interface 14.7.1 Placing ODI DSD Routines in the Same Executable Image (OpenVMS) 14.7.2 Placing ODI DSD Routines in the Same Dynamic Link Library (Windows) 14.7.3 Coordinating Groups in the Same Form/Report 14.7.4 Child Groups 14.7.5 Lists of Values 14.8 ODI Examples in the C Language 14.8.1 OpenVMS Example 14.8.2 Windows Example 14.9 Open Data Interface Routines CHECK CONSTRAINTS COMMIT DELETE GET RECORD INITIALIZE INSERT RESTRICT STREAM ROLLBACK SELECT UPDATE START TRANSACTION TERMINATE UPDATE 15 Introduction to the RALLY Application Development Language (ADL) 15.1 Features of ADL 15.2 Creating ADL Procedures 15.3 Editing, Renaming, Deleting, Copying, and Printing ADL Procedures 15.4 Compiling ADL Procedures 15.5 Invoking ADL Procedures 15.6 Example: Creating an ADL Validation Procedure 16 Elements of ADL 16.1 Syntax Rules 16.2 Data Types 16.2.1 The NUMBER Data Type 16.2.1.1 Specifying the Attributes of Numbers 16.2.1.2 Setting Number Formats in the Definition System 16.2.2 The CHAR Data Type 16.2.3 The DATE Data Type 16.3 Variables 16.3.1 Naming and Declaring Variables 16.3.2 Scope of ADL Variables 16.3.3 Global Variables 16.3.4 Form/Report Fields 16.3.5 Variables Exported from Other ADL Procedures 16.3.6 Data Source Definition Fields 16.3.7 Variables Declared in the Current ADL Procedure-Local Variables 16.3.8 Parameters 16.3.9 Constants 16.4 Functions 16.5 Operators 16.5.1 Precedence of Operators 16.5.2 Arithmetic Operators 16.5.3 Concatenation Operator 16.5.4 Relational Operators 16.5.5 Logical Operators 16.6 Expressions 16.7 Statements 16.7.1 Assignment Statements 16.7.2 Compound Statements 16.7.3 Conditional Statements 16.7.4 Repetitive Statements 16.7.5 RETURN Statements 16.7.6 Call Statements 16.7.7 Procedural Statements 16.8 Writing ADL Procedures 16.8.1 Procedure Headings 16.8.2 Defining Constants 16.8.3 Declaring Variables 16.8.4 Procedure Body 17 Using ADL Procedures 17.1 Using Single ADL Procedures 17.1.1 Computing Values for Form/Report Fields 17.1.2 Validating Form/Report Fields 17.1.3 Providing Users with Context-Sensitive Information 17.1.4 Limiting Reports to a Subset of Available Data 17.1.5 Filling in the Current Day, Month, and Year 17.2 Passing Values to ADL Procedures 17.2.1 Using Single ADL Procedures 17.2.2 Invoking One ADL Procedure with Another 17.2.3 Invoking ADL Procedures with Parameter Packets 17.3 Controlling Action Stacks and Application Flow 17.3.1 Invoking Actions Based on User Input 17.3.1.1 Checking User Response 17.3.1.2 Controlling Application Flow 17.3.2 Generating Values for Use Throughout a Single Task 17.3.2.1 Running the Application with a Single Task 17.3.2.2 Running the Application with Several Tasks 17.3.3 Calling External Program Links to Perform Calculations 18 ADL Data Manipulation Language 18.1 Uses of DML 18.2 RALLY Transaction Control 18.3 ADL Transaction Control 18.4 DML Procedures 18.4.1 DML Status Codes 18.4.2 DML Error Handling 18.5 Reading from Data Sources 18.5.1 Checking for Records in DSDs 18.5.2 Restricting DSD Record Streams 18.6 Writing to Data Sources 18.6.1 Committing Data to Data Sources 18.6.2 Generating Unique ID Numbers 18.7 Deleting Records from Data Sources 18.8 Loading and Unloading Data Between Data Sources 18.9 Using DML with Different Data Sources 18.9.1 Using Oracle Rdb Databases 18.9.1.1 Oracle Rdb Read/Write Transactions 18.9.1.2 Oracle Rdb Read-Only Transactions 18.9.2 Using FIX Files 18.9.3 Using RMS Files 18.9.4 Using DATATRIEVE Domains 18.10 Batch Processing 19 ADL Functions 19.1 Using Functions 19.2 Using Expressions as Function Arguments 19.3 Function Types 19.4 Functions ADD_MONTHS GET_CMD GET_MODE IS_CURRENT_FIELD LAST_DAY LENGTH MONTHS_BETWEEN NEXT_DAY REVERSE_STRING ROUND for Dates ROUND for Numbers SEARCH SUBSTR TO_CHAR for Dates TO_CHAR for Numbers TO_DATE TO_NUMBER TRANSLATE_LOGICAL TRUNC for Dates TRUNC for Numbers UPCASE 20 ADL Built-In Procedures 20.1 Invoking Built-In ADL Procedures 20.2 Procedure Types 20.3 Built-in Procedures CALL_CMD DB_CLOSE DB_COMMIT DB_DELETE DB_GET_FIRST DB_GET_NEXT DB_INSERT DB_OPEN DB_QUERY DB_RESET DB_ROLLBACK DB_UPDATE DEBUG_LOG DEFINE_LOGICAL DELETE_LOGICAL ERROR EXECUTE_CMD FORCE_OUTPUT HELP MAKE_NULL SET_CACHE_SIZE SET_CURRENT_FIELD SET_FAILURE SET_NOTRACE SET_SUCCESS SET_TRACE Part III Oracle RALLY Advanced Application Development Techniques 21 Techniques for Using RALLY and ACMS Together 21.1 An Introduction to VAX ACMS 21.1.1 Efficiency and Performance 21.1.2 Availability and Security 21.2 Techniques for Using RALLY and ACMS Together 21.2.1 Restrictions 21.2.2 Performance Considerations 21.2.3 USERNAMEs, UICs, and RIGHTS 21.3 Running RALLY Applications from ACMS Servers 21.4 Calling ACMS Tasks from RALLY Applications Using External Program Links 21.4.1 Tasks That Use DECforms for Forms Management 21.4.2 Tasks That Interact Only with the Data Source 21.5 Calling ACMS Agents Through the Open Data Interface 21.6 Using RALLY ODI DSDs and an ACMS Agent 21.6.1 Prerequisites 21.6.2 Implementation 21.6.3 RALLY Features Used to Minimize Transaction Length 21.6.4 Introduction to the Example Application 21.6.5 Installing and Running the RALLY-ACMS Example Application 22 Techniques for Handling Text 22.1 Creating Multiline Fields 22.1.1 Characteristics of a Multiline Field 22.1.2 Using Word Wrapping in a Multiline Field 22.1.2.1 Enabling Word Wrapping for a Single Field 22.1.2.2 Enabling Word Wrapping for an Entire Application 22.2 Storing Large Text Fields 23 Techniques for Validating Data 23.1 Validating Data Against the Data Source 23.2 Validating Multiple Fields 23.3 Checking for a Record and Inserting a New Record 24 Techniques for Database Interaction 24.1 Allocating Sequence Numbers 24.2 Displaying Oracle Rdb Null Numeric Fields 25 Form/Report Techniques 25.1 Chaining Form/Reports Together 25.2 Creating Summary Reports with Aggregate Totals 25.3 Creating Floating Total Fields 25.4 Performing Cascading Updates 25.5 Creating Restricted Lists Of Values 25.6 Restricting an LOV Using Run-Time Variables 25.7 Restricting an LOV Using Subset Lists of Values 25.8 Drawing Boxes Around Lists of Values 25.9 Confirming User Actions 25.9.1 Using Form/Reports and ADL Procedures to Confirm User Actions 25.9.2 Using Menu Choices to Confirm Record Deletion 25.10 Updating Form/Reports Automatically 25.11 Trapping the ' Refresh ' Command 25.12 Disabling Legends for Experienced Users 25.13 Displaying Information on a Menu 25.14 Using Context-Sensitive Pop-up Menus 25.15 Using Conditional Lists of Values with Copy Fields 25.16 Invoking Before/After Commit/Update Action Sites with Non-Visited Child Group 26 Miscellaneous Techniques 26.1 Techniques That Use the OpenVMS Username 26.1.1 Accessing the OpenVMS Username Using LIB$GETJPI 26.1.2 Validating the OpenVMS Username on Data Entry 26.1.3 Displaying a Subset of Data Based on User Identification 26.2 Passing Parameters to Batch Applications A Design Specification for RALLY$SALES_INFO A.1 Overview A.2 Data A.2.1 Data Sources A.2.2 Indexes A.2.3 Validation A.2.4 Data Source Definitions A.3 Menus A.3.1 Main Menu A.3.2 Salespeople Menu A.3.3 Customers Menu A.3.4 Products Menu A.3.5 Orders Menu A.3.6 Management Menu A.4 Form/Reports A.4.1 SALESPERSON_ENTRY_FR A.4.2 SALESPERSON_QUERY_FR A.4.3 SALESPERSON_PRINT_FR A.4.4 SALESPERSON_DISTRICT_FR A.4.5 SALESPERSON_LOV_FR A.4.6 DISTRICT_LOV_FR A.4.7 CUSTOMER_ENTRY_FR A.4.8 CUSTOMER_DISPLAY_FR A.4.9 CUSTOMER_PRINT_FR A.4.10 CUSTOMER_LOV_FR A.4.11 PRODUCT_ENTRY_FR A.4.12 PRODUCT_QUERY_FR A.4.13 PRODUCT_DISPLAY_FR A.4.14 PRODUCT_PRINT_FR A.4.15 PRODUCT_LOV_FR A.4.16 PRODUCT_LINE_LOV_FR A.4.17 ORDER_ENTRY_FR A.4.18 ORDER_DISPLAY_FR A.4.19 ORDERS_BY_CUSTOMER_FR A.4.20 BOTTOM_FR A.4.21 GOAL_VARIABLE_FR A.4.22 GOAL_ENTRY_FR A.4.23 GOAL_DISPLAY_FR A.5 Miscellaneous Features A.5.1 Lists of Values A.5.2 ADL Procedures A.5.3 Security Objects A.6 Packaging and Installing the Application B RALLY Transactions B.1 Form/Report Transaction Model B.1.1 Form/Report Read-Only Transactions B.1.2 Form/Report Read/Write Transactions B.2 Relationship Between Form/Report Transactions and Access Method Transactions B.2.1 Features That Influence Transaction Behavior B.3 ADL (DML) Transaction Model B.4 Relationship Between ADL Transactions and Oracle Rdb Transactions B.4.1 Read-Only DSDs B.4.2 Read/Write DSDs B.4.3 Starting the Oracle Rdb Read/Write Transaction B.4.4 Terminating the Oracle Rdb Read/Write Transaction B.4.5 Shared Write B.4.6 Protected and Exclusive Write B.5 Attaches, Detaches, and Caching B.5.1 Attach Caching: Rdb Versus Oracle7 C RALLY Hebrew Option C.1 Field Objects C.2 Form/Report Objects C.3 Menu Objects C.4 DSD Objects C.5 ' Menu Left ' and ' Menu Right ' Commands C.6 ' Toggle Direction ' Command C.7 Setting the OpenVMS Logical Name RALLY$HEBREW_TERMINAL D ADL Reserved Words E Mnemonics for Defining Keys E.1 Valid Mnemonics E.2 Using Printable Characters E.3 Using Octal Key Representation E.4 Using Modifiers E.5 Equivalent Key Sequences E.6 Mnemonic-Octal Conversion E.7 Platform Issues F International Character Set Support F.1 Built-In Character Sets F.2 Building Your Own Character Translation Table F.3 Using Special Keyboard Drivers F.4 Shifted Function Keys F.5 Enhanced Keypad Keys F.6 Limitations for Key Mapping and Translation F.7 RALLY for Windows Information F.8 Sample Character Sets EXAMPLES 10-1 Messages Unloaded from RALLY$COMMERCE 10-2 Help-on-Help Message 10-3 Sample Key Definitions 10-4 Sample Log File 10-5 Facility Definitions on TSTVAX 10-6 RALLY Summary Statistics Report 10-7 Using Reporting Options to Generate a Customized Report 10-8 RALLY FORM/REPORT Reports 10-9 Generating an Oracle Rdb Report for a Specific RALLY Form/Report 10-10 Oracle Rdb Data for Worksheet Form/Report 10-11 Form/Report Resource Utilization Report 10-12 Form/Report Transactions with Oracle Rdb Resource Utilization Report 10-13 Oracle Rdb Database Attaches By Database and Application 12-1 External Routine CONDITION_CODE 12-2 External Routine FUNCTION_VALUE 12-3 External Routine VRD 12-4 Macro File (RALLY$3GL_LINK_TV.MAR) for VRD, CONDITION_CODE, and FUNCTION_VALUE Routines 12-5 Link Command File (RALLY$3GL_LINK.COM) to Link C Routines 16-1 The COMPUTE_INVOICE_ADL Procedure 17-1 The COMPUTE_TRIANGLE_ADL Procedure 18-1 The GET_ADDRESS_ADL Procedure 18-2 The FORM_SET_UP_ADL Procedure 18-3 The GET_ADDRESS2_ADL Procedure 18-4 The GET_NUMBER_ADL Procedure 18-5 The DELETE_RECORDS_ADL Procedure 18-6 The MOVING_DATA_ADL Procedure FIGURES 1-1 Structure of the RALLY$SALES_INFO Application 1-2 Prototype Order Entry Form 1-3 Final Order Entry Form 1-4 Logical Data Flow for Sales Information System 1-5 Order Entry Screen 1-6 Orders by Customer Screen 1-7 Control Flow Diagram for Orders by Customer 1-8 Multi-Developer Application 1-9 Merging Application Files 2-1 Salesperson Directory 2-2 Groups in the SALESPERSON_FORM Form/Report 2-3 Screen Editor Display of SALESPERSON_FORM 2-4 SALESPERSON_DSD Data Source Definition 2-5 SALESPERSON_FORM_UPDATE_PKT Form/Report Packet Mode 2-6 Screen Editor Display of Application's Main Menu 2-7 Menu Choice to Call SALESPERSON_FORM 2-8 MAIN_TASK of RALLY$COMMERCE 2-9 ADL Procedure ELAPSED_DAYS_PROC 2-10 Naming Conventions 2-11 External Object Reference 2-12 Edit Application Menu 2-13 Direct Object Manipulation of Form/Report Fields 2-14 Task and Actions of RALLY$COMMERCE 2-15 Connections Among Menus and Form/Reports 2-16 Action Stack 2-17 Second Object Added to Action Stack 2-18 Menu Removed from the Stack 2-19 Form/Report Removed from the Stack 3-1 Tables, Columns, and Domains for ORDER_ITEM Table 3-2 Tables, Columns, and Domains for ORDER Table 3-3 Primary Keys and Multi-Segment Keys 3-4 Creating a Database Index 4-1 DSDs and Their Relationship to Form/Reports 4-2 Edit Rdb Data Source Definition Characteristics Form 4-3 Record Operation Options for the PRODUCT_DSD Data Source Definition 4-4 Example of Defining an OR Restriction 4-5 Another Example of Defining an OR Restriction 4-6 Defining a Run-Time Parameter 4-7 Parameters for Record Selection Expression 4-8 A Report Needing a DSD Using Several Tables 4-9 Create an RMS Data Source Definition Form 4-10 A Sample DBMS Set Relationship 5-1 Screen Editor Display of Text Areas and Fields 5-2 Text Areas in a Form/Report 5-3 Location Coordinates and Options of the ORDER_AND_ITEM_REPORT Form 5-4 Advanced Location Options for a Group Form 5-5 Data Groups in the ENHANCED_ORDER_AND_ITEM_REPORT Form/Report 5-6 Location of Groups in a Form/Report 5-7 Groups in the Screen Editor 5-8 Hierarchical (Parent-Child) Form/Report 5-9 Invoice Statement - A Hierarchical Form/Report 5-10 Form/Report with Rdb and DATATRIEVE Groups 5-11 Structure of a Form/Report with Sibling Groups 5-12 Form/Report with Sibling Groups 5-13 Coordinates for the Parent and Sibling Groups 5-14 Form/Report with Side-by-Side Sibling Groups 5-15 Salespeople by District Report 5-16 Creating a Control Break Data Group 5-17 Visitation Order 5-18 Conditional Next Field Definition 5-19 Sample Salesperson Form with List of Values 5-20 Choosing List of Values Attributes for a Field 5-21 Using a Conditional List of Values 8-1 Default Global Help Information 8-2 Default Global Error Information 10-1 Merge Utility 10-2 Load/Unload Data Utilities 10-3 Flow of the Debug Task 12-1 External Program Link Parameters 12-2 Argument List 12-3 Composition of Condition Code (OpenVMS Only) 13-1 Item Descriptor Format 13-2 Bound Procedure Descriptor Format 14-1 Structure of a RALLY Application That Uses the ODI 14-2 A Flowchart of the ODI Routines 21-1 RALLY-ACMS Example Application 25-1 Chaining Form/Reports 25-2 Summary Report with Aggregate Totals 25-3 Subset LOV 25-4 Chained Help, Legend, and Error Message Files A-1 Structure of the Sales Information Application A-2 Tables and Connecting Fields TABLES 1-1 Features Illustrated in the RALLY$SALES_INFO Sample Application 1-2 Suggested Transition Criteria for Each Phase 1-3 Form/Reports in Sales Information System 1-4 Data Source Definitions in Sales Information System 1-5 Suggested Naming Conventions for RALLY Objects 2-1 Relational Terminology 2-2 PRODUCT Table in RALLY$COMMERCE Database 2-3 Steps in Defining an Application and the Related RALLY Objects 2-4 Direct Object Manipulation: Some Examples 2-5 Connections Among Menus and Form/Reports 3-1 Creating an Rdb Database 3-2 RALLY Predefined Domains 3-3 Additional Domains Needed for Sample Database 4-1 PRODUCT_DSD Before and After the Reordering of Fields 4-2 Record Selection Expression Operators 4-3 Data Type Codes 5-1 Useful Commands for Screen Editing 5-2 Comparing Joins Defined in DSD and Groups Related in Form/Reports 6-1 Picture Symbols for Date Formats 6-2 Sample Date Formats 6-3 Date Formatting Strings 6-4 OpenVMS Data Types 6-5 Scale Factors 6-6 Formatting Characters 6-7 Number Picture Symbols 6-8 Sample Number Pictures 7-1 Menu-Choice Style Options 10-1 Highlighting in RALLY Messages 10-2 Key Definition File Keywords for RALLY Settings 10-3 RALLY Events 10-4 Resource Utilization Items 10-5 RALLY Data Items 10-6 Events and Items Available in the ALL Class for RALLY 10-7 TRACE Reports 10-8 Columns for Table EPC$1_423_FORM_REPORT 10-9 Columns for Table EPC$1_423_FORM_REPORT_ST 10-10 Columns for Table EPC$1_423_ADL 10-11 Columns for Table EPC$1_423_ADL_ST 12-1 Severity Codes 12-2 READ/WRITE by Passing Mechanism Restrictions 12-3 Data Type by Passing Mechanism Restrictions 12-4 Data Type Codes 12-5 External Data Type Support for Digital UNIX EPLs 12-6 External Data Type Support for MS-DOS and Windows EPLs 12-7 Passing Mechanism Support for Digital UNIX EPLs 12-8 Passing Mechanism Support for MS-DOS and Windows EPLs 13-1 Full Callable Interface Routines 13-2 Files Defining RALLY Symbols 16-1 Sample Date Formats 16-2 ADL Operators 16-3 Precedence of Operators in ADL 18-1 DML Procedures 18-2 Value and Meaning of Common DML Status Codes 19-1 ADL Functions 19-2 Date-Rounding Masks 19-3 Date Truncation Masks 20-1 ADL Procedures 25-1 Action Sites Used to Confirm User Actions 25-2 RALLY Commands and Pop-up Menu Text A-1 Data Source Definitions in Sales Information System A-2 List of Values Usage in Sales Information System A-3 ADL Procedures in Sales Information System E-1 Valid Key Mnemonics E-2 Invalid Modifier Combinations E-3 Equivalent Key Mnemonics E-4 Mnemonic-Octal Conversion