Programming Guide
Introduction
In This Guide
Intended Audience
Database-related Examples
Conventions
Path Notation in This Guide
Documentation
Your Support Options
Writing Scripts and Procedures
Scripts
Frame Scripts
Initialize Statement
Frame Script Event Blocks
Field and Menu Item Scripts
Example--Field and Menu Item Event Blocks
User Class Scripts
Statements in Scripts
Procedures
How You Can Create Procedures in OpenROAD
Global Procedures
Procedure Statement
Returning from a Procedure
Local Procedures
Declaring Forward References for Local Procedures
How You Can Define Local Procedures
Example--Local Procedure
Database Procedures
3GL Procedures
3GL Parameters
Guidelines for Writing C Procedures
Calling Procedures
How You Can Call 4GL Procedures
How You Can Pass Parameters to 4GL Procedures
How You Can Call Database Procedures
How You Can Pass Parameters to and From Database Procedures
How You Can Call Procedures in Expressions
How Procedure Handles Work (ProcHandle Objects)
How You Can Create a ProcHandle Object
How You Can Execute a ProcHandle Object
Restrictions to Using the Call Method
Compiler Limitations
Programming Frames
Overview
How You Can Invoke Frames
FrameExec Object
How the CurFrame System Variable Works
How Frames Access Child and Parent Frames
How You Can Transfer Control Between Frames
How You Can Pass Parameters Between Frames
How You Can Close a Frame
Differences Among the Frame-invoking Statements
How You Can Transfer Control to a New Frame: Callframe Statement
How You Can Return a Value from an Active Child to the Inactive Parent
How You Can Pass Parameters Between an Active Child and Inactive Parent
How You Can Open Concurrent Frames: Openframe Statement
How You Can Pass Parameters Between Active Frames
How You Can Communicate Between Open Frames
How You Can Pass Control While Closing the Parent: Gotoframe Statement
How Returning to a Closed Parent Works
How You Can Pass Parameters Between an Active Child and a Closed Parent
How You Can Change a Frame's Definition
How You Can Block an Open Frame
Pop-up Frames
How You Can Create Your Own Pop-up Frames
How You Can Use Predefined Pop-up Frames
How You Can Call Predefined Pop-up Frames
A Simpler Process for Creating Information and Reply Pop-ups
How You Can Use Ghost Frames
How You Can Run Non-interactive Applications
How You Can Determine If a Frame Is Being Initialized
Working with Classes
Overview
Conceptual Background
How You Can Reference Objects
How You Can Enhance Performance When Declaring Reference Variables
Field Function
How You Can Set and Get Attributes
How You Can Invoke Methods
Using an Object-oriented Approach to Programming
Inheritance
Class Relationships
Inheritance Hierarchy (Generalization/Specialization)
Aggregation (Containing)
User Class Hierarchies
How Polymorphism Works
How You Can Build an Inheritance Tree
How Invoking User Class Methods in 4GL Works
How You Can Create a User Class
How You Can Encapsulate Attributes and Methods
How You Can Write Methods
How You Can Use Polymorphism
Examples of Method: Hire Method
Employee Version
TempEmployee Version
PermanentEmployee Version
Manager Version
External Classes
ActiveX Support
How You Can Use External Classes
Dynamic Programming with External Objects
Non-Formfield External Objects
How You Can Use Collections with External Classes
Example--ActiveX Controls
How You Can Create Fields from User Classes
How You Can Manipulate Objects Generically: Casting
How You Can Work with Attributes
Other Attributes Commonly Used Generically
How You Can Work with Methods
Overview of the OpenROAD System Classes
Object
Class
User Class Source Definition
User Class Runtime Definition
Source Definitions for Applications and Their Components
Running Applications and Their Components
Field and Menu Information
Event Information
XML Support for OpenROAD
XML Export for Migration Tasks
Using XML Export Files for SCM Integration
Using XML Export Files to Extend Scripting Capabilities
Examples of XML Capabilities
Example: Writing XML
Example: Parsing XML
Example: Viewing an XML File in a TreeviewField
Working with a Database
Overview
Conceptual Background
How You Can Access a Database with Standard SQL Statements
Select Statement
Example--Singleton Select
Example--Select Loop
How You Can Select Data into Reference or Array Variables
How You Can Use the Select Statement Generically
Errors Originating in Called 3GL Procedures
How You Can Use the Insert Statement
How You Can Use the Update Statement
How You Can Use the Delete Statement
How You Can Use Other SQL Statements
How You Can Use Database Procedures
How You Can Use the Execute Immediate Statement
How You Can Use the Into Clause with a Select Statement
How You Can Use Cursors to Access the Database
How You Can Use the CursorObject System Class
CursorObject Attributes
How You Can Declare a Cursor
How You Can Open and Position a Cursor
How You Can Update or Delete a Row
How You Can Close a Cursor
How You Can Manage Transactions with Cursors
How You Can Use Methods That Access the Database
How You Can Access a Database with DataStream Objects
How You Can Select a Mode for a DataStream Object
How You Can Use SQLSelect Objects
How You Can Specify the Query
How You Can Run the SQLSelect Query
How You Can Get Next and Previous Rows
How You Can Close the SQLSelect Object
How You Can Use Parameterized Queries
How You Can Use the SetCols Method to Specify the Query
How You Can Use Query Objects
Required Operations
How You Can Update Data with a Query Object
How You Can Delete Data with a Query Object
How You Can Manage Transactions
How You Can Control Concurrency
Sample Concurrency Control Application
How You Can Manage Multiple Sessions and Transactions
How You Can Manage Transactions with Bitmaps, String Objects, Long Byte Objects, Long Vchar Objects, and Data Streams
How You Can Manage Transaction Errors
How Running with Autocommit On Works
How You Can Use the Exit Statement with Transactions
How Programming for Multiple Sessions Works
How You Can Keep Track of the Current Session
How You Can Access the DBSessionObject Object
How You Can Use Concurrent Frames and Multiple Sessions
How You Can Use Cursors, DataStream Objects, and Multiple Sessions
How You Can Open a New Database Session
Connect Method
OpenNew Connection Method
Examples of Opening New Database Connections
How You Can Switch Database Sessions
How You Can Switch Sessions in a Called Frame
How You Can Switch Sessions in an Event Block
How You Can Switch Sessions for a 4GL Procedure
How You Can Switch Sessions for 3GL and Database Procedures
How You Can Disconnect a Session
Handling Database Errors
How You Can Use the ErrorNumber and DBMSError Attributes
How You Can Handle DataStream Errors
How You Can Use BitmapObject and StringObject Methods
How You Can Use LongByteObject and LongVCharObject Methods
How You Can Use the ErrorStatus Attribute
How You Can Use the Inquire_sql Statement
Choosing an Error Handling Strategy
How You Can Use the DBMSErrorPrinting Attribute
How You Can Detect Errors When Working with Bitmaps, String, Long VChar, and Long Byte Objects
Working with Arrays, Table Fields, and Collections
Overview
Arrays and Table Fields--Conceptual Background
Ways to Create an Array
Manipulating Arrays and Table Fields
How You Can Reference Table Fields
Arrays
How You Can Declare an Array
How You Can Reference an Array
Restrictions on Array Structure
How You Can Manipulate Arrays
How You Can Use the _RowState Attribute
Fence Diagram for Row States and Transitions
How You Can Add Rows to an Array
How You Can Change Values in an Array
How You Can Specify an Array Row to be Deleted
How You Can Delete Rows in an Array
How You Can Retrieve Array Information
How Sorting Arrays Works
How You Can Find Values in an Array
Table Fields
Table Fields and Associated Arrays
TableField, ColumnField, and ProtoField Objects
Table Field Components
Table Field Background
Table Title
Table Header
Column Titles
Column Field
Prototype Field
Individual Cells
Table Body
Control Button
Scroll Bar
Summary of Table Field Access Syntax
Table Field Operations
How You Can Display and Remove the Vertical Scroll Bar
How You Can Scroll Through Data
How You Can Use the Vertical Scroll Bar
How You Can Use Navigation Keys to Scroll
How You Can Use Single-character Find
How You Can Trigger SetValue, Exit, and Scroll Events
How You Can Scroll to a Specific Row
How You Can Use the SetInputFocus Method to Scroll
How You Can Use the ActiveRow Attribute to Scroll
How You Can Scroll Indirectly with the Find Method
Horizontal Scroll Bars
How You Can Remove or Add the Control Button
How You Can Enable and Disable User Modifications to Table Field Data
How You Can Update Existing Data in a Table Field Row
How You Can Insert New Rows Before Existing Rows
How You Can Delete Rows
How You Can Append Rows to the End of a Table Field
How You Can Copy Data to PC Clipboard
Column Operations
How You Can Display and Remove Column Headers
How You Can Format a Multiline Header
How You Can Use Hidden Columns
How You Can Turn CellAttributes On
How You Can Use the HasDataChanged Attribute
TableField Methods
InsertColumn and DeleteColumn Methods
WhichRow Method
WhichTableField Method
Controlling Multiple Table Fields with a Single Control Button
How You Can Sort Table Field Data Generically
Collections
How You Can Index into a Declared Collection
How You Can Index into an Undeclared Collection
Working with List Views and Tree Views
Overview
How You Can Use Listview and Treeview Fields
Listview_Treeview_Demo
Import the Demonstration Application
Run the Demonstration Application
Listview Fields
How the Listview Example Works
How You Can Load the Listview Field with Data
Listview Field Styles
Listview Field Events
TreeNode and Tree Classes
TreeNode Class
Appearance
Node Relationships
Tree Class
Attributes
Maintenance Methods
Node Location Methods
Traversal Methods
AddNode Method
Treeview Fields
How You Can Build a Tree
How You Can Attach Information to a Tree Node
How You Can Use Bitmap Labels
How You Can Delete Nodes
Treeview Field Events
Working with Images and Text Strings
Overview
How You Can Work with Images
Image Fields
How You Can Load a Bitmap Image into an Image Field
Relationship Between BitmapObject and ImageField Object
Image Trim
Other Fields
Palette Fields
How You Can Insert an Image into a Palette Field
How You Can Arrange the Display of Palette Fields
BitmapObject Class
How You Can Store Images in Files
How You Can Store Images in a Database
How You Can Display a Bitmap from a Database
Update Bitmaps in a Database
How You Can Create a Bitmap Storage Table
ImageField Object
How You Can Work with Text Strings
How You Can Store Strings in the Database
How You Can Create a String Storage Table
How You Can Load a String into the Database
How You Can Display a String from a Database
How You Can Update Strings in a Database
How You Can Replace the Current StringObject Value
How You Can Replace the Contents of an External File
How You Can Delete Strings from a Database
How You Can Determine If a Database is Unicode-enabled
Using 3GL in Your Application
Overview
How You Can Call 3GL Procedures
Callproc Statement
How You Can Pass Parameters to 3GL Procedures
How You Can Use Exec 4GL Statements in 3GL Procedures
How You Can Pass Structured Data
How You Can Check for Errors
Summary of Exec 4GL Statements
Example--Passing an Array to a 3GL Procedure
How You Can Call the 3GL Procedure
Scale_y_array Procedure
Example--Sending a User Event from 3GL to 4GL
How You Can Use Exec SQL Statements in 3GL Procedures
How You Can Preprocess Exec 4GL and Exec SQL Statements
How You Can Link 3GL Procedures
Technical Tips
4GL/3GL Data Types
Sample 3GL Procedures
3GL Sample
Exec 4GL and Exec SQL Sample
Data Entry Error Handling
Overview
How You Can Use Data Entry Error Handlers
How You Can Change Values with a Data Entry Error Handler
How You Can Access a Hierarchy of Data Entry Error Handlers
How You Can Customize Error Messages
How You Can Pass Control to Another Error Handler
Example--How Data Entry Error Handler Hierarchy Works
Restrictions on Data Entry Error Handlers
Managing Event Queues
Overview
Conceptual Background
How Events Are Executed
Event-based Programming
Order of Events: Event Queues
How You Can Examine and Manipulate Event Queues
Event Types
Frame Events
Field Events
Menu Events
How You Can Interrupt an Event Block
How You Can Obtain Information about the Current Event
Inter-Frame Communication Techniques
Overview
Communicating Between OpenROAD Frames
User Events
Terminate Method
Global Variables
How You Can Communicate Between Frames Using User Events
UserEvent Event Block
How You Can Access the SendUserEvent Parameters
SendUserEvent Method
Message Parameters
Focusbehavior Parameter
Delay Parameter
Errorevent Parameter
WaitFor Method
PurgeUserEvent Method
How You Can Communicate with an External Program Using External User Events
How You Can Register the External Event
RegisterUserEvent Method
UnRegisterUserEvent Method
UserEvent Event Block
How You Can Pass an Integer Value to an Event Block
How You Can Send the External User Event to OpenROAD
IIW4GL_SendUserEvent Procedure
External User Event Demo
How the External User Event Demo Works on Windows
Build the 3GL Application
Import the Sample Application into Your Database
Run the Sample Application
How the External User Event Demo Works on UNIX or Linux
Build the 3GL Application
Import the Sample Application into Your Database
Run the Sample Application
How You Can Communicate Between OpenROAD Applications Using Database Events
How Communication Using a Database Event Works
DBEventObject
How Database Events Work with Multiple Sessions
How You Can Create, Register, and Raise Events
How You Can Create the Event
How You Can Register the Event
How You Can Raise an Event
How You Can Purge Database Events
How You Can Communicate Between Frames with Database Events
Creating Dynamic Frames
Overview
Conceptual Background
How You Can Change Field and Frame Appearance and Behavior
Biases for Fields
Biases for Menu Items
How You Can Set Field and Menu Biases
How You Can Use the CurBias Attribute
How You Can Use the CurBias Attribute for Composite Fields
How You Can Change Frame Modes
Frame Modes
How You Can Use the CurMode Attribute
How You Can Use the Mode-Bias Attributes
How You Can Use the Frame Status Bar
How You Can Create and Modify Fields Dynamically
How You Can Create Dynamic Simple Fields
How You Can Create Dynamic Composite Fields
How You Can Create Dynamic Table Fields and Table Field Columns
How You Can Add a Column to a Table Field
How You Can Remove Fields Dynamically
How You Can Remove a Field from Display
How You Can Restore a Field to Display
How You Can Remove Columns from a Table Field
How You Can Declare a Composite Field's Array Variable Dynamically
How You Can Declare and Undeclare Data
How You Can Change a Dynamic Table Field after Declaring Data
How You Can Manipulate Data in Dynamic Fields
How You Can Set and Get Simple Field Values
How You Can Populate a Dynamic Table Field
How You Can Access Individual Cells of a Dynamic Table Field
How You Can Create a Dynamic Expression
How You Can Set and Get Values with Dynamic Expressions
How You Can Get Values from Unknown Fields
How You Can Manage Operations with a Control Button
Creating a Frame at Runtime
Overview
Conceptual Background
How You Can Build a Frame Dynamically
How You Can Create the Frame and Set Attributes
How You Can Create the Form
How You Can Create the Fields
How You Can Attach Fields to the Form
How You Can Create the Menu
How You Can Create the Script
How You Can Attach the Frame to the Application
How You Can Compile and Run the New Frame
Initialize Statement
How You Can Declare Variables
How You Can Select Tables for the Option Field
How You Can Load Values into a ChoiceField Object
How You Can Display the List
How You Can Initialize Variables
The Go Menu Item (Constructing the Frame)
How You Can Create the FrameSource Object
How You Can Set the FrameSource Attributes
How You Can Create the FrameForm Object
How You Can Construct the Fields
How You Can Set the Form Height and Width
How You Can Complete the SQL Statements
How You Can Create the Frame Menu Items
How You Can Construct a File Menu Group
How Generating the Frame Source Code Works
How You Can Add the Frame to the Application
How You Can Execute the Frame
Close Menu Item
Dynamic Statements Considerations
How You Can Populate a FlexibleForm, StackField, or MatrixField Dynamically
Writing a Template Assistant
Overview
Conceptual Overview
Assistants
How You Can Attach an Assistant to a Template
How You Can Ensure Compatibility Between a Frame Assistant and ApplyTemplate
How You Can Write an Assistant
Example--Frame Template Assistant
How You Can Attach the Assistant to a Frame Template
Example--Field Template Assistant
How You Can Attach the Assistant to a Field Template
How You Can Ensure Compatibility Between the Assistant and ApplyTemplate
How the Frame Creation Process Works
How You Can Use ApplyTemplate on a Frame
How You Can Partition the Frame
High-level Composite Field
Batch Mode Compared to Interactive Mode
How the Field Creation Process Works
How You Can Use ApplyTemplate on a Field
Example--ApplyTemplate Compatibility
How You Can Attach the Assistant to a Frame Template
Debugging Your Application
Overview
How You Can Use the Debugger
Start and Stop the Debugger
How You Can Test an Application
Debug a Single Application
Debug Multiple Applications
How Running in the Debugger Environment Works
Frame States
Transactions
Errors
Application Threads and Thread Identifiers
Synchronization of Concurrent Threads
How You Can Use Break Conditions
Debug Tab
Break Conditions
Set Break Conditions
Deactivate and Reactivate Break Conditions
How You Can Delete Break Conditions
Source Breakpoints
Ways to Set Source Breakpoints
Set Source Breakpoints
Delete Source Breakpoints
Event Break Conditions
Set Event Break Conditions
Break on Event Dialog
Error Break Conditions
Set Error Break Conditions
Call Break Conditions
Set Call Break Conditions
Method Invocation Break Conditions
Set Method Invocation Break Conditions
Thread Start Breakpoints
Set Thread Start Break Conditions
How You Can Log Trace Information
Trace Log Porlet
How You Can Use the Trace Log Portlet
How You Can Control Query Tracing and Execution
How You Can Monitor a Running Application
Current Thread Display
Thread Map
Call Stack Window
Event Queue Window
How You Can Debug Database Queries
How You Can Specify a Database Session
Create a New Database Connection
Open a New Session
Specify One of the Sessions of the Current Application
Run a Query
How Debugging an Application Works
Open the Debugger for an Application
How You Can Use the Debugger Window
Script Display Icons
Display a Different Script
How You Can Control Execution of Your Application
Step Button
Step Into Button
Step To End Button
Continue Button
Using the SK_BREAK Key to Stop Code Execution
Using the SK_BREAK Key to Output the Currently Executing 4GL Stack
How You Can Examine Values of Expressions
Write Expanded Values to the Trace Window
How You Can View Object Variables
Select a Display Option
Select Array Display Settings
Assign Values to Expressions
How You Can Use the Watch Facility
Set a Watch
Limit a Watch to the Current Scope
Open the Watch Window
Close the Watch Window
Turn Off the Watch Facility
How You Can Customize Function Keys and Tooltip Text
Customize the Keyboard
Add a Speedkey Name to Tooltip Text
Edit a Script
Debug an Imaged Application with the MonImage Utility
A. Operating System Differences
Overview
How You Can Use File Specifications
Operating System Commands
Glossary
Programming Guide
Glossary